996a5ef006a1da92b1a36eae3a82ecfb5ee94344
[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 transaction queue linked list node
150  */
151 typedef struct {
152     /** The transaction ID for the transaction awaiting a response */
153     uint32_t transactionId;
154     /** The originating transaction ID.  Maps a transaction created in 
155      *  response to a request received.  */
156     uint32_t originatingTransactionId;
157     /** The transport handle that the transaction was received on.  Used 
158      *  to provide a RM response to the right requesting RM instance */
159     Rm_TransportHandle transportHandle;
160     /** The callback function associated with the transaction ID.  Will
161      *  be called when a response is received matching the transaction ID. */
162     void *transactionCallback;
163     /** Link to the next transaction queue entry */
164     Rm_TransactionQueueEntry *nextEntry;
165 } Rm_TransactionQueueEntry;
167 /**
168  * @brief RM protocol commands.  The first N commands should be synchronized with
169  *        the Rm_ServiceType enum in rm_service.h
170  */
171 typedef enum {
172     /** Resource allocation request */
173     Rm_command_ALLOCATE = Rm_service_RESOURCE_ALLOCATE,
174     /** Block resource allocation request */
175     Rm_command_BLOCK_ALLOCATE = Rm_service_RESOURCE_BLOCK_ALLOCATE,
176     /** Resource allocate by name */
177     Rm_command_ALLOCATE_NAMED = Rm_service_RESOURCE_ALLOCATE_BY_NAME,
178     /** Free resource */
179     Rm_command_FREE = Rm_service_RESOURCE_FREE,
180     /** Free resource block */
181     Rm_command_BLOCK_FREE = Rm_service_RESOURCE_BLOCK_FREE,
182     /** Free named resource */
183     Rm_command_FREE_NAMED = Rm_service_RESOURCE_FREE_BY_NAME,
184     /** Map provided name to specified resource index */
185     Rm_command_MAP_NAME = Rm_service_RESOURCE_MAP_TO_NAME,
186     /** Unmap provided name from tied resource */
187     Rm_command_UNMAP_NAME = Rm_service_RESOURCE_UNMAP_NAME,
188     /** Get the status of the specified resource */
189     Rm_command_RESOURCE_STATUS = Rm_service_RESOURCE_STATUS,
190     /** Resource response - Response applies to all above resource commands */
191     Rm_command_RESOURCE_RESPONSE,
192     /** Policy request */
193     Rm_command_POLICY_REQUEST,
194     /** Policy response */
195     Rm_command_POLICY_RESPONSE
196 } Rm_Command;
198 /**
199  * @brief RM transaction details values.  Details values provide more fine-grained
200  *        information regarding a transaction request or response
201  */
202 typedef enum {
203     /** No details provided for transaction */
204     Rm_transactionDetials_NONE = 0,
205     /** Transaction has been approved */
206     Rm_transactionDetails_RESOURCE_APPROVED = 1,
207     /** Transaction has been denied */
208     Rm_transactionDetails_RESOURCE_DENIED = 2    
209 } Rm_TransactionDetails;
211 /**
212  * @brief RM protocol packet resource information
213  */
214 typedef struct {
215     /** Resource name of resource affected by command */
216     char resName[RM_MAX_RESOURCE_NAME_SIZE_BYTES];
217     /** If applicable, start of resource range affected by command */
218     int32_t resBase;
219     /** If applicable, number of specified resource affected by command */
220     int32_t resNum;
221     /** If applicable, the alignment of the resource affected by the command */
222     uint32_t resAlign;
223     /** If applicable, the NameServer name assigned to the specified
224      *  resource.  Used for commands centering on RM NameServer actions */
225     char resNsName[RM_MAX_RESOURCE_NAME_SIZE_BYTES];
226 } Rm_ResourceInfo;
228 /**
229  * @brief RM transaction is the internalized version of service requests received 
230  *        from components and RM commands received from other RM instances.
231  */
232 typedef struct {
233     /** Transaction type */
234     Rm_Command command;
235     /** ID of transaction.  Maps to the RM protocol packet ID when forwarding
236      *  RM requests or received RM responses. */
237     uint32_t pktId;
238     /** Transaction's associated callback function is the transaction originated
239      *  from a registered component */
240     void *callback;
241     /** Transaction details.  Provides detailed request/response codes such as
242      *  resource denial reasons */
243     uint32_t details;
244     /** Transport the transaction was received on.  Stored in order to provide
245      *  responses to received RM packets */
246     Rm_TransportHandle receivedTransport;
247     /** Transaction details */
248     union {
249         /** If the command has to do with resources these fields
250          *  will contain the resource information */
251         Rm_ResourceInfo resourceInfo;
252         /** Pointer to policy data if the command has to do with policies */
253         char *policyData;
254     } u;
255 } Rm_Transaction;
257 /**
258  * @brief RM transaction contains transaction result information that is to be passed
259  *        back to the entity that was the source of the transaction.  The source can be
260  *        a component that requested a service or a RM instance that sent a command.
261  */
262 typedef struct {
263     int32_t transactionResult;
264     uint32_t transactionId;
265     uint32_t resBase;
266     uint32_t resNum;
267 } Rm_TransactionReceipt;
269 /**
270  * @brief RM protocol packet used to transmit RM commands and resources
271  *        between RM instances.
272  */
273 typedef struct {
274     /** Packet ID - Used to synchronize sent command packets with
275      *              response commands. */
276     uint32_t rmPktId;
277     /** Command issued from source RM instance */
278     uint32_t rmCmd;    
279     /** RM Instance Name - Name of RM instance that is issuing the command.       
280      *                     The instance name will be used to validate the 
281      *                     command against the instance name data stored in
282      *                     the RM policy data */
283     char rmInstName[RM_INST_NAME_MAX_CHARS];
284     /** Details field provides more information about RM request/response transactions
285      *  such as whether a transaction has been approved or denied */
286     uint32_t rmDetails;
287     /** Union separating resource information from policy information */
288     union {
289         /** If the command has to do with one or more resources these fields
290          *  will contain the resource information */
291         Rm_ResourceInfo resInfo;
292         /** If the command has to do with a policy this array will hold the
293          *  policy data */
294         char rmPolicyData[RM_MAX_POLICY_SIZE_BYTES];
295     } u;
296 } Rm_ProtocolPkt;
298 typedef enum {
299     /** running */
300     RM_state_IDLE = 0,
301     /** handling request */
302     RM_state_HANDLING_REQUEST = 1,
303     /** etc...flesh all these out later will need states for the different alloc, free, request/response handlers */
304 } Rm_State;
306 typedef struct {
307     char name[RM_INSTANCE_NAME_MAX_CHARS];
308     Rm_InstType instType;
309     Rm_State instState;
310     bool registeredWithDelegateOrServer;
311     Rm_PolicyHandle instPolicy;  /* Client Delegate only? */
313     /* RM instance transport parameters */
314     Rm_TransRouteMap routeMap;
315     /* RM transaction queue */
316     Rm_TransactionQueue transactionQueue;
317     /* Transport API function pointers - not global in case application wants to
318       * hook up different transports to RM */
319     Rm_TransportCallouts transport;
320     /* Most of the time will be NULL.  Will be NULL if a service request has been made and a callback function
321      * has been specified.  In that case this variable will be populated until the callback is made */
322     void *serviceCallback;
323 } Rm_Inst;
325 Rm_Result Rm_getUsePermissions (Rm_Perms *resourcePermissions);
328 #ifdef __cplusplus
330 #endif
332 #endif /* RM_PVT_H_ */