Base directory structure for new RM
[keystone-rtos/rm-lld.git] / rm.h
1 /**
2  *   @file  rm.h
3  *
4  *   @brief   
5  *      This is the RM LLD 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 */
42 #ifndef RM_H_
43 #define RM_H_
45 #ifdef __cplusplus
46 extern "C" {
47 #endif
49 /* RM resource table defs include file */
50 #include <ti/drv/rm/rmver.h>
51 #include <ti/drv/rm/rm_public_lld.h>
52 #include <ti/drv/rm/resource_table_defs.h>
54 /**  @mainpage Resource Manager Low Level Driver
55  *
56  *   @section intro  Introduction
57  *
58  *   The Resource Manager low level driver (RM LLD) is designed to provide initialization and permissions checking
59  *   for LLD resources.  A system integrator can specify DSP permissions for LLD resources within the system.
60  *   The resource permissions are stored in the RM LLD and used to validate resource requests from supported LLDs.
61  *   Currently, the RM LLD supports permissions for the following LLDs
62  *      - QMSS
63  *      - CPPI
64  *      - PA
65  *    For information on the specific resources supported with each LLD please see @ref RM_LLD_RESOURCE_TABLE.
66  *
67  *    The system integrator must specify the supported LLD resource permissions for all DSPs prior to compile time.
68  *    An array of @ref Rm_Resource objects must be created.  Each @ref Rm_Resource entry in the array specifies
69  *    a resource type, start and end range for the resource, and the initialization and usage permissions for the
70  *    resource for each DSP.  For an example resource table definitions please see the @ref rmResourceTable array
71  *    defined in the resource_table\ directory.  This resource table assigns full initialization and usage permissions
72  *    to all DSPs for all supported resources.  Please note that the resouce table must start with the
73  *    @ref RM_RESOURCE_MAGIC_NUMBER entry and end with the @ref RM_RESOURCE_FINAL_ENTRY.  These
74  *    first and last entries are used the RM LLD to validate and parse the resource table.
75  *
76  *    The RM LLD must be initialized and started prior to all supported LLD initialization and start routines.  The
77  *    @ref Rm_init function should be invoked, and passed a pointer to the integrator defined resource table, on the
78  *    master DSP core in the system.  All other DSP cores should invoke the @ref Rm_start API.  The @ref Rm_init 
79  *    function first initializes the internal permission tables to deny all DSPs access to all resources.  Next the 
80  *    @ref Rm_init function parses the resource table provided and copies all specified permissions into the internal
81  *    tables.  When the permission transfer completes the @ref Rm_init function writes a global synchronization
82  *    object which the @ref Rm_start functions are spinning on.  The slave cores that have invoked @ref Rm_start
83  *    will stop spinning once the global synchronization has been written.  At this time @ref Rm_start will invalidate 
84  *    all internal permission tables so that no further cache invalidate operations need to be performed when 
85  *    checking resource permissions in the data path. The upfront cache invalidate operation is possible because 
86  *    the RM LLD does not allow dynamic resource permission modifications. The permissions defined by the system
87  *    integrator and loaded during RM initialization are static throughout the system up-time.
88  *
89  *    The RM LLD must be registered with a supported LLD in order for the supported LLD to perform resource 
90  *    permission checks.  If the RM LLD is not registered with a supported LLD the LLD will operate as if the RM LLD
91  *    is not there.  This maintains full backwards compatability with existing applications not using the RM LLD.  In order
92  *    to register the RM LLD with supported LLDs the following steps should be taken
93  *      - Get a @ref Rm_Handle via the @ref Rm_getHandle API on each DSP that uses the RM LLD.
94  *      - Register the RM LLD with the supported LLDs by passing the @ref Rm_Handle to the 
95  *          LLD's <<LLD name>>_startCfg API.  Again, this should be performed on all DSP cores using the RM LLD.
96  *          Note: The master core for the QMSS LLD should have the @ref Rm_Handle registered via the Qmss_init API.
97  *    After registering the RM LLD with supported LLDs all supported LLD resources covered by the RM LLD will invoke
98  *    permission check callouts to the RM.  A permission denied or approved response will be given back to the
99  *    invoking LLD based on the permissions stored in the RM LLD for the resource.
100  *
101  *    All internal RM LLD permission tables are placed into a single memory section called ".rm".  This memory section
102  *    MUST be placed in shared memory (MSMC or DDR).  The permission tables are shared between all DSPs utilizing
103  *    the RM LLD.
104  *
105  *    In summary, the initialization flow if the RM LLD is to be utilized should look like the following:
106  *    
107  *    Master DSP Core:
108  *      - Call @ref Rm_init passing in the system integrator defined resource table
109  *      - Call @ref Rm_getHandle
110  *      - Call supported LLD _init or _create functions (for QMSS pass the @ref Rm_Handle inside the 
111  *          Qmss_GlobalConfigParams structure)
112  *      - Call supported LLD _startCfg functions passing the @ref Rm_Handle as an argument
113  *
114  *    Slave DSP Cores:
115  *      - Call @ref Rm_start
116  *      - Call @ref Rm_getHandle
117  *      - Call supported LLD _start functions (if supported)
118  *      - Call supported LLD _startCfg functions passing the @ref Rm_Handle as an argument
119  *  
120  */
121  
122 /* Define RM_LLD_API as a master group in Doxygen format and add all RM LLD API 
123    definitions to this group. */
124 /** @defgroup RM_LLD_API RM LLD Module API
125  *  @{
126  */
127 /** @} */
129 /**
130 @defgroup RM_LLD_SYMBOL  RM Low Level Driver Symbols Defined
131 @ingroup RM_LLD_API
132 */
133 /**
134 @defgroup RM_LLD_ENUM  RM Low Level Driver Enums
135 @ingroup RM_LLD_API
136 */
137 /**
138 @defgroup RM_LLD_RESOURCE_TABLE  RM LLD Resource Table Definition Symbols and Structures
139 @ingroup RM_LLD_API
140 */
141 /**
142 @defgroup RM_LLD_SHARED_RESOURCES  RM LLD ARM and DSP Shared Resources
143 @ingroup RM_LLD_API
144 */
145 /**
146 @defgroup RM_LLD_DATASTRUCT  RM Low Level Driver Data Structures
147 @ingroup RM_LLD_API
148 */
149 /**
150 @defgroup RM_LLD_FUNCTION  RM Low Level Driver Functions
151 @ingroup RM_LLD_API
152 */
153 /**
154 @defgroup RM_LLD_OSAL  RM Low Level Driver OSAL Functions
155 @ingroup RM_LLD_API
156 */
158 /**
159 @addtogroup RM_LLD_SYMBOL
160 @{
161 */
163 /** RM LLD Return And Error Codes */
164 /** RM Resource Okay Return Base */
165 #define RM_OK  0
167 /** RM LLD Error Base */
168 #define RM_ERROR (-64)
169 /** RM LLD failed to populate internal permission tables */
170 #define RM_ERROR_PERMISSION_TABLE_POPULATION_FAILED (RM_ERROR-1)
171 /** RM LLD Table entry population failure */
172 #define RM_ERROR_PERMISSION_TABLE_ENTRY_FAILURE (RM_ERROR-2)
174 /** Master/Slave synchronization defines */
175 /** Permissions table not valid */
176 #define RM_PERMISSION_TABLE_NOT_VALID 0
177 /** Permissions table valid */
178 #define RM_PERMISSION_TABLE_VALID 1
180 /**
181 @}
182 */
184 /** @addtogroup RM_LLD_DATASTRUCT
185 @{ 
186 */
188 /** 
189  * @brief RM Handle for LLDs
190  */
191 typedef void *Rm_Handle;
193 /** 
194 @} 
195 */
197 /* Exported functions available to application */
198 extern Rm_Result Rm_init (const Rm_Resource *rmResourceTable);
199 extern Rm_Result Rm_start (void);
200 extern Rm_Handle Rm_getHandle(void);
201 extern uint32_t Rm_getVersion (void);
202 extern const char* Rm_getVersionStr (void);
204 #ifdef __cplusplus
206 #endif
208 #endif /* RM_H_ */