diff --git a/rm_services.h b/rm_services.h
index a4c4ce91077ab0cc9c6b9c3c4b3636dd10955bf3..142ea9a350a145821e05b5dbdbd2c3aafeec3a3b 100644 (file)
--- a/rm_services.h
+++ b/rm_services.h
/**
- * @file rmservices.h
+ * @file rm_services.h
*
* @brief
* This is the RM include file for services provided to components that
*
* \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
* \par
*/
-#ifndef RMSERVICES_H_
-#define RMSERVICES_H_
+#ifndef RM_SERVICES_H_
+#define RM_SERVICES_H_
#ifdef __cplusplus
extern "C" {
#include <ti/drv/rm/rm.h>
/**
-@addtogroup RMSERVICES_API
+@addtogroup RM_SERVICES_API
@{
*/
-/** 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)
-/** Pre main request was not an allocate use or allocate init request */
-#define RM_SERVICE_DENIED_INVALID_PREMAIN_REQUEST (RM_SERVICE_DENIED_BEGIN+22)
-/** Startup policy denied pre-main allocation request */
-#define RM_SERVICE_DENIED_POLICY_DENIED_PREMAIN_ALLOCATION (RM_SERVICE_DENIED_BEGIN+23)
-/** End of resource denied reasons */
-#define RM_SERVICE_DENIED_END (RM_SERVICE_DENIED_BEGIN+23)
-
-/** 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 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 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)
-
-/**
- * @brief Maximum number of characters in the resource names
- */
-#define RM_RESOURCE_NAME_MAX_CHARS (36)
-
/**
* @brief RM service types
*/
Rm_service_RESOURCE_ALLOCATE_USE,
/** RM resource free service */
Rm_service_RESOURCE_FREE,
- /** RM resource mapping to name service */
+ /** RM NameServer map resource to name service */
Rm_service_RESOURCE_MAP_TO_NAME,
- /** RM resource get by name service */
+ /** RM NameServer get resource by name service */
Rm_service_RESOURCE_GET_BY_NAME,
- /** RM resource name unmapping service */
- Rm_service_RESOURCE_UNMAP_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 {
- /** 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 */
+ /** Service request state. The state can be an approval, denial, or error.
+ * The latter codes start at #RM_OK, #RM_SERVICE_DENIED_BASE, and
+ * #RM_ERROR_BASE, respectively. */
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 */
+ /** 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. */
uint32_t serviceId;
- /** The name of the resource affected by the service request */
- char resourceName[RM_RESOURCE_NAME_MAX_CHARS];
- /** 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. */
+ /** Affected resource name */
+ char resourceName[RM_NAME_MAX_CHARS];
+ /** The resource base value allocated, freed, or mapped to NameServer name. */
int32_t resourceBase;
- /** The number of resources starting from resourceBase allocated in block requests */
+ /** The resource length starting at base allocated, freed, or mapped to
+ * NameServer name. */
uint32_t resourceLength;
} Rm_ServiceRespInfo;
/**
- * @brief RM service callback function structure
+ * @brief RM service callback function
*/
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. */
+ /** 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 provided by the requesting component
+ * @brief RM service request information
*/
typedef struct {
- /** The type of RM service requested */
+ /** The type of service requested */
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 *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. */
+ /** 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 resource base value. */
+ /** The base value of the resource affected by the service request.
+ * #RM_RESOURCE_BASE_UNSPECIFIED can be substituted. */
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. */
+ /** The resource length, starting from #resourceBase affected by the
+ * service request. */
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. */
+/** 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)
- /** Resource alignment in block allocation requests */
+ /** 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 name server name associated with the resource. Used only for
- * allocate and free by name service requests */
- char *resourceNsName;
- /** Component specified callback function used by RM to inform components
- * of service requst results */
+ /** The NameServer name associated, or to be associated, with a resource.
+ * If the service type is #Rm_service_RESOURCE_GET_BY_NAME and the
+ * #resourceBase and #resourceLength fields are not NULL a error will
+ * occur. */
+ const char *resourceNsName;
+ /** Callback function used by RM to provide responses back to application
+ * components after a service request resulted in a blocking operation. */
Rm_ServiceCallback callback;
} Rm_ServiceReqInfo;
/**
- * @brief RM Service Port provided to software components and applications that
- * request RM services for the resources they wish to use
+ * @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 for 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] serviceRequest
- * Service request structure that provides details of the service requested from
- * the RM instance tied to this component
+ * Pointer to the service request structure
*
- * @param[in] serviceResponse
- * 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 *serviceRequest,
- Rm_ServiceRespInfo *serviceResponse);
-} Rm_ServicePort;
-
-/**
- * @brief RM pre-main allocation request information provided by the pre-main
- * startup function requesting the resource */
-typedef struct {
- Rm_PreMainHandle rmPreMainHandle;
- Rm_ServiceReqInfo *request;
-} Rm_PreMainReqCfg;
+ void (*Rm_serviceHandler)(void *rmHandle, const Rm_ServiceReqInfo *serviceRequest,
+ Rm_ServiceRespInfo *serviceResponse);
+} Rm_ServiceHandle;
/**
* @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
+ * 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] preMainRequest
- * Resource pre-main allocation structure that provides details of the
- * resource requested from RM for preallocation
+ * @param[in] rmHandle
+ * RM instance handle from which the service handle will be opened
*
- * @param[out] preMainResponse
- * Contains the result information regarding the pre-main allocation request
+ * @param[out] result
+ * Pointer to a signed int used to return any errors encountered during
+ * the instance initialization process.
*
* @retval
- * Success - 0 - Resource pre-main allocation request okay.
+ * Success - Rm_ServiceHandle and result = #RM_OK
+ * @retval
+ * Failure - NULL Rm_ServiceHandle and result = #RM_ERROR_SERVICE_HANDLE_MEM_ALLOC_FAILED
* @retval
- * Failure - non-zero - Resource pre-main allocation request error.
+ * Failure - NULL Rm_ServiceHandle and result = #RM_ERROR_SERVICE_HANDLE_ALREADY_OPENED
*/
-void Rm_servicePreMainRequest(Rm_PreMainReqCfg *reqCfg, Rm_ServiceRespInfo *preMainResp);
+Rm_ServiceHandle *Rm_serviceOpenHandle(Rm_Handle rmHandle, int32_t *result);
/**
* @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.
+ * This function closes a RM instance's service handle
*
- * @param[in] rmHandle
- * RM instance handle. Used to return a Rm_ServicePort from an RM
- * instance.
+ * @param[in] rmServiceHandle
+ * RM instance service handle to be closed.
*
* @retval
- * Success - RM Service Port. Used by an application or component to
- * request a service from RM.
+ * Success - #RM_OK
* @retval
- * Failure - NULL
+ * Failure - #RM_ERROR_SERVICE_HANDLE_ALREADY_CLOSED
*/
-Rm_ServicePort *Rm_serviceGetPort(Rm_Handle rmHandle);
+int32_t Rm_serviceCloseHandle(Rm_ServiceHandle *rmServiceHandle);
/**
@}
}
#endif
-#endif /* RMSERVICES_H_ */
+#endif /* RM_SERVICES_H_ */