rm.h

   1 /**
   2  *   @file  rm.h
   3  *
   4  *   @brief
   5  *      This is the Resource Manager include file.
   6  *
   7  *  \par
   8  *  ============================================================================
   9  *  @n   (C) Copyright 2012, Texas Instruments, Inc.
  10  *
  11  *  Redistribution and use in source and binary forms, with or without
  12  *  modification, are permitted provided that the following conditions
  13  *  are met:
  14  *
  15  *    Redistributions of source code must retain the above copyright
  16  *    notice, this list of conditions and the following disclaimer.
  17  *
  18  *    Redistributions in binary form must reproduce the above copyright
  19  *    notice, this list of conditions and the following disclaimer in the
  20  *    documentation and/or other materials provided with the
  21  *    distribution.
  22  *
  23  *    Neither the name of Texas Instruments Incorporated nor the names of
  24  *    its contributors may be used to endorse or promote products derived
  25  *    from this software without specific prior written permission.
  26  *
  27  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  28  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  29  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  30  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  31  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  32  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  33  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  34  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  35  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  36  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  37  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  38  *
  39  *  \par
  40 */
  41
  42 #ifndef RM_H_
  43 #define RM_H_
  44
  45 #ifdef __cplusplus
  46 extern "C" {
  47 #endif
  48
  49 /* RM version */
  50 #include <ti/drv/rm/rmver.h>
  51
  52 /**  @mainpage Resource Manager
  53  *
  54  *   @section intro  Introduction
  55  *
  56  *   The Resource Manager low level driver (RM LLD) is designed to provide initialization and permissions checking
  57  *   for LLD resources.  A system integrator can specify DSP permissions for LLD resources within the system.
  58  *   The resource permissions are stored in the RM LLD and used to validate resource requests from supported LLDs.
  59  *   Currently, the RM LLD supports permissions for the following LLDs
  60  *      - QMSS
  61  *      - CPPI
  62  *      - PA
  63  *    For information on the specific resources supported with each LLD please see @ref RM_LLD_RESOURCE_TABLE.
  64  *
  65  *    The system integrator must specify the supported LLD resource permissions for all DSPs prior to compile time.
  66  *    An array of @ref Rm_Resource objects must be created.  Each @ref Rm_Resource entry in the array specifies
  67  *    a resource type, start and end range for the resource, and the initialization and usage permissions for the
  68  *    resource for each DSP.  For an example resource table definitions please see the @ref rmResourceTable array
  69  *    defined in the resource_table\ directory.  This resource table assigns full initialization and usage permissions
  70  *    to all DSPs for all supported resources.  Please note that the resouce table must start with the
  71  *    @ref RM_RESOURCE_MAGIC_NUMBER entry and end with the @ref RM_RESOURCE_FINAL_ENTRY.  These
  72  *    first and last entries are used the RM LLD to validate and parse the resource table.
  73  *
  74  *    The RM LLD must be initialized and started prior to all supported LLD initialization and start routines.  The
  75  *    @ref Rm_init function should be invoked, and passed a pointer to the integrator defined resource table, on the
  76  *    master DSP core in the system.  All other DSP cores should invoke the @ref Rm_start API.  The @ref Rm_init
  77  *    function first initializes the internal permission tables to deny all DSPs access to all resources.  Next the
  78  *    @ref Rm_init function parses the resource table provided and copies all specified permissions into the internal
  79  *    tables.  When the permission transfer completes the @ref Rm_init function writes a global synchronization
  80  *    object which the @ref Rm_start functions are spinning on.  The slave cores that have invoked @ref Rm_start
  81  *    will stop spinning once the global synchronization has been written.  At this time @ref Rm_start will invalidate
  82  *    all internal permission tables so that no further cache invalidate operations need to be performed when
  83  *    checking resource permissions in the data path. The upfront cache invalidate operation is possible because
  84  *    the RM LLD does not allow dynamic resource permission modifications. The permissions defined by the system
  85  *    integrator and loaded during RM initialization are static throughout the system up-time.
  86  *
  87  *    The RM LLD must be registered with a supported LLD in order for the supported LLD to perform resource
  88  *    permission checks.  If the RM LLD is not registered with a supported LLD the LLD will operate as if the RM LLD
  89  *    is not there.  This maintains full backwards compatability with existing applications not using the RM LLD.  In order
  90  *    to register the RM LLD with supported LLDs the following steps should be taken
  91  *      - Get a @ref Rm_Handle via the @ref Rm_getHandle API on each DSP that uses the RM LLD.
  92  *      - Register the RM LLD with the supported LLDs by passing the @ref Rm_Handle to the
  93  *          LLD's <<LLD name>>_startCfg API.  Again, this should be performed on all DSP cores using the RM LLD.
  94  *          Note: The master core for the QMSS LLD should have the @ref Rm_Handle registered via the Qmss_init API.
  95  *    After registering the RM LLD with supported LLDs all supported LLD resources covered by the RM LLD will invoke
  96  *    permission check callouts to the RM.  A permission denied or approved response will be given back to the
  97  *    invoking LLD based on the permissions stored in the RM LLD for the resource.
  98  *
  99  *    All internal RM LLD permission tables are placed into a single memory section called ".rm".  This memory section
 100  *    MUST be placed in shared memory (MSMC or DDR).  The permission tables are shared between all DSPs utilizing
 101  *    the RM LLD.
 102  *
 103  *    In summary, the initialization flow if the RM LLD is to be utilized should look like the following:
 104  *
 105  *    Master DSP Core:
 106  *      - Call @ref Rm_init passing in the system integrator defined resource table
 107  *      - Call @ref Rm_getHandle
 108  *      - Call supported LLD _init or _create functions (for QMSS pass the @ref Rm_Handle inside the
 109  *          Qmss_GlobalConfigParams structure)
 110  *      - Call supported LLD _startCfg functions passing the @ref Rm_Handle as an argument
 111  *
 112  *    Slave DSP Cores:
 113  *      - Call @ref Rm_start
 114  *      - Call @ref Rm_getHandle
 115  *      - Call supported LLD _start functions (if supported)
 116  *      - Call supported LLD _startCfg functions passing the @ref Rm_Handle as an argument
 117  *
 118  */
 119
 120 /* Define RM_LLD_API as a master group in Doxygen format and add all RM LLD API
 121    definitions to this group. */
 122 /** @defgroup RM_LLD_API RM LLD Module API
 123  *  @{
 124  */
 125 /** @} */
 126
 127 /**
 128 @defgroup RM_TRANSPORT_API  RM Transport-Layer API
 129 @ingroup RM_LLD_API
 130 */
 131 /**
 132 @defgroup RM_SERVICES_API  RM Registered Component Services API
 133 @ingroup RM_LLD_API
 134 */
 135 /**
 136 @defgroup RM_POLICY_API  RM Policy modification API
 137 @ingroup RM_LLD_API
 138 */
 139
 140 /* TODO: CANT CONFLICT WITH OTHER ERROR CODES INCLUDING LIBFDT */
 141 #define RM_INIT_OK 0
 142 #define RM_INIT_ERROR_INSTANCE_NAME_TOO_BIG -256
 143 #define RM_INIT_ERROR_POLICY_NO_VALID_INSTANCES_DEFINED -257
 144 #define RM_INIT_ERROR_POLICY_UNKNOWN_INSTANCE -258
 145 #define RM_INIT_ERROR_POLICY_PERMISSION_SYNTAX_ERROR -259
 146 #define RM_INIT_ERROR_POLICY_UNKNOWN_RESOURCE -260
 147 #define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_MORE_THAN_ONE_INSTANCE_GROUP -261
 148 #define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_MORE_THAN_ONE_ASSIGNMENT_CHAR -262
 149 #define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_INVALID_PERM_CHAR -263
 150 #define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_PERM_CHAR_WITHOUT_ASSIGN_CHAR -264
 151 #define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_INVALID_CHAR_ON_RIGHT_WITH_ASSINMENT_ON_LEFT -265
 152
 153 /**
 154  * @brief Maximum number of characters in a RM instance name
 155  */
 156 #define RM_INSTANCE_NAME_MAX_CHARS (32)
 157
 158 /**
 159  * @brief RM Handle provided to application.  The RM Handle is used by the
 160  *        application to distinquish between different RM instances running on
 161  *        the same core.
 162  */
 163 typedef void *Rm_Handle;
 164
 165 /**
 166  * @brief RM Instance types
 167  */
 168 typedef enum {
 169     /** RM Server */
 170     Rm_instType_SERVER = 0,
 171     /** RM Client Delegate */
 172     Rm_instType_CLIENT_DELEGATE = 1,
 173     /** RM Client */
 174     Rm_instType_CLIENT = 2
 175 } Rm_InstType;
 176
 177 /**
 178  * @brief RM instance initialization structure
 179  */
 180 typedef struct {
 181     /** Pointer to RM instance name character array.  The name of the RM instance must
 182      *  be reflected exactly in the initial RM policies provided to the RM
 183      *  tree's Servers and Client Delegates.  The RM instance name is
 184      *  used by the policy to map which instances are allowed defined
 185      *  privileges */
 186     char *instName;
 187     /** RM instance type.  Defines whether the RM instance will be initialized
 188      *  as a RM Server, Client Delegate, or Client */
 189     Rm_InstType instType;
 190     /** [Server Parameter] Pointer to the device-wide resource list.  The list
 191      *  contains all resources available on the device available for
 192      *  allocation.  Servers running on ARM-Linux cores provide a subset
 193      *  of the global device list for allocation.  The subset is formed from
 194      *  the global resources leftover after the Linux DTB is parsed for
 195      *  resources reserved by Linux.
 196      *
 197      *  Note: This parameter will be ignored when the instance type is either
 198      *  Client Delegate or Client */
 199     void *globalResourceList;
 200     /** [Server Parameter When Running on ARM Linux] Pointer to the Linux DTB.
 201      *  The Linux DTB will be parsed for all tracked resources reserved for use
 202      *  by Linux.
 203      *
 204      *  Note: This parameter will be ignored when the instance type is either
 205      *  Client Delegate or Client */
 206     void *linuxDtb;
 207     /** [Server/Client Delegate Paramter] Pointer to the allocation
 208      *  policy.  RM Servers should be initialized with the global policy
 209      *  listing for all RM instances within the system.  RM Client Delegates
 210      *  can be initialized with their local policy, must be a subset of the
 211      *  global policy provided to the Client Delegate's Server.
 212      *
 213      *  Note: The core charged with the task of initializing the BIOS and IPC
 214      *        components must run an RM Client Delegate with an initial policy
 215      *        that allocates a system timer to BIOS and a HW semaphore to IPC
 216      *
 217      *  Note: This parameter will be ignored when the instance type is a
 218      *        Client
 219      */
 220     void *policy;
 221 } Rm_InitCfg;
 222
 223 /* TESTING PURPOSES: SERVER ONLY */
 224 void Rm_printResourceStatus(Rm_Handle *rmHandle);
 225
 226 /**
 227  *  @b Description
 228  *  @n
 229  *      This function initializes a RM instance.
 230  *
 231  *      IMPORTANT: Rm_init must be called prior to any other component startup
 232  *                 APIs (BIOS_start, Ipc_start, etc).
 233  *
 234  *  @param[in]  *initCfg
 235  *      Pointer to structure containing the initialization information for
 236  *      this RM instance.
 237  *
 238  *  @param[in]  *result
 239  *      Pointer to a uint32_t that will contain the result of the RM
 240  *      intialization and handle creation.  Any errors encountered will be
 241  *      returned via this pointer.
 242  *
 243  *  @retval
 244  *      Success - non-zero Rm_Handle returned.
 245  *  @retval
 246  *      Failure - NULL Rm_handle returned.
 247  */
 248 Rm_Handle Rm_init(Rm_InitCfg *initCfg, int32_t *result);
 249
 250 /**
 251  *  @b Description
 252  *  @n
 253  *      The function is used to get the version information of the RM.
 254  *
 255  *  @retval
 256  *      Version Information.
 257  */
 258 uint32_t Rm_getVersion (void);
 259
 260 /**
 261  *  @b Description
 262  *  @n
 263  *      The function is used to get the version string for the RM.
 264  *
 265  *  @retval
 266  *      Version String.
 267  */
 268 const char* Rm_getVersionStr (void);
 269
 270 #ifdef __cplusplus
 271 }
 272 #endif
 273
 274 #endif /* RM_H_ */
 275