Checking in RMv2 progress
[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 typedef Rm_ServiceResult Rm_TransactionResult;
135 /**
136  * @brief RM transport routing map linked list node
137  */
138 typedef struct {
139     /** Transport handle associated with this node */
140     Rm_TransportHandle transHandle;
141     /** The remote RM instance type associated with this node */
142     Rm_InstType remoteInstType;
143     /** Link to the next route node in the route map list */
144     Rm_TransRouteMapNode *nextNode;
145 } Rm_TransRouteMapNode;
147 /**
148  * @brief RM protocol commands.  The first N commands should be synchronized with
149  *        the Rm_ServiceType enum in rm_service.h
150  */
151 typedef enum {
152     /** Resource allocation request */
153     Rm_command_ALLOCATE = Rm_service_RESOURCE_ALLOCATE,
154     /** Block resource allocation request */
155     Rm_command_BLOCK_ALLOCATE = Rm_service_RESOURCE_BLOCK_ALLOCATE,
156     /** Resource allocate by name */
157     Rm_command_ALLOCATE_NAMED = Rm_service_RESOURCE_ALLOCATE_BY_NAME,
158     /** Free resource */
159     Rm_command_FREE = Rm_service_RESOURCE_FREE,
160     /** Free resource block */
161     Rm_command_BLOCK_FREE = Rm_service_RESOURCE_BLOCK_FREE,
162     /** Free named resource */
163     Rm_command_FREE_NAMED = Rm_service_RESOURCE_FREE_BY_NAME,
164     /** Map provided name to specified resource index */
165     Rm_command_MAP_NAME = Rm_service_RESOURCE_MAP_TO_NAME,
166     /** Unmap provided name from tied resource */
167     Rm_command_UNMAP_NAME = Rm_service_RESOURCE_UNMAP_NAME,
168     /** Get the status of the specified resource */
169     Rm_command_RESOURCE_STATUS = Rm_service_RESOURCE_STATUS,
170     /** Policy request */
171     Rm_command_POLICY_REQUEST,
172     /** Policy response */
173     Rm_command_POLICY_RESPONSE
174 } Rm_Command;
176 /**
177  * @brief RM protocol packet resource information
178  */
179 typedef struct {
180     /** Resource name of resource affected by command */
181     char resName[RM_MAX_RESOURCE_NAME_SIZE_BYTES];
182     /** If applicable, start of resource range affected by command */
183     int32_t resBase;
184     /** If applicable, number of specified resource affected by command */
185     int32_t resNum;
186     /** If applicable, the alignment of the resource affected by the command */
187     uint32_t resAlign;
188     /** If applicable, the NameServer name assigned to the specified
189      *  resource.  Used for commands centering on RM NameServer actions */
190     char resNsName[RM_MAX_RESOURCE_NAME_SIZE_BYTES];
191 } Rm_ResourceInfo;
193 /**
194  * @brief RM transaction is the internalized version of service requests received 
195  *        from components and RM commands received from other RM instances.
196  */
197 typedef struct {
198     /* Transaction type */
199     Rm_Command transType;
200     /* Transaction details */
201     union {
202         /** If the command has to do with resources these fields
203          *  will contain the resource information */
204         Rm_ResourceInfo transInfo;
205         /** Pointer to policy data if the command has to do with policies */
206         char *policyData;
207     } u;
208 } Rm_Transaction;
210 /**
211  * @brief RM transaction contains transaction result information that is to be passed
212  *        back to the entity that was the source of the transaction.  The source can be
213  *        a component that requested a service or a RM instance that sent a command.
214  */
215 typedef struct {
216     uint32_t transactionId;
217     uint32_t resBase;
218     uint32_t resNum;
219 } Rm_TransactionReceipt;
221 /**
222  * @brief RM protocol packet used to transmit RM commands and resources
223  *        between RM instances.
224  */
225 typedef struct {
226     /** Packet ID - Used to synchronize sent command packets with any valid
227      *              response commands. */
228     uint32_t rmPktId;
229     /** Response Packet ID - If protocol packet is sent as response to a 
230      *                       received packet the response packet ID field will
231      *                       contain the pktID value of the request packet
232      *                       received */
233     uint32_t rmRespPktId;
234     /** RM Instance Name - Name of RM instance that is issuing the command.       
235      *                     The instance name will be used to validate the 
236      *                     command against the instance name data stored in
237      *                     the RM policy data */
238     char rmInstName[RM_INST_NAME_MAX_CHARS];
239     /** Command issued from source RM instance */
240     uint32_t rmCmd;
241     /** Response code provides requesting RM instance with information about
242      *  the result of any requests made */
243     uint32_t rmRespCode;
244     /** Union separating resource information from policy information */
245     union {
246         /** If the command has to do with one or more resources these fields
247          *  will contain the resource information */
248         Rm_ResourceInfo resInfo;
249         /** If the command has to do with a policy this array will hold the
250          *  policy data */
251         char rmPolicyData[RM_MAX_POLICY_SIZE_BYTES];
252     } u;
253 } Rm_ProtocolPkt;
255 typedef enum {
256     /** running */
257     RM_state_IDLE = 0,
258     /** handling request */
259     RM_state_HANDLING_REQUEST = 1,
260     /** etc...flesh all these out later will need states for the different alloc, free, request/response handlers */
261 } Rm_State;
263 typedef struct {
264     char name[RM_INSTANCE_NAME_MAX_CHARS];
265     Rm_InstType instType;
266     Rm_State instState;
267     bool registeredWithDelegateOrServer;
268     Rm_PolicyHandle instPolicy;  /* Client Delegate only? */
270     /* RM instance transport parameters */
271     Rm_TransRouteMap routeMap;
272     /* Transport API function pointers - not global in case application wants to
273       * hook up different transports to RM */
274     Rm_TransportCallouts transport;
275     /* Most of the time will be NULL.  Will be NULL if a service request has been made and a callback function
276      * has been specified.  In that case this variable will be populated until the callback is made */
277     void *serviceCallback;
278 } Rm_Inst;
280 Rm_Result Rm_getUsePermissions (Rm_Perms *resourcePermissions);
283 #ifdef __cplusplus
285 #endif
287 #endif /* RM_PVT_H_ */