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