b417d6785dd3f31c87dd48a54732c214ad8057f9
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>
51 #include <stdbool.h>
53 /** @mainpage Resource Manager
54 *
55 * @section intro Introduction
56 *
57 * The Resource Manager (RM) is designed to provide an easy to use, extensible
58 * uinified resource management solution on TI devices. RM can be integrated by
59 * a system application to provide resource management services to the system
60 * temporally (pre-main/post-main) and spatially (system subcomponents, task,
61 * cores).
62 *
63 * The RM architecture is instance based. All RM resource management services
64 * must originate from a RM instance. Resource permissions are assigned by a
65 * system integrator using RM instance names provided during the initialization
66 * of each RM instance in use. There are three types of RM instances, all of
67 * which can be used by the system to request resource management services:
68 * - Server - Manages all resource data structures including the resource
69 * allocators, the permissions policies, and a simple NameServer.
70 * There can only be one Server per RM ecosystem. If two Servers
71 * are initialized within a system they must manage mutually
72 * exclusive sets of device resources. There is no limit to the
73 * number of Client and Client Delegate instances that can connect
74 * to the Server
75 * - Client - Used by system components to request resource services. There is
76 * no limit to the number of Clients a system can have. Client
77 * names must be unique since resource permissions are assigned based
78 * on RM instance names. Clients can connect to at most one Server
79 * or Client Delegate, but not both at the same time.
80 * - Client Delegate (CD) - At the moment the CD is not different from the
81 * Client. However, in the future the CD will be able
82 * to act as a proxy for the Server. The CD will be
83 * able to satisfy some service requests from Clients,
84 * offloading some processing from the Server. This
85 * feature will be helpful in situations where a
86 * slower data path exists between the Server and
87 * CD/Client instances. There is no limit to the number
88 * of Clients that can connect to a CD. The CD can
89 * connect to at most one Server.
90 *
91 * RM instances communicate via a generic transport interface. The RM transport
92 * interface expects the application to configure and manage the transport data paths
93 * between RM instances. This allows RM to easily extend to different device
94 * configurations and different devices entirely.
95 *
96 * RM utilizes the BDS-licensed, open source, Flattened Device Tree format to
97 * specify what resources are managed by RM as well as the RM instance permissions
98 * for managed resources. The Global Resource List or GRL defines all device
99 * resources and their ranges that will be tracked by the RM Server. Addition or
100 * subtraction of resources from RM requires one modify only the GRL. RM source code
101 * changes are not required to add or subtract resources from RM's umbrella of
102 * management. RM Policies specify resource permissions for the RM instances. There
103 * are two types of Policies:
104 * - Global Policy - Provided to the Server at initialization and defines the
105 * resource permissions for all RM instances in the system.
106 * All service requests will be validated against the Global
107 * Policy on the Server. If the RM instance is found to not
108 * hold the privileges for the request a denial of the service
109 * will be issued back to the requesting instance.
110 * - Static Policy - Optionally provided to Client and CD instances at
111 * initialization. Allows these instances to statically
112 * allocate resources. This feature is typically used
113 * for RM instances that must allocate resources prior
114 * to the transport connection to the Server being established.
115 * Resources allocated via any Static Policies will
116 * be validated against the Global Policy once the transport
117 * to the Server has been fully established. If a Static
118 * Policy request fails validation with the Global Policy the
119 * RM instance that issued the static request will be placed
120 * into a locked state. The locked state prevents any further
121 * service requests from the instance.
122 *
123 * Combined, the GRL and Policy Device Tree implementations allow RM to easily extend
124 * to new resources without the need to recompile the RM source code.
125 *
126 * RM instances currently provides the following resource services:
127 * - Allocate (initialize) - Allocate a resource for initialization
128 * - Allocate (usage) - Allocate a resource for use
129 * - Free - Free an allocated resource (The free must originate
130 * from the RM instance that allocated the resource
131 * - Map resource to name - Map a specified resource to a NameServer name
132 * - Unmap named resource - Unmap a resource from an existing NameServer name
133 * - Get resource by name - Returns a resource based on a provided NameServer name
134 */
136 /* Define RM_API as a master group in Doxygen format and add all RM API
137 definitions to this group. */
138 /** @defgroup RM_API Resource Manager API
139 * @{
140 */
141 /** @} */
143 /**
144 @defgroup RM_TRANSPORT_API RM Transport API
145 @ingroup RM_API
146 */
147 /**
148 @defgroup RM_SERVICES_API RM Services API
149 @ingroup RM_API
150 */
151 /**
152 @defgroup RM_OSAL_API RM OS Abstraction Layer API
153 @ingroup RM_API
154 */
156 /**
157 @addtogroup RM_API
158 @{
159 */
161 /* RM return and error codes */
162 /** RM successful return code */
163 #define RM_OK 0
164 /** RM processing requested service */
165 #define RM_SERVICE_PROCESSING 1
166 /** RM has approved requested service */
167 #define RM_SERVICE_APPROVED 2
168 /** RM has approved requested service based on static policy. Request will be validated
169 * against global policy once all transports have been registered */
170 #define RM_SERVICE_APPROVED_STATIC 3
172 /** RM service request denial reasons base */
173 #define RM_SERVICE_DENIED_BASE 64
174 /** Request resource not found in policy or allocators */
175 #define RM_SERVICE_DENIED_RES_DOES_NOT_EXIST RM_SERVICE_DENIED_BASE+1
176 /** Request resource range within not found within resource's allocator */
177 #define RM_SERVICE_DENIED_RES_RANGE_DOES_NOT_EXIST RM_SERVICE_DENIED_BASE+2
178 /** Free request resource range not allocated to service's source inst */
179 #define RM_SERVICE_DENIED_RES_NOT_ALLOCD_TO_INST RM_SERVICE_DENIED_BASE+3
180 /** Free request resource range already free */
181 #define RM_SERVICE_DENIED_RES_ALREADY_FREE RM_SERVICE_DENIED_BASE+4
182 /** Allocate request resource range partially allocated (Handling of partial allocations
183 * not yet implemented) */
184 #define RM_SERVICE_DENIED_PARTIAL_ALLOCATION RM_SERVICE_DENIED_BASE+5
185 /** Free request resource range partially free (Handling of partial frees not yet implemented) */
186 #define RM_SERVICE_DENIED_PARTIAL_FREE RM_SERVICE_DENIED_BASE+6
187 /** Requirements of allocate request could not be satisfied (occurs for UNSPECIFIED base
188 * and/or alignment requests */
189 #define RM_SERVICE_DENIED_RES_ALLOC_REQS_NOT_MET RM_SERVICE_DENIED_BASE+7
190 /** NameServer add request name string already exists in NameServer */
191 #define RM_SERVICE_DENIED_NAME_EXISTS_IN_NS RM_SERVICE_DENIED_BASE+8
192 /** Service request instance not in policy "valid-instances" list */
193 #define RM_SERVICE_DENIED_INST_NAME_NOT_VALID RM_SERVICE_DENIED_BASE+9
194 /** Init allocate request resource range not given init privileges in policy */
195 #define RM_SERVICE_DENIED_INIT_PERM_NOT_GIVEN RM_SERVICE_DENIED_BASE+10
196 /** Use allocate request resource range not given use privileges in policy */
197 #define RM_SERVICE_DENIED_USE_PERM_NOT_GIVEN RM_SERVICE_DENIED_BASE+11
198 /** Allocate request resource range marked as exclusive in policy has already been allocated */
199 #define RM_SERVICE_DENIED_EXCLUSIVE_RES_ALLOCD RM_SERVICE_DENIED_BASE+12
200 /** Allocate request resource range allocated to an instance assigned exclusive privileges in policy */
201 #define RM_SERVICE_DENIED_ALLOCD_TO_EXCLUSIVE_INST RM_SERVICE_DENIED_BASE+13
202 /** Static allocate request was not an allocate-use or allocate-init request */
203 #define RM_SERVICE_DENIED_INVALID_STATIC_REQUEST RM_SERVICE_DENIED_BASE+14
204 /** Static allocate request denied by static policy */
205 #define RM_SERVICE_DENIED_BY_STATIC_POLICY RM_SERVICE_DENIED_BASE+15
206 /** RM instance locked from further services since a static allocation failed validation against
207 * global policy. RM instance cannot be unlocked. Please make sure static policy and global policy
208 * are in sync */
209 #define RM_SERVICE_DENIED_RM_INSTANCE_LOCKED RM_SERVICE_DENIED_BASE+16
210 /** Allocate request denied because the resource is already reserved by Linux and "Shared Linux"
211 * privileges are not assigned to the requesting instance */
212 #define RM_SERVICE_DENIED_RES_NOT_SHARED_LINUX RM_SERVICE_DENIED_BASE+17
214 /** Start of libfdt.h error codes */
215 #define RM_ERROR_LIBFDT_START (-1)
216 /** End of libfdt.h error codes */
217 #define RM_ERROR_LIBFDT_END (-13)
219 /** RM error base */
220 #define RM_ERROR_BASE (-64)
221 /** Instance name provided is NULL or greater than RM_NAME_MAX_CHARS */
222 #define RM_ERROR_INVALID_INST_NAME RM_ERROR_BASE-1
223 /** List of "valid-instances" not found in global or static policy */
224 #define RM_ERROR_NO_VALID_INST_IN_POLICY RM_ERROR_BASE-2
225 /** Instance specified in permissions string does not match any instances specified in the
226 * "valid-instances" list */
227 #define RM_ERROR_PERM_STR_INST_NOT_VALID RM_ERROR_BASE-3
228 /** Resource specified in global policy does not have an allocator */
229 #define RM_ERROR_UNKNOWN_RESOURCE_IN_POLICY RM_ERROR_BASE-4
230 /** Permissions string has more than instance group specified.
231 * Ex: assignments = <12 1>, "iux = (RM_Client_Delegate) iu = (RM_Client)"; */
232 #define RM_ERROR_PERM_STR_TOO_MANY_INST_GROUPS RM_ERROR_BASE-5
233 /** Permissions string has more than assignment.
234 * Ex: assignments = <12 1>, "iux = (RM_Client_Delegate) = i"; */
235 #define RM_ERROR_PERM_STR_TOO_MANY_ASSIGN_CHARS RM_ERROR_BASE-6
236 /** Permissions string contains invalid character */
237 #define RM_ERROR_PERM_STR_INVALID_CHAR RM_ERROR_BASE-7
238 /** Permissions string contains a permission character without the assignment operator
239 * Ex: assignments = <12 1>, "iux (RM_Client_Delegate)"; */
240 #define RM_ERROR_PERM_CHAR_WITHOUT_ASSIGN_CHAR RM_ERROR_BASE-8
241 /** Permissions string contains a permission character on opposite side of already made assignment
242 * Ex: assignments = <12 1>, "iux = (RM_Client_Delegate) x"; */
243 #define RM_ERROR_INVALID_PERMS_CHAR_ON_RIGHT RM_ERROR_BASE-9
244 /** Policy resource node contains an unknown property */
245 #define RM_ERROR_UNKNOWN_POLICY_RESOURCE_PROPERTY RM_ERROR_BASE-10
246 /** Instance name provided in "valid-instances" list is greater than RM_NAME_MAX_CHARS */
247 #define RM_ERROR_VALID_INST_NAME_TOO_LONG RM_ERROR_BASE-11
248 /** Instance name in permissions assignment is greater than RM_NAME_MAX_CHARS */
249 #define RM_ERROR_INST_NAME_IN_ASSIGNMENT_TOO_LONG RM_ERROR_BASE-12
250 /** NameServer name in global resource list nameServer assignment is greater than RM_NAME_MAX_CHARS */
251 #define RM_ERROR_GRL_NS_ASSIGNMENT_NAME_TOO_LONG RM_ERROR_BASE-13
252 /** Linux alias assignment in global resource list is invalid */
253 #define RM_ERROR_GRL_INVALID_LINUX_ALIAS_FORMAT RM_ERROR_BASE-14
254 /** Error allocating memory for the service handle */
255 #define RM_ERROR_SERVICE_HANDLE_MEM_ALLOC_FAILED RM_ERROR_BASE-15
256 /** The RM instance service handle has already been opened */
257 #define RM_ERROR_SERVICE_HANDLE_ALREADY_OPENED RM_ERROR_BASE-16
258 /** The RM instance service handle has already been closed */
259 #define RM_ERROR_SERVICE_HANDLE_ALREADY_CLOSED RM_ERROR_BASE-17
260 /** Global Resource List (GRL) resource node contains an unknown property */
261 #define RM_ERROR_GRL_UNKNOWN_RESOURCE_PROPERTY RM_ERROR_BASE-18
262 /** Could not find an allocator for the specified resource */
263 #define RM_ERROR_RES_ALLOCATOR_DOES_NOT_EXIST RM_ERROR_BASE-19
264 /** A resource node is specified more than once in the Global Resource List (GRL) */
265 #define RM_ERROR_GRL_RES_SPECIFIED_MORE_THAN_ONCE RM_ERROR_BASE-20
266 /** No data was found at the GRL resource node's specified Linux alias path */
267 #define RM_ERROR_DATA_NOT_FOUND_AT_LINUX_ALIAS RM_ERROR_BASE-21
268 /** RM server was not provided a Global Resource List (GRL) and global policy at initialization */
269 #define RM_ERROR_INVALID_SERVER_CONFIGURATION RM_ERROR_BASE-22
270 /** Service request type not recognized */
271 #define RM_ERROR_INVALID_SERVICE_TYPE RM_ERROR_BASE-23
272 /** rmAllocPkt transport callout returned NULL for rmPkt */
273 #define RM_ERROR_TRANSPORT_ALLOC_PKT_ERROR RM_ERROR_BASE-24
274 /** rmSendPkt transport callout returned error when attempting to send the rmPkt */
275 #define RM_ERROR_TRANSPORT_SEND_ERROR RM_ERROR_BASE-25
276 /** A RM service transaction could not be created for the service request */
277 #define RM_ERROR_SERVICE_TRANS_NOT_CREATED RM_ERROR_BASE-26
278 /** RM service transaction could not be found in instance's transaction queue */
279 #define RM_ERROR_SERVICE_TRANS_DOES_NOT_EXIST RM_ERROR_BASE-27
280 /** NameServer does not exist in instance, cannot satisfy NameServer service request */
281 #define RM_ERROR_NAMESERVER_DOES_NOT_EXIST RM_ERROR_BASE-28
282 /** Service request to add a name to the NameServer failed */
283 #define RM_ERROR_NAMESERVER_NAME_ADD_FAILED RM_ERROR_BASE-29
284 /** Could not find name specified in service request in NameServer */
285 #define RM_ERROR_NAMESERVER_NAME_DOES_NOT_EXIST RM_ERROR_BASE-30
286 /** Service request made on Client or CD when no transport established and no static policy registered */
287 #define RM_ERROR_REQ_FAILED_NO_STATIC_POLICY RM_ERROR_BASE-31
288 /** RM transport handle has not been registered with the RM instance */
289 #define RM_ERROR_TRANSPORT_HANDLE_DOES_NOT_EXIST RM_ERROR_BASE-32
290 /** RM received a packet with an unknown RM packet type */
291 #define RM_ERROR_RECEIVED_INVALID_PACKET_TYPE RM_ERROR_BASE-33
292 /** RM response packet does not match any requests sent from instance */
293 #define RM_ERROR_PKT_RESP_DOES_NOT_MATCH_ANY_REQ RM_ERROR_BASE-34
294 /** Server attempted to connect to another server or a CD attempted to connect to another CD or
295 * Client attempted to connect to another client */
296 #define RM_ERROR_INVALID_REMOTE_INST_TYPE RM_ERROR_BASE-35
297 /** RM client attempted to register with more than one Server or CD or a CD attempted to register
298 * with more than one Server */
299 #define RM_ERROR_ALREADY_REGD_SERVER_OR_CD RM_ERROR_BASE-36
300 /** Service has both a NameServer name and a base, length, or alignment specified */
301 #define RM_ERROR_NS_NAME_AND_RES_VAL_CONFLICT RM_ERROR_BASE-37
302 /** Instance type not recognized */
303 #define RM_ERROR_INVALID_INST_TYPE RM_ERROR_BASE-38
304 /** Linux DTB alias properties specified in GRL but no Linux DTB provided during server instance init */
305 #define RM_ERROR_GRL_LINUX_ALIAS_BUT_NO_DTB RM_ERROR_BASE-39
306 /** RM attempted to allocate a transport packet but the rmAllocPkt callout was not registered */
307 #define RM_ERROR_TRANSPORT_ALLOC_PKT_NOT_REGD RM_ERROR_BASE-40
308 /** RM attempted to send a packet but the rmSendPkt callout was not registered */
309 #define RM_ERROR_TRANSPORT_SEND_NOT_REGD RM_ERROR_BASE-41
310 /** RM attempted to send a response packet but the transport to the remote instance that sent
311 * the request packet is not registered */
312 #define RM_ERROR_TRANSPORT_REMOTE_HNDL_NOT_REGD RM_ERROR_BASE-42
313 /** RM instance cannot be deleted with transports still registered */
314 #define RM_ERROR_CANT_DELETE_WITH_REGD_TRANSPORT RM_ERROR_BASE-43
315 /** RM instance cannot be deleted with open service handle */
316 #define RM_ERROR_CANT_DELETE_WITH_OPEN_SERV_HNDL RM_ERROR_BASE-44
317 /** RM instance cannot be deleted when there are transactions pending and the
318 * ignorePendingServices parameter is set to false */
319 #define RM_ERROR_CANT_DELETE_PENDING_TRANSACTIONS RM_ERROR_BASE-45
320 /** Only the Server instance can be used to return resource status via the
321 * Rm_resourceStatus API */
322 #define RM_ERROR_INVALID_RES_STATUS_INSTANCE RM_ERROR_BASE-46
324 /**
325 * @brief Maximum number of characters allowed for RM instance, resource, and
326 * NameServer names.
327 */
328 #define RM_NAME_MAX_CHARS (32)
330 /**
331 * @brief RM instance handle. The RM handle is used to register transports
332 * between RM instances and request resource services from the RM
333 * instance.
334 */
335 typedef void *Rm_Handle;
337 /**
338 * @brief RM instance types
339 */
340 typedef enum {
341 /** RM Server */
342 Rm_instType_SERVER = 0,
343 /** RM Client Delegate */
344 Rm_instType_CLIENT_DELEGATE,
345 /** RM Client */
346 Rm_instType_CLIENT,
347 /** DO NOT USE: Last type */
348 Rm_instType_LAST
349 } Rm_InstType;
351 /**
352 * @brief RM server initialization configurations
353 */
354 typedef struct {
355 /** Pointer to the device global resource list (GRL). The GRL contains
356 * all resources on the device that will be managed by RM. The GRL
357 * must be in DTB format. */
358 void *globalResourceList;
359 /** Pointer to the Linux DTB if the RM server is running on ARM Linux.
360 * The Linux DTB will be parsed for all managed resources reserved for use
361 * by Linux. Parsing will be based on "linux-dtb-alias" resource
362 * properties found in the GRL. The Linux DTB must be in DTB format. */
363 void *linuxDtb;
364 /** Pointer to the global policy defining the allocation policies for
365 * RM instances within the system. The global policy must be in DTB
366 * format. */
367 void *globalPolicy;
368 } Rm_ServerCfg;
370 /**
371 * @brief RM client delegate (CD) initialization configurations
372 */
373 typedef struct {
374 /** Pointer to a static policy used by the CD to allocate resources statically.
375 * Static allocations can occur before the instance has been attached to a server
376 * instance within the RM system. This is useful for allocating resources
377 * prior to main(). Resources allocated via the static policy will be verified
378 * against the global policy once the CD connects with the server. The static
379 * policy must be in DTB format. */
380 void *staticPolicy;
381 } Rm_ClientDelegateCfg;
383 /**
384 * @brief RM client initialization configurations
385 */
386 typedef struct {
387 /** Pointer to a static policy used by the client to allocate resources statically.
388 * Static allocations can occur before the instance has been attached to a server
389 * or CD instance within the RM system. This is useful for allocating resources
390 * prior to main(). Resources allocated via the static policy will be verified
391 * against the global policy once the client connects with the server (directly or
392 * indirectly through a CD). The static policy must be in DTB format. */
393 void *staticPolicy;
394 } Rm_ClientCfg;
396 /**
397 * @brief RM instance initialization structure
398 */
399 typedef struct {
400 /** Pointer to a character array containing the instance name. The name of the
401 * RM instance can be no greater than #RM_NAME_MAX_CHARS. The instance name
402 * must match an instance name defined in the "valid-instances" lists contained
403 * in the global and static policy DTS files. Resources and privileges to the
404 * resources will be based on the name assigned to the RM instance*/
405 const char *instName;
406 /** The type of RM instance that will be created. */
407 Rm_InstType instType;
408 /** Instance-type specific configurations */
409 union {
410 /** #Rm_ServerCfg */
411 Rm_ServerCfg serverCfg;
412 /** #Rm_ClientDelegateCfg */
413 Rm_ClientDelegateCfg cdCfg;
414 /** #Rm_ClientCfg */
415 Rm_ClientCfg clientCfg;
416 } instCfg;
417 } Rm_InitCfg;
419 /**
420 * @b Description
421 * @n
422 * This function prints and returns the status for all resources managed by
423 * the RM instance network. The allocate/free status as well as ownership
424 * status will be printed for every resource. Also, the NameServer name
425 * entries will be displayed.
426 *
427 * This function only prints resources when provided the server handle
428 * since the server stores all the resource and NameServer
429 * data structures.
430 *
431 * @param[in] rmServerHandle
432 * Server instance handle.
433 *
434 * @param]in] printResources
435 * TRUE - Resource ownership details will be printed for all
436 * tracked resources
437 * FALSE - Resource ownership details will not be printed. Only
438 * the number of allocated resource ranges will be
439 * returned.
440 *
441 * @retval
442 * Success - Total number of allocated resource nodes owners. Effectively
443 * returns the number of resource ranges still allocated.
444 * @retval
445 * Failure - #RM_ERROR_INVALID_RES_STATUS_INSTANCE
446 */
447 int32_t Rm_resourceStatus(Rm_Handle rmServerHandle, bool printResources);
449 /**
450 * @b Description
451 * @n
452 * This function prints the current status of a RM instance. The
453 * following instance properties will be printed:
454 * a) instance name & type
455 * b) The instance's registered transports
456 * c) All service transactions queued in the instance transaction
457 * queue and their states
458 *
459 * @param[in] rmHandle
460 * Instance handle.
461 */
462 void Rm_instanceStatus(Rm_Handle rmHandle);
464 /**
465 * @b Description
466 * @n
467 * This function initializes a RM instance. There are no restrictions
468 * on the amount of times this function can be called. Each call will
469 * result in a new RM instance. However, a network of RM instances
470 * can have only one RM Server. If an application has multiple RM
471 * Servers the resources managed by each server must be mutually
472 * exclusive.
473 *
474 * If any errors are encountered during the initialization process
475 * the Rm_Handle returned will be NULL.
476 *
477 * @param[in] initCfg
478 * Pointer to the instance initialization structure.
479 *
480 * @param[out] result
481 * Pointer to a signed int used to return any errors encountered during
482 * the instance initialization process.
483 *
484 * @retval
485 * Success - Rm_Handle for instance and result = #RM_OK
486 * @retval
487 * Failure - NULL Rm_Handle and result < #RM_OK
488 */
489 Rm_Handle Rm_init(const Rm_InitCfg *initCfg, int32_t *result);
491 /**
492 * @b Description
493 * @n
494 * This function deletes the specified RM instance. All memory
495 * associated with the instance will be freed.
496 *
497 * @param[in] rmHandle
498 * Instance handle.
499 *
500 * @param[in] ignorePendingServices
501 * TRUE - The instance will be deleted despite any services pending <br>
502 * FALSE - The instance will not be deleted due to at least one service
503 * pending.
504 *
505 * @retval
506 * Success - #RM_OK
507 * @retval
508 * Failure - #RM_ERROR_CANT_DELETE_WITH_OPEN_SERV_HNDL
509 * @retval
510 * Failure - #RM_ERROR_CANT_DELETE_WITH_REGD_TRANSPORT
511 * @retval
512 * Failure - #RM_ERROR_CANT_DELETE_PENDING_TRANSACTIONS
513 */
514 int32_t Rm_delete(Rm_Handle rmHandle, bool ignorePendingServices);
516 /**
517 * @b Description
518 * @n
519 * The function is used to get the version information of RM.
520 *
521 * @retval
522 * Version Information.
523 */
524 uint32_t Rm_getVersion(void);
526 /**
527 * @b Description
528 * @n
529 * The function is used to get the version string for RM.
530 *
531 * @retval
532 * Version String.
533 */
534 const char* Rm_getVersionStr(void);
536 /**
537 @}
538 */
540 #ifdef __cplusplus
541 }
542 #endif
544 #endif /* RM_H_ */