index 6e209076440f1ac2e9db8342c6f02fdf71fdd535..d74afb4c4b64f0b8d77c262dd9dbe8735c31126b 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
+/* Standard includes */
+#include <stdint.h>
+
/* RM version */
#include <ti/drv/rm/rmver.h>
*
* @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 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 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 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.
*
- * 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.
+ * 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.
*
- * 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.
+ * 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.
*
- * 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
+ * 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.
*
- * 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
- *
+ * 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_API
+@{
*/
-/* TODO: CANT CONFLICT WITH OTHER ERROR CODES INCLUDING LIBFDT */
-#define RM_INIT_OK 0
-#define RM_INIT_ERROR_INSTANCE_NAME_TOO_BIG -256
-#define RM_INIT_ERROR_POLICY_NO_VALID_INSTANCES_DEFINED -257
-#define RM_INIT_ERROR_POLICY_UNKNOWN_INSTANCE -258
-#define RM_INIT_ERROR_POLICY_PERMISSION_SYNTAX_ERROR -259
-#define RM_INIT_ERROR_POLICY_UNKNOWN_RESOURCE -260
-#define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_MORE_THAN_ONE_INSTANCE_GROUP -261
-#define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_MORE_THAN_ONE_ASSIGNMENT_CHAR -262
-#define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_INVALID_PERM_CHAR -263
-#define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_PERM_CHAR_WITHOUT_ASSIGN_CHAR -264
-#define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_INVALID_CHAR_ON_RIGHT_WITH_ASSINMENT_ON_LEFT -265
-#define RM_INIT_ERROR_PREMAIN_INST_AND_POSTMAIN_INST_NAMES_DONT_MATCH -266
-#define RM_INIT_ERROR_POLICY_UNKNOWN_RESOURCE_PROPERTY -267
+/* 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 both a NameServer name and a base, length, or alignment */
+#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_INSTANCE_NAME_MAX_CHARS (32)
+#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;
-typedef void *Rm_PreMainHandle;
-
/**
- * @brief RM Instance types
+ * @brief RM instance types
*/
typedef enum {
/** RM Server */
Rm_instType_SERVER = 0,
/** RM Client Delegate */
- Rm_instType_CLIENT_DELEGATE = 1,
+ Rm_instType_CLIENT_DELEGATE,
/** RM Client */
- Rm_instType_CLIENT = 2
+ Rm_instType_CLIENT,
+ /** DO NOT USE: Last type */
+ Rm_instType_LAST
} Rm_InstType;
+/**
+ * @brief RM 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 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 client initialization configurations
+ */
typedef struct {
- char *instName;
- Rm_InstType instType;
- void *startupPolicyDtb;
-} Rm_PreMainInitCfg;
+ /** 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 */
+ /** 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*/
char *instName;
- /** RM instance type. Defines whether the RM instance will be initialized
- * as a RM Server, Client Delegate, or Client */
+ /** 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 Parameter When Running on ARM Linux] Pointer to the Linux DTB.
- * The Linux DTB will be parsed for all tracked resources reserved for use
- * by Linux.
- *
- * Note: This parameter will be ignored when the instance type is either
- * Client Delegate or Client */
- void *linuxDtb;
- /** [Server/Client Delegate Paramter] Pointer to the 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 *policy;
+ /** Instance-type specific configurations */
+ union {
+ /** #Rm_ServerCfg */
+ Rm_ServerCfg serverCfg;
+ /** #Rm_ClientDelegateCfg */
+ Rm_ClientDelegateCfg cdCfg;
+ /** #Rm_ClientCfg */
+ Rm_ClientCfg clientCfg;
+ } instCfg;
} Rm_InitCfg;
-/* TESTING PURPOSES: SERVER ONLY */
-void Rm_printResourceStatus(Rm_Handle *rmHandle);
+/**
+ * @b Description
+ * @n
+ * 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.
+ *
+ * This function only prints resources when provided the server handle
+ * since the server stores all the resource and NameServer
+ * data structures.
+ *
+ * @param[in] rmServerHandle
+ * Server instance handle.
+ */
+void Rm_printResourceStatus(Rm_Handle rmServerHandle);
-Rm_PreMainHandle Rm_preMainInit(Rm_PreMainInitCfg *preMainInitCfg, int32_t *result);
-/** [Server/Client Delegate Parameter] Pre-main allocation handle used to
- * by application to request resources prior to main via the startup policy
- * The preMainHandle will be used to validate the resources allocated prior
- * to main
+/**
+ * @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.
*/
-int32_t Rm_preMainHandleValidateAndDelete(Rm_Handle rmHandle, Rm_PreMainHandle rmPreMainHandle);
+void Rm_printInstanceStatus(Rm_Handle rmHandle);
/**
* @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).
+ * 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] *initCfg
- * Pointer to structure containing the initialization information for
- * this RM instance.
+ * If any errors are encountered during the initialization process
+ * the Rm_Handle returned will be NULL.
*
- * @param[in] *result
- * Pointer to a uint32_t that will contain the result of the RM
- * intialization and handle creation. Any errors encountered will be
- * returned via this pointer.
+ * @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 - non-zero Rm_Handle returned.
+ * Success - Rm_Handle for instance and result = #RM_OK
* @retval
- * Failure - NULL Rm_handle returned.
+ * Failure - NULL Rm_Handle and result < #RM_OK
*/
Rm_Handle Rm_init(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