index 4f59095d17ad16d49e458077a66da921c863bece..4203e0c248c1471ac2b0c706f5dbbb654816d1fd 100644 (file)
--- a/rm.h
+++ b/rm.h
*
* \par
* ============================================================================
- * @n (C) Copyright 2012, Texas Instruments, Inc.
+ * @n (C) Copyright 2012-2013, Texas Instruments, Inc.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
extern "C" {
#endif
-/* RM version */
-#include <ti/drv/rm/rmver.h>
-/* RM component services include */
-#include <ti/drv/rm/rm_services.h>
-/* RM transport include */
-#include <ti/drv/rm/rm_transport.h>
-/* RM policy include */
-#include <ti/drv/rm/rm_policy.h>
+/* Standard includes */
+#include <stdint.h>
/** @mainpage Resource Manager
*
* @section intro Introduction
*
- * The Resource Manager low level driver (RM LLD) is designed to provide initialization and permissions checking
- * for LLD resources. A system integrator can specify DSP permissions for LLD resources within the system.
- * The resource permissions are stored in the RM LLD and used to validate resource requests from supported LLDs.
- * Currently, the RM LLD supports permissions for the following LLDs
- * - QMSS
- * - CPPI
- * - PA
- * For information on the specific resources supported with each LLD please see @ref RM_LLD_RESOURCE_TABLE.
- *
- * The system integrator must specify the supported LLD resource permissions for all DSPs prior to compile time.
- * An array of @ref Rm_Resource objects must be created. Each @ref Rm_Resource entry in the array specifies
- * a resource type, start and end range for the resource, and the initialization and usage permissions for the
- * resource for each DSP. For an example resource table definitions please see the @ref rmResourceTable array
- * defined in the resource_table\ directory. This resource table assigns full initialization and usage permissions
- * to all DSPs for all supported resources. Please note that the resouce table must start with the
- * @ref RM_RESOURCE_MAGIC_NUMBER entry and end with the @ref RM_RESOURCE_FINAL_ENTRY. These
- * first and last entries are used the RM LLD to validate and parse the resource table.
- *
- * The RM LLD must be initialized and started prior to all supported LLD initialization and start routines. The
- * @ref Rm_init function should be invoked, and passed a pointer to the integrator defined resource table, on the
- * master DSP core in the system. All other DSP cores should invoke the @ref Rm_start API. The @ref Rm_init
- * function first initializes the internal permission tables to deny all DSPs access to all resources. Next the
- * @ref Rm_init function parses the resource table provided and copies all specified permissions into the internal
- * tables. When the permission transfer completes the @ref Rm_init function writes a global synchronization
- * object which the @ref Rm_start functions are spinning on. The slave cores that have invoked @ref Rm_start
- * will stop spinning once the global synchronization has been written. At this time @ref Rm_start will invalidate
- * all internal permission tables so that no further cache invalidate operations need to be performed when
- * checking resource permissions in the data path. The upfront cache invalidate operation is possible because
- * the RM LLD does not allow dynamic resource permission modifications. The permissions defined by the system
- * integrator and loaded during RM initialization are static throughout the system up-time.
- *
- * The RM LLD must be registered with a supported LLD in order for the supported LLD to perform resource
- * permission checks. If the RM LLD is not registered with a supported LLD the LLD will operate as if the RM LLD
- * is not there. This maintains full backwards compatability with existing applications not using the RM LLD. In order
- * to register the RM LLD with supported LLDs the following steps should be taken
- * - Get a @ref Rm_Handle via the @ref Rm_getHandle API on each DSP that uses the RM LLD.
- * - Register the RM LLD with the supported LLDs by passing the @ref Rm_Handle to the
- * LLD's <<LLD name>>_startCfg API. Again, this should be performed on all DSP cores using the RM LLD.
- * Note: The master core for the QMSS LLD should have the @ref Rm_Handle registered via the Qmss_init API.
- * After registering the RM LLD with supported LLDs all supported LLD resources covered by the RM LLD will invoke
- * permission check callouts to the RM. A permission denied or approved response will be given back to the
- * invoking LLD based on the permissions stored in the RM LLD for the resource.
- *
- * All internal RM LLD permission tables are placed into a single memory section called ".rm". This memory section
- * MUST be placed in shared memory (MSMC or DDR). The permission tables are shared between all DSPs utilizing
- * the RM LLD.
- *
- * In summary, the initialization flow if the RM LLD is to be utilized should look like the following:
- *
- * Master DSP Core:
- * - Call @ref Rm_init passing in the system integrator defined resource table
- * - Call @ref Rm_getHandle
- * - Call supported LLD _init or _create functions (for QMSS pass the @ref Rm_Handle inside the
- * Qmss_GlobalConfigParams structure)
- * - Call supported LLD _startCfg functions passing the @ref Rm_Handle as an argument
- *
- * Slave DSP Cores:
- * - Call @ref Rm_start
- * - Call @ref Rm_getHandle
- * - Call supported LLD _start functions (if supported)
- * - Call supported LLD _startCfg functions passing the @ref Rm_Handle as an argument
- *
+ * 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.
+ *
+ * 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
+ * - 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_LLD_API as a master group in Doxygen format and add all RM LLD API
+/* Define RM_API as a master group in Doxygen format and add all RM API
definitions to this group. */
-/** @defgroup RM_LLD_API RM LLD Module API
+/** @defgroup RM_API Resource Manager API
* @{
*/
/** @} */
/**
-@defgroup RM_TRANSPORT_API RM Transport-Layer API
-@ingroup RM_LLD_API
+@defgroup RM_TRANSPORT_API RM Transport API
+@ingroup RM_API
*/
/**
-@defgroup RM_SERVICES_API RM Registered Component Services API
-@ingroup RM_LLD_API
+@defgroup RM_SERVICES_API RM Services API
+@ingroup RM_API
*/
/**
-@defgroup RM_POLICY_API RM Policy modification API
-@ingroup RM_LLD_API
+@defgroup RM_OSAL_API RM OS Abstraction Layer API
+@ingroup RM_API
*/
-
/**
-@addtogroup RM_LLD_SYMBOL
+@addtogroup RM_API
@{
*/
-/** RM LLD Return And Error Codes */
-/** RM Resource Okay Return Base */
-#define RM_OK 0
-
-/** RM LLD Error Base */
-#define RM_ERROR (-64)
-/** RM LLD failed to populate internal permission tables */
-#define RM_ERROR_PERMISSION_TABLE_POPULATION_FAILED (RM_ERROR-1)
-/** RM LLD Table entry population failure */
-#define RM_ERROR_PERMISSION_TABLE_ENTRY_FAILURE (RM_ERROR-2)
-
-/** Master/Slave synchronization defines */
-/** Permissions table not valid */
-#define RM_PERMISSION_TABLE_NOT_VALID 0
-/** Permissions table valid */
-#define RM_PERMISSION_TABLE_VALID 1
-
-/**
-@}
-*/
-
-/** @addtogroup RM_LLD_DATASTRUCT
-@{
-*/
-
+/* RM return and error codes */
+/** RM successful return code */
+#define RM_OK 0
+/** RM processing requested service */
+#define RM_SERVICE_PROCESSING 1
+/** RM has approved requested service */
+#define RM_SERVICE_APPROVED 2
+/** 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 3
+
+/** 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
+
+/** 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 is greater than RM_NAME_MAX_CHARS */
+#define RM_ERROR_GRL_NS_ASSIGNMENT_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 opened */
+#define RM_ERROR_SERVICE_HANDLE_ALREADY_OPENED RM_ERROR_BASE-16
+/** The RM instance service handle has already been closed */
+#define RM_ERROR_SERVICE_HANDLE_ALREADY_CLOSED RM_ERROR_BASE-17
+/** Global Resource List (GRL) resource node contains an unknown property */
+#define RM_ERROR_GRL_UNKNOWN_RESOURCE_PROPERTY RM_ERROR_BASE-18
+/** Could not find an allocator for the specified resource */
+#define RM_ERROR_RES_ALLOCATOR_DOES_NOT_EXIST RM_ERROR_BASE-19
+/** A resource node is specified more than once in the Global Resource List (GRL) */
+#define RM_ERROR_GRL_RES_SPECIFIED_MORE_THAN_ONCE RM_ERROR_BASE-20
+/** 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-21
+/** RM server was not provided a Global Resource List (GRL) and global policy at initialization */
+#define RM_ERROR_INVALID_SERVER_CONFIGURATION RM_ERROR_BASE-22
+/** Service request type not recognized */
+#define RM_ERROR_INVALID_SERVICE_TYPE RM_ERROR_BASE-23
+/** Service request did not contain callback function. Callback function must always be provided
+ * with service request since blocking or non-blocking operations cannot be promised. */
+#define RM_ERROR_CALLBACK_NOT_PROVIDED RM_ERROR_BASE-24
+/** rmAllocPkt transport callout returned NULL for rmPkt */
+#define RM_ERROR_TRANSPORT_ALLOC_PKT_ERROR RM_ERROR_BASE-25
+/** rmSendPkt transport callout returned error when attempting to send the rmPkt */
+#define RM_ERROR_TRANSPORT_SEND_ERROR RM_ERROR_BASE-26
+/** A RM service transaction could not be created for the service request */
+#define RM_ERROR_SERVICE_TRANS_NOT_CREATED RM_ERROR_BASE-27
+/** RM service transaction could not be found in instance's transaction queue */
+#define RM_ERROR_SERVICE_TRANS_DOES_NOT_EXIST RM_ERROR_BASE-28
+/** NameServer does not exist in instance, cannot satisfy NameServer service request */
+#define RM_ERROR_NAMESERVER_DOES_NOT_EXIST RM_ERROR_BASE-29
+/** Service request to add a name to the NameServer failed */
+#define RM_ERROR_NAMESERVER_NAME_ADD_FAILED RM_ERROR_BASE-30
+/** Could not find name specified in service request in NameServer */
+#define RM_ERROR_NAMESERVER_NAME_DOES_NOT_EXIST RM_ERROR_BASE-31
+/** 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-32
+/** RM transport handle has not been registered with the RM instance */
+#define RM_ERROR_TRANSPORT_HANDLE_DOES_NOT_EXIST RM_ERROR_BASE-33
+/** RM received a packet with an unknown RM packet type */
+#define RM_ERROR_RECEIVED_INVALID_PACKET_TYPE RM_ERROR_BASE-34
+/** RM response packet does not match any requests sent from instance */
+#define RM_ERROR_PKT_RESP_DOES_NOT_MATCH_ANY_REQ RM_ERROR_BASE-35
+/** 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-36
+/** 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-37
+/** Transport registration callout function pointers specified as valid but were NULL */
+#define RM_ERROR_NULL_CALLOUTS_WHEN_VALID RM_ERROR_BASE-38
+/** Service has both a NameServer name and a base, length, or alignment specified */
+#define RM_ERROR_NS_NAME_AND_RES_VAL_CONFLICT RM_ERROR_BASE-39
+/** Instance type not recognized */
+#define RM_ERROR_INVALID_INST_TYPE RM_ERROR_BASE-40
+/** Linux DTB alias properties specified in GRL but no Linux DTB provided during server instance init */
+#define RM_ERROR_GRL_LINUX_ALIAS_BUT_NO_DTB RM_ERROR_BASE-41
+/** 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-42
+/** RM attempted to send a packet but the rmSendPkt callout was not registered */
+#define RM_ERROR_TRANSPORT_SEND_NOT_REGD RM_ERROR_BASE-43
/**
-@}
-*/
-
-/**
- * @brief Maximum number of characters in a RM instance name
+ * @brief Maximum number of characters allowed for RM instance, resource, and
+ * NameServer names.
*/
-#define RM_INST_NAME_MAX_CHARS (16)
+#define RM_NAME_MAX_CHARS (32)
/**
- * @brief RM Handle provided to application. The RM Handle is used by the
- * application to distinquish between different RM instances running on
- * the same core.
+ * @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 Service Handle provided to components that want to use RM to
- * for management of their resources.
- */
-typedef void *Rm_ServiceHandle;
-
/**
- * @brief RM Instance types
+ * @brief RM instance types
*/
typedef enum {
/** RM Server */
/** RM Client Delegate */
Rm_instType_CLIENT_DELEGATE,
/** RM Client */
- Rm_instType_CLIENT
+ Rm_instType_CLIENT,
+ /** DO NOT USE: Last type */
+ Rm_instType_LAST
} Rm_InstType;
-/**
- * @brief RM transport registration configuration structure
+/**
+ * @brief RM server initialization configurations
*/
typedef struct {
- /** Defines the remote RM instance's type */
- Rm_InstType rmRemoteInstType;
-} Rm_TransCfg;
-
-/**
- * @brief RM transport verification return value
- */
-typedef enum {
- /** RM transport paths verified as working. */
- Rm_transVerify_VERIFIED = 0,
- /** RM transport path verification error. See Rm_TransFailData structure
- * for more information */
- Rm_transVerify_ERROR
-} Rm_TransVerifyResult;
+ /** 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 If the RM transport path verification tests fail this structure
- * will be returned with specifics as to the error
+/**
+ * @brief RM client delegate (CD) initialization configurations
*/
typedef struct {
- /** Failing RM Instance Handle */
- Rm_Handle failingRmHandle;
- /** Failing transport handle */
- Rm_TransHandle failingTransHandle;
- /** If applicable: error codes received from failing transport */
- uint32_t transErrorCode;
-} Rm_TransFailData;
+ /** Pointer to a static policy used by the CD to allocate resources statically.
+ * 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. */
+ void *staticPolicy;
+} Rm_ClientDelegateCfg;
-/**
- * @brief RM pre-main allocation request information provided by the pre-main
- * startup function requesting the resource */
+/**
+ * @brief RM client initialization configurations
+ */
typedef struct {
- /** Pointer to the requested pre-main allocation resource name. The
- * name provided by the component must match the resource names
- * provided in the global resource table and allocation policies */
- char *resourceName;
- /** The pre-main allocation request resource index. Typically this is the
- * resource value. For example, queue number or semaphore number */
- uint32_t resourceIndex;
-} Rm_PreMainAllocInfo;
+ /** 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 instance initialization structure
*/
typedef struct {
- /** Pointer to RM instance name character array. The name of the RM instance must
- * be reflected exactly in the initial RM policies provided to the RM
- * tree's Servers and Client Delegates. The RM instance name is
- * used by the policy to map which instances are allowed defined
- * privileges */
- char *instName;
- /** RM instance type. Defines whether the RM instance will be initialized
- * as a RM Server, Client Delegate, or Client */
+ /** 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;
- /** [Server Parameter] Pointer to the device-wide resource list. The list
- * contains all resources available on the device available for
- * allocation. Servers running on ARM-Linux cores provide a subset
- * of the global device list for allocation. The subset is formed from
- * the global resources leftover after the Linux DTB is parsed for
- * resources reserved by Linux.
- *
- * Note: This parameter will be ignored when the instance type is either
- * Client Delegate or Client */
- void *globalResourceList;
- /** [Server/Client Delegate Paramter] Pointer to the startup allocation
- * policy. RM Servers should be initialized with the global policy
- * listing for all RM instances within the system. RM Client Delegates
- * can be initialized with their local policy, must be a subset of the
- * global policy provided to the Client Delegate's Server.
- *
- * Note: The core charged with the task of initializing the BIOS and IPC
- * components must run an RM Client Delegate with an initial policy
- * that allocates a system timer to BIOS and a HW semaphore to IPC
- *
- * Note: This parameter will be ignored when the instance type is a
- * Client
- */
- void *startupPolicy;
- /** Pointer to application implemented rmAllocPkt API. The API for the
- * provided function must match the rmAllocPkt function pointer API
- * described in rm.h */
- void *rmAllocPktFuncPtr;
- /** Pointer to application implemented rmFreePkt API. The API for the
- * provided function must match the rmFreePkt function pointer API
- * described in rm.h */
- void *rmFreePktFuncPtr;
- /** Pointer to application implemented rmSend API. The API for the
- * provided function must match the rmSend function pointer API
- * described in rm.h */
- void *rmSendFuncPtr;
- /** Pointer to application implemented rmReceive API. The API for the
- * provided function must match the rmReceive function pointer API
- * described in rm.h */
- void *rmReceiveFuncPtr;
- /** Pointer to application implemented rmNumPktsReceived API. The API for
- * the provided function must match the rmNumPktsReceived function
- * pointer API described in rm.h */
- void *rmNumPktsReceivedFuncPtr;
+ /** Instance-type specific configurations */
+ union {
+ /** #Rm_ServerCfg */
+ Rm_ServerCfg serverCfg;
+ /** #Rm_ClientDelegateCfg */
+ Rm_ClientDelegateCfg cdCfg;
+ /** #Rm_ClientCfg */
+ Rm_ClientCfg clientCfg;
+ } instCfg;
} Rm_InitCfg;
-
-/**
- * @b Description
- * @n
- * This function initializes a RM instance.
- *
- * IMPORTANT: Rm_init must be called prior to any other component startup
- * APIs (BIOS_start, Ipc_start, etc).
- *
- * @param[in] *initCfg
- * Pointer to structure containing the initialization information for
- * this RM instance.
- *
- * @retval
- * Success - non-zero Rm_Handle returned.
- * @retval
- * Failure - NULL Rm_handle returned.
- */
-Rm_Handle Rm_init(Rm_InitCfg *initCfg);
-
/**
* @b Description
* @n
- * Non-blocking function used by RTSC pre-main startup functions to
- * allocate RM resources for usage. Pre-main allocated resources will be
- * validated by RM against a memory-mapped startup resource policy.
- * Pre-main allocation of unauthorized resources will result in a system
- * exception.
- *
- * Note: Resource pre-main allocations can only occur on a core that is
- * running a RM Server or Client Delegate that has a startup policy
- * allowing the allocation of pre-main resources
+ * This function prints 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.
*
- * @param[in] preMainAllocInfo
- * Resource pre-main allocation structure that provides details of the
- * resource requested from RM for preallocation
+ * This function only prints resources when provided the server handle
+ * since the server stores all the resource and NameServer
+ * data structures.
*
- * @retval
- * Success - 0 - Resource pre-main allocation request okay.
- * @retval
- * Failure - non-zero - Resource pre-main allocation request error.
+ * @param[in] rmServerHandle
+ * Server instance handle.
*/
-Rm_Result Rm_preMainAllocResource(Rm_PreMainAllocInfo
- *preMainAllocInfo);
-
+void Rm_printResourceStatus(Rm_Handle rmServerHandle);
/**
* @b Description
* @n
- * This function returns a RM service handle to the application to
- * provide to software components (LLDs, BIOS, etc) that want to use RM.
+ * 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
- * RM instance handle. Used to return a ServiceHandle from the proper
- * RM instance in cases where there are multiple RM instances running on
- * a single core.
- *
- * @retval
- * Success - RM Service Handle. Used as an input parameter for
- * component startCfg functions.
- * @retval
- * Failure - NULL
+ * Instance handle.
*/
-Rm_ServiceHandle Rm_getServiceHandle(Rm_Handle rmHandle);
+void Rm_printInstanceStatus(Rm_Handle rmHandle);
/**
* @b Description
* @n
- * This function is used to register transports with RM for sending and
- * receiving packets between RM instances over application transport
- * data paths.
+ * 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.
*
- * @param[in] rmHandle
- * RM instance to which the transport will be registered. Used internally
- * by RM if there are more than one RM instances per core.
- *
- * @param[in] transCfg
- * Transport registration configuration structure. Provides information
- * regarding the application transports remote entity. For example,
- * if the transCfg structure specifies the remote type is the RM Server
- * RM will know any Server requests must be pushed to the application
- * transport API with the transport handle returned to the application
+ * If any errors are encountered during the initialization process
+ * the Rm_Handle returned will be NULL.
*
- * @retval
- * Success - non-NULL RM transport handle. No two transport handles
- * returned by RM should be the same.
- * @retval
- * Failure - NULL
- */
-Rm_TransHandle Rm_registerTransport (Rm_Handle rmHandle,
- Rm_TransCfg *transCfg);
-
-/**
- * @b Description
- * @n
- * This function places the selected RM instance into the transport
- * verification state. When all RM instances in the tree are placed
- * in the transport verification state a transport path verification
- * test will take place to verify the application transport paths between
- * all RM tree nodes are connected correctly.
+ * @param[in] initCfg
+ * Pointer to the instance initialization structure.
*
- * Note: This API should not be called until all transport have been
- * registered with RM
- *
- * @param[in] rmHandle
- * Which RM instance to begin the transport verification process
- *
- * @param[in] timeout
- * Number of ______ (cycles, usec, msec???) to wait before signaling a
- * transport path verification timeout
- *
- * @param[in] failData
- * Pointer to an empty Rm_TransFailData structure. If the transport
- * verification process fails this structure will return with transport
- * failure data
+ * @param[out] result
+ * Pointer to a signed int used to return any errors encountered during
+ * the instance initialization process.
*
* @retval
- * Success - 0 - Transport Verification succeeded
+ * Success - Rm_Handle for instance and result = #RM_OK
* @retval
- * Failure - non-0 - Transport Verification failed
+ * Failure - NULL Rm_Handle and result < #RM_OK
*/
-Rm_TransVerifyResult Rm_verifyTransport (Rm_Handle, uint32_t timeout,
- Rm_TransFailData *failData);
+Rm_Handle Rm_init(const Rm_InitCfg *initCfg, int32_t *result);
/**
* @b Description
* @n
- * The function is used to get the version information of the RM.
+ * The function is used to get the version information of RM.
*
* @retval
* Version Information.
/**
* @b Description
* @n
- * The function is used to get the version string for the RM.
+ * The function is used to get the version string for RM.
*
* @retval
* Version String.
*/
const char* Rm_getVersionStr (void);
+/**
+@}
+*/
+
#ifdef __cplusplus
}
#endif