diff --git a/rm_services.h b/rm_services.h
index 501a77ee0c7c20d14227ab62d88a104836c1c335..a00292bf43a20c0efc2e935c96b06c4c90772c06 100644 (file)
--- a/rm_services.h
+++ b/rm_services.h
* @file rm_services.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
* ============================================================================
- * @n (C) Copyright 2012, Texas Instruments, Inc.
+ * @n (C) Copyright 2012-2013, Texas Instruments, Inc.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
extern "C" {
#endif
+/* RM includes */
+#include <ti/drv/rm/rm.h>
+
/**
@addtogroup RM_SERVICES_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 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)
-
-/** 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)
-/** 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)
-/** 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)
-
/**
* @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 resource allocate for initialization service */
+ Rm_service_RESOURCE_ALLOCATE_INIT = 0,
+ /** RM resource allocate for use service */
+ Rm_service_RESOURCE_ALLOCATE_USE,
/** 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 resource mapping to name service */
- Rm_service_RESOURCE_MAP_TO_NAME = 6,
- /** 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_FREE,
+ /** RM resource status service - returns the reference count for specified
+ * resource. */
+ Rm_service_RESOURCE_STATUS,
+ /** RM NameServer map resource to name service */
+ Rm_service_RESOURCE_MAP_TO_NAME,
+ /** RM NameServer get resource by name service */
+ Rm_service_RESOURCE_GET_BY_NAME,
+ /** RM NameServer unmap resource from name service */
+ Rm_service_RESOURCE_UNMAP_NAME,
+ /** DO NOT USE: Last type */
+ Rm_service_LAST
} Rm_ServiceType;
/**
- * @brief RM service response information provided by RM back to the
- * requesting component
+ * @brief RM service response information used by RM to provide service
+ * request results back to the application components
*/
typedef struct {
- /** Result 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
- * be returned if the service request is satisfied immediately */
- uint32_t requestId;
- /** 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;
+ /** RM instance handle from which the service request that spawned this
+ * result originated. Used by application to sort responses, received
+ * via callback function, from RM instances located on the same core. */
+ Rm_Handle rmHandle;
+ /** Service request state. State values can be found in rm.h starting
+ * with #RM_SERVICE_PROCESSING, #RM_SERVICE_DENIED_BASE, and
+ * #RM_ERROR_LIBFDT_START */
+ int32_t serviceState;
+ /** The service ID is returned to the application in order to match service
+ * responses received at a later time via the provided callback function
+ * because RM required a blocking operation in order to satisfy the
+ * resource request. <br> <br> The service ID will never have a value of
+ * zero. */
+ uint32_t serviceId;
+ /** Affected resource name */
+ char resourceName[RM_NAME_MAX_CHARS];
+ /** The resource base value allocated, freed, or mapped to NameServer name. */
+ int32_t resourceBase;
+ /** The resource length starting at base allocated, freed, or mapped to
+ * NameServer name. */
+ uint32_t resourceLength;
+/** resourceNumOwners is not valid unless >= 0 */
+#define RM_RESOURCE_NUM_OWNERS_INVALID (-1)
+ /** Current number of owners for the returned resource. A value greater
+ * than one means the resource is being shared. This value is only valid
+ * if the serviceState is RM_SERVICE_APPROVED or RM_SERVICE_APPROVED_STATIC. */
+ int32_t resourceNumOwners;
} Rm_ServiceRespInfo;
/**
- * @brief RM service request information provided by the requesting component
+ * @brief RM service callback function
*/
typedef struct {
- /** The type of RM service requested */
- Rm_ServiceType serviceType;
- /** 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;
- /** 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;
- /** Resource alignment in block allocation requests */
- uint32_t resAlign;
- /** 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);
+ /** Component callback function. RM calls this function when a blocking
+ * resource service request is complete. The callback function supplied
+ * for this parameter must match the function pointer prototype. */
+ void (*serviceCallback) (Rm_ServiceRespInfo *serviceResponse);
+} Rm_ServiceCallback;
+
+/**
+ * @brief RM service request information
+ */
+typedef struct {
+ /** The type of service requested */
+ Rm_ServiceType type;
+ /** Pointer to an array containing the resource name affected by
+ * the request. The resource name must match a resource node name
+ * defined in the GRL and global/static policy. The request will be
+ * denied if the resource name does not match any resource node names
+ * in the policy */
+ const char *resourceName;
+/** Informs RM to find the next available resource block of length
+ * resourceLength and alignment resourceAlignment for allocation. This
+ * parameter is only valid for resource allocate service types. */
+#define RM_RESOURCE_BASE_UNSPECIFIED (-1)
+ /** The base value of the resource affected by the service request.
+ * #RM_RESOURCE_BASE_UNSPECIFIED can be substituted. */
+ int32_t resourceBase;
+ /** The resource length, starting from #resourceBase affected by the
+ * service request. */
+ uint32_t resourceLength;
+/** Informs RM to find the next available resource block with length
+ * resourceLength and the alignment specified in
+ * a) The resource node in the policy if it has the "allocation-alignment"
+ * property defined.
+ * b) The default alignment of 1 if no alignment is specified in the policy
+ * for the resource.
+ * This value is only valid if resourceBase is set to #RM_RESOURCE_BASE_UNSPECIFIED */
+#define RM_RESOURCE_ALIGNMENT_UNSPECIFIED (-1)
+ /** Alignment of the resource affected by the service request. Only valid
+ * if resourceBase is set to #RM_RESOURCE_BASE_UNSPECIFIED.
+ * #RM_RESOURCE_ALIGNMENT_UNSPECIFIED can be substituted. */
+ int32_t resourceAlignment;
+ /** The NameServer name associated, or to be associated, with a resource.
+ * The NameServer name has precedence over #resourceBase and #resourceLength
+ * for all resource modification service types as well as
+ * #Rm_service_RESOURCE_GET_BY_NAME. If the NameServer name and the base
+ * and length are not NULL the resource information retrieved from the
+ * NameServer entry for the name will replace the values present in
+ * #resourceBase and #resourceLength */
+ const char *resourceNsName;
+ /** Callback function used by RM to provide responses back to application
+ * components after a service request resulted in a blocking operation.
+ * If no callback function is provided the RM instance will block until
+ * the service response is ready. */
+ 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 handle provided to application components for requesting
+ * services
*/
typedef struct {
- /** RM instance handle for which the service handle was registered */
+ /** RM instance handle from which the service handle was allocated from. */
void *rmHandle;
/**
* @b Description
* @n
- * Callout function used by components to request a resource service
- * from a RM instance
+ * Processes service requests from application components. Responses
+ * are returned immediately if the service request could be satisfied
+ * without blocking. If the service request requires a blocking operation,
+ * such as forwarding the service request to another instance for
+ * validation, the response will be received via the Rm_ServerCallback
*
* @param[in] rmHandle
- * RM instance handle specifying the RM instance that should handle the
- * service request
+ * RM instance handle specifies the instance that handles the service
+ * request. The request's result, if policy checks are involved, will be
+ * based on the permissions assigned to the rmHandle's instance name within
+ * global/static policy.
*
- * @param[in] requestInfo
- * Service request structure that provides details of the service requested from
- * the RM instance tied to this component
+ * @param[in] serviceRequest
+ * Pointer to the service request structure
*
- * @param[in] responseInfo
- * Service response structure that provides details of RM's response to the
- * service request
+ * @param[out] serviceResponse
+ * Pointer to a service response structure.
*/
- void (*rmService)(void *rmHandle, Rm_ServiceReqInfo *requestInfo,
- Rm_ServiceRespInfo *responseInfo);
-} Rm_ServicesPort;
+ void (*Rm_serviceHandler)(void *rmHandle, const Rm_ServiceReqInfo *serviceRequest,
+ Rm_ServiceRespInfo *serviceResponse);
+} Rm_ServiceHandle;
+
+/**
+ * @b Description
+ * @n
+ * This function returns a RM service handle to the application to
+ * provide services to software components (LLDs, BIOS, etc) that want to use RM
+ * for resource management. Only one service handle can be opened from
+ * each RM instance.
+ *
+ * @param[in] rmHandle
+ * RM instance handle from which the service handle will be opened
+ *
+ * @param[out] result
+ * Pointer to a signed int used to return any errors encountered during
+ * the instance initialization process.
+ *
+ * @retval
+ * Success - Rm_ServiceHandle and result = #RM_OK
+ * @retval
+ * Failure - NULL Rm_ServiceHandle and result = #RM_ERROR_SERVICE_HANDLE_MEM_ALLOC_FAILED
+ */
+Rm_ServiceHandle *Rm_serviceOpenHandle(Rm_Handle rmHandle, int32_t *result);
+
+/**
+ * @b Description
+ * @n
+ * This function closes a RM instance's service handle
+ *
+ * @param[in] rmServiceHandle
+ * RM instance service handle to be closed.
+ *
+ * @retval
+ * Success - #RM_OK
+ * @retval
+ * Failure - #RM_ERROR_SERVICE_HANDLE_ALREADY_CLOSED
+ */
+int32_t Rm_serviceCloseHandle(Rm_ServiceHandle *rmServiceHandle);
/**
@}