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-2013, 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 mapping to name service */
  69     Rm_service_RESOURCE_MAP_TO_NAME,
  70     /** RM resource get by name service */
  71     Rm_service_RESOURCE_GET_BY_NAME,
  72     /** RM resource name unmapping service */
  73     Rm_service_RESOURCE_UNMAP_NAME,
  74     /** DO NOT USE: Last type */
  75     Rm_service_LAST
  76 } Rm_ServiceType;
  77
  78 /**
  79  * @brief RM service response information provided by RM back to the
  80  *        requesting component
  81  */
  82 typedef struct {
  83     /** State of the service request.
  84      *  Non-negative result: RM has taken an action based on the request
  85      *  Negative result: RM has encountered an error handling the request */
  86     int32_t serviceState;
  87     /** A service ID will be returned to the component if the requested service cannot
  88      *  be completed immediately.  The service ID can be used by the component to identify
  89      *  service responses received via the component callback function.  A service ID will not
  90      *  be returned if the service request is satisfied immediately */
  91     uint32_t serviceId;
  92     /** The name of the resource affected by the service request */
  93     char resourceName[RM_NAME_MAX_CHARS];
  94     /** The base value of the returned resource.  In the case of a block resource allocation
  95      *  response this field will contain the base value of the block. */
  96     int32_t resourceBase;
  97     /** The number of resources starting from resourceBase allocated in block requests */
  98     uint32_t resourceLength;
  99 } Rm_ServiceRespInfo;
 100
 101 /**
 102  * @brief RM service callback function structure
 103  */
 104 typedef struct {
 105     /** Component callback function.  RM will call this function when the
 106      *  resource service request is completed. The callback function supplied
 107      *  for this parameter must match this function pointer prototype. */
 108     void (*serviceCallback) (Rm_ServiceRespInfo *serviceResponse);
 109 } Rm_ServiceCallback;
 110
 111 /**
 112  * @brief RM service request information provided by the requesting component
 113  */
 114 typedef struct {
 115     /** The type of RM service requested */
 116     Rm_ServiceType type;
 117     /** Pointer to the name of the resource requested.  The
 118      *  name provided by the component must match the resource node names
 119      *  provided in the global resource table and allocation policies */
 120     char *resourceName;
 121 /** An allocate service can be requested with an unspecified resource base.
 122  *  If this occurs the RM Client Delegate or Server will assign the next available
 123  *  resource or set of resources based on the allocation type. */
 124 #define RM_RESOURCE_BASE_UNSPECIFIED (-1)
 125     /** The resource base value. */
 126     int32_t resourceBase;
 127     /** The number of the specified resource to be allocated starting from
 128      *  resourceBase.  Will be greater than one only for block allocate
 129      *  and free service requests. */
 130     uint32_t resourceLength;
 131 /** An allocate service can be requested with an unspecified resource alignment.
 132  *  WARNING: Only applicapable if resourceBase is unspecified
 133  *
 134  *  If the alignment is unspecified the RM Client Delegate or Server will allocate
 135  *  the resources from a default alignment as specified in the global policy. */
 136 #define RM_RESOURCE_ALIGNMENT_UNSPECIFIED (-1)
 137     /** Resource alignment in block allocation requests */
 138     int32_t resourceAlignment;
 139     /** The name server name associated with the resource.  Used only for
 140      *  allocate and free by name service requests */
 141     char *resourceNsName;
 142     /** Component specified callback function used by RM to inform components
 143      *  of service requst results */
 144     Rm_ServiceCallback callback;
 145 } Rm_ServiceReqInfo;
 146
 147 /**
 148  * @brief RM Service Handle provided to software components and applications that
 149  *        request RM services for the resources they wish to use
 150  */
 151 typedef struct {
 152     /** RM instance handle for which the service handle was registered */
 153     void *rmHandle;
 154     /**
 155      *  @b Description
 156      *  @n
 157      *      Callout function used by components to request a resource service
 158      *      from a RM instance
 159      *
 160      *   @param[in] rmHandle
 161      *      RM instance handle specifying the RM instance that should handle the
 162      *      service request
 163      *
 164      *  @param[in]  serviceRequest
 165      *      Service request structure that provides details of the service requested from
 166      *      the RM instance tied to this component
 167      *
 168      *  @param[in]  serviceResponse
 169      *      Service response structure that provides details of RM's response to the
 170      *      service request
 171      */
 172     void (*Rm_serviceHandler)(void *rmHandle, Rm_ServiceReqInfo *serviceRequest,
 173                               Rm_ServiceRespInfo *serviceResponse);
 174 } Rm_ServiceHandle;
 175
 176 /**
 177  *  @b Description
 178  *  @n
 179  *      This function returns a RM service handle to the application to
 180  *      provide services to software components (LLDs, BIOS, etc) that want to use RM
 181  *      for resource management.
 182  *
 183  *  @param[in]  rmHandle
 184  *      RM instance handle.  Used to return a Rm_ServicePort from an RM
 185  *      instance.
 186  *
 187  *  @retval
 188  *      Success - RM Service Handle.  Used by an application or component to
 189  *                request a service from RM.
 190  *  @retval
 191  *      Failure - NULL
 192  */
 193 Rm_ServiceHandle *Rm_serviceOpenHandle(Rm_Handle rmHandle, int32_t *result);
 194
 195 /**
 196  *  @b Description
 197  *  @n
 198  *      This function closes a RM instance's service handle
 199  *
 200  *  @param[in]  rmServiceHandle
 201  *      RM instance service handle to be closed.
 202  */
 203 int32_t Rm_serviceCloseHandle(Rm_ServiceHandle *rmServiceHandle);
 204
 205 /**
 206 @}
 207 */
 208
 209 #ifdef __cplusplus
 210 }
 211 #endif
 212
 213 #endif /* RM_SERVICES_H_ */
 214