index ca6f1d2811a586fd4702a4f21beb6cc86dcbb2cd..349508b8ddf111b7ded33421d58416714b290ab0 100644 (file)
--- a/rm.h
+++ b/rm.h
/* Standard includes */
#include <stdint.h>
-/* RM version */
-#include <ti/drv/rm/rmver.h>
-
/** @mainpage Resource Manager
*
* @section intro Introduction
*
- * The Resource Manager low level driver (RM LLD) is designed to provide initialization and permissions checking
- *
+ * The Resource Manager (RM) is designed to provide an easy to use, extensible
+ * uinified resource management solution on TI devices. RM can be integrated by
+ * a system application to provide resource management services to the system
+ * temporally (pre-main/post-main) and spatially (system subcomponents, task,
+ * cores).
+ *
+ * The RM architecture is instance based. All RM resource management services
+ * must originate from a RM instance. Resource permissions are assigned by a
+ * system integrator using RM instance names provided during the initialization
+ * of each RM instance in use. There are three types of RM instances, all of
+ * which can be used by the system to request resource management services:
+ * - Server - Manages all resource data structures including the resource
+ * allocators, the permissions policies, and a simple NameServer.
+ * There can only be one Server per RM ecosystem. If two Servers
+ * are initialized within a system they must manage mutually
+ * exclusive sets of device resources. There is no limit to the
+ * number of Client and Client Delegate instances that can connect
+ * to the Server
+ * - Client - Used by system components to request resource services. There is
+ * no limit to the number of Clients a system can have. Client
+ * names must be unique since resource permissions are assigned based
+ * on RM instance names. Clients can connect to at most one Server
+ * or Client Delegate, but not both at the same time.
+ * - Client Delegate (CD) - At the moment the CD is not different from the
+ * Client. However, in the future the CD will be able
+ * to act as a proxy for the Server. The CD will be
+ * able to satisfy some service requests from Clients,
+ * offloading some processing from the Server. This
+ * feature will be helpful in situations where a
+ * slower data path exists between the Server and
+ * CD/Client instances. There is no limit to the number
+ * of Clients that can connect to a CD. The CD can
+ * connect to at most one Server.
+ *
+ * RM instances communicate via a generic transport interface. The RM transport
+ * interface expects the application to configure and manage the transport data paths
+ * 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
+ * resources and their ranges that will be tracked by the RM Server. Addition or
+ * subtraction of resources from RM requires one modify only the GRL. RM source code
+ * changes are not required to add or subtract resources from RM's umbrella of
+ * management. RM Policies specify resource permissions for the RM instances. There
+ * are two types of Policies:
+ * - Global Policy - Provided to the Server at initialization and defines the
+ * resource permissions for all RM instances in the system.
+ * All service requests will be validated against the Global
+ * Policy on the Server. If the RM instance is found to not
+ * hold the privileges for the request a denial of the service
+ * will be issued back to the requesting instance.
+ * - Static Policy - Optionally provided to Client and CD instances at
+ * initialization. Allows these instances to statically
+ * allocate resources. This feature is typically used
+ * for RM instances that must allocate resources prior
+ * to the transport connection to the Server being established.
+ * Resources allocated via any Static Policies will
+ * be validated against the Global Policy once the transport
+ * to the Server has been fully established. If a Static
+ * Policy request fails validation with the Global Policy the
+ * RM instance that issued the static request will be placed
+ * into a locked state. The locked state prevents any further
+ * service requests from the instance.
+ *
+ * Combined, the GRL and Policy Device Tree implementations allow RM to easily extend
+ * to new resources without the need to recompile the RM source code.
+ *
+ * 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
+ * - Unmap named resource - Unmap a resource from an existing NameServer name
+ * - Get resource by name - Returns a resource based on a provided NameServer name
*/
/* Define RM_API as a master group in Doxygen format and add all RM API
/** @} */
/**
-@defgroup RM_TRANSPORT_API RM Transport-Layer API
+@defgroup RM_TRANSPORT_API RM Transport API
@ingroup RM_API
*/
/**
-@defgroup RM_SERVICES_API RM Registered Component Services API
+@defgroup RM_SERVICES_API RM Services API
@ingroup RM_API
*/
+/**
+@defgroup RM_OSAL_API RM OS Abstraction Layer API
+@ingroup RM_API
+*/
+
+/**
+@addtogroup RM_API
+@{
+*/
-/* TODO: CANT CONFLICT WITH OTHER ERROR CODES INCLUDING LIBFDT */
-#define RM_INIT_OK 0
-#define RM_INIT_ERROR_INSTANCE_NAME_TOO_BIG -256
-#define RM_INIT_ERROR_POLICY_NO_VALID_INSTANCES_DEFINED -257
-#define RM_INIT_ERROR_POLICY_UNKNOWN_INSTANCE -258
-#define RM_INIT_ERROR_POLICY_PERMISSION_SYNTAX_ERROR -259
-#define RM_INIT_ERROR_POLICY_UNKNOWN_RESOURCE -260
-#define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_MORE_THAN_ONE_INSTANCE_GROUP -261
-#define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_MORE_THAN_ONE_ASSIGNMENT_CHAR -262
-#define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_INVALID_PERM_CHAR -263
-#define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_PERM_CHAR_WITHOUT_ASSIGN_CHAR -264
-#define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_INVALID_CHAR_ON_RIGHT_WITH_ASSINMENT_ON_LEFT -265
-#define RM_INIT_ERROR_POLICY_UNKNOWN_RESOURCE_PROPERTY -267
-#define RM_INIT_ERROR_POLICY_VALID_INSTANCE_NAME_TOO_LONG -268
-#define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_INSTANCE_NAME_IN_ASSIGNMENT_TOO_LONG -269
-#define RM_INIT_ERROR_NS_ASSIGNMENT_NAME_TOO_LONG -270
-#define RM_INIT_ERROR_GRL_INVALID_LINUX_ALIAS_FORMAT -271
-#define RM_INIT_ERROR_SERVICE_HANDLE_MEMORY_ALLOC_FAILED -272
-#define RM_INIT_ERROR_SERVICE_HANDLE_ALREADY_ALLOCATED -273
-#define RM_INIT_ERROR_SERVICE_HANDLE_ALREADY_CLOSED_FOR_INSTANCE -274
-#define RM_INIT_ERROR_UNKNOWN_RESOURCE_LIST_PROPERTY_TYPE -275
-#define RM_INIT_ERROR_ALLOCATOR_DOES_NOT_EXIST -276
-#define RM_INIT_ERROR_RESOURCE_OVERLAP_WHEN_CREATING_ALLOCATOR -277
-#define RM_INIT_ERROR_COULD_NOT_LOCATE_RESOURCE_IN_LINUX_DTB -278
+/* RM return and error codes */
+/** RM successful return code */
+#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 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 4
-/** RM Service Request State Codes and Errors */
-/** RM Service Request State Code Base */
-#define RM_SERVICE_STATE_BASE (0)
-/** RM internal state okay - This value is for internal use by RM. It should never be
- * seen as a return value during normal operation */
-#define RM_SERVICE_STATE_OKAY (RM_SERVICE_STATE_BASE)
-/** RM service is being processed. Typically this means the service is
- * being sent to a higher level RM agent for processing */
-#define RM_SERVICE_PROCESSING (RM_SERVICE_STATE_BASE+1)
-/** RM service was approved. The resource data in the response is valid if
- * the service has been approved. */
-#define RM_SERVICE_APPROVED_AND_COMPLETED (RM_SERVICE_STATE_BASE+2)
-/** Beginning of resource denied reasons */
-#define RM_SERVICE_DENIED_BEGIN (RM_SERVICE_STATE_BASE+3)
-/** RM could not find an allocator for the resource specified with the provided name */
-#define RM_SERVICE_DENIED_RESOURCE_DOES_NOT_EXIST (RM_SERVICE_DENIED_BEGIN)
-/** A resource value within the specifed base+range could not be found within the resource's
- * allocator. No action was taken on the resources. */
-#define RM_SERVICE_DENIED_RESOURCE_VALUE_RANGE_DOES_NOT_EXIST (RM_SERVICE_DENIED_BEGIN+1)
-/** A resource value within the specifed base+range was not allocated to the RM instance
- * that is the source of the request. No action was taken on the resources. */
-#define RM_SERVICE_DENIED_RESOURCE_NOT_ALLOCATED_TO_INSTANCE_REQUESTING_THE_SERVICE (RM_SERVICE_DENIED_BEGIN+2)
-/** A resource value within the specifed base+range is already free */
-#define RM_SERVICE_DENIED_RESOURCE_ALREADY_FREE (RM_SERVICE_DENIED_BEGIN+3)
-/** A resource value within the specifed base+range is already allocated to another
- * RM instance. */
-#define RM_SERVICE_DENIED_RESOURCE_ALREADY_ALLOCATED (RM_SERVICE_DENIED_BEGIN+4)
-/** The resource range specified for freeing included free and allocated resoruces. */
-#define RM_SERVICE_DENIED_INVALID_RESOURCE_RANGE (RM_SERVICE_DENIED_BEGIN+5)
-/** No free resource ranges could be found that satisfy the resource base, length, and
- * alignment requirements */
-#define RM_SERVICE_DENIED_RESOURCE_ALLOCATION_REQUIREMENTS_COULD_NOT_BE_SATISFIED (RM_SERVICE_DENIED_BEGIN+6)
-/** The RM instance requesting the service is not defined in the policy */
-#define RM_SERVICE_DENIED_RM_INST_NOT_DEFINED_IN_POLICY (RM_SERVICE_DENIED_BEGIN+7)
-/** The resource in the service request is not defined in the policy */
-#define RM_SERVICE_DENIED_RESOURCE_NOT_DEFINED_IN_POLICY (RM_SERVICE_DENIED_BEGIN+8)
-/** The resource has multiple assigned range definitions */
-#define RM_SERVICE_DENIED_ASSIGNED_RANGE_SPECIFICATION_ERROR (RM_SERVICE_DENIED_BEGIN+9)
-/** The resource has multiple allocation size definitions */
-#define RM_SERVICE_DENIED_ALLOCATION_SIZE_SPECIFICATION_ERROR (RM_SERVICE_DENIED_BEGIN+10)
-/** The resource has multiple assigned name definitions */
-#define RM_SERVICE_DENIED_ASSIGNED_NAME_SPECIFICATION_ERROR (RM_SERVICE_DENIED_BEGIN+11)
-/** The resource has multiple allocation alignment definitions */
-#define RM_SERVICE_DENIED_ALLOCATION_ALIGNMENT_SPECIFICATION_ERROR (RM_SERVICE_DENIED_BEGIN+12)
-/** The resource node in the policy has an unknown property type */
-#define RM_SERVICE_DENIED_UNKNOWN_POLICY_PROPERTY (RM_SERVICE_DENIED_BEGIN+13)
-/** The policy does not approve of the resources requested by the RM instance in the service
- * request */
-#define RM_SERVICE_DENIED_POLICY_DENIAL (RM_SERVICE_DENIED_BEGIN+14)
-/** Attempt to add object to NameServer denied: The object name already exists in the NameServer */
-#define RM_SERVICE_DENIED_NAMESERVER_ERROR_NAME_ALREADY_EXISTS (RM_SERVICE_DENIED_BEGIN+15)
-/** No valid ranges were specified for the resource within the RM instance's node within the policy.
- * By default all resource requests for this resource are denied */
-#define RM_SERVICE_DENIED_POLICY_DENIAL_NO_RANGES_SPECIFIED (RM_SERVICE_DENIED_BEGIN+16)
-/** The instance name of the service requesting instance is not in the policy valid instance list */
-#define RM_SERVICE_DENIED_ORIGINATING_INSTANCE_NAME_NOT_VALID (RM_SERVICE_DENIED_BEGIN+17)
-/** The policy does not specify any assignment ranges for the resource in the service request */
-#define RM_SERVICE_DENIED_NO_RANGE_ASSIGNMENTS_FOR_POLICY (RM_SERVICE_DENIED_BEGIN+18)
-/** The resource couldn't be allocated because the requesting instance was not given the init/use
- * permissions in the policy */
-#define RM_SERVICE_DENIED_INIT_USE_PERMISSION_DENIED (RM_SERVICE_DENIED_BEGIN+19)
-/** The resource couldn't be allocated because the requesting instance has exclusive privileges in the
- * policy but the resource was already allocated */
-#define RM_SERVICE_DENIED_REQUESTER_HAS_EXCLUSIVE_PRIV_BUT_RESOURCE_ALLOCATED (RM_SERVICE_DENIED_BEGIN+20)
-/** The resource couldn't be allocated because it was already allocated to an instance with exclusive
- * privileges for the resource */
-#define RM_SERVICE_DENIED_RESOURCE_ALLOCATED_TO_INSTANCE_WITH_EXCLUSIVE_PRIV (RM_SERVICE_DENIED_BEGIN+21)
-/** Static request was not an allocate use or allocate init request */
-#define RM_SERVICE_DENIED_INVALID_STATIC_REQUEST (RM_SERVICE_DENIED_BEGIN+22)
-/** Startup policy denied static allocation request */
-#define RM_SERVICE_DENIED_POLICY_DENIED_STATIC_ALLOCATION (RM_SERVICE_DENIED_BEGIN+23)
-/** End of resource denied reasons */
-#define RM_SERVICE_DENIED_END (RM_SERVICE_DENIED_BEGIN+23)
+/** RM service request denial reasons base */
+#define RM_SERVICE_DENIED_BASE 64
+/** Request resource not found in policy or allocators */
+#define RM_SERVICE_DENIED_RES_DOES_NOT_EXIST RM_SERVICE_DENIED_BASE+1
+/** Request resource range within not found within resource's allocator */
+#define RM_SERVICE_DENIED_RES_RANGE_DOES_NOT_EXIST RM_SERVICE_DENIED_BASE+2
+/** Free request resource range not allocated to service's source inst */
+#define RM_SERVICE_DENIED_RES_NOT_ALLOCD_TO_INST RM_SERVICE_DENIED_BASE+3
+/** Free request resource range already free */
+#define RM_SERVICE_DENIED_RES_ALREADY_FREE RM_SERVICE_DENIED_BASE+4
+/** Allocate request resource range partially allocated (Handling of partial allocations
+ * not yet implemented) */
+#define RM_SERVICE_DENIED_PARTIAL_ALLOCATION RM_SERVICE_DENIED_BASE+5
+/** Free request resource range partially free (Handling of partial frees not yet implemented) */
+#define RM_SERVICE_DENIED_PARTIAL_FREE RM_SERVICE_DENIED_BASE+6
+/** Requirements of allocate request could not be satisfied (occurs for UNSPECIFIED base
+ * and/or alignment requests */
+#define RM_SERVICE_DENIED_RES_ALLOC_REQS_NOT_MET RM_SERVICE_DENIED_BASE+7
+/** NameServer add request name string already exists in NameServer */
+#define RM_SERVICE_DENIED_NAME_EXISTS_IN_NS RM_SERVICE_DENIED_BASE+8
+/** Service request instance not in policy "valid-instances" list */
+#define RM_SERVICE_DENIED_INST_NAME_NOT_VALID RM_SERVICE_DENIED_BASE+9
+/** Init allocate request resource range not given init privileges in policy */
+#define RM_SERVICE_DENIED_INIT_PERM_NOT_GIVEN RM_SERVICE_DENIED_BASE+10
+/** Use allocate request resource range not given use privileges in policy */
+#define RM_SERVICE_DENIED_USE_PERM_NOT_GIVEN RM_SERVICE_DENIED_BASE+11
+/** Allocate request resource range marked as exclusive in policy has already been allocated */
+#define RM_SERVICE_DENIED_EXCLUSIVE_RES_ALLOCD RM_SERVICE_DENIED_BASE+12
+/** Allocate request resource range allocated to an instance assigned exclusive privileges in policy */
+#define RM_SERVICE_DENIED_ALLOCD_TO_EXCLUSIVE_INST RM_SERVICE_DENIED_BASE+13
+/** Static allocate request was not an allocate-use or allocate-init request */
+#define RM_SERVICE_DENIED_INVALID_STATIC_REQUEST RM_SERVICE_DENIED_BASE+14
+/** Static allocate request denied by static policy */
+#define RM_SERVICE_DENIED_BY_STATIC_POLICY RM_SERVICE_DENIED_BASE+15
+/** RM instance locked from further services since a static allocation failed validation against
+ * 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 Service Request Error Code Base */
-#define RM_SERVICE_ERROR_BASE (-64)
-/** RM service request type not recognized */
-#define RM_SERVICE_ERROR_INVALID_SERVICE_TYPE (RM_SERVICE_ERROR_BASE)
-/** RM Service request was not provided a component callback
- * function. Service requests may result in blocking operations. A callback
- * function must always be provided with a service request since
- * blocked or non-blocked operations cannot be promised. */
-#define RM_SERVICE_ERROR_CALLBACK_NOT_PROVIDED (RM_SERVICE_ERROR_BASE-1)
-/** RM service request needs to be forwarded to another RM agent but no transports
- * have been registered */
-#define RM_SERVICE_ERROR_NO_TRANSPORT_REGISTERED (RM_SERVICE_ERROR_BASE-2)
-/** RM service request needs to be forwarded but no client delegate or server has
- * been registered with the RM instance */
-#define RM_SERVICE_ERROR_NOT_REGISTERED_WITH_DEL_OR_SERVER (RM_SERVICE_ERROR_BASE-3)
-/** RM service request needs to be forwarded but the transport packet alloc API
- * has not been provided */
-#define RM_SERVICE_ERROR_TRANSPORT_PKT_ALLOC_API_NULL (RM_SERVICE_ERROR_BASE-4)
-/** A failure occurred within a registered transport's packet alloc API */
-#define RM_SERVICE_ERROR_TRANSPORT_ALLOC_PKT_ERROR (RM_SERVICE_ERROR_BASE-5)
-/** RM service request needs to be forwarded but the transport returned an error
- * when trying to send the RM packet to the higher level agent */
-#define RM_SERVICE_ERROR_TRANPSPORT_SEND_ERROR (RM_SERVICE_ERROR_BASE-7)
-/** RM service response from higher level agent did not match any requests made
- * by the provided RM instance */
-#define RM_SERVICE_ERROR_TRANSACTION_DOES_NOT_EXIST_FOR_THIS_RM_INSTANCE (RM_SERVICE_ERROR_BASE-8)
-/** RM failed to allocate memory for new service transaction */
-#define RM_SERVICE_ERROR_TRANSACTION_FAILED_TO_ALLOCATE (RM_SERVICE_ERROR_BASE-9)
-/** RM could not find the service transaction in the RM instance's transaction queue */
-#define RM_SERVICE_ERROR_SERVICE_TRANSACTION_DOES_NOT_EXIST (RM_SERVICE_ERROR_BASE-10)
-/** A failure occurred within a registered transport's packet free API */
-#define RM_SERVICE_ERROR_TRANSPORT_FREE_PKT_ERROR (RM_SERVICE_ERROR_BASE-11)
-/** Invalid NameServer object modification on non-Server instance */
-#define RM_SERVICE_ERROR_NAMESERVER_OBJECT_MOD_ON_INVALID_INSTANCE (RM_SERVICE_ERROR_BASE-12)
-/** Request failed because both a NameServer name and a resource range were specified */
-#define RM_SERVICE_ERROR_NAMESERVER_NAME_AND_RESOURCE_RANGE_BOTH_DEFINED (RM_SERVICE_ERROR_BASE-13)
-/** Error occurred when trying to add an object to the NameServer */
-#define RM_SERVICE_ERROR_NAMESERVER_OBJECT_ADD_FAILED (RM_SERVICE_ERROR_BASE-14)
-/** Could not find the object specified in the service request in the NameServer */
-#define RM_SERVICE_ERROR_NAMESERVER_ERROR_NAME_DOES_NOT_EXIST (RM_SERVICE_ERROR_BASE-15)
+/** 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)
-/** RM Transport Result Return Codes */
-/** RM Transport Success Code Base */
-#define RM_TRANSPORT_OK_BASE (0)
-/** RM transport action was successful. */
-#define RM_TRANSPORT_SUCCESSFUL (RM_TRANSPORT_OK_BASE)
+/** Start of libfdt.h error codes */
+#define RM_ERROR_LIBFDT_START (-1)
+/** End of libfdt.h error codes */
+#define RM_ERROR_LIBFDT_END (-13)
-/** RM Transport Error Code Base */
-#define RM_TRANSPORT_ERROR_BASE (-64)
+/** RM error base */
+#define RM_ERROR_BASE (-64)
+/** Instance name provided is NULL or greater than RM_NAME_MAX_CHARS */
+#define RM_ERROR_INVALID_INST_NAME RM_ERROR_BASE-1
+/** List of "valid-instances" not found in global or static policy */
+#define RM_ERROR_NO_VALID_INST_IN_POLICY RM_ERROR_BASE-2
+/** Instance specified in permissions string does not match any instances specified in the
+ * "valid-instances" list */
+#define RM_ERROR_PERM_STR_INST_NOT_VALID RM_ERROR_BASE-3
+/** Resource specified in global policy does not have an allocator */
+#define RM_ERROR_UNKNOWN_RESOURCE_IN_POLICY RM_ERROR_BASE-4
+/** Permissions string has more than instance group specified.
+ * Ex: assignments = <12 1>, "iux = (RM_Client_Delegate) iu = (RM_Client)"; */
+#define RM_ERROR_PERM_STR_TOO_MANY_INST_GROUPS RM_ERROR_BASE-5
+/** Permissions string has more than assignment.
+ * Ex: assignments = <12 1>, "iux = (RM_Client_Delegate) = i"; */
+#define RM_ERROR_PERM_STR_TOO_MANY_ASSIGN_CHARS RM_ERROR_BASE-6
+/** Permissions string contains invalid character */
+#define RM_ERROR_PERM_STR_INVALID_CHAR RM_ERROR_BASE-7
+/** Permissions string contains a permission character without the assignment operator
+ * Ex: assignments = <12 1>, "iux (RM_Client_Delegate)"; */
+#define RM_ERROR_PERM_CHAR_WITHOUT_ASSIGN_CHAR RM_ERROR_BASE-8
+/** Permissions string contains a permission character on opposite side of already made assignment
+ * Ex: assignments = <12 1>, "iux = (RM_Client_Delegate) x"; */
+#define RM_ERROR_INVALID_PERMS_CHAR_ON_RIGHT RM_ERROR_BASE-9
+/** Policy resource node contains an unknown property */
+#define RM_ERROR_UNKNOWN_POLICY_RESOURCE_PROPERTY RM_ERROR_BASE-10
+/** Instance name provided in "valid-instances" list is greater than RM_NAME_MAX_CHARS */
+#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
+/** 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 */
+#define RM_ERROR_SERVICE_HANDLE_MEM_ALLOC_FAILED RM_ERROR_BASE-15
+/** The RM instance service handle has already been closed */
+#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-17
+/** Could not find an allocator for the specified resource */
+#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-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-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-21
+/** Service request type not recognized */
+#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-23
+/** rmSendPkt transport callout returned error when attempting to send the rmPkt */
+#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-25
+/** RM service transaction could not be found in instance's transaction queue */
+#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-27
+/** Service request to add a name to the NameServer failed */
+#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-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-30
/** RM transport handle has not been registered with the RM instance */
-#define RM_TRANSPORT_ERROR_HANDLE_HAS_NOT_BEEN_REGISTERED (RM_TRANSPORT_ERROR_BASE-1)
-/** RM packets are available but an error was encountered during reception */
-#define RM_TRANSPORT_ERROR_PACKET_RECEPTION_ERROR (RM_TRANSPORT_ERROR_BASE-3)
+#define RM_ERROR_TRANSPORT_HANDLE_DOES_NOT_EXIST RM_ERROR_BASE-31
/** RM received a packet with an unknown RM packet type */
-#define RM_TRANSPORT_ERROR_INVALID_PACKET_TYPE (RM_TRANSPORT_ERROR_BASE-4)
-/** RM resource request transaction could not be found matching the response received */
-#define RM_TRANSPORT_ERROR_MATCHING_RESOURCE_REQUEST_NOT_FOUND (RM_TRANSPORT_ERROR_BASE-5)
-/** RM NameServer request transaction could not be found matching the response received */
-#define RM_TRANSPORT_ERROR_MATCHING_NAME_SERVER_REQUEST_NOT_FOUND (RM_TRANSPORT_ERROR_BASE-6)
-/** RM server cannot connect to other servers and CDs cannot connect to other CDs */
-#define RM_TRANSPORT_ERROR_INVALID_REMOTE_INST_TYPE (RM_TRANSPORT_ERROR_BASE-7)
-/** RM clients can't register with more than one Server or CD. CDs can't register with more than one Server */
-#define RM_TRANSPORT_ERROR_REGISTERING_WITH_MORE_THAN_ONE_SERVER_OR_CD (RM_TRANSPORT_ERROR_BASE-8)
-/** Transport callouts provided to RM were specified as valid but NULL was provided */
-#define RM_TRANSPORT_ERROR_CALLOUTS_VALID_BUT_NULL_PROVIDED (RM_TRANSPORT_ERROR_BASE-10)
+#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-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-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-35
+/** Instance type not recognized */
+#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-37
+/** RM attempted to send a packet but the rmSendPkt callout was not registered */
+#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
#define RM_NAME_MAX_CHARS (32)
/**
- * @brief RM Handle provided to application. The RM Handle is used by the
- * application to distinquish between different RM instances running on
- * the same core.
+ * @brief RM instance handle. The RM handle is used to register transports
+ * between RM instances and request resource services from the RM
+ * instance.
*/
typedef void *Rm_Handle;
-typedef void *Rm_PreMainHandle;
-
/**
- * @brief RM Instance types
+ * @brief RM instance types
*/
typedef enum {
/** RM Server */
Rm_instType_SERVER = 0,
/** RM Client Delegate */
- Rm_instType_CLIENT_DELEGATE = 1,
+ Rm_instType_CLIENT_DELEGATE,
/** RM Client */
- Rm_instType_CLIENT = 2
+ 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 instance initialization structure
+/**
+ * @brief RM server (includes shared server) initialization configurations
*/
typedef struct {
- /** Pointer to RM instance name character array. The name of the RM instance must
- * be reflected exactly in the initial RM policies provided to the RM
- * tree's Servers and Client Delegates. The RM instance name is
- * used by the policy to map which instances are allowed defined
- * privileges */
- char *instName;
- /** RM instance type. Defines whether the RM instance will be initialized
- * as a RM Server, Client Delegate, or Client */
- Rm_InstType instType;
- /** [Server Parameter] Pointer to the device-wide resource list. The list
- * contains all resources available on the device available for
- * allocation. Servers running on ARM-Linux cores provide a subset
- * of the global device list for allocation. The subset is formed from
- * the global resources leftover after the Linux DTB is parsed for
- * resources reserved by Linux.
- *
- * Note: This parameter will be ignored when the instance type is either
- * Client Delegate or Client */
+ /** Pointer to the device global resource list (GRL). The GRL contains
+ * all resources on the device that will be managed by RM. The GRL
+ * must be in DTB format. */
void *globalResourceList;
- /** [Server Parameter When Running on ARM Linux] Pointer to the Linux DTB.
- * The Linux DTB will be parsed for all tracked resources reserved for use
- * by Linux.
- *
- * Note: This parameter will be ignored when the instance type is either
- * Client Delegate or Client */
+ /** Pointer to the Linux DTB if the RM server is running on ARM Linux.
+ * The Linux DTB will be parsed for all managed resources reserved for use
+ * by Linux. Parsing will be based on "linux-dtb-alias" resource
+ * properties found in the GRL. The Linux DTB must be in DTB format. */
void *linuxDtb;
- /** [Server/Client Delegate Paramter] Pointer to the allocation
- * policy. RM Servers should be initialized with the global policy
- * listing for all RM instances within the system. RM Client Delegates
- * can be initialized with their local policy, must be a subset of the
- * global policy provided to the Client Delegate's Server.
+ /** Pointer to the global policy defining the allocation policies for
+ * RM instances within the system. The global policy must be in DTB
+ * format. */
+ void *globalPolicy;
+} Rm_ServerCfg;
+
+/**
+ * @brief RM client delegate (CD) initialization configurations
+ */
+typedef struct {
+ /** 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.
*
- * Note: The core charged with the task of initializing the BIOS and IPC
- * components must run an RM Client Delegate with an initial policy
- * that allocates a system timer to BIOS and a HW semaphore to IPC
- *
- * Note: This parameter will be ignored when the instance type is a
- * Client
- */
- void *dynamicPolicy;
- /** static policy used for pre-main allocation of resources. Resources given
- * in the static will be verified against the global policy once the RM
- * system is fully initialized */
+ * 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;
+
+/**
+ * @brief RM client initialization configurations
+ */
+typedef struct {
+ /** Pointer to a static policy used by the client to allocate resources statically.
+ * Static allocations can occur before the instance has been attached to a server
+ * or CD 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 client connects with the server (directly or
+ * indirectly through a CD). The static policy must be in DTB format. */
void *staticPolicy;
-} Rm_InitCfg;
+} Rm_ClientCfg;
-/* TESTING PURPOSES: SERVER ONLY */
-void Rm_printResourceStatus(Rm_Handle *rmHandle);
+/**
+ * @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;
-Rm_PreMainHandle Rm_preMainInit(Rm_PreMainInitCfg *preMainInitCfg, int32_t *result);
+/**
+ * @brief RM instance initialization structure
+ */
+typedef struct {
+ /** Pointer to a character array containing the instance name. The name of the
+ * RM instance can be no greater than #RM_NAME_MAX_CHARS. The instance name
+ * 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;
+ /** The type of RM instance that will be created. */
+ Rm_InstType instType;
+ /** Instance-type specific configurations */
+ union {
+ /** #Rm_ServerCfg */
+ Rm_ServerCfg serverCfg;
+ /** #Rm_ClientDelegateCfg */
+ Rm_ClientDelegateCfg cdCfg;
+ /** #Rm_ClientCfg */
+ Rm_ClientCfg clientCfg;
+ /** #Rm_SharedClientCfg */
+ Rm_SharedClientCfg sharedClientCfg;
+ } instCfg;
+} Rm_InitCfg;
+/**
+ * @b Description
+ * @n
+ * 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 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] 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
+ */
+int32_t Rm_resourceStatus(Rm_Handle rmHandle, int printResources);
-int32_t Rm_validateStaticRequests(Rm_Handle rmHandle);
+/**
+ * @b Description
+ * @n
+ * This function prints the current status of a RM instance. The
+ * following instance properties will be printed:
+ * a) instance name & type
+ * b) The instance's registered transports
+ * c) All service transactions queued in the instance transaction
+ * queue and their states
+ *
+ * @param[in] rmHandle
+ * Instance handle.
+ */
+void Rm_instanceStatus(Rm_Handle rmHandle);
/**
* @b Description
* @n
- * This function initializes a RM instance.
- *
- * IMPORTANT: Rm_init must be called prior to any other component startup
- * APIs (BIOS_start, Ipc_start, etc).
+ * This function initializes a RM instance. There are no restrictions
+ * on the amount of times this function can be called. Each call will
+ * 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. Additionally if an application has multiple RM shared
+ * servers the resources they manage must be mutually exclusive as well
*
- * @param[in] *initCfg
- * Pointer to structure containing the initialization information for
- * this RM instance.
+ * If any errors are encountered during the initialization process
+ * the Rm_Handle returned will be NULL.
*
- * @param[in] *result
- * Pointer to a uint32_t that will contain the result of the RM
- * intialization and handle creation. Any errors encountered will be
- * returned via this pointer.
+ * @param[in] initCfg
+ * Pointer to the instance initialization structure.
*
+ * @param[out] result
+ * Pointer to a signed int used to return any errors encountered during
+ * the instance initialization process.
+ *
+ * @retval
+ * Success - Rm_Handle for instance and result = #RM_OK
+ * @retval
+ * Failure - NULL Rm_Handle and result < #RM_OK
+ */
+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
- * Success - non-zero Rm_Handle returned.
+ * Failure - #RM_ERROR_CANT_DELETE_WITH_OPEN_SERV_HNDL
* @retval
- * Failure - NULL Rm_handle returned.
+ * Failure - #RM_ERROR_CANT_DELETE_WITH_REGD_TRANSPORT
+ * @retval
+ * Failure - #RM_ERROR_CANT_DELETE_PENDING_TRANSACTIONS
*/
-Rm_Handle Rm_init(Rm_InitCfg *initCfg, int32_t *result);
+int32_t Rm_delete(Rm_Handle rmHandle, int ignorePendingServices);
/**
* @b Description
* @n
- * The function is used to get the version information of the RM.
+ * The function is used to get the version information of RM.
*
* @retval
* Version Information.
*/
-uint32_t Rm_getVersion (void);
+uint32_t Rm_getVersion(void);
/**
* @b Description
* @n
- * The function is used to get the version string for the RM.
+ * The function is used to get the version string for RM.
*
* @retval
* Version String.
*/
-const char* Rm_getVersionStr (void);
+const char* Rm_getVersionStr(void);
+
+/**
+@}
+*/
#ifdef __cplusplus
}