Checking in RMv2 progress
[keystone-rtos/rm-lld.git] / rm.h
diff --git a/rm.h b/rm.h
index 771bd7bcbb6cefaabfc924158da4be102bacb560..4f59095d17ad16d49e458077a66da921c863bece 100644 (file)
--- a/rm.h
+++ b/rm.h
@@ -2,7 +2,7 @@
  *   @file  rm.h
  *
  *   @brief   
- *      This is the RM LLD include file.
+ *      This is the Resource Manager include file.
  *
  *  \par
  *  ============================================================================
 extern "C" {
 #endif
 
-/* RM resource table defs include file */
+/* RM version */
 #include <ti/drv/rm/rmver.h>
-#include <ti/drv/rm/rm_public_lld.h>
-#include <ti/drv/rm/resource_table_defs.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>
 
-/**  @mainpage Resource Manager Low Level Driver
+/**  @mainpage Resource Manager
  *
  *   @section intro  Introduction
  *
@@ -127,34 +131,19 @@ extern "C" {
 /** @} */
 
 /**
-@defgroup RM_LLD_SYMBOL  RM Low Level Driver Symbols Defined
+@defgroup RM_TRANSPORT_API  RM Transport-Layer API
 @ingroup RM_LLD_API
 */
 /**
-@defgroup RM_LLD_ENUM  RM Low Level Driver Enums
+@defgroup RM_SERVICES_API  RM Registered Component Services API
 @ingroup RM_LLD_API
 */
 /**
-@defgroup RM_LLD_RESOURCE_TABLE  RM LLD Resource Table Definition Symbols and Structures
-@ingroup RM_LLD_API
-*/
-/**
-@defgroup RM_LLD_SHARED_RESOURCES  RM LLD ARM and DSP Shared Resources
-@ingroup RM_LLD_API
-*/
-/**
-@defgroup RM_LLD_DATASTRUCT  RM Low Level Driver Data Structures
-@ingroup RM_LLD_API
-*/
-/**
-@defgroup RM_LLD_FUNCTION  RM Low Level Driver Functions
-@ingroup RM_LLD_API
-*/
-/**
-@defgroup RM_LLD_OSAL  RM Low Level Driver OSAL Functions
+@defgroup RM_POLICY_API  RM Policy modification API
 @ingroup RM_LLD_API
 */
 
+
 /**
 @addtogroup RM_LLD_SYMBOL
 @{
@@ -185,21 +174,288 @@ extern "C" {
 @{ 
 */
 
+
+/** 
+@} 
+*/
+
+/** 
+ * @brief Maximum number of characters in a RM instance name
+ */
+#define RM_INST_NAME_MAX_CHARS (16)
+
 /** 
- * @brief RM Handle for LLDs
+ * @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.
  */
 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
+ */
+typedef enum {
+    /** RM Server */
+    Rm_instType_SERVER = 0,
+    /** RM Client Delegate */
+    Rm_instType_CLIENT_DELEGATE,
+    /** RM Client */
+    Rm_instType_CLIENT
+} Rm_InstType;
+
+/** 
+ * @brief RM transport registration configuration structure
+ */
+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;
+
+/** 
+ * @brief If the RM transport path verification tests fail this structure
+ *        will be returned with specifics as to the error
+ */
+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;
+
+/** 
+ * @brief RM pre-main allocation request information provided by the pre-main 
+ *        startup function requesting the resource */
+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;
+
+/** 
+ * @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 */
+    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;
+} Rm_InitCfg;
 
-/* Exported functions available to application */
-extern Rm_Result Rm_init (const Rm_Resource *rmResourceTable);
-extern Rm_Result Rm_start (void);
-extern Rm_Handle Rm_getHandle(void);
-extern uint32_t Rm_getVersion (void);
-extern const char* Rm_getVersionStr (void);
+
+/**
+ *  @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
+ *
+ *  @param[in]  preMainAllocInfo
+ *      Resource pre-main allocation structure that provides details of the 
+ *      resource requested from RM for preallocation
+ *
+ *  @retval
+ *      Success - 0 - Resource pre-main allocation request okay.
+ *  @retval
+ *      Failure - non-zero - Resource pre-main allocation request error.
+ */
+Rm_Result Rm_preMainAllocResource(Rm_PreMainAllocInfo 
+                                                   *preMainAllocInfo);
+
+
+/**
+ *  @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.
+ *
+ *  @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
+ */
+Rm_ServiceHandle Rm_getServiceHandle(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.
+ *
+ *  @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
+ *
+ *  @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.
+ *
+ *      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
+ *
+ *  @retval
+ *      Success - 0 - Transport Verification succeeded
+ *  @retval
+ *      Failure - non-0 - Transport Verification failed
+ */
+Rm_TransVerifyResult Rm_verifyTransport (Rm_Handle, uint32_t timeout, 
+                                         Rm_TransFailData *failData);
+
+/**
+ *  @b Description
+ *  @n  
+ *      The function is used to get the version information of the RM.
+ *
+ *  @retval
+ *      Version Information.
+ */
+uint32_t Rm_getVersion (void);
+
+/**
+ *  @b Description
+ *  @n  
+ *      The function is used to get the version string for the RM.
+ *
+ *  @retval
+ *      Version String.
+ */
+const char* Rm_getVersionStr (void);
 
 #ifdef __cplusplus
 }