1 /**
2 * @file rm.h
3 *
4 * @brief
5 * This is the Resource Manager include file.
6 *
7 * \par
8 * ============================================================================
9 * @n (C) Copyright 2012-2013, Texas Instruments, Inc.
10 *
11 * Redistribution and use in source and binary forms, with or without
12 * modification, are permitted provided that the following conditions
13 * are met:
14 *
15 * Redistributions of source code must retain the above copyright
16 * notice, this list of conditions and the following disclaimer.
17 *
18 * Redistributions in binary form must reproduce the above copyright
19 * notice, this list of conditions and the following disclaimer in the
20 * documentation and/or other materials provided with the
21 * distribution.
22 *
23 * Neither the name of Texas Instruments Incorporated nor the names of
24 * its contributors may be used to endorse or promote products derived
25 * from this software without specific prior written permission.
26 *
27 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
28 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
29 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
30 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
31 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
32 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
33 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
34 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
35 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
36 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
37 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
38 *
39 * \par
40 */
42 #ifndef RM_H_
43 #define RM_H_
45 #ifdef __cplusplus
46 extern "C" {
47 #endif
49 /* Standard includes */
50 #include <stdint.h>
52 /* RM version */
53 #include <ti/drv/rm/rmver.h>
55 /** @mainpage Resource Manager
56 *
57 * @section intro Introduction
58 *
59 * The Resource Manager
60 *
61 */
63 /* Define RM_API as a master group in Doxygen format and add all RM API
64 definitions to this group. */
65 /** @defgroup RM_API Resource Manager API
66 * @{
67 */
68 /** @} */
70 /**
71 @defgroup RM_TRANSPORT_API RM Transport API
72 @ingroup RM_API
73 */
74 /**
75 @defgroup RM_SERVICES_API RM Services API
76 @ingroup RM_API
77 */
78 /**
79 @defgroup RM_OSAL_API RM OS Abstraction Layer API
80 @ingroup RM_API
81 */
83 /**
84 @addtogroup RM_API
85 @{
86 */
88 /* RM return and error codes */
89 /** RM successful return code */
90 #define RM_OK 0
91 /** RM processing requested service */
92 #define RM_SERVICE_PROCESSING 1
93 /** RM has approved requested service */
94 #define RM_SERVICE_APPROVED 2
95 /** RM has approved requested service based on static policy. Request will be validated
96 * against global policy once all transports have been registered */
97 #define RM_SERVICE_APPROVED_STATIC 3
99 /** RM service request denial reasons base */
100 #define RM_SERVICE_DENIED_BASE 64
101 /** Request resource not found in policy or allocators */
102 #define RM_SERVICE_DENIED_RES_DOES_NOT_EXIST RM_SERVICE_DENIED_BASE+1
103 /** Request resource range within not found within resource's allocator */
104 #define RM_SERVICE_DENIED_RES_RANGE_DOES_NOT_EXIST RM_SERVICE_DENIED_BASE+2
105 /** Free request resource range not allocated to service's source inst */
106 #define RM_SERVICE_DENIED_RES_NOT_ALLOCD_TO_INST RM_SERVICE_DENIED_BASE+3
107 /** Free request resource range already free */
108 #define RM_SERVICE_DENIED_RES_ALREADY_FREE RM_SERVICE_DENIED_BASE+4
109 /** Allocate request resource range partially allocated (Handling of partial allocations
110 * not yet implemented) */
111 #define RM_SERVICE_DENIED_PARTIAL_ALLOCATION RM_SERVICE_DENIED_BASE+5
112 /** Free request resource range partially free (Handling of partial frees not yet implemented) */
113 #define RM_SERVICE_DENIED_PARTIAL_FREE RM_SERVICE_DENIED_BASE+6
114 /** Requirements of allocate request could not be satisfied (occurs for UNSPECIFIED base
115 * and/or alignment requests */
116 #define RM_SERVICE_DENIED_RES_ALLOC_REQS_NOT_MET RM_SERVICE_DENIED_BASE+7
117 /** NameServer add request name string already exists in NameServer */
118 #define RM_SERVICE_DENIED_NAME_EXISTS_IN_NS RM_SERVICE_DENIED_BASE+8
119 /** Service request instance not in policy "valid-instances" list */
120 #define RM_SERVICE_DENIED_INST_NAME_NOT_VALID RM_SERVICE_DENIED_BASE+9
121 /** Init allocate request resource range not given init privileges in policy */
122 #define RM_SERVICE_DENIED_INIT_PERM_NOT_GIVEN RM_SERVICE_DENIED_BASE+10
123 /** Use allocate request resource range not given use privileges in policy */
124 #define RM_SERVICE_DENIED_USE_PERM_NOT_GIVEN RM_SERVICE_DENIED_BASE+11
125 /** Allocate request resource range marked as exclusive in policy has already been allocated */
126 #define RM_SERVICE_DENIED_EXCLUSIVE_RES_ALLOCD RM_SERVICE_DENIED_BASE+12
127 /** Allocate request resource range allocated to an instance assigned exclusive privileges in policy */
128 #define RM_SERVICE_DENIED_ALLOCD_TO_EXCLUSIVE_INST RM_SERVICE_DENIED_BASE+13
129 /** Static allocate request was not an allocate-use or allocate-init request */
130 #define RM_SERVICE_DENIED_INVALID_STATIC_REQUEST RM_SERVICE_DENIED_BASE+14
131 /** Static allocate request denied by static policy */
132 #define RM_SERVICE_DENIED_BY_STATIC_POLICY RM_SERVICE_DENIED_BASE+15
133 /** RM instance locked from further services since a static allocation failed validation against
134 * global policy. RM instance cannot be unlocked. Please make sure static policy and global policy
135 * are in sync */
136 #define RM_SERVICE_DENIED_RM_INSTANCE_LOCKED RM_SERVICE_DENIED_BASE+16
138 /** Start of libfdt.h error codes */
139 #define RM_ERROR_LIBFDT_START (-1)
140 /** End of libfdt.h error codes */
141 #define RM_ERROR_LIBFDT_END (-13)
143 /** RM error base */
144 #define RM_ERROR_BASE (-64)
145 /** Instance name provided is NULL or greater than RM_NAME_MAX_CHARS */
146 #define RM_ERROR_INVALID_INST_NAME RM_ERROR_BASE-1
147 /** List of "valid-instances" not found in global or static policy */
148 #define RM_ERROR_NO_VALID_INST_IN_POLICY RM_ERROR_BASE-2
149 /** Instance specified in permissions string does not match any instances specified in the
150 * "valid-instances" list */
151 #define RM_ERROR_PERM_STR_INST_NOT_VALID RM_ERROR_BASE-3
152 /** Resource specified in global policy does not have an allocator */
153 #define RM_ERROR_UNKNOWN_RESOURCE_IN_POLICY RM_ERROR_BASE-4
154 /** Permissions string has more than instance group specified.
155 * Ex: assignments = <12 1>, "iux = (RM_Client_Delegate) iu = (RM_Client)"; */
156 #define RM_ERROR_PERM_STR_TOO_MANY_INST_GROUPS RM_ERROR_BASE-5
157 /** Permissions string has more than assignment.
158 * Ex: assignments = <12 1>, "iux = (RM_Client_Delegate) = i"; */
159 #define RM_ERROR_PERM_STR_TOO_MANY_ASSIGN_CHARS RM_ERROR_BASE-6
160 /** Permissions string contains invalid character */
161 #define RM_ERROR_PERM_STR_INVALID_CHAR RM_ERROR_BASE-7
162 /** Permissions string contains a permission character without the assignment operator
163 * Ex: assignments = <12 1>, "iux (RM_Client_Delegate)"; */
164 #define RM_ERROR_PERM_CHAR_WITHOUT_ASSIGN_CHAR RM_ERROR_BASE-8
165 /** Permissions string contains a permission character on opposite side of already made assignment
166 * Ex: assignments = <12 1>, "iux = (RM_Client_Delegate) x"; */
167 #define RM_ERROR_INVALID_PERMS_CHAR_ON_RIGHT RM_ERROR_BASE-9
168 /** Policy resource node contains an unknown property */
169 #define RM_ERROR_UNKNOWN_POLICY_RESOURCE_PROPERTY RM_ERROR_BASE-10
170 /** Instance name provided in "valid-instances" list is greater than RM_NAME_MAX_CHARS */
171 #define RM_ERROR_VALID_INST_NAME_TOO_LONG RM_ERROR_BASE-11
172 /** Instance name in permissions assignment is greater than RM_NAME_MAX_CHARS */
173 #define RM_ERROR_INST_NAME_IN_ASSIGNMENT_TOO_LONG RM_ERROR_BASE-12
174 /** NameServer name in global resource list nameServer assignment is greater than RM_NAME_MAX_CHARS */
175 #define RM_ERROR_GRL_NS_ASSIGNMENT_NAME_TOO_LONG RM_ERROR_BASE-13
176 /** Linux alias assignment in global resource list is invalid */
177 #define RM_ERROR_GRL_INVALID_LINUX_ALIAS_FORMAT RM_ERROR_BASE-14
178 /** Error allocating memory for the service handle */
179 #define RM_ERROR_SERVICE_HANDLE_MEM_ALLOC_FAILED RM_ERROR_BASE-15
180 /** The RM instance service handle has already been opened */
181 #define RM_ERROR_SERVICE_HANDLE_ALREADY_OPENED RM_ERROR_BASE-16
182 /** The RM instance service handle has already been closed */
183 #define RM_ERROR_SERVICE_HANDLE_ALREADY_CLOSED RM_ERROR_BASE-17
184 /** Global Resource List (GRL) resource node contains an unknown property */
185 #define RM_ERROR_GRL_UNKNOWN_RESOURCE_PROPERTY RM_ERROR_BASE-18
186 /** Could not find an allocator for the specified resource */
187 #define RM_ERROR_RES_ALLOCATOR_DOES_NOT_EXIST RM_ERROR_BASE-19
188 /** A resource node is specified more than once in the Global Resource List (GRL) */
189 #define RM_ERROR_GRL_RES_SPECIFIED_MORE_THAN_ONCE RM_ERROR_BASE-20
190 /** No data was found at the GRL resource node's specified Linux alias path */
191 #define RM_ERROR_DATA_NOT_FOUND_AT_LINUX_ALIAS RM_ERROR_BASE-21
192 /** RM server was not provided a Global Resource List (GRL) and global policy at initialization */
193 #define RM_ERROR_INVALID_SERVER_CONFIGURATION RM_ERROR_BASE-22
194 /** Service request type not recognized */
195 #define RM_ERROR_INVALID_SERVICE_TYPE RM_ERROR_BASE-23
196 /** Service request did not contain callback function. Callback function must always be provided
197 * with service request since blocking or non-blocking operations cannot be promised. */
198 #define RM_ERROR_CALLBACK_NOT_PROVIDED RM_ERROR_BASE-24
199 /** rmAllocPkt transport callout returned NULL for rmPkt */
200 #define RM_ERROR_TRANSPORT_ALLOC_PKT_ERROR RM_ERROR_BASE-25
201 /** rmSendPkt transport callout returned error when attempting to send the rmPkt */
202 #define RM_ERROR_TRANSPORT_SEND_ERROR RM_ERROR_BASE-26
203 /** A RM service transaction could not be created for the service request */
204 #define RM_ERROR_SERVICE_TRANS_NOT_CREATED RM_ERROR_BASE-27
205 /** RM service transaction could not be found in instance's transaction queue */
206 #define RM_ERROR_SERVICE_TRANS_DOES_NOT_EXIST RM_ERROR_BASE-28
207 /** NameServer does not exist in instance, cannot satisfy NameServer service request */
208 #define RM_ERROR_NAMESERVER_DOES_NOT_EXIST RM_ERROR_BASE-29
209 /** Service request to add a name to the NameServer failed */
210 #define RM_ERROR_NAMESERVER_NAME_ADD_FAILED RM_ERROR_BASE-30
211 /** Could not find name specified in service request in NameServer */
212 #define RM_ERROR_NAMESERVER_NAME_DOES_NOT_EXIST RM_ERROR_BASE-31
213 /** Service request made on Client or CD when no transport established and no static policy registered */
214 #define RM_ERROR_REQ_FAILED_NO_STATIC_POLICY RM_ERROR_BASE-32
215 /** RM transport handle has not been registered with the RM instance */
216 #define RM_ERROR_TRANSPORT_HANDLE_DOES_NOT_EXIST RM_ERROR_BASE-33
217 /** RM received a packet with an unknown RM packet type */
218 #define RM_ERROR_RECEIVED_INVALID_PACKET_TYPE RM_ERROR_BASE-34
219 /** RM response packet does not match any requests sent from instance */
220 #define RM_ERROR_PKT_RESP_DOES_NOT_MATCH_ANY_REQ RM_ERROR_BASE-35
221 /** Server attempted to connect to another server or a CD attempted to connect to another CD or
222 * Client attempted to connect to another client */
223 #define RM_ERROR_INVALID_REMOTE_INST_TYPE RM_ERROR_BASE-36
224 /** RM client attempted to register with more than one Server or CD or a CD attempted to register
225 * with more than one Server */
226 #define RM_ERROR_ALREADY_REGD_SERVER_OR_CD RM_ERROR_BASE-37
227 /** Transport registration callout function pointers specified as valid but were NULL */
228 #define RM_ERROR_NULL_CALLOUTS_WHEN_VALID RM_ERROR_BASE-38
229 /** Service both a NameServer name and a base, length, or alignment */
230 #define RM_ERROR_NS_NAME_AND_RES_VAL_CONFLICT RM_ERROR_BASE-39
231 /** Instance type not recognized */
232 #define RM_ERROR_INVALID_INST_TYPE RM_ERROR_BASE-40
233 /** Linux DTB alias properties specified in GRL but no Linux DTB provided during server instance init */
234 #define RM_ERROR_GRL_LINUX_ALIAS_BUT_NO_DTB RM_ERROR_BASE-41
235 /** RM attempted to allocate a transport packet but the rmAllocPkt callout was not registered */
236 #define RM_ERROR_TRANSPORT_ALLOC_PKT_NOT_REGD RM_ERROR_BASE-42
237 /** RM attempted to send a packet but the rmSendPkt callout was not registered */
238 #define RM_ERROR_TRANSPORT_SEND_NOT_REGD RM_ERROR_BASE-43
240 /**
241 * @brief Maximum number of characters allowed for RM instance, resource, and
242 * NameServer names.
243 */
244 #define RM_NAME_MAX_CHARS (32)
246 /**
247 * @brief RM instance handle. The RM handle is used to register transports
248 * between RM instances and request resource services from the RM
249 * instance.
250 */
251 typedef void *Rm_Handle;
253 /**
254 * @brief RM instance types
255 */
256 typedef enum {
257 /** RM Server */
258 Rm_instType_SERVER = 0,
259 /** RM Client Delegate */
260 Rm_instType_CLIENT_DELEGATE,
261 /** RM Client */
262 Rm_instType_CLIENT,
263 /** DO NOT USE: Last type */
264 Rm_instType_LAST
265 } Rm_InstType;
267 /**
268 * @brief RM server initialization configurations
269 */
270 typedef struct {
271 /** Pointer to the device global resource list (GRL). The GRL contains
272 * all resources on the device that will be managed by RM. The GRL
273 * must be in DTB format. */
274 void *globalResourceList;
275 /** Pointer to the Linux DTB if the RM server is running on ARM Linux.
276 * The Linux DTB will be parsed for all managed resources reserved for use
277 * by Linux. Parsing will be based on "linux-dtb-alias" resource
278 * properties found in the GRL. The Linux DTB must be in DTB format. */
279 void *linuxDtb;
280 /** Pointer to the global policy defining the allocation policies for
281 * RM instances within the system. The global policy must be in DTB
282 * format. */
283 void *globalPolicy;
284 } Rm_ServerCfg;
286 /**
287 * @brief RM client delegate (CD) initialization configurations
288 */
289 typedef struct {
290 /** Pointer to a static policy used by the CD to allocate resources statically.
291 * Static allocations can occur before the instance has been attached to a server
292 * instance within the RM system. This is useful for allocating resources
293 * prior to main(). Resources allocated via the static policy will be verified
294 * against the global policy once the CD connects with the server. The static
295 * policy must be in DTB format. */
296 void *staticPolicy;
297 } Rm_ClientDelegateCfg;
299 /**
300 * @brief RM client initialization configurations
301 */
302 typedef struct {
303 /** Pointer to a static policy used by the client to allocate resources statically.
304 * Static allocations can occur before the instance has been attached to a server
305 * or CD instance within the RM system. This is useful for allocating resources
306 * prior to main(). Resources allocated via the static policy will be verified
307 * against the global policy once the client connects with the server (directly or
308 * indirectly through a CD). The static policy must be in DTB format. */
309 void *staticPolicy;
310 } Rm_ClientCfg;
312 /**
313 * @brief RM instance initialization structure
314 */
315 typedef struct {
316 /** Pointer to a character array containing the instance name. The name of the
317 * RM instance can be no greater than #RM_NAME_MAX_CHARS. The instance name
318 * must match an instance name defined in the "valid-instances" lists contained
319 * in the global and static policy DTS files. Resources and privileges to the
320 * resources will be based on the name assigned to the RM instance*/
321 char *instName;
322 /** The type of RM instance that will be created. */
323 Rm_InstType instType;
324 /** Instance-type specific configurations */
325 union {
326 /** #Rm_ServerCfg */
327 Rm_ServerCfg serverCfg;
328 /** #Rm_ClientDelegateCfg */
329 Rm_ClientDelegateCfg cdCfg;
330 /** #Rm_ClientCfg */
331 Rm_ClientCfg clientCfg;
332 } instCfg;
333 } Rm_InitCfg;
335 /**
336 * @b Description
337 * @n
338 * This function prints the status for all resources managed by the
339 * RM instance network. The allocate/free status as well as ownership
340 * status will be printed for every resource. Also, the NameServer name
341 * entries will be displayed.
342 *
343 * This function only prints resources when provided the server handle
344 * since the server stores all the resource and NameServer
345 * data structures.
346 *
347 * @param[in] rmServerHandle
348 * Server instance handle.
349 */
350 void Rm_printResourceStatus(Rm_Handle rmServerHandle);
352 /**
353 * @b Description
354 * @n
355 * This function prints the current status of a RM instance. The
356 * following instance properties will be printed:
357 * a) instance name & type
358 * b) The instance's registered transports
359 * c) All service transactions queued in the instance transaction
360 * queue and their states
361 *
362 * @param[in] rmHandle
363 * Instance handle.
364 */
365 void Rm_printInstanceStatus(Rm_Handle rmHandle);
367 /**
368 * @b Description
369 * @n
370 * This function initializes a RM instance. There are no restrictions
371 * on the amount of times this function can be called. Each call will
372 * result in a new RM instance. However, a network of RM instances
373 * can have only one RM Server. If an application has multiple RM
374 * Servers the resources managed by each server must be mutually
375 * exclusive.
376 *
377 * If any errors are encountered during the initialization process
378 * the Rm_Handle returned will be NULL.
379 *
380 * @param[in] initCfg
381 * Pointer to the instance initialization structure.
382 *
383 * @param[out] result
384 * Pointer to a signed int used to return any errors encountered during
385 * the instance initialization process.
386 *
387 * @retval
388 * Success - Rm_Handle for instance and result = #RM_OK
389 * @retval
390 * Failure - NULL Rm_Handle and result < #RM_OK
391 */
392 Rm_Handle Rm_init(Rm_InitCfg *initCfg, int32_t *result);
394 /**
395 * @b Description
396 * @n
397 * The function is used to get the version information of RM.
398 *
399 * @retval
400 * Version Information.
401 */
402 uint32_t Rm_getVersion (void);
404 /**
405 * @b Description
406 * @n
407 * The function is used to get the version string for RM.
408 *
409 * @retval
410 * Version String.
411 */
412 const char* Rm_getVersionStr (void);
414 /**
415 @}
416 */
418 #ifdef __cplusplus
419 }
420 #endif
422 #endif /* RM_H_ */