index 4203e0c248c1471ac2b0c706f5dbbb654816d1fd..349508b8ddf111b7ded33421d58416714b290ab0 100644 (file)
--- a/rm.h
+++ b/rm.h
* between RM instances. This allows RM to easily extend to different device
* configurations and different devices entirely.
*
+ * Shared memory versions of the Server and Client are available for configuration
+ * in cases where the DSP applications cannot tolerate blocking operations or long wait
+ * times for resources. The Shared Server - Shared Client model assumes all memory
+ * allocated via the OSAL layer is within shared memory. RM service requests
+ * received from Shared Servers and Shared Clients will be handled via accesses
+ * to the resource management data structures existing in shared memory.
+ * - Shared Server - Essentially a Server instance that expects to be allocated
+ * from shared memory via the application-supplied OSAL functions.
+ * Shared Client instances will piggyback on the Shared Server
+ * instance to allocate/free resources without the need to setup
+ * transports between the instances. Access to the resource
+ * management data structures is managed through OSAL implemented
+ * cache writeback and invalidate operations.
+ * - Shared Client - Must be provided a Shared Server handle at initialization time.
+ * The Shared Client will essentially use the resource management
+ * data structures, created in shared memory when the Shared Server
+ * was initialized, to handle any server requests.
+
* RM utilizes the BDS-licensed, open source, Flattened Device Tree format to
* specify what resources are managed by RM as well as the RM instance permissions
* for managed resources. The Global Resource List or GRL defines all device
* RM instances currently provides the following resource services:
* - Allocate (initialize) - Allocate a resource for initialization
* - Allocate (usage) - Allocate a resource for use
+ * - Status - Return the reference count for a specified resource
* - Free - Free an allocated resource (The free must originate
* from the RM instance that allocated the resource
* - Map resource to name - Map a specified resource to a NameServer name
#define RM_OK 0
/** RM processing requested service */
#define RM_SERVICE_PROCESSING 1
+/** RM CD has placed on the request on hold pending a Server response */
+#define RM_SERVICE_PENDING_SERVER_RESPONSE 2
/** RM has approved requested service */
-#define RM_SERVICE_APPROVED 2
+#define RM_SERVICE_APPROVED 3
/** RM has approved requested service based on static policy. Request will be validated
* against global policy once all transports have been registered */
-#define RM_SERVICE_APPROVED_STATIC 3
+#define RM_SERVICE_APPROVED_STATIC 4
/** RM service request denial reasons base */
#define RM_SERVICE_DENIED_BASE 64
* global policy. RM instance cannot be unlocked. Please make sure static policy and global policy
* are in sync */
#define RM_SERVICE_DENIED_RM_INSTANCE_LOCKED RM_SERVICE_DENIED_BASE+16
+/** Allocate request denied because the resource is already reserved by Linux and "Shared Linux"
+ * privileges are not assigned to the requesting instance */
+#define RM_SERVICE_DENIED_RES_NOT_SHARED_LINUX RM_SERVICE_DENIED_BASE+17
+/** Status request resource range partially found (Handling of partial status requests not yet implemented) */
+#define RM_SERVICE_DENIED_PARTIAL_STATUS RM_SERVICE_DENIED_BASE+18
+
+/** RM Client Delegate instance is not stable. RM system operation cannot be guarateed
+ * if a CD instance is used. At the time please manage resources using Server and Client
+ * instances - tracked by SDOCM00100797 */
+#define RM_WARNING_CD_INSTANCE_NOT_STABLE (-1024)
/** Start of libfdt.h error codes */
#define RM_ERROR_LIBFDT_START (-1)
#define RM_ERROR_GRL_INVALID_LINUX_ALIAS_FORMAT RM_ERROR_BASE-14
/** Error allocating memory for the service handle */
#define RM_ERROR_SERVICE_HANDLE_MEM_ALLOC_FAILED RM_ERROR_BASE-15
-/** The RM instance service handle has already been opened */
-#define RM_ERROR_SERVICE_HANDLE_ALREADY_OPENED RM_ERROR_BASE-16
/** The RM instance service handle has already been closed */
-#define RM_ERROR_SERVICE_HANDLE_ALREADY_CLOSED RM_ERROR_BASE-17
+#define RM_ERROR_SERVICE_HANDLE_ALREADY_CLOSED RM_ERROR_BASE-16
/** Global Resource List (GRL) resource node contains an unknown property */
-#define RM_ERROR_GRL_UNKNOWN_RESOURCE_PROPERTY RM_ERROR_BASE-18
+#define RM_ERROR_GRL_UNKNOWN_RESOURCE_PROPERTY RM_ERROR_BASE-17
/** Could not find an allocator for the specified resource */
-#define RM_ERROR_RES_ALLOCATOR_DOES_NOT_EXIST RM_ERROR_BASE-19
+#define RM_ERROR_RES_ALLOCATOR_DOES_NOT_EXIST RM_ERROR_BASE-18
/** A resource node is specified more than once in the Global Resource List (GRL) */
-#define RM_ERROR_GRL_RES_SPECIFIED_MORE_THAN_ONCE RM_ERROR_BASE-20
+#define RM_ERROR_GRL_RES_SPECIFIED_MORE_THAN_ONCE RM_ERROR_BASE-19
/** No data was found at the GRL resource node's specified Linux alias path */
-#define RM_ERROR_DATA_NOT_FOUND_AT_LINUX_ALIAS RM_ERROR_BASE-21
+#define RM_ERROR_DATA_NOT_FOUND_AT_LINUX_ALIAS RM_ERROR_BASE-20
/** RM server was not provided a Global Resource List (GRL) and global policy at initialization */
-#define RM_ERROR_INVALID_SERVER_CONFIGURATION RM_ERROR_BASE-22
+#define RM_ERROR_INVALID_SERVER_CONFIGURATION RM_ERROR_BASE-21
/** Service request type not recognized */
-#define RM_ERROR_INVALID_SERVICE_TYPE RM_ERROR_BASE-23
-/** Service request did not contain callback function. Callback function must always be provided
- * with service request since blocking or non-blocking operations cannot be promised. */
-#define RM_ERROR_CALLBACK_NOT_PROVIDED RM_ERROR_BASE-24
+#define RM_ERROR_INVALID_SERVICE_TYPE RM_ERROR_BASE-22
/** rmAllocPkt transport callout returned NULL for rmPkt */
-#define RM_ERROR_TRANSPORT_ALLOC_PKT_ERROR RM_ERROR_BASE-25
+#define RM_ERROR_TRANSPORT_ALLOC_PKT_ERROR RM_ERROR_BASE-23
/** rmSendPkt transport callout returned error when attempting to send the rmPkt */
-#define RM_ERROR_TRANSPORT_SEND_ERROR RM_ERROR_BASE-26
+#define RM_ERROR_TRANSPORT_SEND_ERROR RM_ERROR_BASE-24
/** A RM service transaction could not be created for the service request */
-#define RM_ERROR_SERVICE_TRANS_NOT_CREATED RM_ERROR_BASE-27
+#define RM_ERROR_SERVICE_TRANS_NOT_CREATED RM_ERROR_BASE-25
/** RM service transaction could not be found in instance's transaction queue */
-#define RM_ERROR_SERVICE_TRANS_DOES_NOT_EXIST RM_ERROR_BASE-28
+#define RM_ERROR_SERVICE_TRANS_DOES_NOT_EXIST RM_ERROR_BASE-26
/** NameServer does not exist in instance, cannot satisfy NameServer service request */
-#define RM_ERROR_NAMESERVER_DOES_NOT_EXIST RM_ERROR_BASE-29
+#define RM_ERROR_NAMESERVER_DOES_NOT_EXIST RM_ERROR_BASE-27
/** Service request to add a name to the NameServer failed */
-#define RM_ERROR_NAMESERVER_NAME_ADD_FAILED RM_ERROR_BASE-30
+#define RM_ERROR_NAMESERVER_NAME_ADD_FAILED RM_ERROR_BASE-28
/** Could not find name specified in service request in NameServer */
-#define RM_ERROR_NAMESERVER_NAME_DOES_NOT_EXIST RM_ERROR_BASE-31
+#define RM_ERROR_NAMESERVER_NAME_DOES_NOT_EXIST RM_ERROR_BASE-29
/** Service request made on Client or CD when no transport established and no static policy registered */
-#define RM_ERROR_REQ_FAILED_NO_STATIC_POLICY RM_ERROR_BASE-32
+#define RM_ERROR_REQ_FAILED_NO_STATIC_POLICY RM_ERROR_BASE-30
/** RM transport handle has not been registered with the RM instance */
-#define RM_ERROR_TRANSPORT_HANDLE_DOES_NOT_EXIST RM_ERROR_BASE-33
+#define RM_ERROR_TRANSPORT_HANDLE_DOES_NOT_EXIST RM_ERROR_BASE-31
/** RM received a packet with an unknown RM packet type */
-#define RM_ERROR_RECEIVED_INVALID_PACKET_TYPE RM_ERROR_BASE-34
+#define RM_ERROR_RECEIVED_INVALID_PACKET_TYPE RM_ERROR_BASE-32
/** RM response packet does not match any requests sent from instance */
-#define RM_ERROR_PKT_RESP_DOES_NOT_MATCH_ANY_REQ RM_ERROR_BASE-35
+#define RM_ERROR_PKT_RESP_DOES_NOT_MATCH_ANY_REQ RM_ERROR_BASE-33
/** Server attempted to connect to another server or a CD attempted to connect to another CD or
* Client attempted to connect to another client */
-#define RM_ERROR_INVALID_REMOTE_INST_TYPE RM_ERROR_BASE-36
+#define RM_ERROR_INVALID_REMOTE_INST_TYPE RM_ERROR_BASE-34
/** RM client attempted to register with more than one Server or CD or a CD attempted to register
* with more than one Server */
-#define RM_ERROR_ALREADY_REGD_SERVER_OR_CD RM_ERROR_BASE-37
-/** Transport registration callout function pointers specified as valid but were NULL */
-#define RM_ERROR_NULL_CALLOUTS_WHEN_VALID RM_ERROR_BASE-38
-/** Service has both a NameServer name and a base, length, or alignment specified */
-#define RM_ERROR_NS_NAME_AND_RES_VAL_CONFLICT RM_ERROR_BASE-39
+#define RM_ERROR_ALREADY_REGD_SERVER_OR_CD RM_ERROR_BASE-35
/** Instance type not recognized */
-#define RM_ERROR_INVALID_INST_TYPE RM_ERROR_BASE-40
-/** Linux DTB alias properties specified in GRL but no Linux DTB provided during server instance init */
-#define RM_ERROR_GRL_LINUX_ALIAS_BUT_NO_DTB RM_ERROR_BASE-41
+#define RM_ERROR_INVALID_INST_TYPE RM_ERROR_BASE-36
/** RM attempted to allocate a transport packet but the rmAllocPkt callout was not registered */
-#define RM_ERROR_TRANSPORT_ALLOC_PKT_NOT_REGD RM_ERROR_BASE-42
+#define RM_ERROR_TRANSPORT_ALLOC_PKT_NOT_REGD RM_ERROR_BASE-37
/** RM attempted to send a packet but the rmSendPkt callout was not registered */
-#define RM_ERROR_TRANSPORT_SEND_NOT_REGD RM_ERROR_BASE-43
+#define RM_ERROR_TRANSPORT_SEND_NOT_REGD RM_ERROR_BASE-38
+/** RM instance cannot be deleted with transports still registered */
+#define RM_ERROR_CANT_DELETE_WITH_REGD_TRANSPORT RM_ERROR_BASE-39
+/** RM instance cannot be deleted with open service handle */
+#define RM_ERROR_CANT_DELETE_WITH_OPEN_SERV_HNDL RM_ERROR_BASE-40
+/** RM instance cannot be deleted when there are transactions pending and the
+ * ignorePendingServices parameter is set to false */
+#define RM_ERROR_CANT_DELETE_PENDING_TRANSACTIONS RM_ERROR_BASE-41
+/** Only the Server instance can be used to return resource status via the
+ * Rm_resourceStatus API */
+#define RM_ERROR_INVALID_RES_STATUS_INSTANCE RM_ERROR_BASE-42
+/** RM Shared Server and Client instances should always return a finished request since
+ * the instance has access to the resource structures no matter what core the service
+ * is requested from */
+#define RM_ERROR_SHARED_INSTANCE_UNFINISHED_REQ RM_ERROR_BASE-43
+/** RM Shared Server and Client instances cannot register transports */
+#define RM_ERROR_SHARED_INSTANCE_CANNOT_REG_TRANS RM_ERROR_BASE-44
+/** RM Shared Client handle was provided an invalid Shared Server handle. The shared
+ * server handle was either NULL or was not an instance of type Rm_instType_SHARED_SERVER */
+#define RM_ERROR_INVALID_SHARED_SERVER_HANDLE RM_ERROR_BASE-45
+/** A RM Client failed to create a new transaction to request data from the Server in order
+ * to potentially process a transaction on a Client Delegate */
+#define RM_ERROR_TRANS_REQ_TO_SERVER_NOT_CREATED RM_ERROR_BASE-46
+/** Service request required a policy check but instance was not initialized with a policy */
+#define RM_ERROR_INSTANCE_HAS_NO_POLICY RM_ERROR_BASE-47
+/** RM Client Delegate was not provided a policy at initialization */
+#define RM_ERROR_INVALID_CD_CONFIGURATION RM_ERROR_BASE-48
+/** RM CD freed local resources which allowed a free request of local request to be sent to
+ * the Server. The Server free failed so the CD tried to realloc the local resources
+ * that were originally freed. The re-allocate operation failed causing a resource loss
+ * on the CD */
+#define RM_ERROR_LOST_RESOURCES_ON_CD RM_ERROR_BASE-49
/**
* @brief Maximum number of characters allowed for RM instance, resource, and
Rm_instType_CLIENT_DELEGATE,
/** RM Client */
Rm_instType_CLIENT,
+ /** RM Shared Server - Server instance stored in shared memory that allows
+ * multiple DSP cores to request services without the need to configure
+ * and register transports. Allows requests to be fulfilled from any DSP
+ * core without blocking */
+ Rm_instType_SHARED_SERVER,
+ /** RM Shared Client - Piggybacks on the Shared Server instance to handle
+ * service requests from resource and policy data structures in shared
+ * memory */
+ Rm_instType_SHARED_CLIENT,
/** DO NOT USE: Last type */
Rm_instType_LAST
} Rm_InstType;
/**
- * @brief RM server initialization configurations
+ * @brief RM server (includes shared server) initialization configurations
*/
typedef struct {
/** Pointer to the device global resource list (GRL). The GRL contains
* @brief RM client delegate (CD) initialization configurations
*/
typedef struct {
- /** Pointer to a static policy used by the CD to allocate resources statically.
- * Static allocations can occur before the instance has been attached to a server
- * instance within the RM system. This is useful for allocating resources
- * prior to main(). Resources allocated via the static policy will be verified
- * against the global policy once the CD connects with the server. The static
- * policy must be in DTB format. */
- void *staticPolicy;
+ /** Pointer to a client delegate policy used by the CD to allocate resources
+ * without contacting the server. The cdPolicy will be used by the CD to
+ * determine whether clients connected to the CD can be allocated resources
+ * provided to the CD by the server.
+ *
+ * The cdPolicy will also act as a static policy until the transport to the
+ * server has been established. Static allocations can occur before the
+ * instance has been attached to a server instance within the RM system.
+ * This is useful for allocating resources prior to main(). Resources allocated
+ * via the static policy will be verified against the global policy once the
+ * CD connects with the server. The static policy must be in DTB format.
+ *
+ * To guarantee proper resource permission synchronization between the CD
+ * and server the cdPolicy must either be an exact copy of the globalPolicy
+ * or a exact replica of a subset of the globalPolicy provided to the server
+ * at initialization. */
+ void *cdPolicy;
} Rm_ClientDelegateCfg;
/**
void *staticPolicy;
} Rm_ClientCfg;
+/**
+ * @brief RM shared client initialization configurations
+ */
+typedef struct {
+ /** RM Shared Server handle. Typically, the Shared Server handle is created on
+ * DSP core designated for system initialization. The application then
+ * the Shared Server handle, located in shared memory, to the other DSP cores.
+ * These DSP cores can then piggyback onto the shared memory data structures in
+ * the Shared Server via the Shared Client */
+ Rm_Handle sharedServerHandle;
+} Rm_SharedClientCfg;
+
/**
* @brief RM instance initialization structure
*/
* must match an instance name defined in the "valid-instances" lists contained
* in the global and static policy DTS files. Resources and privileges to the
* resources will be based on the name assigned to the RM instance*/
- const char *instName;
+ const char *instName;
/** The type of RM instance that will be created. */
- Rm_InstType instType;
+ Rm_InstType instType;
/** Instance-type specific configurations */
union {
/** #Rm_ServerCfg */
- Rm_ServerCfg serverCfg;
+ Rm_ServerCfg serverCfg;
/** #Rm_ClientDelegateCfg */
Rm_ClientDelegateCfg cdCfg;
/** #Rm_ClientCfg */
- Rm_ClientCfg clientCfg;
+ Rm_ClientCfg clientCfg;
+ /** #Rm_SharedClientCfg */
+ Rm_SharedClientCfg sharedClientCfg;
} instCfg;
} Rm_InitCfg;
/**
* @b Description
* @n
- * This function prints the status for all resources managed by the
- * RM instance network. The allocate/free status as well as ownership
+ * This function prints and returns the status for all resources managed by
+ * the RM instance network. The allocate/free status as well as ownership
* status will be printed for every resource. Also, the NameServer name
* entries will be displayed.
*
- * This function only prints resources when provided the server handle
- * since the server stores all the resource and NameServer
- * data structures.
+ * This function will return error if a Client handle is provided since
+ * Clients do not track any resource data structures
+ *
+ * @param[in] rmHandle
+ * Instance handle.
*
- * @param[in] rmServerHandle
- * Server instance handle.
+ * @param[in] printResources
+ * Non-zero - Resource ownership details will be printed for all
+ * tracked resources
+ * 0 - Resource ownership details will not be printed. Only
+ * the number of allocated resource ranges will be
+ * returned.
+ *
+ * @retval
+ * Success - Total number of allocated resource nodes owners. Effectively
+ * returns the number of resource ranges still allocated.
+ * @retval
+ * Failure - #RM_ERROR_INVALID_RES_STATUS_INSTANCE
*/
-void Rm_printResourceStatus(Rm_Handle rmServerHandle);
+int32_t Rm_resourceStatus(Rm_Handle rmHandle, int printResources);
/**
* @b Description
* @param[in] rmHandle
* Instance handle.
*/
-void Rm_printInstanceStatus(Rm_Handle rmHandle);
+void Rm_instanceStatus(Rm_Handle rmHandle);
/**
* @b Description
* result in a new RM instance. However, a network of RM instances
* can have only one RM Server. If an application has multiple RM
* Servers the resources managed by each server must be mutually
- * exclusive.
+ * exclusive. Additionally if an application has multiple RM shared
+ * servers the resources they manage must be mutually exclusive as well
*
* If any errors are encountered during the initialization process
* the Rm_Handle returned will be NULL.
*/
Rm_Handle Rm_init(const Rm_InitCfg *initCfg, int32_t *result);
+/**
+ * @b Description
+ * @n
+ * This function deletes the specified RM instance. All memory
+ * associated with the instance will be freed.
+ *
+ * @param[in] rmHandle
+ * Instance handle.
+ *
+ * @param[in] ignorePendingServices
+ * Non-zero - The instance will be deleted despite any services pending <br>
+ * 0 - The instance will not be deleted due to at least one service
+ * pending.
+ *
+ * @retval
+ * Success - #RM_OK
+ * @retval
+ * Failure - #RM_ERROR_CANT_DELETE_WITH_OPEN_SERV_HNDL
+ * @retval
+ * Failure - #RM_ERROR_CANT_DELETE_WITH_REGD_TRANSPORT
+ * @retval
+ * Failure - #RM_ERROR_CANT_DELETE_PENDING_TRANSACTIONS
+ */
+int32_t Rm_delete(Rm_Handle rmHandle, int ignorePendingServices);
+
/**
* @b Description
* @n
* @retval
* Version Information.
*/
-uint32_t Rm_getVersion (void);
+uint32_t Rm_getVersion(void);
/**
* @b Description
* @retval
* Version String.
*/
-const char* Rm_getVersionStr (void);
+const char* Rm_getVersionStr(void);
/**
@}