Small change to test commit name
[keystone-rtos/rm-lld.git] / include / rm_pvt.h
1 /*
2  *  file  rm_pvt.h
3  *
4  *  Private data structures of Resource Manager.
5  *
6  *  ============================================================================
7  *      (C) Copyright 2012, Texas Instruments, Inc.
8  * 
9  *  Redistribution and use in source and binary forms, with or without 
10  *  modification, are permitted provided that the following conditions 
11  *  are met:
12  *
13  *    Redistributions of source code must retain the above copyright 
14  *    notice, this list of conditions and the following disclaimer.
15  *
16  *    Redistributions in binary form must reproduce the above copyright
17  *    notice, this list of conditions and the following disclaimer in the 
18  *    documentation and/or other materials provided with the   
19  *    distribution.
20  *
21  *    Neither the name of Texas Instruments Incorporated nor the names of
22  *    its contributors may be used to endorse or promote products derived
23  *    from this software without specific prior written permission.
24  *
25  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
26  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
27  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
28  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
29  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
30  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
31  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
32  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
33  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
34  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
35  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36  *
37  *  \par
38 */
40 #ifndef RM_PVT_H_
41 #define RM_PVT_H_
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
47 /* Device Include */
48 #include <c6x.h>
50 /* RM includes */
51 #include <ti/drv/rm/rm_services.h>
52 #include <ti/drv/rm/rm_policy.h>
53 #include <ti/drv/rm/rm_transport.h>
55 /* RM permissions structure for CPPI DMA channels and flows */
56 typedef struct
57 {
58     /** Array of pointers to each DMAs channel or flow permissions
59        * From CPPI LLD - DMA 0 = SRIO
60        *                          DMA 1 = AIF
61        *                          DMA 2 = FFTC A
62        *                          DMA 3 = FFTC B
63        *                          DMA 4 = PASS
64        *                          DMA 5 = QMSS
65        *                          DMA 6 = FFTC C
66        *                          DMA 7 = BCP 
67        * 
68        * Note: Some DMAs may not be supported based on the device */
69     Rm_Perms *dmaPermPtrs[RM_CPPI_MAX_DMAS];
70 } Rm_CppiChAndFlowPerms;
72 /* RM Cache Line Alignment Defines and Macros */
74 #define RM_MAX_CACHE_ALIGN 128  /* Maximum alignment for cache line size */
76 /* This macro generates compiler error if postulate is false, so 
77  * allows 0 overhead compile time size check.  This "works" when
78  * the expression contains sizeof() which otherwise doesn't work
79  * with preprocessor */
80 #define RM_COMPILE_TIME_SIZE_CHECK(postulate)                         \
81    do {                                                                 \
82        typedef struct {                                                 \
83          uint8_t NegativeSizeIfPostulateFalse[((int)(postulate))*2 - 1];\
84        } PostulateCheck_t;                                              \
85    }                                                                    \
86    while (0)
88 /* Macro to pad out internal permission structures to multiple of RM_MAX_CACHE_ALIGN bytes
89   * The macro prevent something else from being placed on same cache line as the permission.  
90   * arrays.  Note that pad[0] is illegal, so must add full RM_MAX_CACHE_ALIGN if structure
91   * is already padded by chance. */
92 #define RM_ALIGN_PERMISSIONS_ARRAY(numElements, permStructType) ( \
93      (((sizeof(permStructType) * (numElements)) % RM_MAX_CACHE_ALIGN) == 0) ? (numElements) : \
94      ((numElements) + \
95        (RM_MAX_CACHE_ALIGN - \
96          ((sizeof(permStructType) * (numElements)) % RM_MAX_CACHE_ALIGN))/sizeof(permStructType)))
98 /* RM Global Sync Object (unpadded) */
99 typedef struct
101     /** Rm_init/Rm_start synchronization object. */
102     uint8_t globalSyncObj;
103 } Rm_Sync_Obj_Unpadded;
105 /* RM Global Sync Object (padded) */
106 typedef struct
108     /** Data structure without padding, so sizeof() can compute padding */
109     Rm_Sync_Obj_Unpadded obj;
110     /** Pad out to end of RM_MAX_CACHE_ALIGN bytes to prevent something else
111      * from being placed on same cache line as Rm_Synci_Obj.  Note that 
112      * pad[0] is illegal, so must add full RM_MAX_CACHE_ALIGN if structure
113      * is already padded by chance. */
114     uint8_t  pad[RM_MAX_CACHE_ALIGN - 
115                        (sizeof(Rm_Sync_Obj_Unpadded) % RM_MAX_CACHE_ALIGN)];
116 } Rm_Sync_Obj;
118 /** Maximum number of characters allowed for instance names */
119 #define RM_INSTANCE_NAME_MAX_CHARS 24
122 /** Assigned to the Start/EndIndex entries in the protocol packet to request
123  *  the next available resource instead of a specific index */
124 #define RM_NEXT_AVAILABLE_RESOURCE (-1)
126 /** Maximum size of a transmittable RM policy in bytes */
127 #define RM_MAX_POLICY_SIZE_BYTES (64)  // Placeholder: This will change 
128                                        // during development
130 /** Pointer to RM instance's transport routing map */
131 typedef void *Rm_TransRouteMap;
133 /** Pointer to RM instance's transaction queue */
134 typedef void *Rm_TransactionQueue;
136 /**
137  * @brief RM transport routing map linked list node
138  */
139 typedef struct {
140     /** Transport handle associated with this node */
141     Rm_TransportHandle transHandle;
142     /** The remote RM instance type associated with this node */
143     Rm_InstType remoteInstType;
144     /** Link to the next route node in the route map list */
145     Rm_TransRouteMapNode *nextNode;
146 } Rm_TransRouteMapNode;
148 /**
149  * @brief RM protocol commands.  The first N commands should be synchronized with
150  *        the Rm_ServiceType enum in rm_service.h
151  */
152 typedef enum {
153     /** Resource allocation request */
154     Rm_command_ALLOCATE = Rm_service_RESOURCE_ALLOCATE,
155     /** Block resource allocation request */
156     Rm_command_BLOCK_ALLOCATE = Rm_service_RESOURCE_BLOCK_ALLOCATE,
157     /** Resource allocate by name */
158     Rm_command_ALLOCATE_NAMED = Rm_service_RESOURCE_ALLOCATE_BY_NAME,
159     /** Free resource */
160     Rm_command_FREE = Rm_service_RESOURCE_FREE,
161     /** Free resource block */
162     Rm_command_BLOCK_FREE = Rm_service_RESOURCE_BLOCK_FREE,
163     /** Free named resource */
164     Rm_command_FREE_NAMED = Rm_service_RESOURCE_FREE_BY_NAME,
165     /** Map provided name to specified resource index */
166     Rm_command_MAP_NAME = Rm_service_RESOURCE_MAP_TO_NAME,
167     /** Unmap provided name from tied resource */
168     Rm_command_UNMAP_NAME = Rm_service_RESOURCE_UNMAP_NAME,
169     /** Get the status of the specified resource */
170     Rm_command_RESOURCE_STATUS = Rm_service_RESOURCE_STATUS,
171     /** Resource response - Response applies to all above resource commands */
172     Rm_command_RESOURCE_RESPONSE,
173     /** Policy request */
174     Rm_command_POLICY_REQUEST,
175     /** Policy response */
176     Rm_command_POLICY_RESPONSE
177 } Rm_Command;
179 /**
180  * @brief RM transaction details values.  Details values provide more fine-grained
181  *        information regarding a transaction request or response
182  */
183 typedef enum {
184     /** No details provided for transaction */
185     Rm_transactionDetials_NONE = 0,
186     /** Transaction has been approved */
187     Rm_transactionDetails_RESOURCE_APPROVED = 1,
188     /** Transaction has been denied */
189     Rm_transactionDetails_RESOURCE_DENIED = 2    
190 } Rm_TransactionDetails;
192 /**
193  * @brief RM protocol packet resource information
194  */
195 typedef struct {
196     /** Resource name of resource affected by command */
197     char resName[RM_MAX_RESOURCE_NAME_SIZE_BYTES];
198     /** If applicable, start of resource range affected by command */
199     int32_t resBase;
200     /** If applicable, number of specified resource affected by command */
201     int32_t resNum;
202     /** If applicable, the alignment of the resource affected by the command */
203     uint32_t resAlign;
204     /** If applicable, the NameServer name assigned to the specified
205      *  resource.  Used for commands centering on RM NameServer actions */
206     char resNsName[RM_MAX_RESOURCE_NAME_SIZE_BYTES];
207 } Rm_ResourceInfo;
209 /**
210  * @brief RM transactions are the internalized version of service requests received 
211  *        from components and RM commands received from other RM instances.
212  *        Transactions that cannot immediately be serviced are placed in the RM
213  *        instance's transaction queue.
214  */
215 typedef struct {
216     /** Transaction type */
217     Rm_Command command;
218     /** ID of transaction.  Maps to the RM protocol packet ID when forwarding
219      *  RM requests or received RM responses. */
220     uint32_t transactionId;
221     /** Transaction's associated callback function is the transaction originated
222      *  from a registered component */
223     void *callback;
224     /** Transaction details.  Provides detailed request/response codes such as
225      *  resource denial reasons */
226     uint32_t details;
227     /** Transport the transaction was received on.  Stored in order to provide
228      *  responses to received RM packets */
229     Rm_TransportHandle transportReceivedOn;
230     /** Transaction details */
231     union {
232         /** If the command has to do with resources these fields
233          *  will contain the resource information */
234         Rm_ResourceInfo resourceInfo;
235         /** Pointer to policy data if the command has to do with policies */
236         char *policyData;
237     } u;
238     /** Link to the next transaction in the queue */
239     Rm_Transaction *nextTransaction;    
240 } Rm_Transaction;
242 /**
243  * @brief RM transaction contains transaction result information that is to be passed
244  *        back to the entity that was the source of the transaction.  The source can be
245  *        a component that requested a service or a RM instance that sent a command.
246  */
247 typedef struct {
248     int32_t transactionResult;
249     uint32_t transactionId;
250     uint32_t resBase;
251     uint32_t resNum;
252 } Rm_TransactionReceipt;
254 /**
255  * @brief RM protocol packet used to transmit RM commands and resources
256  *        between RM instances.
257  */
258 typedef struct {
259     /** Packet ID - Used to synchronize sent command packets with
260      *              response commands. */
261     uint32_t rmPktId;
262     /** Command issued from source RM instance */
263     uint32_t rmCmd;    
264     /** RM Instance Name - Name of RM instance that is issuing the command.       
265      *                     The instance name will be used to validate the 
266      *                     command against the instance name data stored in
267      *                     the RM policy data */
268     char rmInstName[RM_INST_NAME_MAX_CHARS];
269     /** Details field provides more information about RM request/response transactions
270      *  such as whether a transaction has been approved or denied */
271     uint32_t rmDetails;
272     /** Union separating resource information from policy information */
273     union {
274         /** If the command has to do with one or more resources these fields
275          *  will contain the resource information */
276         Rm_ResourceInfo resInfo;
277         /** If the command has to do with a policy this array will hold the
278          *  policy data */
279         char rmPolicyData[RM_MAX_POLICY_SIZE_BYTES];
280     } u;
281 } Rm_ProtocolPkt;
283 typedef enum {
284     /** running */
285     RM_state_IDLE = 0,
286     /** handling request */
287     RM_state_HANDLING_REQUEST = 1,
288     /** etc...flesh all these out later will need states for the different alloc, free, request/response handlers */
289 } Rm_State;
291 typedef struct {
292     char name[RM_INSTANCE_NAME_MAX_CHARS];
293     Rm_InstType instType;
294     Rm_State instState;
295     bool registeredWithDelegateOrServer;
296     Rm_PolicyHandle instPolicy;  /* Client Delegate only? */
298     /* RM instance transport parameters */
299     Rm_TransRouteMap routeMap;
300     /* RM transaction queue */
301     Rm_TransactionQueue transactionQueue;
302     /* Transport API function pointers - not global in case application wants to
303       * hook up different transports to RM */
304     Rm_TransportCallouts transport;
305     /* Most of the time will be NULL.  Will be NULL if a service request has been made and a callback function
306      * has been specified.  In that case this variable will be populated until the callback is made */
307     void *serviceCallback;
308 } Rm_Inst;
310 Rm_Result Rm_getUsePermissions (Rm_Perms *resourcePermissions);
313 #ifdef __cplusplus
315 #endif
317 #endif /* RM_PVT_H_ */