/** * @file rm.h * * @brief * This is the Resource Manager include file. * * \par * ============================================================================ * @n (C) Copyright 2012, Texas Instruments, Inc. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the * distribution. * * Neither the name of Texas Instruments Incorporated nor the names of * its contributors may be used to endorse or promote products derived * from this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * * \par */ #ifndef RM_H_ #define RM_H_ #ifdef __cplusplus extern "C" { #endif /* RM version */ #include /** @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 <>_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 * */ /* Define RM_LLD_API as a master group in Doxygen format and add all RM LLD API definitions to this group. */ /** @defgroup RM_LLD_API RM LLD Module API * @{ */ /** @} */ /** @defgroup RM_TRANSPORT_API RM Transport-Layer API @ingroup RM_LLD_API */ /** @defgroup RM_SERVICES_API RM Registered Component Services API @ingroup RM_LLD_API */ /** @defgroup RM_POLICY_API RM Policy modification API @ingroup RM_LLD_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 - 261 /** * @brief Maximum number of characters in a RM instance name */ #define RM_INSTANCE_NAME_MAX_CHARS (24) /** * @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 Instance types */ typedef enum { /** RM Server */ Rm_instType_SERVER = 0, /** RM Client Delegate */ Rm_instType_CLIENT_DELEGATE = 1, /** RM Client */ Rm_instType_CLIENT = 2 } Rm_InstType; /** * @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 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; } Rm_InitCfg; /* TESTING PURPOSES: SERVER ONLY */ void Rm_printResourceStatus(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). * * @param[in] *initCfg * Pointer to structure containing the initialization information for * this RM instance. * * @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. * * @retval * Success - non-zero Rm_Handle returned. * @retval * Failure - NULL Rm_handle returned. */ 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. * * @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 } #endif #endif /* RM_H_ */