Increased number of infra Qs used by Kernel on K2l for UDMA
[keystone-rtos/rm-lld.git] / 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 */
43 #ifndef RM_SERVICES_H_
44 #define RM_SERVICES_H_
46 #ifdef __cplusplus
47 extern "C" {
48 #endif
50 /* RM includes */
51 #include <ti/drv/rm/rm.h>
53 /**
54 @addtogroup RM_SERVICES_API
55 @{
56 */
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;
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 name. */
103     int32_t   resourceBase;
104     /** The resource length starting at base allocated, freed, or mapped to
105      *  NameServer name. */
106     uint32_t  resourceLength;
107 /** resourceNumOwners is not valid unless >= 0 */
108 #define RM_RESOURCE_NUM_OWNERS_INVALID (-1)      
109     /** Current number of owners for the returned resource.  A value greater
110      *  than one means the resource is being shared.  This value is only valid
111      *  if the serviceState is RM_SERVICE_APPROVED or RM_SERVICE_APPROVED_STATIC. */
112     int32_t   resourceNumOwners;
113 /** instAllocCount is not valid unless >= 0 */
114 #define RM_INST_ALLOC_COUNT_INVALID (-1) 
115     /** Number of times the requesting instance has allocated the returned resource.
116      *  This value is only valid if the serviceState is RM_SERVICE_APPROVED or
117      *  RM_SERVICE_APPROVED_STATIC */
118     int32_t   instAllocCount;
119 } Rm_ServiceRespInfo;
121 /** 
122  * @brief RM service callback function
123  */
124 typedef struct {
125     /** Component callback function.  RM calls this function when a blocking 
126      *  resource service request is complete. The callback function supplied
127      *  for this parameter must match the function pointer prototype. */
128     void (*serviceCallback) (Rm_ServiceRespInfo *serviceResponse);
129 } Rm_ServiceCallback;
131 /** 
132  * @brief RM service request information
133  */
134 typedef struct {
135     /** The type of service requested */
136     Rm_ServiceType      type;
137     /** Pointer to an array containing the resource name affected by
138      *  the request.  The resource name must match a resource node name
139      *  defined in the GRL and global/static policy.  The request will be
140      *  denied if the resource name does not match any resource node names
141      *  in the policy */
142     const char         *resourceName;
143 /** Informs RM to find the next available resource block of length
144  *  resourceLength and alignment resourceAlignment for allocation.  This
145  *  parameter is only valid for resource allocate service types. */
146 #define RM_RESOURCE_BASE_UNSPECIFIED (-1)  
147     /** The base value of the resource affected by the service request.
148      *  #RM_RESOURCE_BASE_UNSPECIFIED can be substituted. */
149     int32_t             resourceBase;
150     /** The resource length, starting from #resourceBase affected by the
151      *  service request. */
152     uint32_t            resourceLength;
153 /** Informs RM to find the next available resource block with length
154  *  resourceLength and the alignment specified in 
155  *  a) The resource node in the policy if it has the "allocation-alignment"
156  *     property defined.
157  *  b) The default alignment of 1 if no alignment is specified in the policy
158  *     for the resource.
159  *  This value is only valid if resourceBase is set to #RM_RESOURCE_BASE_UNSPECIFIED */
160 #define RM_RESOURCE_ALIGNMENT_UNSPECIFIED (-1)      
161     /** Alignment of the resource affected by the service request.  Only valid
162      *  if resourceBase is set to #RM_RESOURCE_BASE_UNSPECIFIED.
163      *  #RM_RESOURCE_ALIGNMENT_UNSPECIFIED can be substituted. */
164     int32_t             resourceAlignment;
165     /** The NameServer name associated, or to be associated, with a resource. 
166      *  The NameServer name has precedence over #resourceBase and #resourceLength
167      *  for all resource modification service types as well as
168      *  #Rm_service_RESOURCE_GET_BY_NAME.  If the NameServer name and the base
169      *  and length are not NULL the resource information retrieved from the
170      *  NameServer entry for the name will replace the values present in
171      *  #resourceBase and #resourceLength */
172     const char         *resourceNsName;
173     /** Callback function used by RM to provide responses back to application
174      *  components after a service request resulted in a blocking operation.
175      *  If no callback function is provided the RM instance will block until
176      *  the service response is ready. */
177     Rm_ServiceCallback  callback;
178 } Rm_ServiceReqInfo;
180 /** 
181  * @brief RM service handle provided to application components for requesting
182  *        services
183  */
184 typedef struct {
185     /** RM instance handle from which the service handle was allocated from. */
186     void *rmHandle;
187     /**
188      *  @b Description
189      *  @n  
190      *      Processes service requests from application components.  Responses
191      *      are returned immediately if the service request could be satisfied 
192      *      without blocking.  If the service request requires a blocking operation,
193      *      such as forwarding the service request to another instance for
194      *      validation, the response will be received via the Rm_ServerCallback
195      *
196      *   @param[in] rmHandle
197      *      RM instance handle specifies the instance that handles the service
198      *      request.  The request's result, if policy checks are involved, will be
199      *      based on the permissions assigned to the rmHandle's instance name within
200      *      global/static policy.
201      *  
202      *  @param[in]  serviceRequest
203      *      Pointer to the service request structure
204      *
205      *  @param[out]  serviceResponse
206      *      Pointer to a service response structure.
207      */
208     void (*Rm_serviceHandler)(void *rmHandle, const Rm_ServiceReqInfo *serviceRequest,
209                               Rm_ServiceRespInfo *serviceResponse);
210 } Rm_ServiceHandle;
212 /**
213  *  @b Description
214  *  @n  
215  *      This function returns a RM service handle to the application to 
216  *      provide services to software components (LLDs, BIOS, etc) that want to use RM
217  *      for resource management. Only one service handle can be opened from
218  *      each RM instance.
219  *
220  *  @param[in]  rmHandle
221  *      RM instance handle from which the service handle will be opened
222  *
223  *  @param[out] result
224  *      Pointer to a signed int used to return any errors encountered during
225  *      the instance initialization process.
226  *
227  *  @retval
228  *      Success - Rm_ServiceHandle and result = #RM_OK
229  *  @retval
230  *      Failure - NULL Rm_ServiceHandle and result = #RM_ERROR_SERVICE_HANDLE_MEM_ALLOC_FAILED
231  */
232 Rm_ServiceHandle *Rm_serviceOpenHandle(Rm_Handle rmHandle, int32_t *result);
234 /**
235  *  @b Description
236  *  @n  
237  *      This function closes a RM instance's service handle
238  *
239  *  @param[in]  rmServiceHandle
240  *      RM instance service handle to be closed.
241  *
242  *  @retval
243  *      Success - #RM_OK
244  *  @retval
245  *      Failure - #RM_ERROR_SERVICE_HANDLE_ALREADY_CLOSED
246  */
247 int32_t Rm_serviceCloseHandle(Rm_ServiceHandle *rmServiceHandle);
249 /** 
250 @} 
251 */
253 #ifdef __cplusplus
255 #endif
257 #endif /* RM_SERVICES_H_ */