diff --git a/rm_services.h b/rm_services.h
index 501a77ee0c7c20d14227ab62d88a104836c1c335..0f824598d316d679a937088fa667af32550dff56 100644 (file)
--- a/rm_services.h
+++ b/rm_services.h
/**
- * @file rm_services.h
+ * @file rmservices.h
*
* @brief
- * This is the RM include file for services provided to components that register a RM
- * instance
+ * This is the RM include file for services provided to components that
+ * register a RM instance
*
* \par
* ============================================================================
* \par
*/
-#ifndef RM_SERVICES_H_
-#define RM_SERVICES_H_
+#ifndef RMSERVICES_H_
+#define RMSERVICES_H_
#ifdef __cplusplus
extern "C" {
#endif
+/* RM includes */
+#include <ti/drv/rm/rm.h>
+
/**
-@addtogroup RM_SERVICES_API
+@addtogroup RMSERVICES_API
@{
*/
-/**
- * @brief RM will return the next available resource if the component assigns
- * "not specified" in the resourceIndex field when the resource allocate
- * service is initiated.
- */
-#define RM_SERVICE_INDEX_NOT_SPECIFIED (-1)
-
-/** RM Service Request (serviceResult) Action Codes and Errors */
-/** RM Service Request Action Code Base */
-#define RM_SERVICE_ACTION_BASE (0)
-/** RM service was approved. The resource data in the response is valid if
- * the service has been approved. */
-#define RM_SERVICE_APPROVED (RM_SERVICE_ACTION_BASE)
-/** RM service was denied. The resource data in the response is not valid */
-#define RM_SERVICE_DENIED (RM_SERVICE_APPROVED+1)
+/** 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_DENIED+2)
+#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)
+/** End of resource denied reasons */
+#define RM_SERVICE_DENIED_END (RM_SERVICE_DENIED_BEGIN+4)
/** RM Service Request Error Code Base */
#define RM_SERVICE_ERROR_BASE (-64)
/** 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)
-/** RM service request needs to be forwarded but the transport packet alloc returned
- * NULL for the packet buffer */
-#define RM_SERVICE_ERROR_TRANSPORT_NULL_PKT_BUF (RM_SERVICE_ERROR_BASE-5)
+/** 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 buffer allocated by transport
* is not large enough to fit the RM transport packet */
#define RM_SERVICE_ERROR_TRANSPORT_PKT_BUF_TOO_SMALL (RM_SERVICE_ERROR_BASE-6)
/** 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 request needs to be forwarded but the transport packet send API
- * has not been provided */
-#define RM_SERVICE_ERROR_TRANSPORT_PKT_SEND_API_NULL (RM_SERVICE_ERROR_BASE-8)
+/** 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_EXST_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)
+
+/**
+ * @brief Maximum number of characters in the resource names
+ */
+#define RM_RESOURCE_NAME_MAX_CHARS (36)
/**
* @brief RM service types
*/
typedef enum {
- /** First service type. Used by RM for bounds checking. Should
- * not be used by component. */
- Rm_service_FIRST = 0,
/** RM resource allocate service */
- Rm_service_RESOURCE_ALLOCATE = 0,
- /** RM resource block allocate service */
- Rm_service_RESOURCE_BLOCK_ALLOCATE = 1,
- /** RM resource allocate by name service */
- Rm_service_RESOURCE_ALLOCATE_BY_NAME = 2,
+ Rm_service_RESOURCE_ALLOCATE = 0,
/** RM resource free service */
- Rm_service_RESOURCE_FREE = 3,
- /** RM resource block free service */
- Rm_service_RESOURCE_BLOCK_FREE = 4,
- /** RM resource free by name service */
- Rm_service_RESOURCE_FREE_BY_NAME = 5,
+ Rm_service_RESOURCE_FREE = 1,
/** RM resource mapping to name service */
- Rm_service_RESOURCE_MAP_TO_NAME = 6,
+ Rm_service_RESOURCE_MAP_TO_NAME = 2,
+ /** RM resource get by name service */
+ Rm_service_RESOURCE_GET_BY_NAME = 3,
/** RM resource name unmapping service */
- Rm_service_RESOURCE_UNMAP_NAME = 7,
- /** RM resource status service */
- Rm_service_RESOURCE_STATUS = 8,
- /** Last service type. Used by RM for bounds checking. Should
- * not be used by component. */
- Rm_service_LAST = 8
+ Rm_service_RESOURCE_UNMAP_NAME = 4
} Rm_ServiceType;
+/**
+ * @brief RM pre-main allocation request information provided by the pre-main
+ * startup function requesting the resource */
+typedef struct {
+ /** Pointer to the requested pre-main allocation resource name. The
+ * name provided by the component must match the resource names
+ * provided in the global resource table and allocation policies */
+ char *resourceName;
+ /** The pre-main allocation request resource base value. For example,
+ * queue number or semaphore number */
+ uint32_t resourceBase;
+ /** Range of resource starting at resourceBase */
+ uint32_t resourceRange;
+} Rm_PreMainAllocInfo;
+
/**
* @brief RM service response information provided by RM back to the
* requesting component
*/
typedef struct {
- /** Result of the service request
+ /** State of the service request.
* Non-negative result: RM has taken an action based on the request
* Negative result: RM has encountered an error handling the request */
- int32_t serviceResult;
- /** A request ID will be returned to the component if the requested service cannot
- * be completed immediately. The request ID can be used by the component to identify
- * service responses received via the component callback function. A request ID will not
+ int32_t serviceState;
+ /** A service ID will be returned to the component if the requested service cannot
+ * be completed immediately. The service ID can be used by the component to identify
+ * service responses received via the component callback function. A service ID will not
* be returned if the service request is satisfied immediately */
- uint32_t requestId;
+ uint32_t serviceId;
/** The base value of the returned resource. In the case of a block resource allocation
* response this field will contain the base value of the block. */
- int32_t resBase;
- /** The number of resources allocated in block requests */
- uint32_t resNum;
+ int32_t resourceBase;
+ /** The number of resources starting from resourceBase allocated in block requests */
+ uint32_t resourceLength;
} Rm_ServiceRespInfo;
+/**
+ * @brief RM service callback function structure
+ */
+typedef struct {
+ /** Component callback function. RM will call this function when the
+ * resource service request is completed. The callback function supplied
+ * for this parameter must match this function pointer prototype. */
+ void (*serviceCallback) (Rm_ServiceRespInfo *serviceResponse);
+} Rm_ServiceCallback;
+
/**
* @brief RM service request information provided by the requesting component
*/
typedef struct {
/** The type of RM service requested */
- Rm_ServiceType serviceType;
+ Rm_ServiceType type;
/** Pointer to the name of the resource requested. The
* name provided by the component must match the resource node names
* provided in the global resource table and allocation policies */
- char *resName;
+ char *resourceName;
+/** An allocate service can be requested with an unspecified resource base.
+ * If this occurs the RM Client Delegate or Server will assign the next available
+ * resource or set of resources based on the allocation type. */
+#define RM_RESOURCE_BASE_UNSPECIFIED (-1)
/** The resource base value. */
- int32_t resBase;
- /** The number of the specified resources. Will be greater than one only
- * for block allocate and free service requests. */
- uint32_t resNum;
+ int32_t resourceBase;
+ /** The number of the specified resource to be allocated starting from
+ * resourceBase. Will be greater than one only for block allocate
+ * and free service requests. */
+ uint32_t resourceLength;
+/** An allocate service can be requested with an unspecified resource alignment.
+ * WARNING: Only applicapable if resourceBase is unspecified
+ *
+ * If the alignment is unspecified the RM Client Delegate or Server will allocate
+ * the resources from a default alignment as specified in the global policy. */
+#define RM_RESOURCE_ALIGNMENT_UNSPECIFIED (-1)
/** Resource alignment in block allocation requests */
- uint32_t resAlign;
+ int32_t resourceAlignment;
/** The name server name associated with the resource. Used only for
* allocate and free by name service requests */
- char *resNsName;
- /** Component callback function. RM will call this function when the
- * resource service request is completed. The callback function supplied
- * for this parameter must match this function pointer prototype. */
- void (*serviceCallback) (Rm_ServiceRespInfo *responseInfo);
+ char *resourceNsName;
+ /** Component specified callback function used by RM to inform components
+ * of service requst results */
+ Rm_ServiceCallback callback;
} Rm_ServiceReqInfo;
/**
- * @brief RM Service Handle provided to software components that
- * request RM services for the resources they control
+ * @brief RM Service Port provided to software components and applications that
+ * request RM services for the resources they wish to use
*/
typedef struct {
/** RM instance handle for which the service handle was registered */
* RM instance handle specifying the RM instance that should handle the
* service request
*
- * @param[in] requestInfo
+ * @param[in] serviceRequest
* Service request structure that provides details of the service requested from
* the RM instance tied to this component
*
- * @param[in] responseInfo
+ * @param[in] serviceResponse
* Service response structure that provides details of RM's response to the
* service request
*/
- void (*rmService)(void *rmHandle, Rm_ServiceReqInfo *requestInfo,
- Rm_ServiceRespInfo *responseInfo);
-} Rm_ServicesPort;
+ void (*rmService)(void *rmHandle, Rm_ServiceReqInfo *serviceRequest,
+ Rm_ServiceRespInfo *serviceResponse);
+} Rm_ServicePort;
+
+/**
+ * @b Description
+ * @n
+ * Non-blocking function used by RTSC pre-main startup functions to
+ * allocate RM resources for usage. Pre-main allocated resources will be
+ * validated by RM against a memory-mapped startup resource policy.
+ * Pre-main allocation of unauthorized resources will result in a system
+ * exception.
+ *
+ * Note: Resource pre-main allocations can only occur on a core that is
+ * running a RM Server or Client Delegate that has a startup policy
+ * allowing the allocation of pre-main resources
+ *
+ * @param[in] preMainAllocInfo
+ * Resource pre-main allocation structure that provides details of the
+ * resource requested from RM for preallocation
+ *
+ * @param[out] serviceResponse
+ * Contains the result information regarding the pre-main allocation request
+ *
+ * @retval
+ * Success - 0 - Resource pre-main allocation request okay.
+ * @retval
+ * Failure - non-zero - Resource pre-main allocation request error.
+ */
+void Rm_preMainAllocService (Rm_PreMainAllocInfo *preMainAllocInfo,
+ Rm_ServiceRespInfo *serviceResponse);
+
+/**
+ * @b Description
+ * @n
+ * This function returns a RM service port to the application to
+ * provide to software components (LLDs, BIOS, etc) that want to use RM
+ * for resource management.
+ *
+ * @param[in] rmHandle
+ * RM instance handle. Used to return a Rm_ServicePort from an RM
+ * instance.
+ *
+ * @retval
+ * Success - RM Service Port. Used by an application or component to
+ * request a service from RM.
+ * @retval
+ * Failure - NULL
+ */
+Rm_ServicePort *Rm_getServicePort(Rm_Handle rmHandle);
/**
@}
}
#endif
-#endif /* RM_SERVICES_H_ */
+#endif /* RMSERVICES_H_ */