index 87d6920500b5210e501fc402993c282fe62a380e..4203e0c248c1471ac2b0c706f5dbbb654816d1fd 100644 (file)
--- a/rm.h
+++ b/rm.h
/* Standard includes */
#include <stdint.h>
-/* RM version */
-#include <ti/drv/rm/rmver.h>
-
/** @mainpage Resource Manager
*
* @section intro Introduction
*
- * The Resource Manager low level driver (RM LLD) is designed to provide initialization and permissions checking
- *
+ * 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_API as a master group in Doxygen format and add all RM API
/** @} */
/**
-@defgroup RM_TRANSPORT_API RM Transport-Layer API
+@defgroup RM_TRANSPORT_API RM Transport API
@ingroup RM_API
*/
/**
-@defgroup RM_SERVICES_API RM Registered Component Services API
+@defgroup RM_SERVICES_API RM Services API
@ingroup RM_API
*/
/**
@{
*/
-/** RM return and Error Codes */
+/* RM return and error codes */
/** RM successful return code */
#define RM_OK 0
/** RM processing requested service */
* are in sync */
#define RM_SERVICE_DENIED_RM_INSTANCE_LOCKED RM_SERVICE_DENIED_BASE+16
-/** See libfdt.h for error codes -1 through -13 */
+/** Start of libfdt.h error codes */
#define RM_ERROR_LIBFDT_START (-1)
-/** See libfdt.h for error codes -1 through -13 */
+/** End of libfdt.h error codes */
#define RM_ERROR_LIBFDT_END (-13)
-/** RM Error Base */
+/** 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
#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 */
+/** 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 not Linux DTB provided during server instance init */
+/** 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 allowed for RM instance, resource, and
#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 Instance types
+ * @brief RM instance types
*/
typedef enum {
/** RM Server */
Rm_instType_LAST
} Rm_InstType;
+/**
+ * @brief RM server initialization configurations
+ */
typedef struct {
- /** [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 */
+ /** 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;
- /** [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 */
+ /** 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;
- /** [Server 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
- */
+ /** 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 {
- /** static policy used for pre-main allocation of resources. Resources given
- * in the static will be verified against the global policy once the RM
- * system is fully initialized */
+ /** 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 {
- /** static policy used for pre-main allocation of resources. Resources given
- * in the static will be verified against the global policy once the RM
- * system is fully initialized */
+ /** 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;
+ /** 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 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);
-void Rm_printResourceStatus(Rm_Handle *rmHandle);
-Rm_Handle Rm_init(Rm_InitCfg *initCfg, int32_t *result);
+/**
+ * @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_printInstanceStatus(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.
+ *
+ * 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
+ * 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