Coded basic test project started removing receipt construct
[keystone-rtos/rm-lld.git] / include / rm_loc.h
1 /*
2  *  file  rmloc.h
3  *
4  *  General 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 RMLOC_H_
41 #define RMLOC_H_
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
47 /* RM external includes */
48 #include <ti/drv/rm/rm_services.h>
49 #include <ti/drv/rm/rm_policy.h>
50 #include <ti/drv/rm/rm_transport.h>
52 #if 0
53 /* RM permissions structure for CPPI DMA channels and flows */
54 typedef struct
55 {
56     /** Array of pointers to each DMAs channel or flow permissions
57        * From CPPI LLD - DMA 0 = SRIO
58        *                          DMA 1 = AIF
59        *                          DMA 2 = FFTC A
60        *                          DMA 3 = FFTC B
61        *                          DMA 4 = PASS
62        *                          DMA 5 = QMSS
63        *                          DMA 6 = FFTC C
64        *                          DMA 7 = BCP 
65        * 
66        * Note: Some DMAs may not be supported based on the device */
67     Rm_Perms *dmaPermPtrs[RM_CPPI_MAX_DMAS];
68 } Rm_CppiChAndFlowPerms;
70 /* RM Cache Line Alignment Defines and Macros */
72 #define RM_MAX_CACHE_ALIGN 128  /* Maximum alignment for cache line size */
74 /* This macro generates compiler error if postulate is false, so 
75  * allows 0 overhead compile time size check.  This "works" when
76  * the expression contains sizeof() which otherwise doesn't work
77  * with preprocessor */
78 #define RM_COMPILE_TIME_SIZE_CHECK(postulate)                         \
79    do {                                                                 \
80        typedef struct {                                                 \
81          uint8_t NegativeSizeIfPostulateFalse[((int)(postulate))*2 - 1];\
82        } PostulateCheck_t;                                              \
83    }                                                                    \
84    while (0)
86 /* Macro to pad out internal permission structures to multiple of RM_MAX_CACHE_ALIGN bytes
87   * The macro prevent something else from being placed on same cache line as the permission.  
88   * arrays.  Note that pad[0] is illegal, so must add full RM_MAX_CACHE_ALIGN if structure
89   * is already padded by chance. */
90 #define RM_ALIGN_PERMISSIONS_ARRAY(numElements, permStructType) ( \
91      (((sizeof(permStructType) * (numElements)) % RM_MAX_CACHE_ALIGN) == 0) ? (numElements) : \
92      ((numElements) + \
93        (RM_MAX_CACHE_ALIGN - \
94          ((sizeof(permStructType) * (numElements)) % RM_MAX_CACHE_ALIGN))/sizeof(permStructType)))
96 /* RM Global Sync Object (unpadded) */
97 typedef struct
98 {
99     /** Rm_init/Rm_start synchronization object. */
100     uint8_t globalSyncObj;
101 } Rm_Sync_Obj_Unpadded;
103 /* RM Global Sync Object (padded) */
104 typedef struct
106     /** Data structure without padding, so sizeof() can compute padding */
107     Rm_Sync_Obj_Unpadded obj;
108     /** Pad out to end of RM_MAX_CACHE_ALIGN bytes to prevent something else
109      * from being placed on same cache line as Rm_Synci_Obj.  Note that 
110      * pad[0] is illegal, so must add full RM_MAX_CACHE_ALIGN if structure
111      * is already padded by chance. */
112     uint8_t  pad[RM_MAX_CACHE_ALIGN - 
113                        (sizeof(Rm_Sync_Obj_Unpadded) % RM_MAX_CACHE_ALIGN)];
114 } Rm_Sync_Obj;
115 #endif
117 /** Maximum size of a transmittable RM policy in bytes */
118 #define RM_MAX_POLICY_SIZE_BYTES (64)  // Placeholder: This will change 
119                                        // during development
121 /** Pointer to RM instance's transport routing map */
122 typedef void *Rm_TransportRouteMap;
124 /** Pointer to RM instance's transaction queue */
125 typedef void *Rm_TransactionQueue;
127 /**
128  * @brief RM transaction details values.  Details values provide more fine-grained
129  *        information regarding a transaction request or response
130  */
131 typedef enum {
132     /** Transaction is being processed */
133     Rm_transactionState_PROCESSING = 0,
134     /** Transaction has been approved */
135     Rm_transactionState_TRANSACTION_APPROVED = 1,
136     /** Transaction has been denied */
137     Rm_transactionState_TRANSACTION_DENIED = 2  
138 } Rm_TransactionState;
140 /**
141  * @brief RM protocol packet resource information
142  */
143 typedef struct {
144     /** Resource name of resource affected by command */
145     char name[RM_RESOURCE_NAME_MAX_CHARS];
146     /** If applicable, start of resource range affected by command.  If
147      *  RM_RESOURCE_UNSPECIFIED is assigned the higher level RM agent*/
148     int32_t base;
149     /** If applicable, range of specified resource, starting from base, affected by command */
150     uint32_t range;
151     /** If applicable, the alignment of the resource affected by the command */
152     int32_t alignment;
153     /** If applicable, the NameServer name assigned to the specified
154      *  resource.  Used for commands centering on RM NameServer actions */
155     char nsName[RM_RESOURCE_NAME_MAX_CHARS];
156 } Rm_ResourceInfo;
158 /**
159  * @brief RM transactions are the internalized version of service requests received 
160  *        from components and RM commands received from other RM instances.
161  *        Transactions that cannot immediately be serviced are placed in the RM
162  *        instance's transaction queue.  The transactions track all service
163  *        requests within the RM infrastructure.
164  */
165 typedef struct {
166     /** Transaction service type */
167     Rm_ServiceType type;
168     /** Local ID of the transaction. */
169     uint32_t localId;
170     /** ID of transaction on lower level RM instance that generated the
171      *  packet that resulted in the creation of the transaction.  The
172      *  originating ID will be placed in the transaction's response packet
173      *  to the lower level RM instance.  The lower level RM instance will 
174      *  match the response packet with the originating request using the ID */
175     uint32_t remoteOriginatingId;
176     /** Name of the RM instance the transaction originated from */
177     char sourceInstName[RM_INSTANCE_NAME_MAX_CHARS];
178     /** Transaction's associated callback function */
179     Rm_ServiceCallback callback;
180     /** Transaction state */
181     Rm_TransactionState state;
182     /** Transaction result.  The codes are externally visible and tracked
183      *  in rmservices.h */
184     int32_t result;
185     /** Resource information */
186     Rm_ResourceInfo resourceInfo;
187     /** Link to the next transaction in the queue */
188     void *nextTransaction;    
189 } Rm_Transaction;
191 typedef struct {
192     char name[RM_INSTANCE_NAME_MAX_CHARS];
193     Rm_InstType instType;
194     bool registeredWithDelegateOrServer;
195     Rm_PolicyHandle instPolicy;  /* Client Delegate only? */
196     /* RM instance transport parameters */
197     Rm_TransportRouteMap routeMap;
198     /* RM Transaction sequence number counter */
199     uint32_t transactionSeqNum;
200     /* RM transaction queue */
201     Rm_TransactionQueue transactionQueue;
202     /* Transport API function pointers - not global in case application wants to
203       * hook up different transports to RM */
204     Rm_TransportCallouts transport;
205 } Rm_Inst;
207 Rm_Transaction *Rm_transactionQueueAdd(Rm_Inst *rmInst, uint32_t transactionId);
208 Rm_Transaction *Rm_transactionQueueFind(Rm_Inst *rmInst, uint32_t transactionId);
209 int32_t Rm_transactionQueueDelete(Rm_Inst *rmInst, uint32_t transactionId);
210 uint32_t Rm_transactionGetSequenceNum(Rm_Inst *rmInst);
212 void Rm_transactionProcessor (Rm_Inst *rmInst, Rm_Transaction *transaction, 
213                               Rm_TransactionReceipt *receipt);
216 #ifdef __cplusplus
218 #endif
220 #endif /* RMLOC_H_ */