Adding policy checking feature on RM Server
[keystone-rtos/rm-lld.git] / 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 */
42 #ifndef RM_H_
43 #define RM_H_
45 #ifdef __cplusplus
46 extern "C" {
47 #endif
49 /* RM version */
50 #include <ti/drv/rm/rmver.h>
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 /** @} */
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 */
140 /** 
141  * @brief Maximum number of characters in a RM instance name
142  */
143 #define RM_INSTANCE_NAME_MAX_CHARS (24)
145 /** 
146  * @brief RM Handle provided to application.  The RM Handle is used by the
147  *        application to distinquish between different RM instances running on
148  *        the same core.
149  */
150 typedef void *Rm_Handle;
152 /** 
153  * @brief RM Instance types
154  */
155 typedef enum {
156     /** RM Server */
157     Rm_instType_SERVER = 0,
158     /** RM Client Delegate */
159     Rm_instType_CLIENT_DELEGATE = 1,
160     /** RM Client */
161     Rm_instType_CLIENT = 2
162 } Rm_InstType;
164 /** 
165  * @brief RM instance initialization structure
166  */
167 typedef struct {
168     /** Pointer to RM instance name character array.  The name of the RM instance must
169      *  be reflected exactly in the initial RM policies provided to the RM
170      *  tree's Servers and Client Delegates.  The RM instance name is
171      *  used by the policy to map which instances are allowed defined 
172      *  privileges */
173     char *instName;
174     /** RM instance type.  Defines whether the RM instance will be initialized
175      *  as a RM Server, Client Delegate, or Client */
176     Rm_InstType instType;
177     /** [Server Parameter] Pointer to the device-wide resource list.  The list
178      *  contains all resources available on the device available for 
179      *  allocation.  Servers running on ARM-Linux cores provide a subset
180      *  of the global device list for allocation.  The subset is formed from
181      *  the global resources leftover after the Linux DTB is parsed for 
182      *  resources reserved by Linux.  
183      *  
184      *  Note: This parameter will be ignored when the instance type is either 
185      *  Client Delegate or Client */
186     void *globalResourceList;
187     /** [Server Parameter When Running on ARM Linux] Pointer to the Linux DTB.  
188      *  The Linux DTB will be parsed for all tracked resources reserved for use
189      *  by Linux.
190      *  
191      *  Note: This parameter will be ignored when the instance type is either 
192      *  Client Delegate or Client */
193     void *linuxDtb;    
194     /** [Server/Client Delegate Paramter] Pointer to the allocation
195      *  policy.  RM Servers should be initialized with the global policy 
196      *  listing for all RM instances within the system.  RM Client Delegates 
197      *  can be initialized with their local policy, must be a subset of the 
198      *  global policy provided to the Client Delegate's Server.
199      *
200      *  Note: The core charged with the task of initializing the BIOS and IPC
201      *        components must run an RM Client Delegate with an initial policy
202      *        that allocates a system timer to BIOS and a HW semaphore to IPC
203      *  
204      *  Note: This parameter will be ignored when the instance type is a 
205      *        Client 
206      */
207     void *policy;
208 } Rm_InitCfg;
210 /* TESTING PURPOSES: SERVER ONLY */
211 void Rm_printResourceStatus(Rm_Handle *rmHandle);
213 /**
214  *  @b Description
215  *  @n  
216  *      This function initializes a RM instance.
217  * 
218  *      IMPORTANT: Rm_init must be called prior to any other component startup
219  *                 APIs (BIOS_start, Ipc_start, etc).
220  *
221  *  @param[in]  *initCfg
222  *      Pointer to structure containing the initialization information for
223  *      this RM instance.
224  *
225  *  @retval
226  *      Success - non-zero Rm_Handle returned.
227  *  @retval
228  *      Failure - NULL Rm_handle returned.
229  */
230 Rm_Handle Rm_init(Rm_InitCfg *initCfg);
232 /**
233  *  @b Description
234  *  @n  
235  *      The function is used to get the version information of the RM.
236  *
237  *  @retval
238  *      Version Information.
239  */
240 uint32_t Rm_getVersion (void);
242 /**
243  *  @b Description
244  *  @n  
245  *      The function is used to get the version string for the RM.
246  *
247  *  @retval
248  *      Version String.
249  */
250 const char* Rm_getVersionStr (void);
252 #ifdef __cplusplus
254 #endif
256 #endif /* RM_H_ */