abdf555128db250c50bd72aa4d3e0406596196cf
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 /** The resource range specified for freeing included free and allocated resoruces. */
86 #define RM_SERVICE_DENIED_INVALID_RESOURCE_RANGE (RM_SERVICE_DENIED_BEGIN+5)
87 /** No free resource ranges could be found that satisfy the resource base, length, and
88 * alignment requirements */
89 #define RM_SERVICE_DENIED_RESOURCE_ALLOCATION_REQUIREMENTS_COULD_NOT_BE_SATISFIED (RM_SERVICE_DENIED_BEGIN+6)
90 /** The RM instance requesting the service is not defined in the policy */
91 #define RM_SERVICE_DENIED_RM_INST_NOT_DEFINED_IN_POLICY (RM_SERVICE_DENIED_BEGIN+7)
92 /** The resource in the service request is not defined in the policy */
93 #define RM_SERVICE_DENIED_RESOURCE_NOT_DEFINED_IN_POLICY (RM_SERVICE_DENIED_BEGIN+8)
94 /** The resource has multiple assigned range definitions */
95 #define RM_SERVICE_DENIED_ASSIGNED_RANGE_SPECIFICATION_ERROR (RM_SERVICE_DENIED_BEGIN+9)
96 /** The resource has multiple allocation size definitions */
97 #define RM_SERVICE_DENIED_ALLOCATION_SIZE_SPECIFICATION_ERROR (RM_SERVICE_DENIED_BEGIN+10)
98 /** The resource has multiple assigned name definitions */
99 #define RM_SERVICE_DENIED_ASSIGNED_NAME_SPECIFICATION_ERROR (RM_SERVICE_DENIED_BEGIN+11)
100 /** The resource has multiple allocation alignment definitions */
101 #define RM_SERVICE_DENIED_ALLOCATION_ALIGNMENT_SPECIFICATION_ERROR (RM_SERVICE_DENIED_BEGIN+12)
102 /** The resource node in the policy has an unknown property type */
103 #define RM_SERVICE_DENIED_UNKNOWN_POLICY_PROPERTY (RM_SERVICE_DENIED_BEGIN+13)
104 /** The policy does not approve of the resources requested by the RM instance in the service
105 * request */
106 #define RM_SERVICE_DENIED_POLICY_DENIAL (RM_SERVICE_DENIED_BEGIN+14)
107 /** Attempt to add object to NameServer denied: The object name already exists in the NameServer */
108 #define RM_SERVICE_DENIED_NAMESERVER_ERROR_NAME_ALREADY_EXISTS (RM_SERVICE_DENIED_BEGIN+15)
109 /** No valid ranges were specified for the resource within the RM instance's node within the policy.
110 * By default all resource requests for this resource are denied */
111 #define RM_SERVICE_DENIED_POLICY_DENIAL_NO_RANGES_SPECIFIED (RM_SERVICE_DENIED_BEGIN+16)
112 /** The instance name of the service requesting instance is not in the policy valid instance list */
113 #define RM_SERVICE_DENIED_ORIGINATING_INSTANCE_NAME_NOT_VALID (RM_SERVICE_DENIED_BEGIN+17)
114 /** End of resource denied reasons */
115 #define RM_SERVICE_DENIED_END (RM_SERVICE_DENIED_BEGIN+17)
117 /** RM Service Request Error Code Base */
118 #define RM_SERVICE_ERROR_BASE (-64)
119 /** RM service request type not recognized */
120 #define RM_SERVICE_ERROR_INVALID_SERVICE_TYPE (RM_SERVICE_ERROR_BASE)
121 /** RM Service request was not provided a component callback
122 * function. Service requests may result in blocking operations. A callback
123 * function must always be provided with a service request since
124 * blocked or non-blocked operations cannot be promised. */
125 #define RM_SERVICE_ERROR_CALLBACK_NOT_PROVIDED (RM_SERVICE_ERROR_BASE-1)
126 /** RM service request needs to be forwarded to another RM agent but no transports
127 * have been registered */
128 #define RM_SERVICE_ERROR_NO_TRANSPORT_REGISTERED (RM_SERVICE_ERROR_BASE-2)
129 /** RM service request needs to be forwarded but no client delegate or server has
130 * been registered with the RM instance */
131 #define RM_SERVICE_ERROR_NOT_REGISTERED_WITH_DEL_OR_SERVER (RM_SERVICE_ERROR_BASE-3)
132 /** RM service request needs to be forwarded but the transport packet alloc API
133 * has not been provided */
134 #define RM_SERVICE_ERROR_TRANSPORT_PKT_ALLOC_API_NULL (RM_SERVICE_ERROR_BASE-4)
135 /** A failure occurred within a registered transport's packet alloc API */
136 #define RM_SERVICE_ERROR_TRANSPORT_ALLOC_PKT_ERROR (RM_SERVICE_ERROR_BASE-5)
137 /** RM service request needs to be forwarded but the buffer allocated by transport
138 * is not large enough to fit the RM transport packet */
139 #define RM_SERVICE_ERROR_TRANSPORT_PKT_BUF_TOO_SMALL (RM_SERVICE_ERROR_BASE-6)
140 /** RM service request needs to be forwarded but the transport returned an error
141 * when trying to send the RM packet to the higher level agent */
142 #define RM_SERVICE_ERROR_TRANPSPORT_SEND_ERROR (RM_SERVICE_ERROR_BASE-7)
143 /** RM service response from higher level agent did not match any requests made
144 * by the provided RM instance */
145 #define RM_SERVICE_ERROR_TRANSACTION_DOES_NOT_EXIST_FOR_THIS_RM_INSTANCE (RM_SERVICE_ERROR_BASE-8)
146 /** RM failed to allocate memory for new service transaction */
147 #define RM_SERVICE_ERROR_TRANSACTION_FAILED_TO_ALLOCATE (RM_SERVICE_ERROR_BASE-9)
148 /** RM could not find the service transaction in the RM instance's transaction queue */
149 #define RM_SERVICE_ERROR_SERVICE_TRANSACTION_DOES_NOT_EXIST (RM_SERVICE_ERROR_BASE-10)
150 /** A failure occurred within a registered transport's packet free API */
151 #define RM_SERVICE_ERROR_TRANSPORT_FREE_PKT_ERROR (RM_SERVICE_ERROR_BASE-11)
152 /** Invalid NameServer object modification on non-Server instance */
153 #define RM_SERVICE_ERROR_NAMESERVER_OBJECT_MOD_ON_INVALID_INSTANCE (RM_SERVICE_ERROR_BASE-12)
154 /** Request failed because both a NameServer name and a resource range were specified */
155 #define RM_SERVICE_ERROR_NAMESERVER_NAME_AND_RESOURCE_RANGE_BOTH_DEFINED (RM_SERVICE_ERROR_BASE-13)
156 /** Error occurred when trying to add an object to the NameServer */
157 #define RM_SERVICE_ERROR_NAMESERVER_OBJECT_ADD_FAILED (RM_SERVICE_ERROR_BASE-14)
158 /** Could not find the object specified in the service request in the NameServer */
159 #define RM_SERVICE_ERROR_NAMESERVER_ERROR_NAME_DOES_NOT_EXIST (RM_SERVICE_ERROR_BASE-15)
161 /**
162 * @brief Maximum number of characters in the resource names
163 */
164 #define RM_RESOURCE_NAME_MAX_CHARS (36)
166 /**
167 * @brief RM service types
168 */
169 typedef enum {
170 /** RM resource allocate for initialization service */
171 Rm_service_RESOURCE_ALLOCATE_INIT = 0,
172 /** RM resource allocate for use service */
173 Rm_service_RESOURCE_ALLOCATE_USE,
174 /** RM resource free service */
175 Rm_service_RESOURCE_FREE,
176 /** RM resource mapping to name service */
177 Rm_service_RESOURCE_MAP_TO_NAME,
178 /** RM resource get by name service */
179 Rm_service_RESOURCE_GET_BY_NAME,
180 /** RM resource name unmapping service */
181 Rm_service_RESOURCE_UNMAP_NAME
182 } Rm_ServiceType;
184 /**
185 * @brief RM pre-main allocation request information provided by the pre-main
186 * startup function requesting the resource */
187 typedef struct {
188 /** Pointer to the requested pre-main allocation resource name. The
189 * name provided by the component must match the resource names
190 * provided in the global resource table and allocation policies */
191 char *resourceName;
192 /** The pre-main allocation request resource base value. For example,
193 * queue number or semaphore number */
194 uint32_t resourceBase;
195 /** Range of resource starting at resourceBase */
196 uint32_t resourceRange;
197 } Rm_PreMainAllocInfo;
199 /**
200 * @brief RM service response information provided by RM back to the
201 * requesting component
202 */
203 typedef struct {
204 /** State of the service request.
205 * Non-negative result: RM has taken an action based on the request
206 * Negative result: RM has encountered an error handling the request */
207 int32_t serviceState;
208 /** A service ID will be returned to the component if the requested service cannot
209 * be completed immediately. The service ID can be used by the component to identify
210 * service responses received via the component callback function. A service ID will not
211 * be returned if the service request is satisfied immediately */
212 uint32_t serviceId;
213 /** The name of the resource affected by the service request */
214 char resourceName[RM_RESOURCE_NAME_MAX_CHARS];
215 /** The base value of the returned resource. In the case of a block resource allocation
216 * response this field will contain the base value of the block. */
217 int32_t resourceBase;
218 /** The number of resources starting from resourceBase allocated in block requests */
219 uint32_t resourceLength;
220 } Rm_ServiceRespInfo;
222 /**
223 * @brief RM service callback function structure
224 */
225 typedef struct {
226 /** Component callback function. RM will call this function when the
227 * resource service request is completed. The callback function supplied
228 * for this parameter must match this function pointer prototype. */
229 void (*serviceCallback) (Rm_ServiceRespInfo *serviceResponse);
230 } Rm_ServiceCallback;
232 /**
233 * @brief RM service request information provided by the requesting component
234 */
235 typedef struct {
236 /** The type of RM service requested */
237 Rm_ServiceType type;
238 /** Pointer to the name of the resource requested. The
239 * name provided by the component must match the resource node names
240 * provided in the global resource table and allocation policies */
241 char *resourceName;
242 /** An allocate service can be requested with an unspecified resource base.
243 * If this occurs the RM Client Delegate or Server will assign the next available
244 * resource or set of resources based on the allocation type. */
245 #define RM_RESOURCE_BASE_UNSPECIFIED (-1)
246 /** The resource base value. */
247 int32_t resourceBase;
248 /** The number of the specified resource to be allocated starting from
249 * resourceBase. Will be greater than one only for block allocate
250 * and free service requests. */
251 uint32_t resourceLength;
252 /** An allocate service can be requested with an unspecified resource alignment.
253 * WARNING: Only applicapable if resourceBase is unspecified
254 *
255 * If the alignment is unspecified the RM Client Delegate or Server will allocate
256 * the resources from a default alignment as specified in the global policy. */
257 #define RM_RESOURCE_ALIGNMENT_UNSPECIFIED (-1)
258 /** Resource alignment in block allocation requests */
259 int32_t resourceAlignment;
260 /** The name server name associated with the resource. Used only for
261 * allocate and free by name service requests */
262 char *resourceNsName;
263 /** Component specified callback function used by RM to inform components
264 * of service requst results */
265 Rm_ServiceCallback callback;
266 } Rm_ServiceReqInfo;
268 /**
269 * @brief RM Service Port provided to software components and applications that
270 * request RM services for the resources they wish to use
271 */
272 typedef struct {
273 /** RM instance handle for which the service handle was registered */
274 void *rmHandle;
275 /**
276 * @b Description
277 * @n
278 * Callout function used by components to request a resource service
279 * from a RM instance
280 *
281 * @param[in] rmHandle
282 * RM instance handle specifying the RM instance that should handle the
283 * service request
284 *
285 * @param[in] serviceRequest
286 * Service request structure that provides details of the service requested from
287 * the RM instance tied to this component
288 *
289 * @param[in] serviceResponse
290 * Service response structure that provides details of RM's response to the
291 * service request
292 */
293 void (*rmService)(void *rmHandle, Rm_ServiceReqInfo *serviceRequest,
294 Rm_ServiceRespInfo *serviceResponse);
295 } Rm_ServicePort;
297 /**
298 * @b Description
299 * @n
300 * Non-blocking function used by RTSC pre-main startup functions to
301 * allocate RM resources for usage. Pre-main allocated resources will be
302 * validated by RM against a memory-mapped startup resource policy.
303 * Pre-main allocation of unauthorized resources will result in a system
304 * exception.
305 *
306 * Note: Resource pre-main allocations can only occur on a core that is
307 * running a RM Server or Client Delegate that has a startup policy
308 * allowing the allocation of pre-main resources
309 *
310 * @param[in] preMainAllocInfo
311 * Resource pre-main allocation structure that provides details of the
312 * resource requested from RM for preallocation
313 *
314 * @param[out] serviceResponse
315 * Contains the result information regarding the pre-main allocation request
316 *
317 * @retval
318 * Success - 0 - Resource pre-main allocation request okay.
319 * @retval
320 * Failure - non-zero - Resource pre-main allocation request error.
321 */
322 void Rm_preMainAllocService (Rm_PreMainAllocInfo *preMainAllocInfo,
323 Rm_ServiceRespInfo *serviceResponse);
325 /**
326 * @b Description
327 * @n
328 * This function returns a RM service port to the application to
329 * provide to software components (LLDs, BIOS, etc) that want to use RM
330 * for resource management.
331 *
332 * @param[in] rmHandle
333 * RM instance handle. Used to return a Rm_ServicePort from an RM
334 * instance.
335 *
336 * @retval
337 * Success - RM Service Port. Used by an application or component to
338 * request a service from RM.
339 * @retval
340 * Failure - NULL
341 */
342 Rm_ServicePort *Rm_getServicePort(Rm_Handle rmHandle);
344 /**
345 @}
346 */
348 #ifdef __cplusplus
349 }
350 #endif
352 #endif /* RMSERVICES_H_ */