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