rm_services.h

   1 /**
   2  *   @file  rm_services.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-2015, 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 RM_SERVICES_H_
  44 #define RM_SERVICES_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 RM_SERVICES_API
  55 @{
  56 */
  57
  58 /**
  59  * @brief RM service types
  60  */
  61 typedef enum {
  62     /** RM resource allocate for initialization service */
  63     Rm_service_RESOURCE_ALLOCATE_INIT = 0,
  64     /** RM resource allocate for use service */
  65     Rm_service_RESOURCE_ALLOCATE_USE,
  66     /** RM resource free service */
  67     Rm_service_RESOURCE_FREE,
  68     /** RM resource status service - returns the reference count for specified
  69      *  resource. */
  70     Rm_service_RESOURCE_STATUS,
  71     /** RM NameServer map resource to name service */
  72     Rm_service_RESOURCE_MAP_TO_NAME,
  73     /** RM NameServer get resource by name service */
  74     Rm_service_RESOURCE_GET_BY_NAME,
  75     /** RM NameServer unmap resource from name service */
  76     Rm_service_RESOURCE_UNMAP_NAME,
  77     /** DO NOT USE: Last type */
  78     Rm_service_LAST
  79 } Rm_ServiceType;
  80
  81 /**
  82  * @brief RM service response information used by RM to provide service
  83  *        request results back to the application components
  84  */
  85 typedef struct {
  86     /** RM instance handle from which the service request that spawned this
  87      *  result originated.  Used by application to sort responses, received
  88      *  via callback function, from RM instances located on the same core. */
  89     Rm_Handle rmHandle;
  90     /** Service request state.  State values can be found in rm.h starting
  91      *  with #RM_SERVICE_PROCESSING, #RM_SERVICE_DENIED_BASE, and
  92      *  #RM_ERROR_LIBFDT_START */
  93     int32_t   serviceState;
  94     /** The service ID is returned to the application in order to match service
  95      *  responses received at a later time via the provided callback function
  96      *  because RM required a blocking operation in order to satisfy the
  97      *  resource request. <br> <br> The service ID will never have a value of
  98      *  zero. */
  99     uint32_t  serviceId;
 100     /** Affected resource name */
 101     char      resourceName[RM_NAME_MAX_CHARS];
 102     /** The resource base value allocated, freed, or mapped to NameServer
 103      *  name. */
 104     int32_t   resourceBase;
 105     /** The resource length starting at base allocated, freed, or mapped to
 106      *  NameServer name. */
 107     uint32_t  resourceLength;
 108 /** resourceNumOwners is not valid unless >= 0 */
 109 #define RM_RESOURCE_NUM_OWNERS_INVALID (-1)
 110     /** Current number of owners for the returned resource.  A value greater
 111      *  than one means the resource is being shared.  This value is only valid
 112      *  if the serviceState is RM_SERVICE_APPROVED or
 113      *  RM_SERVICE_APPROVED_STATIC. */
 114     int32_t   resourceNumOwners;
 115 /** instAllocCount is not valid unless >= 0 */
 116 #define RM_INST_ALLOC_COUNT_INVALID    (-1)
 117     /** Number of times the requesting instance has allocated the returned
 118      *  resource.  This value is only valid if the serviceState is
 119      *  RM_SERVICE_APPROVED or RM_SERVICE_APPROVED_STATIC */
 120     int32_t   instAllocCount;
 121 } Rm_ServiceRespInfo;
 122
 123 /**
 124  * @brief RM service callback function
 125  */
 126 typedef struct {
 127     /** Component callback function.  RM calls this function when a blocking
 128      *  resource service request is complete. The callback function supplied
 129      *  for this parameter must match the function pointer prototype. */
 130     void (*serviceCallback) (Rm_ServiceRespInfo *serviceResponse);
 131 } Rm_ServiceCallback;
 132
 133 /**
 134  * @brief RM service request information
 135  */
 136 typedef struct {
 137     /** The type of service requested */
 138     Rm_ServiceType      type;
 139     /** Pointer to an array containing the resource name affected by
 140      *  the request.  The resource name must match a resource node name
 141      *  defined in the GRL and global/static policy.  The request will be
 142      *  denied if the resource name does not match any resource node names
 143      *  in the policy */
 144     const char         *resourceName;
 145 /** Informs RM to find the next available resource block of length
 146  *  resourceLength and alignment resourceAlignment for allocation.  This
 147  *  parameter is only valid for resource allocate service types. */
 148 #define RM_RESOURCE_BASE_UNSPECIFIED (-1)
 149     /** The base value of the resource affected by the service request.
 150      *  #RM_RESOURCE_BASE_UNSPECIFIED can be substituted. */
 151     int32_t             resourceBase;
 152     /** The resource length, starting from #resourceBase affected by the
 153      *  service request. */
 154     uint32_t            resourceLength;
 155 /** Informs RM to find the next available resource block with length
 156  *  resourceLength and the alignment specified in
 157  *  a) The resource node in the policy if it has the "allocation-alignment"
 158  *     property defined.
 159  *  b) The default alignment of 1 if no alignment is specified in the policy
 160  *     for the resource.
 161  *  This value is only valid if resourceBase is set to
 162  *  #RM_RESOURCE_BASE_UNSPECIFIED */
 163 #define RM_RESOURCE_ALIGNMENT_UNSPECIFIED (-1)
 164     /** Alignment of the resource affected by the service request.  Only valid
 165      *  if resourceBase is set to #RM_RESOURCE_BASE_UNSPECIFIED.
 166      *  #RM_RESOURCE_ALIGNMENT_UNSPECIFIED can be substituted. */
 167     int32_t             resourceAlignment;
 168     /** The NameServer name associated, or to be associated, with a resource.
 169      *  The NameServer name has precedence over #resourceBase and
 170      *  #resourceLength for all resource modification service types as well as
 171      *  #Rm_service_RESOURCE_GET_BY_NAME.  If the NameServer name and the base
 172      *  and length are not NULL the resource information retrieved from the
 173      *  NameServer entry for the name will replace the values present in
 174      *  #resourceBase and #resourceLength */
 175     const char         *resourceNsName;
 176     /** Callback function used by RM to provide responses back to application
 177      *  components after a service request resulted in a blocking operation.
 178      *  If no callback function is provided the RM instance will block until
 179      *  the service response is ready. */
 180     Rm_ServiceCallback  callback;
 181 } Rm_ServiceReqInfo;
 182
 183 /**
 184  * @brief RM service handle provided to application components for requesting
 185  *        services
 186  */
 187 typedef struct {
 188     /** RM instance handle from which the service handle was allocated from. */
 189     void *rmHandle;
 190     /**
 191      *  @b Description
 192      *  @n
 193      *      Processes service requests from application components.  Responses
 194      *      are returned immediately if the service request could be satisfied
 195      *      without blocking.  If the service request requires a blocking
 196      *      operation, such as forwarding the service request to another
 197      *      instance for validation, the response will be received via the
 198      *      Rm_ServerCallback
 199      *
 200      *   @param[in] rmHandle
 201      *      RM instance handle specifies the instance that handles the service
 202      *      request.  The request's result, if policy checks are involved, will
 203      *      be based on the permissions assigned to the rmHandle's instance
 204      *      name within global/static policy.
 205      *
 206      *  @param[in]  serviceRequest
 207      *      Pointer to the service request structure
 208      *
 209      *  @param[out]  serviceResponse
 210      *      Pointer to a service response structure.
 211      */
 212     void (*Rm_serviceHandler)(void *rmHandle,
 213                               const Rm_ServiceReqInfo *serviceRequest,
 214                               Rm_ServiceRespInfo *serviceResponse);
 215 } Rm_ServiceHandle;
 216
 217 /**
 218  *  @b Description
 219  *  @n
 220  *      This function returns a RM service handle to the application to
 221  *      provide services to software components (LLDs, BIOS, etc) that want to
 222  *      use RM for resource management. Only one service handle can be opened
 223  *      from each RM instance.
 224  *
 225  *  @param[in]  rmHandle
 226  *      RM instance handle from which the service handle will be opened
 227  *
 228  *  @param[out] result
 229  *      Pointer to a signed int used to return any errors encountered during
 230  *      the instance initialization process.
 231  *
 232  *  @retval
 233  *      Success - Rm_ServiceHandle and result = #RM_OK
 234  *  @retval
 235  *      Failure - NULL Rm_ServiceHandle and
 236  *                result = #RM_ERROR_SERVICE_HANDLE_MEM_ALLOC_FAILED
 237  */
 238 Rm_ServiceHandle *Rm_serviceOpenHandle(Rm_Handle rmHandle, int32_t *result);
 239
 240 /**
 241  *  @b Description
 242  *  @n
 243  *      This function closes a RM instance's service handle
 244  *
 245  *  @param[in]  rmServiceHandle
 246  *      RM instance service handle to be closed.
 247  *
 248  *  @retval
 249  *      Success - #RM_OK
 250  *  @retval
 251  *      Failure - #RM_ERROR_SERVICE_HANDLE_ALREADY_CLOSED
 252  */
 253 int32_t Rm_serviceCloseHandle(Rm_ServiceHandle *rmServiceHandle);
 254
 255 /**
 256 @}
 257 */
 258
 259 #ifdef __cplusplus
 260 }
 261 #endif
 262
 263 #endif /* RM_SERVICES_H_ */
 264