index 0745d743ba389e16699f743e00cf6216d8922065..0d81d1230754c63915258ecc3bf4308cf099b33a 100644 (file)
--- a/rm.h
+++ b/rm.h
*
* \par
* ============================================================================
- * @n (C) Copyright 2012-2013, Texas Instruments, Inc.
+ * @n (C) Copyright 2012-2014, Texas Instruments, Inc.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* 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
/** 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_VALID_INST_NAME_TOO_LONG RM_ERROR_BASE-11
/** Instance name in permissions assignment is greater than RM_NAME_MAX_CHARS */
#define RM_ERROR_INST_NAME_IN_ASSIGNMENT_TOO_LONG RM_ERROR_BASE-12
-/** NameServer name in global resource list nameServer assignment is greater than RM_NAME_MAX_CHARS */
-#define RM_ERROR_GRL_NS_ASSIGNMENT_NAME_TOO_LONG RM_ERROR_BASE-13
+/** NameServer name in global resource list nameServer assignment and/or service request
+ * is greater than RM_NAME_MAX_CHARS */
+#define RM_ERROR_NAMESERVER_NAME_TOO_LONG RM_ERROR_BASE-13
/** Linux alias assignment in global resource list is invalid */
#define RM_ERROR_GRL_INVALID_LINUX_ALIAS_FORMAT RM_ERROR_BASE-14
/** Error allocating memory for the service handle */
/** 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-35
-/** 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-36
/** Instance type not recognized */
-#define RM_ERROR_INVALID_INST_TYPE RM_ERROR_BASE-37
+#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-38
+#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-39
-/** RM attempted to send a response packet but the transport to the remote instance that sent
- * the request packet is not registered */
-#define RM_ERROR_TRANSPORT_REMOTE_HNDL_NOT_REGD RM_ERROR_BASE-40
+#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-41
+#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-42
+#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-43
+#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-44
+#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-45
+#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-46
+#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-47
+#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
+/** The service source inst name and RM packet source instance names are not available
+ * for the given type of RM packet */
+#define RM_ERROR_PKT_AND_SERVICE_SRC_NOT_AVAIL RM_ERROR_BASE-50
+/** The provided character buffer that will contain the service source inst name or pkt
+ * source inst name is not of size RM_NAME_MAX_CHARS */
+#define RM_ERROR_SRC_NAME_BUF_INVALID_SIZE RM_ERROR_BASE-51
+/** A resource name specified in the GRL, policy, and/or service request is greater than
+ * RM_NAME_MAX_CHARS */
+#define RM_ERROR_RESOURCE_NAME_TOO_LONG RM_ERROR_BASE-52
+/** RM failed to create a new allocator - Occurred because an instance that does not use
+ * allocators tried to create one (RM Client) */
+#define RM_ERROR_COULD_NOT_CREATE_NEW_ALLOCATOR RM_ERROR_BASE-53
/**
* @brief Maximum number of characters allowed for RM instance, resource, and
* @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;
/**
const char *instName;
/** The type of RM instance that will be created. */
Rm_InstType instType;
+ /** Instance's multi-threaded semaphore object. Two or more RM instances can have
+ * their service transactions to the Server serialized by providing a valid
+ * multi-threaded semaphore object. The semaphore object will be used by the
+ * Osal_rmMtCsEnter and Osal_rmMtCsExit functions. The multi-threaded
+ * semaphore associated with the provided object will be taken when a
+ * service transaction is requested. The semaphore will be released when
+ * the service response is returned. This will serialize the transactions
+ * of any RM instance initialized with the same multi-threaded sem object.
+ * Multi-threaded semaphores will not be used if NULL is provided as the object */
+ uint32_t *mtSemObj;
/** Instance-type specific configurations */
union {
/** #Rm_ServerCfg */
* 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] rmServerHandle
- * Server instance handle.
+ * @param[in] rmHandle
+ * Instance handle.
*
- * @param]in] printResources
+ * @param[in] printResources
* Non-zero - Resource ownership details will be printed for all
* tracked resources
* 0 - Resource ownership details will not be printed. Only
* @retval
* Failure - #RM_ERROR_INVALID_RES_STATUS_INSTANCE
*/
-int32_t Rm_resourceStatus(Rm_Handle rmServerHandle, int printResources);
+int32_t Rm_resourceStatus(Rm_Handle rmHandle, int printResources);
/**
* @b Description