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