rm_services.h

   1 /**
   2  *   @file  rmservices.h
   3  *
   4  *   @brief
   5  *      This is the RM include file for services provided to components that
   6  *      register a RM instance
   7  *
   8  *  \par
   9  *  ============================================================================
  10  *  @n   (C) Copyright 2012, Texas Instruments, Inc.
  11  *
  12  *  Redistribution and use in source and binary forms, with or without
  13  *  modification, are permitted provided that the following conditions
  14  *  are met:
  15  *
  16  *    Redistributions of source code must retain the above copyright
  17  *    notice, this list of conditions and the following disclaimer.
  18  *
  19  *    Redistributions in binary form must reproduce the above copyright
  20  *    notice, this list of conditions and the following disclaimer in the
  21  *    documentation and/or other materials provided with the
  22  *    distribution.
  23  *
  24  *    Neither the name of Texas Instruments Incorporated nor the names of
  25  *    its contributors may be used to endorse or promote products derived
  26  *    from this software without specific prior written permission.
  27  *
  28  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  29  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  30  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  31  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  32  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  33  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  34  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  35  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  36  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  37  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  38  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  39  *
  40  *  \par
  41 */
  42
  43 #ifndef RMSERVICES_H_
  44 #define RMSERVICES_H_
  45
  46 #ifdef __cplusplus
  47 extern "C" {
  48 #endif
  49
  50 /* RM includes */
  51 #include <ti/drv/rm/rm.h>
  52
  53 /**
  54 @addtogroup RMSERVICES_API
  55 @{
  56 */
  57
  58 /** RM Service Request State Codes and Errors */
  59 /** RM Service Request State Code Base */
  60 #define RM_SERVICE_STATE_BASE (0)
  61 /** RM internal state okay - This value is for internal use by RM.  It should never be
  62  *  seen as a return value during normal operation */
  63 #define RM_SERVICE_STATE_OKAY (RM_SERVICE_STATE_BASE)
  64 /** RM service is being processed.  Typically this means the service is
  65  *  being sent to a higher level RM agent for processing */
  66 #define RM_SERVICE_PROCESSING (RM_SERVICE_STATE_BASE+1)
  67 /** RM service was approved.  The resource data in the response is valid if
  68  *  the service has been approved. */
  69 #define RM_SERVICE_APPROVED_AND_COMPLETED (RM_SERVICE_STATE_BASE+2)
  70 /** Beginning of resource denied reasons */
  71 #define RM_SERVICE_DENIED_BEGIN (RM_SERVICE_STATE_BASE+3)
  72 /** RM could not find an allocator for the resource specified with the provided name */
  73 #define RM_SERVICE_DENIED_RESOURCE_DOES_NOT_EXIST (RM_SERVICE_DENIED_BEGIN)
  74 /** A resource value within the specifed base+range could not be found within the resource's
  75  *  allocator.  No action was taken on the resources. */
  76 #define RM_SERVICE_DENIED_RESOURCE_VALUE_IN_RANGE_DOES_NOT_EXIST (RM_SERVICE_DENIED_BEGIN+1)
  77 /** A resource value within the specifed base+range was not allocated to the RM instance
  78  *  that is the source of the request.  No action was taken on the resources. */
  79 #define RM_SERVICE_DENIED_RESOURCE_NOT_ALLOCATED_TO_INSTANCE_REQUESTING_THE_SERVICE (RM_SERVICE_DENIED_BEGIN+2)
  80 /** A resource value within the specifed base+range is already free */
  81 #define RM_SERVICE_DENIED_RESOURCE_ALREADY_FREE (RM_SERVICE_DENIED_BEGIN+3)
  82 /** A resource value within the specifed base+range is already allocated to another
  83  *  RM instance. */
  84 #define RM_SERVICE_DENIED_RESOURCE_ALREADY_ALLOCATED (RM_SERVICE_DENIED_BEGIN+4)
  85 /** End of resource denied reasons */
  86 #define RM_SERVICE_DENIED_END (RM_SERVICE_DENIED_BEGIN+4)
  87
  88 /** RM Service Request Error Code Base */
  89 #define RM_SERVICE_ERROR_BASE (-64)
  90 /** RM service request type not recognized */
  91 #define RM_SERVICE_ERROR_INVALID_SERVICE_TYPE (RM_SERVICE_ERROR_BASE)
  92 /** RM Service request was not provided a component callback
  93  *  function.  Service requests may result in blocking operations.  A callback
  94  *  function must always be provided with a service request since
  95  *  blocked or non-blocked operations cannot be promised.  */
  96 #define RM_SERVICE_ERROR_CALLBACK_NOT_PROVIDED (RM_SERVICE_ERROR_BASE-1)
  97 /** RM service request needs to be forwarded to another RM agent but no transports
  98  *  have been registered */
  99 #define RM_SERVICE_ERROR_NO_TRANSPORT_REGISTERED (RM_SERVICE_ERROR_BASE-2)
 100 /** RM service request needs to be forwarded but no client delegate or server has
 101  *  been registered with the RM instance */
 102 #define RM_SERVICE_ERROR_NOT_REGISTERED_WITH_DEL_OR_SERVER (RM_SERVICE_ERROR_BASE-3)
 103 /** RM service request needs to be forwarded but the transport packet alloc API
 104  *  has not been provided */
 105 #define RM_SERVICE_ERROR_TRANSPORT_PKT_ALLOC_API_NULL (RM_SERVICE_ERROR_BASE-4)
 106 /** A failure occurred within a registered transport's packet alloc API */
 107 #define RM_SERVICE_ERROR_TRANSPORT_ALLOC_PKT_ERROR (RM_SERVICE_ERROR_BASE-5)
 108 /** RM service request needs to be forwarded but the buffer allocated by transport
 109  *  is not large enough to fit the RM transport packet */
 110 #define RM_SERVICE_ERROR_TRANSPORT_PKT_BUF_TOO_SMALL (RM_SERVICE_ERROR_BASE-6)
 111 /** RM service request needs to be forwarded but the transport returned an error
 112  *  when trying to send the RM packet to the higher level agent */
 113 #define RM_SERVICE_ERROR_TRANPSPORT_SEND_ERROR (RM_SERVICE_ERROR_BASE-7)
 114 /** RM service response from higher level agent did not match any requests made
 115  *  by the provided RM instance */
 116 #define RM_SERVICE_ERROR_TRANSACTION_DOES_NOT_EXST_FOR_THIS_RM_INSTANCE (RM_SERVICE_ERROR_BASE-8)
 117 /** RM failed to allocate memory for new service transaction */
 118 #define RM_SERVICE_ERROR_TRANSACTION_FAILED_TO_ALLOCATE (RM_SERVICE_ERROR_BASE-9)
 119 /** RM could not find the service transaction in the RM instance's transaction queue */
 120 #define RM_SERVICE_ERROR_SERVICE_TRANSACTION_DOES_NOT_EXIST (RM_SERVICE_ERROR_BASE-10)
 121 /** A failure occurred within a registered transport's packet free API */
 122 #define RM_SERVICE_ERROR_TRANSPORT_FREE_PKT_ERROR (RM_SERVICE_ERROR_BASE-11)
 123 /** Invalid NameServer object modification on non-Server instance */
 124 #define RM_SERVICE_ERROR_NAMESERVER_OBJECT_MOD_ON_INVALID_INSTANCE (RM_SERVICE_ERROR_BASE-12)
 125
 126
 127 /**
 128  * @brief Maximum number of characters in the resource names
 129  */
 130 #define RM_RESOURCE_NAME_MAX_CHARS (24)
 131
 132 /**
 133  * @brief RM service types
 134  */
 135 typedef enum {
 136     /** First service type.  Used by RM for bounds checking.  Should
 137      *  not be used by component. */
 138     Rm_service_FIRST = 0,
 139     /** RM resource allocate service */
 140     Rm_service_RESOURCE_ALLOCATE = 0,
 141     /** RM resource block allocate service */
 142     Rm_service_RESOURCE_BLOCK_ALLOCATE = 1,
 143     /** RM resource allocate by name service */
 144     Rm_service_RESOURCE_ALLOCATE_BY_NAME = 2,
 145     /** RM resource free service */
 146     Rm_service_RESOURCE_FREE = 3,
 147     /** RM resource block free service */
 148     Rm_service_RESOURCE_BLOCK_FREE = 4,
 149     /** RM resource free by name service */
 150     Rm_service_RESOURCE_FREE_BY_NAME = 5,
 151     /** RM resource mapping to name service */
 152     Rm_service_RESOURCE_MAP_TO_NAME = 6,
 153     /** RM resource name unmapping service */
 154     Rm_service_RESOURCE_UNMAP_NAME = 7,
 155     /** Last service type.  Used by RM for bounds checking.  Should
 156      *  not be used by component. */
 157     Rm_service_LAST = 7
 158 } Rm_ServiceType;
 159
 160 /**
 161  * @brief RM pre-main allocation request information provided by the pre-main
 162  *        startup function requesting the resource */
 163 typedef struct {
 164     /** Pointer to the requested pre-main allocation resource name.  The
 165      *  name provided by the component must match the resource names
 166      *  provided in the global resource table and allocation policies */
 167     char *resourceName;
 168     /** The pre-main allocation request resource base value.  For example,
 169      *  queue number or semaphore number */
 170     uint32_t resourceBase;
 171     /** Range of resource starting at resourceBase */
 172     uint32_t resourceRange;
 173 } Rm_PreMainAllocInfo;
 174
 175 /**
 176  * @brief RM service response information provided by RM back to the
 177  *        requesting component
 178  */
 179 typedef struct {
 180     /** State of the service request.
 181      *  Non-negative result: RM has taken an action based on the request
 182      *  Negative result: RM has encountered an error handling the request */
 183     int32_t serviceState;
 184     /** A service ID will be returned to the component if the requested service cannot
 185      *  be completed immediately.  The service ID can be used by the component to identify
 186      *  service responses received via the component callback function.  A service ID will not
 187      *  be returned if the service request is satisfied immediately */
 188     uint32_t serviceId;
 189     /** The base value of the returned resource.  In the case of a block resource allocation
 190      *  response this field will contain the base value of the block. */
 191     int32_t resourceBase;
 192     /** The range of resources starting from resourceBase allocated in block requests */
 193     uint32_t resourceRange;
 194 } Rm_ServiceRespInfo;
 195
 196 /**
 197  * @brief RM service callback function structure
 198  */
 199 typedef struct {
 200     /** Component callback function.  RM will call this function when the
 201      *  resource service request is completed. The callback function supplied
 202      *  for this parameter must match this function pointer prototype. */
 203     void (*serviceCallback) (Rm_ServiceRespInfo *serviceResponse);
 204 } Rm_ServiceCallback;
 205
 206 /**
 207  * @brief RM service request information provided by the requesting component
 208  */
 209 typedef struct {
 210     /** The type of RM service requested */
 211     Rm_ServiceType type;
 212     /** Pointer to the name of the resource requested.  The
 213      *  name provided by the component must match the resource node names
 214      *  provided in the global resource table and allocation policies */
 215     char *resourceName;
 216 /** An allocate service can be requested with an unspecified resource base.
 217  *  If this occurs the RM Client Delegate or Server will assign the next available
 218  *  resource or set of resources based on the allocation type. */
 219 #define RM_RESOURCE_BASE_UNSPECIFIED (-1)
 220     /** The resource base value. */
 221     int32_t resourceBase;
 222     /** The range of the specified resource to be allocated starting from
 223      *  resourceBase.  Will be greater than one only for block allocate
 224      *  and free service requests. */
 225     uint32_t resourceRange;
 226 /** An allocate service can be requested with an unspecified resource alignment.
 227  *  WARNING: Only applicapable if resourceBase is unspecified
 228  *
 229  *  If the alignment is unspecified the RM Client Delegate or Server will allocate
 230  *  the resources from a default alignment as specified in the global policy. */
 231 #define RM_RESOURCE_ALIGNMENT_UNSPECIFIED (-1)
 232     /** Resource alignment in block allocation requests */
 233     int32_t resourceAlignment;
 234     /** The name server name associated with the resource.  Used only for
 235      *  allocate and free by name service requests */
 236     char *resourceNsName;
 237     /** Component specified callback function used by RM to inform components
 238      *  of service requst results */
 239     Rm_ServiceCallback callback;
 240 } Rm_ServiceReqInfo;
 241
 242 /**
 243  * @brief RM Service Port provided to software components and applications that
 244  *        request RM services for the resources they wish to use
 245  */
 246 typedef struct {
 247     /** RM instance handle for which the service handle was registered */
 248     void *rmHandle;
 249     /**
 250      *  @b Description
 251      *  @n
 252      *      Callout function used by components to request a resource service
 253      *      from a RM instance
 254      *
 255      *   @param[in] rmHandle
 256      *      RM instance handle specifying the RM instance that should handle the
 257      *      service request
 258      *
 259      *  @param[in]  serviceRequest
 260      *      Service request structure that provides details of the service requested from
 261      *      the RM instance tied to this component
 262      *
 263      *  @param[in]  serviceResponse
 264      *      Service response structure that provides details of RM's response to the
 265      *      service request
 266      */
 267     void (*rmService)(void *rmHandle, Rm_ServiceReqInfo *serviceRequest,
 268                       Rm_ServiceRespInfo *serviceResponse);
 269 } Rm_ServicePort;
 270
 271 /**
 272  *  @b Description
 273  *  @n
 274  *      Non-blocking function used by RTSC pre-main startup functions to
 275  *      allocate RM resources for usage.  Pre-main allocated resources will be
 276  *      validated by RM against a memory-mapped startup resource policy.
 277  *      Pre-main allocation of unauthorized resources will result in a system
 278  *      exception.
 279  *
 280  *      Note: Resource pre-main allocations can only occur on a core that is
 281  *            running a RM Server or Client Delegate that has a startup policy
 282  *            allowing the allocation of pre-main resources
 283  *
 284  *  @param[in]  preMainAllocInfo
 285  *      Resource pre-main allocation structure that provides details of the
 286  *      resource requested from RM for preallocation
 287  *
 288  *  @param[out] serviceResponse
 289  *      Contains the result information regarding the pre-main allocation request
 290  *
 291  *  @retval
 292  *      Success - 0 - Resource pre-main allocation request okay.
 293  *  @retval
 294  *      Failure - non-zero - Resource pre-main allocation request error.
 295  */
 296 void Rm_preMainAllocService (Rm_PreMainAllocInfo *preMainAllocInfo,
 297                              Rm_ServiceRespInfo *serviceResponse);
 298
 299 /**
 300  *  @b Description
 301  *  @n
 302  *      This function returns a RM service port to the application to
 303  *      provide to software components (LLDs, BIOS, etc) that want to use RM
 304  *      for resource management.
 305  *
 306  *  @param[in]  rmHandle
 307  *      RM instance handle.  Used to return a Rm_ServicePort from an RM
 308  *      instance.
 309  *
 310  *  @retval
 311  *      Success - RM Service Port.  Used by an application or component to
 312  *                request a service from RM.
 313  *  @retval
 314  *      Failure - NULL
 315  */
 316 Rm_ServicePort *Rm_getServicePort(Rm_Handle rmHandle);
 317
 318 /**
 319 @}
 320 */
 321
 322 #ifdef __cplusplus
 323 }
 324 #endif
 325
 326 #endif /* RMSERVICES_H_ */
 327