Fixes for multi-threaded client test
[keystone-rtos/rm-lld.git] / rm.h
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.
112  
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  */
153  
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 and/or service request
278  *  is greater than RM_NAME_MAX_CHARS */
279 #define RM_ERROR_NAMESERVER_NAME_TOO_LONG          RM_ERROR_BASE-13
280 /** Linux alias assignment in global resource list is invalid */
281 #define RM_ERROR_GRL_INVALID_LINUX_ALIAS_FORMAT    RM_ERROR_BASE-14
282 /** Error allocating memory for the service handle */
283 #define RM_ERROR_SERVICE_HANDLE_MEM_ALLOC_FAILED   RM_ERROR_BASE-15
284 /** The RM instance service handle has already been closed */
285 #define RM_ERROR_SERVICE_HANDLE_ALREADY_CLOSED     RM_ERROR_BASE-16
286 /** Global Resource List (GRL) resource node contains an unknown property */
287 #define RM_ERROR_GRL_UNKNOWN_RESOURCE_PROPERTY     RM_ERROR_BASE-17
288 /** Could not find an allocator for the specified resource */
289 #define RM_ERROR_RES_ALLOCATOR_DOES_NOT_EXIST      RM_ERROR_BASE-18
290 /** A resource node is specified more than once in the Global Resource List (GRL) */
291 #define RM_ERROR_GRL_RES_SPECIFIED_MORE_THAN_ONCE  RM_ERROR_BASE-19
292 /** No data was found at the GRL resource node's specified Linux alias path */
293 #define RM_ERROR_DATA_NOT_FOUND_AT_LINUX_ALIAS     RM_ERROR_BASE-20
294 /** RM server was not provided a Global Resource List (GRL) and global policy at initialization */
295 #define RM_ERROR_INVALID_SERVER_CONFIGURATION      RM_ERROR_BASE-21
296 /** Service request type not recognized */
297 #define RM_ERROR_INVALID_SERVICE_TYPE              RM_ERROR_BASE-22
298 /** rmAllocPkt transport callout returned NULL for rmPkt */
299 #define RM_ERROR_TRANSPORT_ALLOC_PKT_ERROR         RM_ERROR_BASE-23
300 /** rmSendPkt transport callout returned error when attempting to send the rmPkt */
301 #define RM_ERROR_TRANSPORT_SEND_ERROR              RM_ERROR_BASE-24
302 /** A RM service transaction could not be created for the service request */
303 #define RM_ERROR_SERVICE_TRANS_NOT_CREATED         RM_ERROR_BASE-25
304 /** RM service transaction could not be found in instance's transaction queue */
305 #define RM_ERROR_SERVICE_TRANS_DOES_NOT_EXIST      RM_ERROR_BASE-26
306 /** NameServer does not exist in instance, cannot satisfy NameServer service request */
307 #define RM_ERROR_NAMESERVER_DOES_NOT_EXIST         RM_ERROR_BASE-27
308 /** Service request to add a name to the NameServer failed */
309 #define RM_ERROR_NAMESERVER_NAME_ADD_FAILED        RM_ERROR_BASE-28
310 /** Could not find name specified in service request in NameServer */
311 #define RM_ERROR_NAMESERVER_NAME_DOES_NOT_EXIST    RM_ERROR_BASE-29
312 /** Service request made on Client or CD when no transport established and no static policy registered */
313 #define RM_ERROR_REQ_FAILED_NO_STATIC_POLICY       RM_ERROR_BASE-30
314 /** RM transport handle has not been registered with the RM instance */
315 #define RM_ERROR_TRANSPORT_HANDLE_DOES_NOT_EXIST   RM_ERROR_BASE-31
316 /** RM received a packet with an unknown RM packet type */
317 #define RM_ERROR_RECEIVED_INVALID_PACKET_TYPE      RM_ERROR_BASE-32
318 /** RM response packet does not match any requests sent from instance */
319 #define RM_ERROR_PKT_RESP_DOES_NOT_MATCH_ANY_REQ   RM_ERROR_BASE-33
320 /** Server attempted to connect to another server or a CD attempted to connect to another CD or
321  *  Client attempted to connect to another client */
322 #define RM_ERROR_INVALID_REMOTE_INST_TYPE          RM_ERROR_BASE-34
323 /** RM client attempted to register with more than one Server or CD or a CD attempted to register 
324  *  with more than one Server */
325 #define RM_ERROR_ALREADY_REGD_SERVER_OR_CD         RM_ERROR_BASE-35
326 /** Instance type not recognized */
327 #define RM_ERROR_INVALID_INST_TYPE                 RM_ERROR_BASE-36
328 /** RM attempted to allocate a transport packet but the rmAllocPkt callout was not registered */
329 #define RM_ERROR_TRANSPORT_ALLOC_PKT_NOT_REGD      RM_ERROR_BASE-37
330 /** RM attempted to send a packet but the rmSendPkt callout was not registered */
331 #define RM_ERROR_TRANSPORT_SEND_NOT_REGD           RM_ERROR_BASE-38
332 /** RM instance cannot be deleted with transports still registered */
333 #define RM_ERROR_CANT_DELETE_WITH_REGD_TRANSPORT   RM_ERROR_BASE-39
334 /** RM instance cannot be deleted with open service handle */
335 #define RM_ERROR_CANT_DELETE_WITH_OPEN_SERV_HNDL   RM_ERROR_BASE-40
336 /** RM instance cannot be deleted when there are transactions pending and the 
337  *  ignorePendingServices parameter is set to false */
338 #define RM_ERROR_CANT_DELETE_PENDING_TRANSACTIONS  RM_ERROR_BASE-41
339 /** Only the Server instance can be used to return resource status via the
340  *  Rm_resourceStatus API */
341 #define RM_ERROR_INVALID_RES_STATUS_INSTANCE       RM_ERROR_BASE-42
342 /** RM Shared Server and Client instances should always return a finished request since 
343  *  the instance has access to the resource structures no matter what core the service
344  *  is requested from */
345 #define RM_ERROR_SHARED_INSTANCE_UNFINISHED_REQ    RM_ERROR_BASE-43
346 /** RM Shared Server and Client instances cannot register transports */
347 #define RM_ERROR_SHARED_INSTANCE_CANNOT_REG_TRANS  RM_ERROR_BASE-44
348 /** RM Shared Client handle was provided an invalid Shared Server handle.  The shared
349  *  server handle was either NULL or was not an instance of type Rm_instType_SHARED_SERVER */
350 #define RM_ERROR_INVALID_SHARED_SERVER_HANDLE      RM_ERROR_BASE-45
351 /** A RM Client failed to create a new transaction to request data from the Server in order
352  *  to potentially process a transaction on a Client Delegate */
353 #define RM_ERROR_TRANS_REQ_TO_SERVER_NOT_CREATED   RM_ERROR_BASE-46
354 /** Service request required a policy check but instance was not initialized with a policy */
355 #define RM_ERROR_INSTANCE_HAS_NO_POLICY            RM_ERROR_BASE-47
356 /** RM Client Delegate was not provided a policy at initialization */
357 #define RM_ERROR_INVALID_CD_CONFIGURATION          RM_ERROR_BASE-48
358 /** RM CD freed local resources which allowed a free request of local request to be sent to
359  *  the Server.  The Server free failed so the CD tried to realloc the local resources 
360  *  that were originally freed.  The re-allocate operation failed causing a resource loss
361  *  on the CD */
362 #define RM_ERROR_LOST_RESOURCES_ON_CD              RM_ERROR_BASE-49
363 /** The service source inst name and RM packet source instance names are not available
364  *  for the given type of RM packet */
365 #define RM_ERROR_PKT_AND_SERVICE_SRC_NOT_AVAIL     RM_ERROR_BASE-50
366 /** The provided character buffer that will contain the service source inst name or pkt
367  *  source inst name is not of size RM_NAME_MAX_CHARS */
368 #define RM_ERROR_SRC_NAME_BUF_INVALID_SIZE         RM_ERROR_BASE-51
369 /** A resource name specified in the GRL, policy, and/or service request is greater than
370  *  RM_NAME_MAX_CHARS */
371 #define RM_ERROR_RESOURCE_NAME_TOO_LONG            RM_ERROR_BASE-52
372 /** RM failed to create a new allocator - Occurred because an instance that does not use
373  *  allocators tried to create one (RM Client) */
374 #define RM_ERROR_COULD_NOT_CREATE_NEW_ALLOCATOR    RM_ERROR_BASE-53
376 /** 
377  * @brief Maximum number of characters allowed for RM instance, resource, and
378  *        NameServer names.
379  */
380 #define RM_NAME_MAX_CHARS (32)
382 /** 
383  * @brief RM instance handle.  The RM handle is used to register transports
384  *        between RM instances and request resource services from the RM
385  *        instance.
386  */
387 typedef void *Rm_Handle;
389 /** 
390  * @brief RM instance types
391  */
392 typedef enum {
393     /** RM Server */
394     Rm_instType_SERVER = 0,
395     /** RM Client Delegate */
396     Rm_instType_CLIENT_DELEGATE,
397     /** RM Client */
398     Rm_instType_CLIENT,
399     /** RM Shared Server - Server instance stored in shared memory that allows
400      *  multiple DSP cores to request services without the need to configure
401      *  and register transports.  Allows requests to be fulfilled from any DSP
402      *  core without blocking */
403     Rm_instType_SHARED_SERVER,
404     /** RM Shared Client - Piggybacks on the Shared Server instance to handle
405      *  service requests from resource and policy data structures in shared
406      *  memory */
407     Rm_instType_SHARED_CLIENT,
408     /** DO NOT USE: Last type */
409     Rm_instType_LAST
410 } Rm_InstType;
412 /**
413  * @brief RM server (includes shared server) initialization configurations
414  */
415 typedef struct {
416     /** Pointer to the device global resource list (GRL).  The GRL contains 
417      *  all resources on the device that will be managed by RM.  The GRL
418      *  must be in DTB format. */
419     void *globalResourceList;
420     /** Pointer to the Linux DTB if the RM server is running on ARM Linux.
421      *  The Linux DTB will be parsed for all managed resources reserved for use
422      *  by Linux.  Parsing will be based on "linux-dtb-alias" resource
423      *  properties found in the GRL.  The Linux DTB must be in DTB format.  */
424     void *linuxDtb;    
425     /** Pointer to the global policy defining the allocation policies for
426      *  RM instances within the system.  The global policy must be in DTB
427      *  format. */
428     void *globalPolicy;    
429 } Rm_ServerCfg;
431 /**
432  * @brief RM client delegate (CD) initialization configurations
433  */
434 typedef struct {
435     /** Pointer to a client delegate policy used by the CD to allocate resources 
436      *  without contacting the server.  The cdPolicy will be used by the CD to
437      *  determine whether clients connected to the CD can be allocated resources
438      *  provided to the CD by the server. 
439      *
440      *  The cdPolicy will also act as a static policy until the transport to the
441      *  server has been established.  Static allocations can occur before the 
442      *  instance has been attached to a server instance within the RM system.  
443      *  This is useful for allocating resources prior to main().  Resources allocated
444      *  via the static policy will be verified against the global policy once the 
445      *  CD connects with the server.  The static policy must be in DTB format.  
446      *
447      *  To guarantee proper resource permission synchronization between the CD
448      *  and server the cdPolicy must either be an exact copy of the globalPolicy
449      *  or a exact replica of a subset of the globalPolicy provided to the server
450      *  at initialization. */
451     void *cdPolicy;
452 } Rm_ClientDelegateCfg;
454 /**
455  * @brief RM client initialization configurations
456  */
457 typedef struct {
458     /** Pointer to a static policy used by the client to allocate resources statically.
459      *  Static allocations can occur before the instance has been attached to a server
460      *  or CD instance within the RM system.  This is useful for allocating resources
461      *  prior to main().  Resources allocated via the static policy will be verified
462      *  against the global policy once the client connects with the server (directly or
463      *  indirectly through a CD).  The static policy must be in DTB format. */
464     void *staticPolicy;
465 } Rm_ClientCfg;
467 /**
468  * @brief RM shared client initialization configurations
469  */
470 typedef struct {
471     /** RM Shared Server handle.  Typically, the Shared Server handle is created on
472      *  DSP core designated for system initialization.  The application then
473      *  the Shared Server handle, located in shared memory, to the other DSP cores.
474      *  These DSP cores can then piggyback onto the shared memory data structures in
475      *  the Shared Server via the Shared Client */
476      Rm_Handle sharedServerHandle;
477 } Rm_SharedClientCfg;
479 /** 
480  * @brief RM instance initialization structure
481  */
482 typedef struct {
483     /** Pointer to a character array containing the instance name.  The name of the 
484      *  RM instance can be no greater than #RM_NAME_MAX_CHARS.  The instance name
485      *  must match an instance name defined in the "valid-instances" lists contained
486      *  in the global and static policy DTS files.  Resources and privileges to the
487      *  resources will be based on the name assigned to the RM instance*/
488     const char  *instName;
489     /** The type of RM instance that will be created. */
490     Rm_InstType  instType;
491     /** Instance's multi-threaded semaphore object.  Two or more RM instances can have
492      *  their service transactions to the Server serialized by providing a valid
493      *  multi-threaded semaphore object.  The semaphore object will be used by the 
494      *  Osal_rmMtCsEnter and Osal_rmMtCsExit functions.  The multi-threaded
495      *  semaphore associated with the provided object will be taken when a
496      *  service transaction is requested.  The semaphore will be released when
497      *  the service response is returned.  This will serialize the transactions
498      *  of any RM instance initialized with the same multi-threaded sem object.
499      *  Multi-threaded semaphores will not be used if NULL is provided as the object */
500     uint32_t    *mtSemObj;
501     /** Instance-type specific configurations */
502     union {
503         /** #Rm_ServerCfg */
504         Rm_ServerCfg         serverCfg;
505         /** #Rm_ClientDelegateCfg */
506         Rm_ClientDelegateCfg cdCfg;
507         /** #Rm_ClientCfg */
508         Rm_ClientCfg         clientCfg;
509         /** #Rm_SharedClientCfg */
510         Rm_SharedClientCfg   sharedClientCfg;
511     } instCfg;
512 } Rm_InitCfg;
514 /**
515  *  @b Description
516  *  @n  
517  *      This function prints and returns the status for all resources managed by
518  *      the RM instance network.  The allocate/free status as well as ownership
519  *      status will be printed for every resource.  Also, the NameServer name
520  *      entries will be displayed.
521  *
522  *      This function will return error if a Client handle is provided since
523  *      Clients do not track any resource data structures
524  *
525  *  @param[in]  rmHandle
526  *      Instance handle.
527  *
528  *  @param[in]  printResources
529  *      Non-zero - Resource ownership details will be printed for all
530  *                 tracked resources
531  *      0        - Resource ownership details will not be printed.  Only
532  *                 the number of allocated resource ranges will be 
533  *                 returned.
534  *
535  *  @retval
536  *      Success - Total number of allocated resource nodes owners.  Effectively
537  *                returns the number of resource ranges still allocated. 
538  *  @retval
539  *      Failure - #RM_ERROR_INVALID_RES_STATUS_INSTANCE  
540  */
541 int32_t Rm_resourceStatus(Rm_Handle rmHandle, int printResources);
543 /**
544  *  @b Description
545  *  @n  
546  *      This function prints the current status of a RM instance.  The
547  *      following instance properties will be printed:
548  *      a) instance name & type
549  *      b) The instance's registered transports 
550  *      c) All service transactions queued in the instance transaction
551  *         queue and their states
552  *
553  *  @param[in]  rmHandle
554  *      Instance handle.
555  */
556 void Rm_instanceStatus(Rm_Handle rmHandle);
558 /**
559  *  @b Description
560  *  @n  
561  *      This function initializes a RM instance.  There are no restrictions
562  *      on the amount of times this function can be called.  Each call will
563  *      result in a new RM instance.  However, a network of RM instances
564  *      can have only one RM Server.  If an application has multiple RM
565  *      Servers the resources managed by each server must be mutually
566  *      exclusive.  Additionally if an application has multiple RM shared
567  *      servers the resources they manage must be mutually exclusive as well
568  *
569  *      If any errors are encountered during the initialization process
570  *      the Rm_Handle returned will be NULL.
571  *
572  *  @param[in]  initCfg
573  *      Pointer to the instance initialization structure.
574  *
575  *  @param[out] result
576  *      Pointer to a signed int used to return any errors encountered during
577  *      the instance initialization process.
578  *
579  *  @retval
580  *      Success - Rm_Handle for instance and result = #RM_OK
581  *  @retval
582  *      Failure - NULL Rm_Handle and result < #RM_OK
583  */
584 Rm_Handle Rm_init(const Rm_InitCfg *initCfg, int32_t *result);
586 /**
587  *  @b Description
588  *  @n  
589  *      This function deletes the specified RM instance.  All memory
590  *      associated with the instance will be freed.
591  *
592  *  @param[in]  rmHandle
593  *      Instance handle.
594  *
595  *  @param[in]  ignorePendingServices
596  *      Non-zero - The instance will be deleted despite any services pending <br>
597  *      0        - The instance will not be deleted due to at least one service
598  *                 pending.
599  *
600  *  @retval
601  *      Success - #RM_OK
602  *  @retval
603  *      Failure - #RM_ERROR_CANT_DELETE_WITH_OPEN_SERV_HNDL
604  *  @retval
605  *      Failure - #RM_ERROR_CANT_DELETE_WITH_REGD_TRANSPORT
606  *  @retval
607  *      Failure - #RM_ERROR_CANT_DELETE_PENDING_TRANSACTIONS 
608  */
609 int32_t Rm_delete(Rm_Handle rmHandle, int ignorePendingServices);
611 /**
612  *  @b Description
613  *  @n  
614  *      The function is used to get the version information of RM.
615  *
616  *  @retval
617  *      Version Information.
618  */
619 uint32_t Rm_getVersion(void);
621 /**
622  *  @b Description
623  *  @n  
624  *      The function is used to get the version string for RM.
625  *
626  *  @retval
627  *      Version String.
628  */
629 const char* Rm_getVersionStr(void);
631 /** 
632 @} 
633 */
635 #ifdef __cplusplus
637 #endif
639 #endif /* RM_H_ */