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>
51 /* RM component services include */
52 #include <ti/drv/rm/rm_services.h>
53 /* RM transport include */
54 #include <ti/drv/rm/rm_transport.h>
55 /* RM policy include */
56 #include <ti/drv/rm/rm_policy.h>
58 /** @mainpage Resource Manager
59 *
60 * @section intro Introduction
61 *
62 * The Resource Manager low level driver (RM LLD) is designed to provide initialization and permissions checking
63 * for LLD resources. A system integrator can specify DSP permissions for LLD resources within the system.
64 * The resource permissions are stored in the RM LLD and used to validate resource requests from supported LLDs.
65 * Currently, the RM LLD supports permissions for the following LLDs
66 * - QMSS
67 * - CPPI
68 * - PA
69 * For information on the specific resources supported with each LLD please see @ref RM_LLD_RESOURCE_TABLE.
70 *
71 * The system integrator must specify the supported LLD resource permissions for all DSPs prior to compile time.
72 * An array of @ref Rm_Resource objects must be created. Each @ref Rm_Resource entry in the array specifies
73 * a resource type, start and end range for the resource, and the initialization and usage permissions for the
74 * resource for each DSP. For an example resource table definitions please see the @ref rmResourceTable array
75 * defined in the resource_table\ directory. This resource table assigns full initialization and usage permissions
76 * to all DSPs for all supported resources. Please note that the resouce table must start with the
77 * @ref RM_RESOURCE_MAGIC_NUMBER entry and end with the @ref RM_RESOURCE_FINAL_ENTRY. These
78 * first and last entries are used the RM LLD to validate and parse the resource table.
79 *
80 * The RM LLD must be initialized and started prior to all supported LLD initialization and start routines. The
81 * @ref Rm_init function should be invoked, and passed a pointer to the integrator defined resource table, on the
82 * master DSP core in the system. All other DSP cores should invoke the @ref Rm_start API. The @ref Rm_init
83 * function first initializes the internal permission tables to deny all DSPs access to all resources. Next the
84 * @ref Rm_init function parses the resource table provided and copies all specified permissions into the internal
85 * tables. When the permission transfer completes the @ref Rm_init function writes a global synchronization
86 * object which the @ref Rm_start functions are spinning on. The slave cores that have invoked @ref Rm_start
87 * will stop spinning once the global synchronization has been written. At this time @ref Rm_start will invalidate
88 * all internal permission tables so that no further cache invalidate operations need to be performed when
89 * checking resource permissions in the data path. The upfront cache invalidate operation is possible because
90 * the RM LLD does not allow dynamic resource permission modifications. The permissions defined by the system
91 * integrator and loaded during RM initialization are static throughout the system up-time.
92 *
93 * The RM LLD must be registered with a supported LLD in order for the supported LLD to perform resource
94 * permission checks. If the RM LLD is not registered with a supported LLD the LLD will operate as if the RM LLD
95 * is not there. This maintains full backwards compatability with existing applications not using the RM LLD. In order
96 * to register the RM LLD with supported LLDs the following steps should be taken
97 * - Get a @ref Rm_Handle via the @ref Rm_getHandle API on each DSP that uses the RM LLD.
98 * - Register the RM LLD with the supported LLDs by passing the @ref Rm_Handle to the
99 * LLD's <<LLD name>>_startCfg API. Again, this should be performed on all DSP cores using the RM LLD.
100 * Note: The master core for the QMSS LLD should have the @ref Rm_Handle registered via the Qmss_init API.
101 * After registering the RM LLD with supported LLDs all supported LLD resources covered by the RM LLD will invoke
102 * permission check callouts to the RM. A permission denied or approved response will be given back to the
103 * invoking LLD based on the permissions stored in the RM LLD for the resource.
104 *
105 * All internal RM LLD permission tables are placed into a single memory section called ".rm". This memory section
106 * MUST be placed in shared memory (MSMC or DDR). The permission tables are shared between all DSPs utilizing
107 * the RM LLD.
108 *
109 * In summary, the initialization flow if the RM LLD is to be utilized should look like the following:
110 *
111 * Master DSP Core:
112 * - Call @ref Rm_init passing in the system integrator defined resource table
113 * - Call @ref Rm_getHandle
114 * - Call supported LLD _init or _create functions (for QMSS pass the @ref Rm_Handle inside the
115 * Qmss_GlobalConfigParams structure)
116 * - Call supported LLD _startCfg functions passing the @ref Rm_Handle as an argument
117 *
118 * Slave DSP Cores:
119 * - Call @ref Rm_start
120 * - Call @ref Rm_getHandle
121 * - Call supported LLD _start functions (if supported)
122 * - Call supported LLD _startCfg functions passing the @ref Rm_Handle as an argument
123 *
124 */
126 /* Define RM_LLD_API as a master group in Doxygen format and add all RM LLD API
127 definitions to this group. */
128 /** @defgroup RM_LLD_API RM LLD Module API
129 * @{
130 */
131 /** @} */
133 /**
134 @defgroup RM_TRANSPORT_API RM Transport-Layer API
135 @ingroup RM_LLD_API
136 */
137 /**
138 @defgroup RM_SERVICES_API RM Registered Component Services API
139 @ingroup RM_LLD_API
140 */
141 /**
142 @defgroup RM_POLICY_API RM Policy modification API
143 @ingroup RM_LLD_API
144 */
147 /**
148 @addtogroup RM_LLD_SYMBOL
149 @{
150 */
152 /** RM LLD Return And Error Codes */
153 /** RM Resource Okay Return Base */
154 #define RM_OK 0
156 /** RM LLD Error Base */
157 #define RM_ERROR (-64)
158 /** RM LLD failed to populate internal permission tables */
159 #define RM_ERROR_PERMISSION_TABLE_POPULATION_FAILED (RM_ERROR-1)
160 /** RM LLD Table entry population failure */
161 #define RM_ERROR_PERMISSION_TABLE_ENTRY_FAILURE (RM_ERROR-2)
163 /** Master/Slave synchronization defines */
164 /** Permissions table not valid */
165 #define RM_PERMISSION_TABLE_NOT_VALID 0
166 /** Permissions table valid */
167 #define RM_PERMISSION_TABLE_VALID 1
169 /**
170 @}
171 */
173 /** @addtogroup RM_LLD_DATASTRUCT
174 @{
175 */
178 /**
179 @}
180 */
182 /**
183 * @brief Maximum number of characters in a RM instance name
184 */
185 #define RM_INST_NAME_MAX_CHARS (16)
187 /**
188 * @brief RM Handle provided to application. The RM Handle is used by the
189 * application to distinquish between different RM instances running on
190 * the same core.
191 */
192 typedef void *Rm_Handle;
194 /**
195 * @brief RM Service Handle provided to components that want to use RM to
196 * for management of their resources.
197 */
198 typedef void *Rm_ServiceHandle;
200 /**
201 * @brief RM Instance types
202 */
203 typedef enum {
204 /** RM Server */
205 Rm_instType_SERVER = 0,
206 /** RM Client Delegate */
207 Rm_instType_CLIENT_DELEGATE,
208 /** RM Client */
209 Rm_instType_CLIENT
210 } Rm_InstType;
212 /**
213 * @brief RM transport registration configuration structure
214 */
215 typedef struct {
216 /** Defines the remote RM instance's type */
217 Rm_InstType rmRemoteInstType;
218 } Rm_TransCfg;
220 /**
221 * @brief RM transport verification return value
222 */
223 typedef enum {
224 /** RM transport paths verified as working. */
225 Rm_transVerify_VERIFIED = 0,
226 /** RM transport path verification error. See Rm_TransFailData structure
227 * for more information */
228 Rm_transVerify_ERROR
229 } Rm_TransVerifyResult;
231 /**
232 * @brief If the RM transport path verification tests fail this structure
233 * will be returned with specifics as to the error
234 */
235 typedef struct {
236 /** Failing RM Instance Handle */
237 Rm_Handle failingRmHandle;
238 /** Failing transport handle */
239 Rm_TransHandle failingTransHandle;
240 /** If applicable: error codes received from failing transport */
241 uint32_t transErrorCode;
242 } Rm_TransFailData;
244 /**
245 * @brief RM pre-main allocation request information provided by the pre-main
246 * startup function requesting the resource */
247 typedef struct {
248 /** Pointer to the requested pre-main allocation resource name. The
249 * name provided by the component must match the resource names
250 * provided in the global resource table and allocation policies */
251 char *resourceName;
252 /** The pre-main allocation request resource index. Typically this is the
253 * resource value. For example, queue number or semaphore number */
254 uint32_t resourceIndex;
255 } Rm_PreMainAllocInfo;
257 /**
258 * @brief RM instance initialization structure
259 */
260 typedef struct {
261 /** Pointer to RM instance name character array. The name of the RM instance must
262 * be reflected exactly in the initial RM policies provided to the RM
263 * tree's Servers and Client Delegates. The RM instance name is
264 * used by the policy to map which instances are allowed defined
265 * privileges */
266 char *instName;
267 /** RM instance type. Defines whether the RM instance will be initialized
268 * as a RM Server, Client Delegate, or Client */
269 Rm_InstType instType;
270 /** [Server Parameter] Pointer to the device-wide resource list. The list
271 * contains all resources available on the device available for
272 * allocation. Servers running on ARM-Linux cores provide a subset
273 * of the global device list for allocation. The subset is formed from
274 * the global resources leftover after the Linux DTB is parsed for
275 * resources reserved by Linux.
276 *
277 * Note: This parameter will be ignored when the instance type is either
278 * Client Delegate or Client */
279 void *globalResourceList;
280 /** [Server/Client Delegate Paramter] Pointer to the startup allocation
281 * policy. RM Servers should be initialized with the global policy
282 * listing for all RM instances within the system. RM Client Delegates
283 * can be initialized with their local policy, must be a subset of the
284 * global policy provided to the Client Delegate's Server.
285 *
286 * Note: The core charged with the task of initializing the BIOS and IPC
287 * components must run an RM Client Delegate with an initial policy
288 * that allocates a system timer to BIOS and a HW semaphore to IPC
289 *
290 * Note: This parameter will be ignored when the instance type is a
291 * Client
292 */
293 void *startupPolicy;
294 /** Pointer to application implemented rmAllocPkt API. The API for the
295 * provided function must match the rmAllocPkt function pointer API
296 * described in rm.h */
297 void *rmAllocPktFuncPtr;
298 /** Pointer to application implemented rmFreePkt API. The API for the
299 * provided function must match the rmFreePkt function pointer API
300 * described in rm.h */
301 void *rmFreePktFuncPtr;
302 /** Pointer to application implemented rmSend API. The API for the
303 * provided function must match the rmSend function pointer API
304 * described in rm.h */
305 void *rmSendFuncPtr;
306 /** Pointer to application implemented rmReceive API. The API for the
307 * provided function must match the rmReceive function pointer API
308 * described in rm.h */
309 void *rmReceiveFuncPtr;
310 /** Pointer to application implemented rmNumPktsReceived API. The API for
311 * the provided function must match the rmNumPktsReceived function
312 * pointer API described in rm.h */
313 void *rmNumPktsReceivedFuncPtr;
314 } Rm_InitCfg;
317 /**
318 * @b Description
319 * @n
320 * This function initializes a RM instance.
321 *
322 * IMPORTANT: Rm_init must be called prior to any other component startup
323 * APIs (BIOS_start, Ipc_start, etc).
324 *
325 * @param[in] *initCfg
326 * Pointer to structure containing the initialization information for
327 * this RM instance.
328 *
329 * @retval
330 * Success - non-zero Rm_Handle returned.
331 * @retval
332 * Failure - NULL Rm_handle returned.
333 */
334 Rm_Handle Rm_init(Rm_InitCfg *initCfg);
336 /**
337 * @b Description
338 * @n
339 * Non-blocking function used by RTSC pre-main startup functions to
340 * allocate RM resources for usage. Pre-main allocated resources will be
341 * validated by RM against a memory-mapped startup resource policy.
342 * Pre-main allocation of unauthorized resources will result in a system
343 * exception.
344 *
345 * Note: Resource pre-main allocations can only occur on a core that is
346 * running a RM Server or Client Delegate that has a startup policy
347 * allowing the allocation of pre-main resources
348 *
349 * @param[in] preMainAllocInfo
350 * Resource pre-main allocation structure that provides details of the
351 * resource requested from RM for preallocation
352 *
353 * @retval
354 * Success - 0 - Resource pre-main allocation request okay.
355 * @retval
356 * Failure - non-zero - Resource pre-main allocation request error.
357 */
358 Rm_Result Rm_preMainAllocResource(Rm_PreMainAllocInfo
359 *preMainAllocInfo);
362 /**
363 * @b Description
364 * @n
365 * This function returns a RM service handle to the application to
366 * provide to software components (LLDs, BIOS, etc) that want to use RM.
367 *
368 * @param[in] rmHandle
369 * RM instance handle. Used to return a ServiceHandle from the proper
370 * RM instance in cases where there are multiple RM instances running on
371 * a single core.
372 *
373 * @retval
374 * Success - RM Service Handle. Used as an input parameter for
375 * component startCfg functions.
376 * @retval
377 * Failure - NULL
378 */
379 Rm_ServiceHandle Rm_getServiceHandle(Rm_Handle rmHandle);
381 /**
382 * @b Description
383 * @n
384 * This function is used to register transports with RM for sending and
385 * receiving packets between RM instances over application transport
386 * data paths.
387 *
388 * @param[in] rmHandle
389 * RM instance to which the transport will be registered. Used internally
390 * by RM if there are more than one RM instances per core.
391 *
392 * @param[in] transCfg
393 * Transport registration configuration structure. Provides information
394 * regarding the application transports remote entity. For example,
395 * if the transCfg structure specifies the remote type is the RM Server
396 * RM will know any Server requests must be pushed to the application
397 * transport API with the transport handle returned to the application
398 *
399 * @retval
400 * Success - non-NULL RM transport handle. No two transport handles
401 * returned by RM should be the same.
402 * @retval
403 * Failure - NULL
404 */
405 Rm_TransHandle Rm_registerTransport (Rm_Handle rmHandle,
406 Rm_TransCfg *transCfg);
408 /**
409 * @b Description
410 * @n
411 * This function places the selected RM instance into the transport
412 * verification state. When all RM instances in the tree are placed
413 * in the transport verification state a transport path verification
414 * test will take place to verify the application transport paths between
415 * all RM tree nodes are connected correctly.
416 *
417 * Note: This API should not be called until all transport have been
418 * registered with RM
419 *
420 * @param[in] rmHandle
421 * Which RM instance to begin the transport verification process
422 *
423 * @param[in] timeout
424 * Number of ______ (cycles, usec, msec???) to wait before signaling a
425 * transport path verification timeout
426 *
427 * @param[in] failData
428 * Pointer to an empty Rm_TransFailData structure. If the transport
429 * verification process fails this structure will return with transport
430 * failure data
431 *
432 * @retval
433 * Success - 0 - Transport Verification succeeded
434 * @retval
435 * Failure - non-0 - Transport Verification failed
436 */
437 Rm_TransVerifyResult Rm_verifyTransport (Rm_Handle, uint32_t timeout,
438 Rm_TransFailData *failData);
440 /**
441 * @b Description
442 * @n
443 * The function is used to get the version information of the RM.
444 *
445 * @retval
446 * Version Information.
447 */
448 uint32_t Rm_getVersion (void);
450 /**
451 * @b Description
452 * @n
453 * The function is used to get the version string for the RM.
454 *
455 * @retval
456 * Version String.
457 */
458 const char* Rm_getVersionStr (void);
460 #ifdef __cplusplus
461 }
462 #endif
464 #endif /* RM_H_ */