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 /**
51 @addtogroup RMSERVICES_API
52 @{
53 */
55 /** RM Service Request (serviceResult) Action Codes and Errors */
56 /** RM Service Request Action Code Base */
57 #define RM_SERVICE_ACTION_BASE (0)
58 /** RM internal action okay - This value is for internal use by RM. It should never be
59 * seen as a return value during normal operation */
60 #define RM_SERVICE_ACTION_OKAY (RM_SERVICE_ACTION_BASE)
61 /** RM service was approved. The resource data in the response is valid if
62 * the service has been approved. */
63 #define RM_SERVICE_APPROVED (RM_SERVICE_ACTION_BASE+1)
64 /** Beginning of resource denied reasons */
65 #define RM_SERVICE_DENIED_BEGIN (RM_SERVICE_ACTION_BASE+2)
66 /** End of resource denied reasons */
67 #define RM_SERVICE_DENIED_END (RM_SERVICE_ACTION_BASE+2)
68 /** RM service is being processed. Typically this means the service is
69 * being sent to a higher level RM agent for processing */
70 #define RM_SERVICE_PROCESSING (RM_SERVICE_ACTION_BASE+3)
72 /** RM Service Request Error Code Base */
73 #define RM_SERVICE_ERROR_BASE (-64)
74 /** RM service request type not recognized */
75 #define RM_SERVICE_ERROR_INVALID_SERVICE_TYPE (RM_SERVICE_ERROR_BASE)
76 /** RM Service request was not provided a component callback
77 * function. Service requests may result in blocking operations. A callback
78 * function must always be provided with a service request since
79 * blocked or non-blocked operations cannot be promised. */
80 #define RM_SERVICE_ERROR_CALLBACK_NOT_PROVIDED (RM_SERVICE_ERROR_BASE-1)
81 /** RM service request needs to be forwarded to another RM agent but no transports
82 * have been registered */
83 #define RM_SERVICE_ERROR_NO_TRANSPORT_REGISTERED (RM_SERVICE_ERROR_BASE-2)
84 /** RM service request needs to be forwarded but no client delegate or server has
85 * been registered with the RM instance */
86 #define RM_SERVICE_ERROR_NOT_REGISTERED_WITH_DEL_OR_SERVER (RM_SERVICE_ERROR_BASE-3)
87 /** RM service request needs to be forwarded but the transport packet alloc API
88 * has not been provided */
89 #define RM_SERVICE_ERROR_TRANSPORT_PKT_ALLOC_API_NULL (RM_SERVICE_ERROR_BASE-4)
90 /** A failure occurred within a registered transport's packet alloc API */
91 #define RM_SERVICE_ERROR_TRANSPORT_ALLOC_PKT_ERROR (RM_SERVICE_ERROR_BASE-5)
92 /** RM service request needs to be forwarded but the buffer allocated by transport
93 * is not large enough to fit the RM transport packet */
94 #define RM_SERVICE_ERROR_TRANSPORT_PKT_BUF_TOO_SMALL (RM_SERVICE_ERROR_BASE-6)
95 /** RM service request needs to be forwarded but the transport returned an error
96 * when trying to send the RM packet to the higher level agent */
97 #define RM_SERVICE_ERROR_TRANPSPORT_SEND_ERROR (RM_SERVICE_ERROR_BASE-7)
98 /** RM service response from higher level agent did not match any requests made
99 * by the provided RM instance */
100 #define RM_SERVICE_ERROR_TRANSACTION_DOES_NOT_EXST_FOR_THIS_RM_INSTANCE (RM_SERVICE_ERROR_BASE-8)
101 /** RM failed to allocate memory for new service transaction */
102 #define RM_SERVICE_ERROR_TRANSACTION_FAILED_TO_ALLOCATE (RM_SERVICE_ERROR_BASE-9)
103 /** RM found no service transactions queued when trying to delete a received service
104 * transaction */
105 #define RM_SERVICE_ERROR_NO_TRANSACTIONS_IN_QUEUE (RM_SERVICE_ERROR_BASE-10)
106 /** RM could not find the service transaction in the RM instance's transaction queue */
107 #define RM_SERVICE_ERROR_SERVICE_TRANSACTION_DOES_NOT_EXIST (RM_SERVICE_ERROR_BASE-11)
108 /** RM received a response transaction and found a request transaction awaiting a response.
109 * However, the request transaction was not in the "awaiting response" state */
110 #define RM_SERVICE_ERROR_INVALID_REQUEST_TRANSACTION_STATE_UPON_RESPONSE (RM_SERVICE_ERROR_BASE-12)
111 /** RM Client instance received a service transaction response that did not have a
112 * matching service request that originated on the Client instance */
113 #define RM_SERVICE_ERROR_INVALID_TRANSACTION_RECEIVED_ON_CLIENT (RM_SERVICE_ERROR_BASE-13)
114 /** A failure occurred within a registered transport's packet free API */
115 #define RM_SERVICE_ERROR_TRANSPORT_FREE_PKT_ERROR (RM_SERVICE_ERROR_BASE-14)
117 /** RM Transport Error Code Base */
118 #define RM_TRANSPORT_ERROR_BASE (-128)
119 /** The transport handle provided to the RM instance was not registered with the RM instance */
120 #define RM_TRANSPORT_ERROR_TRANSPORT_HANDLE_NOT_REGISTERED_WITH_INSTANCE (RM_TRANSPORT_ERROR_BASE)
121 /** RM received a packet with an unknown RM packet type */
122 #define RM_TRANSPORT_ERROR_INVALID_PACKET_TYPE (RM_TRANSPORT_ERROR_BASE-1)
124 /**
125 * @brief RM service types
126 */
127 typedef enum {
128 /** First service type. Used by RM for bounds checking. Should
129 * not be used by component. */
130 Rm_service_FIRST = 0,
131 /** RM resource allocate service */
132 Rm_service_RESOURCE_ALLOCATE = 0,
133 /** RM resource block allocate service */
134 Rm_service_RESOURCE_BLOCK_ALLOCATE = 1,
135 /** RM resource allocate by name service */
136 Rm_service_RESOURCE_ALLOCATE_BY_NAME = 2,
137 /** RM resource free service */
138 Rm_service_RESOURCE_FREE = 3,
139 /** RM resource block free service */
140 Rm_service_RESOURCE_BLOCK_FREE = 4,
141 /** RM resource free by name service */
142 Rm_service_RESOURCE_FREE_BY_NAME = 5,
143 /** RM resource mapping to name service */
144 Rm_service_RESOURCE_MAP_TO_NAME = 6,
145 /** RM resource name unmapping service */
146 Rm_service_RESOURCE_UNMAP_NAME = 7,
147 /** Last service type. Used by RM for bounds checking. Should
148 * not be used by component. */
149 Rm_service_LAST = 7
150 } Rm_ServiceType;
152 /**
153 * @brief RM service response information provided by RM back to the
154 * requesting component
155 */
156 typedef struct {
157 /** Result of the service request
158 * Non-negative result: RM has taken an action based on the request
159 * Negative result: RM has encountered an error handling the request */
160 int32_t serviceResult;
161 /** A request ID will be returned to the component if the requested service cannot
162 * be completed immediately. The request ID can be used by the component to identify
163 * service responses received via the component callback function. A request ID will not
164 * be returned if the service request is satisfied immediately */
165 uint32_t requestId;
166 /** The base value of the returned resource. In the case of a block resource allocation
167 * response this field will contain the base value of the block. */
168 int32_t resourceBase;
169 /** The range of resources starting from resourceBase allocated in block requests */
170 uint32_t resourceRange;
171 } Rm_ServiceRespInfo;
173 /**
174 * @brief RM service request information provided by the requesting component
175 */
176 typedef struct {
177 /** The type of RM service requested */
178 Rm_ServiceType type;
179 /** Pointer to the name of the resource requested. The
180 * name provided by the component must match the resource node names
181 * provided in the global resource table and allocation policies */
182 char *resourceName;
183 /** An allocate service can be requested with an unspecified resource base.
184 * If this occurs the RM Client Delegate or Server will assign the next available
185 * resource or set of resources based on the allocation type. */
186 #define RM_RESOURCE_BASE_UNSPECIFIED (-1)
187 /** The resource base value. */
188 int32_t resourceBase;
189 /** The range of the specified resource to be allocated starting from
190 * resourceBase. Will be greater than one only for block allocate
191 * and free service requests. */
192 uint32_t resourceRange;
193 /** An allocate service can be requested with an unspecified resource alignment.
194 * WARNING: Only applicapable if resourceBase is unspecified
195 *
196 * If the alignment is unspecified the RM Client Delegate or Server will allocate
197 * the resources from a default alignment as specified in the global policy. */
198 #define RM_RESOURCE_ALIGNMENT_UNSPECIFIED (-1)
199 /** Resource alignment in block allocation requests */
200 int32_t resourceAlignment;
201 /** The name server name associated with the resource. Used only for
202 * allocate and free by name service requests */
203 char *resourceNsName;
204 /** Component callback function. RM will call this function when the
205 * resource service request is completed. The callback function supplied
206 * for this parameter must match this function pointer prototype. */
207 void (*serviceCallback) (Rm_ServiceRespInfo *serviceResponse);
208 } Rm_ServiceReqInfo;
210 /**
211 * @brief RM Service Port provided to software components and applications that
212 * request RM services for the resources they wish to use
213 */
214 typedef struct {
215 /** RM instance handle for which the service handle was registered */
216 void *rmHandle;
217 /**
218 * @b Description
219 * @n
220 * Callout function used by components to request a resource service
221 * from a RM instance
222 *
223 * @param[in] rmHandle
224 * RM instance handle specifying the RM instance that should handle the
225 * service request
226 *
227 * @param[in] serviceRequest
228 * Service request structure that provides details of the service requested from
229 * the RM instance tied to this component
230 *
231 * @param[in] serviceResponse
232 * Service response structure that provides details of RM's response to the
233 * service request
234 */
235 void (*rmService)(void *rmHandle, Rm_ServiceReqInfo *serviceRequest,
236 Rm_ServiceRespInfo *serviceResponse);
237 } Rm_ServicesPort;
239 /**
240 @}
241 */
243 #ifdef __cplusplus
244 }
245 #endif
247 #endif /* RMSERVICES_H_ */