aligned the k2g RM DTS files to KeyStone

[keystone-rtos/rm-lld.git] / rm.h

/**
 *   @file  rm.h
 *
 *   @brief   
 *      This is the Resource Manager include file.
 *
 *  \par
 *  ============================================================================
 *  @n   (C) Copyright 2012-2015, Texas Instruments, Inc.
 * 
 *  Redistribution and use in source and binary forms, with or without 
 *  modification, are permitted provided that the following conditions 
 *  are met:
 *
 *    Redistributions of source code must retain the above copyright 
 *    notice, this list of conditions and the following disclaimer.
 *
 *    Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the 
 *    documentation and/or other materials provided with the   
 *    distribution.
 *
 *    Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
 *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
 *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
 *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
 *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
 *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
 *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
 *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *  \par
*/

#ifndef RM_H_
#define RM_H_

#ifdef __cplusplus
extern "C" {
#endif

/* Standard includes */
#include <stdint.h>

/**  @mainpage Resource Manager
 *
 *   @section intro  Introduction
 *
 *   The Resource Manager (RM) is designed to provide an easy to use,
 *   extensible uinified resource management solution on TI devices.  RM can be
 *   integrated by a system application to provide resource management services
 *   to the system temporally (pre-main/post-main) and spatially (system
 *   subcomponents, task, cores).
 *
 *   The RM architecture is instance based.  All RM resource management
 *   services must originate from a RM instance.  Resource permissions are
 *   assigned by a system integrator using RM instance names provided during the
 *   initialization of each RM instance in use.  There are three types of RM
 *   instances, all of which can be used by the system to request resource
 *   management services:
 *    - Server - Manages all resource data structures including the resource
 *               allocators, the permissions policies, and a simple NameServer.
 *               There can only be one Server per RM ecosystem.  If two Servers
 *               are initialized within a system they must manage mutually
 *               exclusive sets of device resources.  There is no limit to the
 *               number of Client and Client Delegate instances that can connect
 *               to the Server
 *    - Client - Used by system components to request resource services.  There
 *               is no limit to the number of Clients a system can have.  Client
 *               names must be unique since resource permissions are assigned
 *               based on RM instance names.  Clients can connect to at most
 *               one Server or Client Delegate, but not both at the same time.
 *    - Client Delegate (CD) - At the moment the CD is not different from the
 *                             Client.  However, in the future the CD will be
 *                             able to act as a proxy for the Server.  The CD
 *                             will be able to satisfy some service requests
 *                             from Clients, offloading some processing from
 *                             the Server.  This feature will be helpful in
 *                             situations where a slower data path exists
 *                             between the Server and CD/Client instances.
 *                             There is no limit to the number of Clients that
 *                             can connect to a CD.  The CD can connect to at
 *                             most one Server.
 *
 *   RM instances communicate via a generic transport interface.  The RM
 *   transport interface expects the application to configure and manage the
 *   transport data paths between RM instances.  This allows RM to easily
 *   extend to different device configurations and different devices entirely.
 *
 *   Shared memory versions of the Server and Client are available for
 *   configuration in cases where the DSP applications cannot tolerate blocking
 *   operations or long wait times for resources.  The Shared Server - Shared
 *   Client model assumes all memory allocated via the OSAL layer is within
 *   shared memory.  RM service requests received from Shared Servers and
 *   Shared Clients will be handled via accesses to the resource management
 *   data structures existing in shared memory.
 *   - Shared Server - Essentially a Server instance that expects to be
 *                     allocated from shared memory via the application-supplied
 *                     OSAL functions.  Shared Client instances will piggyback
 *                     on the Shared Server instance to allocate/free resources
 *                     without the need to setup transports between the
 *                     instances.  Access to the resource management data
 *                     structures is managed through OSAL implemented cache
 *                     writeback and invalidate operations.
 *   - Shared Client - Must be provided a Shared Server handle at initialization
 *                     time.  The Shared Client will essentially use the
 *                     resource management data structures, created in shared
 *                     memory when the Shared Server was initialized, to handle
 *                     any server requests.
 *
 *   RM utilizes the BDS-licensed, open source, Flattened Device Tree format to
 *   specify what resources are managed by RM as well as the RM instance
 *   permissions for managed resources.  The Global Resource List or GRL defines
 *   all device resources and their ranges that will be tracked by the
 *   RM Server.  Addition or subtraction of resources from RM requires one
 *   modify only the GRL.  RM source code changes are not required to add or
 *   subtract resources from RM's umbrella of management.  RM Policies specify
 *   resource permissions for the RM instances.  There are two types of
 *   Policies:
 *    - Global Policy - Provided to the Server at initialization and defines
 *                      the resource permissions for all RM instances in the
 *                      system.  All service requests will be validated against
 *                      the Global Policy on the Server.  If the RM instance is
 *                      found to not hold the privileges for the request a
 *                      denial of the service will be issued back to the
 *                      requesting instance.
 *    - Static Policy - Optionally provided to Client and CD instances at
 *                      initialization.  Allows these instances to statically
 *                      allocate resources.  This feature is typically used
 *                      for RM instances that must allocate resources prior
 *                      to the transport connection to the Server being
 *                      established.  Resources allocated via any Static
 *                      Policies will be validated against the Global Policy
 *                      once the transport 
 *                      to the Server has been fully established.  If a Static
 *                      Policy request fails validation with the Global Policy
 *                      the RM instance that issued the static request will be
 *                      placed into a locked state.  The locked state prevents
 *                      any further service requests from the instance.
 *
 *   Combined, the GRL and Policy Device Tree implementations allow RM to easily
 *   extend to new resources without the need to recompile the RM source code.
 *
 *   RM instances currently provides the following resource services:
 *    - Allocate (initialize) - Allocate a resource for initialization
 *    - Allocate (usage)      - Allocate a resource for use
 *    - Status                - Return the reference count for a specified
 *                              resource
 *    - Free                  - Free an allocated resource (The free must
 *                              originate from the RM instance that allocated
 *                              the resource
 *    - Map resource to name  - Map a specified resource to a NameServer name
 *    - Unmap named resource  - Unmap a resource from an existing NameServer name
 *    - Get resource by name  - Returns a resource based on a provided NameServer
 *                              name
 */

/* Define RM_API as a master group in Doxygen format and add all RM API 
   definitions to this group. */
/** @defgroup RM_API Resource Manager API
 *  @{
 */
/** @} */

/**
@defgroup RM_TRANSPORT_API  RM Transport API
@ingroup RM_API
*/
/**
@defgroup RM_SERVICES_API  RM Services API
@ingroup RM_API
*/
/**
@defgroup RM_OSAL_API RM OS Abstraction Layer API
@ingroup RM_API
*/

/**
@addtogroup RM_API
@{
*/

/* RM return and error codes */
/** RM successful return code */
#define RM_OK                                      0
/** RM processing requested service */
#define RM_SERVICE_PROCESSING                      1
/** RM CD has placed on the request on hold pending a Server response */
#define RM_SERVICE_PENDING_SERVER_RESPONSE         2
/** RM has approved requested service */
#define RM_SERVICE_APPROVED                        3
/** RM has approved requested service based on static policy.  Request will be
 *  validated against global policy once all transports have been registered */
#define RM_SERVICE_APPROVED_STATIC                 4

/** RM service request denial reasons base */
#define RM_SERVICE_DENIED_BASE                     64
/** Request resource not found in policy or allocators */
#define RM_SERVICE_DENIED_RES_DOES_NOT_EXIST       RM_SERVICE_DENIED_BASE+1
/** Request resource range within not found within resource's allocator */
#define RM_SERVICE_DENIED_RES_RANGE_DOES_NOT_EXIST RM_SERVICE_DENIED_BASE+2
/** Free request resource range not allocated to service's source inst */
#define RM_SERVICE_DENIED_RES_NOT_ALLOCD_TO_INST   RM_SERVICE_DENIED_BASE+3
/** Free request resource range already free */
#define RM_SERVICE_DENIED_RES_ALREADY_FREE         RM_SERVICE_DENIED_BASE+4
/** Allocate request resource range partially allocated (Handling of partial
 *  allocations not yet implemented) */
#define RM_SERVICE_DENIED_PARTIAL_ALLOCATION       RM_SERVICE_DENIED_BASE+5
/** Free request resource range partially free (Handling of partial frees not
 *  yet implemented) */
#define RM_SERVICE_DENIED_PARTIAL_FREE             RM_SERVICE_DENIED_BASE+6
/** Requirements of allocate request could not be satisfied (occurs for
 *  UNSPECIFIED base and/or alignment requests */
#define RM_SERVICE_DENIED_RES_ALLOC_REQS_NOT_MET   RM_SERVICE_DENIED_BASE+7
/** NameServer add request name string already exists in NameServer */
#define RM_SERVICE_DENIED_NAME_EXISTS_IN_NS        RM_SERVICE_DENIED_BASE+8
/** Service request instance not in policy "valid-instances" list */
#define RM_SERVICE_DENIED_INST_NAME_NOT_VALID      RM_SERVICE_DENIED_BASE+9
/** Init allocate request resource range not given init privileges in policy */
#define RM_SERVICE_DENIED_INIT_PERM_NOT_GIVEN      RM_SERVICE_DENIED_BASE+10
/** Use allocate request resource range not given use privileges in policy */
#define RM_SERVICE_DENIED_USE_PERM_NOT_GIVEN       RM_SERVICE_DENIED_BASE+11
/** Allocate request resource range marked as exclusive in policy has already
 *  been allocated */
#define RM_SERVICE_DENIED_EXCLUSIVE_RES_ALLOCD     RM_SERVICE_DENIED_BASE+12
/** Allocate request resource range allocated to an instance assigned exclusive
 *  privileges in policy */
#define RM_SERVICE_DENIED_ALLOCD_TO_EXCLUSIVE_INST RM_SERVICE_DENIED_BASE+13
/** Static allocate request was not an allocate-use or allocate-init request */
#define RM_SERVICE_DENIED_INVALID_STATIC_REQUEST   RM_SERVICE_DENIED_BASE+14
/** Static allocate request denied by static policy */
#define RM_SERVICE_DENIED_BY_STATIC_POLICY         RM_SERVICE_DENIED_BASE+15
/** RM instance locked from further services since a static allocation failed
 *  validation against global policy.  RM instance cannot be unlocked.  Please
 *  make sure static policy and global policy are in sync */
#define RM_SERVICE_DENIED_RM_INSTANCE_LOCKED       RM_SERVICE_DENIED_BASE+16
/** Allocate request denied because the resource is already reserved by Linux
 *  and "Shared Linux" privileges are not assigned to the requesting instance */
#define RM_SERVICE_DENIED_RES_NOT_SHARED_LINUX     RM_SERVICE_DENIED_BASE+17
/** Status request resource range partially found (Handling of partial status
 *  requests not yet implemented) */
#define RM_SERVICE_DENIED_PARTIAL_STATUS           RM_SERVICE_DENIED_BASE+18

/** RM Client Delegate instance is not stable.  RM system operation cannot be
 *  guarateed if a CD instance is used.  At the time please manage resources
 *  using Server and Client instances - tracked by SDOCM00100797 */
#define RM_WARNING_CD_INSTANCE_NOT_STABLE          (-1024)

/** Start of libfdt.h error codes */
#define RM_ERROR_LIBFDT_START                      (-1)
/** End of libfdt.h error codes */
#define RM_ERROR_LIBFDT_END                        (-13)

/** RM error base */
#define RM_ERROR_BASE                              (-64)
/** Instance name provided is NULL or greater than RM_NAME_MAX_CHARS */
#define RM_ERROR_INVALID_INST_NAME                 RM_ERROR_BASE-1
/** List of "valid-instances" not found in global or static policy */
#define RM_ERROR_NO_VALID_INST_IN_POLICY           RM_ERROR_BASE-2
/** Instance specified in permissions string does not match any instances
 *  specified in the "valid-instances" list */
#define RM_ERROR_PERM_STR_INST_NOT_VALID           RM_ERROR_BASE-3
/** Resource specified in global policy does not have an allocator */
#define RM_ERROR_UNKNOWN_RESOURCE_IN_POLICY        RM_ERROR_BASE-4
/** Permissions string has more than instance group specified.
 *  Ex: assignments = <12 1>, "iux = (RM_Client_Delegate) iu = (RM_Client)"; */
#define RM_ERROR_PERM_STR_TOO_MANY_INST_GROUPS     RM_ERROR_BASE-5
/** Permissions string has more than assignment.
 *  Ex: assignments = <12 1>, "iux = (RM_Client_Delegate) = i"; */
#define RM_ERROR_PERM_STR_TOO_MANY_ASSIGN_CHARS    RM_ERROR_BASE-6
/** Permissions string contains invalid character */
#define RM_ERROR_PERM_STR_INVALID_CHAR             RM_ERROR_BASE-7
/** Permissions string contains a permission character without the assignment
 *  operator Ex: assignments = <12 1>, "iux (RM_Client_Delegate)"; */
#define RM_ERROR_PERM_CHAR_WITHOUT_ASSIGN_CHAR     RM_ERROR_BASE-8
/** Permissions string contains a permission character on opposite side of
 *  already made assignment
 *  Ex: assignments = <12 1>, "iux = (RM_Client_Delegate) x"; */
#define RM_ERROR_INVALID_PERMS_CHAR_ON_RIGHT       RM_ERROR_BASE-9
/** Policy resource node contains an unknown property */
#define RM_ERROR_UNKNOWN_POLICY_RESOURCE_PROPERTY  RM_ERROR_BASE-10
/** Instance name provided in "valid-instances" list is greater than
 *  RM_NAME_MAX_CHARS */
#define RM_ERROR_VALID_INST_NAME_TOO_LONG          RM_ERROR_BASE-11
/** Instance name in permissions assignment is greater than RM_NAME_MAX_CHARS */
#define RM_ERROR_INST_NAME_IN_ASSIGNMENT_TOO_LONG  RM_ERROR_BASE-12
/** NameServer name in global resource list nameServer assignment and/or
 *  service request is greater than RM_NAME_MAX_CHARS */
#define RM_ERROR_NAMESERVER_NAME_TOO_LONG          RM_ERROR_BASE-13
/** Linux alias assignment in global resource list is invalid */
#define RM_ERROR_GRL_INVALID_LINUX_ALIAS_FORMAT    RM_ERROR_BASE-14
/** Error allocating memory for the service handle */
#define RM_ERROR_SERVICE_HANDLE_MEM_ALLOC_FAILED   RM_ERROR_BASE-15
/** The RM instance service handle has already been closed */
#define RM_ERROR_SERVICE_HANDLE_ALREADY_CLOSED     RM_ERROR_BASE-16
/** Global Resource List (GRL) resource node contains an unknown property */
#define RM_ERROR_GRL_UNKNOWN_RESOURCE_PROPERTY     RM_ERROR_BASE-17
/** Could not find an allocator for the specified resource */
#define RM_ERROR_RES_ALLOCATOR_DOES_NOT_EXIST      RM_ERROR_BASE-18
/** A resource node is specified more than once in either the
 *  Global Resource List (GRL) or policy.  GRL for RM Server. Policy for
 *  CD or Client */
#define RM_ERROR_RES_SPECIFIED_MORE_THAN_ONCE      RM_ERROR_BASE-19
/** No data was found at the GRL resource node's specified Linux alias path */
#define RM_ERROR_DATA_NOT_FOUND_AT_LINUX_ALIAS     RM_ERROR_BASE-20
/** RM server was not provided a Global Resource List (GRL) and global policy
 *  at initialization */
#define RM_ERROR_INVALID_SERVER_CONFIGURATION      RM_ERROR_BASE-21
/** Service request type not recognized */
#define RM_ERROR_INVALID_SERVICE_TYPE              RM_ERROR_BASE-22
/** rmAllocPkt transport callout returned NULL for rmPkt */
#define RM_ERROR_TRANSPORT_ALLOC_PKT_ERROR         RM_ERROR_BASE-23
/** rmSendPkt transport callout returned error when attempting to send the
 *  rmPkt */
#define RM_ERROR_TRANSPORT_SEND_ERROR              RM_ERROR_BASE-24
/** A RM service transaction could not be created for the service request */
#define RM_ERROR_SERVICE_TRANS_NOT_CREATED         RM_ERROR_BASE-25
/** RM service transaction could not be found in instance's transaction queue */
#define RM_ERROR_SERVICE_TRANS_DOES_NOT_EXIST      RM_ERROR_BASE-26
/** NameServer does not exist in instance, cannot satisfy NameServer service
 *  request */
#define RM_ERROR_NAMESERVER_DOES_NOT_EXIST         RM_ERROR_BASE-27
/** Service request to add a name to the NameServer failed */
#define RM_ERROR_NAMESERVER_NAME_ADD_FAILED        RM_ERROR_BASE-28
/** Could not find name specified in service request in NameServer */
#define RM_ERROR_NAMESERVER_NAME_DOES_NOT_EXIST    RM_ERROR_BASE-29
/** Service request made on Client or CD when no transport established and no
 *  static policy registered */
#define RM_ERROR_REQ_FAILED_NO_STATIC_POLICY       RM_ERROR_BASE-30
/** RM transport handle has not been registered with the RM instance */
#define RM_ERROR_TRANSPORT_HANDLE_DOES_NOT_EXIST   RM_ERROR_BASE-31
/** RM received a packet with an unknown RM packet type */
#define RM_ERROR_RECEIVED_INVALID_PACKET_TYPE      RM_ERROR_BASE-32
/** RM response packet does not match any requests sent from instance */
#define RM_ERROR_PKT_RESP_DOES_NOT_MATCH_ANY_REQ   RM_ERROR_BASE-33
/** Server attempted to connect to another server or a CD attempted to connect
 *  to another CD or Client attempted to connect to another client */
#define RM_ERROR_INVALID_REMOTE_INST_TYPE          RM_ERROR_BASE-34
/** RM client attempted to register with more than one Server or CD or a CD
 *  attempted to register with more than one Server */
#define RM_ERROR_ALREADY_REGD_SERVER_OR_CD         RM_ERROR_BASE-35
/** Instance type not recognized */
#define RM_ERROR_INVALID_INST_TYPE                 RM_ERROR_BASE-36
/** RM attempted to allocate a transport packet but the rmAllocPkt callout was
 *  not registered */
#define RM_ERROR_TRANSPORT_ALLOC_PKT_NOT_REGD      RM_ERROR_BASE-37
/** RM attempted to send a packet but the rmSendPkt callout was not
 *  registered */
#define RM_ERROR_TRANSPORT_SEND_NOT_REGD           RM_ERROR_BASE-38
/** RM instance cannot be deleted with transports still registered */
#define RM_ERROR_CANT_DELETE_WITH_REGD_TRANSPORT   RM_ERROR_BASE-39
/** RM instance cannot be deleted with open service handle */
#define RM_ERROR_CANT_DELETE_WITH_OPEN_SERV_HNDL   RM_ERROR_BASE-40
/** RM instance cannot be deleted when there are transactions pending and the
 *  ignorePendingServices parameter is set to false */
#define RM_ERROR_CANT_DELETE_PENDING_TRANSACTIONS  RM_ERROR_BASE-41
/** Only the Server instance can be used to return resource status via the
 *  Rm_resourceStatus API */
#define RM_ERROR_INVALID_RES_STATUS_INSTANCE       RM_ERROR_BASE-42
/** RM Shared Server and Client instances should always return a finished
 *  request since the instance has access to the resource structures no matter
 *  what core the service is requested from */
#define RM_ERROR_SHARED_INSTANCE_UNFINISHED_REQ    RM_ERROR_BASE-43
/** RM Shared Server and Client instances cannot register transports */
#define RM_ERROR_SHARED_INSTANCE_CANNOT_REG_TRANS  RM_ERROR_BASE-44
/** RM Shared Client handle was provided an invalid Shared Server handle.
 *  The shared server handle was either NULL or was not an instance of type
 *  Rm_instType_SHARED_SERVER */
#define RM_ERROR_INVALID_SHARED_SERVER_HANDLE      RM_ERROR_BASE-45
/** A RM Client failed to create a new transaction to request data from the
 *  Server in order to potentially process a transaction on a Client Delegate */
#define RM_ERROR_TRANS_REQ_TO_SERVER_NOT_CREATED   RM_ERROR_BASE-46
/** Service request required a policy check but instance was not initialized
 *  with a policy */
#define RM_ERROR_INSTANCE_HAS_NO_POLICY            RM_ERROR_BASE-47
/** RM Client Delegate was not provided a policy at initialization */
#define RM_ERROR_INVALID_CD_CONFIGURATION          RM_ERROR_BASE-48
/** RM CD freed local resources which allowed a free request of local request
 *  to be sent to the Server.  The Server free failed so the CD tried to
 *  realloc the local resources that were originally freed.  The re-allocate
 *  operation failed causing a resource loss on the CD */
#define RM_ERROR_LOST_RESOURCES_ON_CD              RM_ERROR_BASE-49
/** The service source inst name and RM packet source instance names are not
 *  available for the given type of RM packet */
#define RM_ERROR_PKT_AND_SERVICE_SRC_NOT_AVAIL     RM_ERROR_BASE-50
/** The provided character buffer that will contain the service source inst
 *  name or pkt source inst name is not of size RM_NAME_MAX_CHARS */
#define RM_ERROR_SRC_NAME_BUF_INVALID_SIZE         RM_ERROR_BASE-51
/** A resource name specified in the GRL, policy, and/or service request is
 *  greater than RM_NAME_MAX_CHARS */
#define RM_ERROR_RESOURCE_NAME_TOO_LONG            RM_ERROR_BASE-52
/** RM failed to create a new allocator - Occurred because an instance that
 *  does not use allocators tried to create one (RM Client) */
#define RM_ERROR_COULD_NOT_CREATE_NEW_ALLOCATOR    RM_ERROR_BASE-53
/** Could not allocate the memory needed to store the root entry of the
 *  allocator tree */
#define RM_ERROR_COULD_NOT_INIT_ALLOC_TREE         RM_ERROR_BASE-54
/** The instance's allocator tree could not be populated because of an invalid
 *  combination of instance type, GRL, and policy.  The valid combinations are:
 *  Server OR Shared Server --> Requires GRL and Policy.  Optional Linux DTB
 *  Client Delegate         --> Requires Policy.
 *  Client                  --> Optional Static Policy. */
#define RM_ERROR_INVALID_ALLOCATOR_INIT            RM_ERROR_BASE-55
/** A resource node in the GRL does not have at least a resource range or a
 *  NameServer assignment defined.  At a minimum, each node in the GRL must
 *  have a resource range or NameServer assignment */
#define RM_ERROR_GRL_INVALID_NODE_DEF              RM_ERROR_BASE-56
/** OSAL malloc failed when allocating an allocator node's resource tree */
#define RM_ERROR_MALLOC_FAILED_RES_TREE            RM_ERROR_BASE-57
/** OSAL malloc failed when allocating an allocator node's policy tree */
#define RM_ERROR_MALLOC_FAILED_POL_TREE            RM_ERROR_BASE-58
/** OSAL malloc failed when allocating a resource tree node */
#define RM_ERROR_MALLOC_FAILED_RES_NODE            RM_ERROR_BASE-59
/** A resource specified in the GRL could not be found in the policy */
#define RM_ERROR_RES_DOES_NOT_EXIST_IN_POLICY      RM_ERROR_BASE-60
/** Server's response to CD request has invalid service type */
#define RM_ERROR_SERVER_RESP_INVALID_SERVICE_TYPE  RM_ERROR_BASE-61

/**
 * @brief Maximum number of characters allowed for RM instance, resource, and
 *        NameServer names.
 */
#define RM_NAME_MAX_CHARS (32)

/**
 * @brief RM instance handle.  The RM handle is used to register transports
 *        between RM instances and request resource services from the RM
 *        instance.
 */
typedef void *Rm_Handle;

/**
 * @brief RM instance types
 */
typedef enum {
    /** RM Server */
    Rm_instType_SERVER = 0,
    /** RM Client Delegate */
    Rm_instType_CLIENT_DELEGATE,
    /** RM Client */
    Rm_instType_CLIENT,
    /** RM Shared Server - Server instance stored in shared memory that allows
     *  multiple DSP cores to request services without the need to configure
     *  and register transports.  Allows requests to be fulfilled from any DSP
     *  core without blocking */
    Rm_instType_SHARED_SERVER,
    /** RM Shared Client - Piggybacks on the Shared Server instance to handle
     *  service requests from resource and policy data structures in shared
     *  memory */
    Rm_instType_SHARED_CLIENT,
    /** DO NOT USE: Last type */
    Rm_instType_LAST
} Rm_InstType;

/**
 * @brief RM server (includes shared server) initialization configurations
 */
typedef struct {
    /** Pointer to the device global resource list (GRL).  The GRL contains 
     *  all resources on the device that will be managed by RM.  The GRL
     *  must be in DTB format. */
    void *globalResourceList;
    /** Pointer to the Linux DTB if the RM server is running on ARM Linux.
     *  The Linux DTB will be parsed for all managed resources reserved for use
     *  by Linux.  Parsing will be based on "linux-dtb-alias" resource
     *  properties found in the GRL.  The Linux DTB must be in DTB format.  */
    void *linuxDtb;
    /** Pointer to the global policy defining the allocation policies for
     *  RM instances within the system.  The global policy must be in DTB
     *  format. */
    void *globalPolicy;
} Rm_ServerCfg;

/**
 * @brief RM client delegate (CD) initialization configurations
 */
typedef struct {
    /** Pointer to a client delegate policy used by the CD to allocate resources
     *  without contacting the server.  The cdPolicy will be used by the CD to
     *  determine whether clients connected to the CD can be allocated resources
     *  provided to the CD by the server. 
     *
     *  The cdPolicy will also act as a static policy until the transport to the
     *  server has been established.  Static allocations can occur before the
     *  instance has been attached to a server instance within the RM system.
     *  This is useful for allocating resources prior to main().  Resources
     *  allocated via the static policy will be verified against the global
     *  policy once the CD connects with the server.  The static policy must be
     *  in DTB format.
     *
     *  To guarantee proper resource permission synchronization between the CD
     *  and server the cdPolicy must either be an exact copy of the globalPolicy
     *  or a exact replica of a subset of the globalPolicy provided to the
     *  server at initialization. */
    void *cdPolicy;
} Rm_ClientDelegateCfg;

/**
 * @brief RM client initialization configurations
 */
typedef struct {
    /** Pointer to a static policy used by the client to allocate resources
     *  statically.  Static allocations can occur before the instance has been
     *  attached to a server or CD instance within the RM system.  This is
     *  useful for allocating resources prior to main().  Resources allocated
     *  via the static policy will be verified against the global policy once
     *  the client connects with the server (directly or indirectly through a
     *  CD).  The static policy must be in DTB format. */
    void *staticPolicy;
} Rm_ClientCfg;

/**
 * @brief RM shared client initialization configurations
 */
typedef struct {
    /** RM Shared Server handle.  Typically, the Shared Server handle is
     *  created on DSP core designated for system initialization.  The
     *  application then the Shared Server handle, located in shared memory, to
     *  the other DSP cores.  These DSP cores can then piggyback onto the
     *  shared memory data structures in the Shared Server via the Shared
     *  Client */
     Rm_Handle sharedServerHandle;
} Rm_SharedClientCfg;

/**
 * @brief RM instance initialization structure
 */
typedef struct {
    /** Pointer to a character array containing the instance name.  The name of
     *  the RM instance can be no greater than #RM_NAME_MAX_CHARS.  The instance
     *  name must match an instance name defined in the "valid-instances" lists
     *  contained in the global and static policy DTS files.  Resources and
     *  privileges to the resources will be based on the name assigned to the
     *  RM instance*/
    const char  *instName;
    /** The type of RM instance that will be created. */
    Rm_InstType  instType;
    /** Instance's multi-threaded semaphore object.  Two or more RM instances
     *  can have their service transactions to the Server serialized by
     *  providing a valid multi-threaded semaphore object.  The semaphore
     *  object will be used by the Osal_rmMtCsEnter and Osal_rmMtCsExit
     *  functions.  The multi-threaded semaphore associated with the provided
     *  object will be taken when a service transaction is requested.  The
     *  semaphore will be released when the service response is returned.  This
     *  will serialize the transactions of any RM instance initialized with the
     *  same multi-threaded sem object.  Multi-threaded semaphores will not be
     *  used if NULL is provided as the object */
    uint32_t    *mtSemObj;
    /** Instance-type specific configurations */
    union {
        /** #Rm_ServerCfg */
        Rm_ServerCfg         serverCfg;
        /** #Rm_ClientDelegateCfg */
        Rm_ClientDelegateCfg cdCfg;
        /** #Rm_ClientCfg */
        Rm_ClientCfg         clientCfg;
        /** #Rm_SharedClientCfg */
        Rm_SharedClientCfg   sharedClientCfg;
    } instCfg;
} Rm_InitCfg;

/**
 *  @b Description
 *  @n
 *      This function prints and returns the status for all resources managed by
 *      the RM instance network.  The allocate/free status as well as ownership
 *      status will be printed for every resource.  Also, the NameServer name
 *      entries will be displayed.
 *
 *      This function will return error if a Client handle is provided since
 *      Clients do not track any resource data structures
 *
 *  @param[in]  rmHandle
 *      Instance handle.
 *
 *  @param[in]  printResources
 *      Non-zero - Resource ownership details will be printed for all
 *                 tracked resources
 *      0        - Resource ownership details will not be printed.  Only
 *                 the number of allocated resource ranges will be 
 *                 returned.
 *
 *  @retval
 *      Success - Total number of allocated resource nodes owners.  Effectively
 *                returns the number of resource ranges still allocated.
 *  @retval
 *      Failure - #RM_ERROR_INVALID_RES_STATUS_INSTANCE
 */
int32_t Rm_resourceStatus(Rm_Handle rmHandle, int printResources);

/**
 *  @b Description
 *  @n
 *      This function prints the current status of a RM instance.  The
 *      following instance properties will be printed:
 *      a) instance name & type
 *      b) The instance's registered transports 
 *      c) All service transactions queued in the instance transaction
 *         queue and their states
 *
 *  @param[in]  rmHandle
 *      Instance handle.
 */
void Rm_instanceStatus(Rm_Handle rmHandle);

/**
 *  @b Description
 *  @n
 *      This function initializes a RM instance.  There are no restrictions
 *      on the amount of times this function can be called.  Each call will
 *      result in a new RM instance.  However, a network of RM instances
 *      can have only one RM Server.  If an application has multiple RM
 *      Servers the resources managed by each server must be mutually
 *      exclusive.  Additionally if an application has multiple RM shared
 *      servers the resources they manage must be mutually exclusive as well
 *
 *      If any errors are encountered during the initialization process
 *      the Rm_Handle returned will be NULL.
 *
 *  @param[in]  initCfg
 *      Pointer to the instance initialization structure.
 *
 *  @param[out] result
 *      Pointer to a signed int used to return any errors encountered during
 *      the instance initialization process.
 *
 *  @retval
 *      Success - Rm_Handle for instance and result = #RM_OK
 *  @retval
 *      Failure - NULL Rm_Handle and result < #RM_OK
 */
Rm_Handle Rm_init(const Rm_InitCfg *initCfg, int32_t *result);

/**
 *  @b Description
 *  @n
 *      This function deletes the specified RM instance.  All memory
 *      associated with the instance will be freed.
 *
 *  @param[in]  rmHandle
 *      Instance handle.
 *
 *  @param[in]  ignorePendingServices
 *      Non-zero - The instance will be deleted despite any services pending<br>
 *      0        - The instance will not be deleted due to at least one service
 *                 pending.
 *
 *  @retval
 *      Success - #RM_OK
 *  @retval
 *      Failure - #RM_ERROR_CANT_DELETE_WITH_OPEN_SERV_HNDL
 *  @retval
 *      Failure - #RM_ERROR_CANT_DELETE_WITH_REGD_TRANSPORT
 *  @retval
 *      Failure - #RM_ERROR_CANT_DELETE_PENDING_TRANSACTIONS 
 */
int32_t Rm_delete(Rm_Handle rmHandle, int ignorePendingServices);

/**
 *  @b Description
 *  @n
 *      The function is used to get the version information of RM.
 *
 *  @retval
 *      Version Information.
 */
uint32_t Rm_getVersion(void);

/**
 *  @b Description
 *  @n
 *      The function is used to get the version string for RM.
 *
 *  @retval
 *      Version String.
 */
const char* Rm_getVersionStr(void);

/**
@}
*/

#ifdef __cplusplus
}
#endif

#endif /* RM_H_ */