Checking in RMv2 progress
[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>
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  */
125  
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
462 #endif
464 #endif /* RM_H_ */