5b2a2d9c0f048a28ce8099d048687327de8b6869
[keystone-rtos/rm-lld.git] / 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 */
43 #ifndef RMSERVICES_H_
44 #define RMSERVICES_H_
46 #ifdef __cplusplus
47 extern "C" {
48 #endif
50 /* RM includes */
51 #include <ti/drv/rm/rm.h>
53 /**
54 @addtogroup RMSERVICES_API
55 @{
56 */
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_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)
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 /** Request failed because both a NameServer name and a resource range were specified */
126 #define RM_SERVICE_ERROR_NAMESERVER_NAME_AND_RESOURCE_RANGE_BOTH_DEFINED (RM_SERVICE_ERROR_BASE-13)
128 /**
129  * @brief Maximum number of characters in the resource names
130  */
131 #define RM_RESOURCE_NAME_MAX_CHARS (24)
133 /** 
134  * @brief RM service types
135  */
136 typedef enum {
137     /** First service type.  Used by RM for bounds checking.  Should
138      *  not be used by component. */
139     Rm_service_FIRST = 0,
140     /** RM resource allocate service */
141     Rm_service_RESOURCE_ALLOCATE = 0,  
142     /** RM resource free service */
143     Rm_service_RESOURCE_FREE = 1,
144     /** RM resource mapping to name service */
145     Rm_service_RESOURCE_MAP_TO_NAME = 2,
146     /** RM resource get by name service */
147     Rm_service_RESOURCE_GET_BY_NAME = 3,
148     /** RM resource name unmapping service */
149     Rm_service_RESOURCE_UNMAP_NAME = 4,
150     /** Last service type.  Used by RM for bounds checking.  Should
151      *  not be used by component. */
152     Rm_service_LAST = 4
153 } Rm_ServiceType;
155 /** 
156  * @brief RM pre-main allocation request information provided by the pre-main 
157  *        startup function requesting the resource */
158 typedef struct {
159     /** Pointer to the requested pre-main allocation resource name.  The 
160      *  name provided by the component must match the resource names
161      *  provided in the global resource table and allocation policies */
162     char *resourceName;
163     /** The pre-main allocation request resource base value.  For example, 
164      *  queue number or semaphore number */
165     uint32_t resourceBase;
166     /** Range of resource starting at resourceBase */
167     uint32_t resourceRange;
168 } Rm_PreMainAllocInfo;
170 /** 
171  * @brief RM service response information provided by RM back to the 
172  *        requesting component
173  */
174 typedef struct {
175     /** State of the service request.
176      *  Non-negative result: RM has taken an action based on the request
177      *  Negative result: RM has encountered an error handling the request */
178     int32_t serviceState;
179     /** A service ID will be returned to the component if the requested service cannot
180      *  be completed immediately.  The service ID can be used by the component to identify
181      *  service responses received via the component callback function.  A service ID will not
182      *  be returned if the service request is satisfied immediately */
183     uint32_t serviceId;
184     /** The base value of the returned resource.  In the case of a block resource allocation 
185      *  response this field will contain the base value of the block. */
186     int32_t resourceBase;
187     /** The number of resources starting from resourceBase allocated in block requests */
188     uint32_t resourceLength;
189 } Rm_ServiceRespInfo;
191 /** 
192  * @brief RM service callback function structure
193  */
194 typedef struct {
195     /** Component callback function.  RM will call this function when the 
196      *  resource service request is completed. The callback function supplied
197      *  for this parameter must match this function pointer prototype. */
198     void (*serviceCallback) (Rm_ServiceRespInfo *serviceResponse);
199 } Rm_ServiceCallback;
201 /** 
202  * @brief RM service request information provided by the requesting component
203  */
204 typedef struct {
205     /** The type of RM service requested */
206     Rm_ServiceType type;
207     /** Pointer to the name of the resource requested.  The 
208      *  name provided by the component must match the resource node names
209      *  provided in the global resource table and allocation policies */
210     char *resourceName;
211 /** An allocate service can be requested with an unspecified resource base. 
212  *  If this occurs the RM Client Delegate or Server will assign the next available
213  *  resource or set of resources based on the allocation type. */
214 #define RM_RESOURCE_BASE_UNSPECIFIED (-1)  
215     /** The resource base value. */
216     int32_t resourceBase;
217     /** The number of the specified resource to be allocated starting from 
218      *  resourceBase.  Will be greater than one only for block allocate
219      *  and free service requests. */
220     uint32_t resourceLength;
221 /** An allocate service can be requested with an unspecified resource alignment.
222  *  WARNING: Only applicapable if resourceBase is unspecified
223  *
224  *  If the alignment is unspecified the RM Client Delegate or Server will allocate
225  *  the resources from a default alignment as specified in the global policy. */
226 #define RM_RESOURCE_ALIGNMENT_UNSPECIFIED (-1)      
227     /** Resource alignment in block allocation requests */
228     int32_t resourceAlignment;
229     /** The name server name associated with the resource.  Used only for 
230      *  allocate and free by name service requests */
231     char *resourceNsName;
232     /** Component specified callback function used by RM to inform components
233      *  of service requst results */
234     Rm_ServiceCallback callback;
235 } Rm_ServiceReqInfo;
237 /** 
238  * @brief RM Service Port provided to software components and applications that 
239  *        request RM services for the resources they wish to use
240  */
241 typedef struct {
242     /** RM instance handle for which the service handle was registered */
243     void *rmHandle;
244     /**
245      *  @b Description
246      *  @n  
247      *      Callout function used by components to request a resource service 
248      *      from a RM instance
249      *
250      *   @param[in] rmHandle
251      *      RM instance handle specifying the RM instance that should handle the
252      *      service request
253      *  
254      *  @param[in]  serviceRequest
255      *      Service request structure that provides details of the service requested from
256      *      the RM instance tied to this component
257      *
258      *  @param[in]  serviceResponse
259      *      Service response structure that provides details of RM's response to the
260      *      service request
261      */
262     void (*rmService)(void *rmHandle, Rm_ServiceReqInfo *serviceRequest,
263                       Rm_ServiceRespInfo *serviceResponse);
264 } Rm_ServicePort;
266 /**
267  *  @b Description
268  *  @n  
269  *      Non-blocking function used by RTSC pre-main startup functions to
270  *      allocate RM resources for usage.  Pre-main allocated resources will be 
271  *      validated by RM against a memory-mapped startup resource policy.
272  *      Pre-main allocation of unauthorized resources will result in a system
273  *      exception.
274  *
275  *      Note: Resource pre-main allocations can only occur on a core that is 
276  *            running a RM Server or Client Delegate that has a startup policy
277  *            allowing the allocation of pre-main resources
278  *
279  *  @param[in]  preMainAllocInfo
280  *      Resource pre-main allocation structure that provides details of the 
281  *      resource requested from RM for preallocation
282  *
283  *  @param[out] serviceResponse
284  *      Contains the result information regarding the pre-main allocation request
285  *
286  *  @retval
287  *      Success - 0 - Resource pre-main allocation request okay.
288  *  @retval
289  *      Failure - non-zero - Resource pre-main allocation request error.
290  */
291 void Rm_preMainAllocService (Rm_PreMainAllocInfo *preMainAllocInfo,
292                              Rm_ServiceRespInfo *serviceResponse);
294 /**
295  *  @b Description
296  *  @n  
297  *      This function returns a RM service port to the application to 
298  *      provide to software components (LLDs, BIOS, etc) that want to use RM
299  *      for resource management.
300  *
301  *  @param[in]  rmHandle
302  *      RM instance handle.  Used to return a Rm_ServicePort from an RM
303  *      instance.
304  *
305  *  @retval
306  *      Success - RM Service Port.  Used by an application or component to
307  *                request a service from RM.
308  *  @retval
309  *      Failure - NULL
310  */
311 Rm_ServicePort *Rm_getServicePort(Rm_Handle rmHandle);
313 /** 
314 @} 
315 */
317 #ifdef __cplusplus
319 #endif
321 #endif /* RMSERVICES_H_ */