5806800691c46278ab838e97c519974c3e896f6e
[keystone-rtos/rm-lld.git] / include / rm_loc.h
1 /*
2  *  file  rm_loc.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_transport.h>
51 /* AVL BBST includes */
52 #include <ti/drv/rm/include/tree.h>
54 /** Maximum size of a transmittable RM policy in bytes */
55 #define RM_MAX_POLICY_SIZE_BYTES (64)  // Placeholder: This will change 
56                                        // during development
58 /** Pointer to RM instance's transport routing map */
59 typedef void *Rm_TransportRouteMap;
61 /** Pointer to RM instance's transaction queue */
62 typedef void *Rm_TransactionQueue;
64 /** Pointer to the RM instance's allocators */
65 typedef void *Rm_Allocators;
67 /** Pointer to the RM instance's NameServer (Valid only on Server) */
68 typedef void *Rm_NameServer;
70 /** Pointer to the RM instance's policy information */
71 typedef void *Rm_Policy;
73 /** Pointer to the RM instance's valid policy instances */
74 typedef void *Rm_PolicyValidInstances;
77 /**
78  * @brief RM protocol packet resource information
79  */
80 typedef struct {
81     /** Resource name of resource affected by command */
82     char     name[RM_RESOURCE_NAME_MAX_CHARS];
83     /** If applicable, start of resource range affected by command.  If
84      *  RM_RESOURCE_UNSPECIFIED is assigned the higher level RM agent*/
85     int32_t  base;
86     /** If applicable, number of specified resource, starting from base, affected by command */
87     uint32_t length;
88     /** If applicable, the alignment of the resource affected by the command */
89     int32_t  alignment;
90     /** If applicable, the NameServer name assigned to the specified
91      *  resource.  Used for commands centering on RM NameServer actions */
92     char     nsName[RM_RESOURCE_NAME_MAX_CHARS];
93 } Rm_ResourceInfo;
95 /**
96  * @brief RM transactions are the internalized version of service requests received 
97  *        from components and RM commands received from other RM instances.
98  *        Transactions that cannot immediately be serviced are placed in the RM
99  *        instance's transaction queue.  The transactions track all service
100  *        requests within the RM infrastructure.
101  */
102 typedef struct {
103     /** Transaction service type */
104     Rm_ServiceType type;
105     /** Local ID of the transaction. */
106     uint32_t localId;
107     /** ID of transaction in RM instance that generated the
108      *  packet that resulted in the creation of the transaction.  The
109      *  originating ID will be placed in the transaction's response packet
110      *  to the lower level RM instance.  The lower level RM instance will 
111      *  match the response packet with the originating request using the ID */
112     uint32_t remoteOriginatingId;
113     /** Name of the RM instance the RM packet, that spawned the transaction,
114      *  originated from */
115     char pktSrcInstName[RM_INSTANCE_NAME_MAX_CHARS];
116     /** Transaction's associated callback function */
117     Rm_ServiceCallback callback;
118     /** Transaction state.  The codes are externally visible and tracked
119      *  in rmservices.h */
120     int32_t state;
121     /** Name of the RM instance the service originated from */
122     char serviceSrcInstName[RM_INSTANCE_NAME_MAX_CHARS];    
123     /** Resource information */
124     Rm_ResourceInfo resourceInfo;
125     /** Link to the next transaction in the queue */
126     void *nextTransaction;    
127 } Rm_Transaction;
129 typedef struct {
130     const void *rangeData;
131     int32_t     rangeLen;
132     const void *nsAssignData;
133     int32_t     nsAssignLen;
134     const void *linuxAliasData;
135     int32_t     linuxAliasLen;
136 } Rm_ResourceProperties;
138 typedef enum {
139     Rm_allocatorOp_ALLOCATE = 0,
140     Rm_allocatorOp_FREE,
141     Rm_allocatorOp_PRE_ALLOCATE
142 } Rm_AllocatorOp;
144 typedef struct {
145     void            *serviceSrcInstNode;
146     Rm_AllocatorOp   operation;
147     uint32_t         allocType;
148     Rm_ResourceInfo *resourceInfo;
149 } Rm_AllocatorOpInfo;
151 typedef struct Rm_Allocator_s {
152     char resourceName[RM_RESOURCE_NAME_MAX_CHARS];
153     /** Pointer to the first resource entry in the allocator */
154     void *allocatorRootEntry;
155     /** Pointer to next resource allocator */
156     struct Rm_Allocator_s *nextAllocator;
157 } Rm_Allocator;
159 typedef struct {
160     char name[RM_INSTANCE_NAME_MAX_CHARS];
161     Rm_InstType instType;
162     bool registeredWithDelegateOrServer;
163     Rm_Policy policy;
164     Rm_PolicyValidInstances validInstances;    
165     Rm_Allocators allocators;
166     Rm_NameServer nameServer;
167     /* RM instance transport parameters */
168     Rm_TransportRouteMap routeMap;
169     /* RM Transaction sequence number counter */
170     uint32_t transactionSeqNum;
171     /* RM transaction queue */
172     Rm_TransactionQueue transactionQueue;
173     /* Transport API function pointers - not global in case application wants to
174       * hook up different transports to RM */
175     Rm_TransportCallouts transport;
176 } Rm_Inst;
178 Rm_Transaction *Rm_transactionQueueAdd(Rm_Inst *rmInst);
179 Rm_Transaction *Rm_transactionQueueFind(Rm_Inst *rmInst, uint32_t transactionId);
180 int32_t Rm_transactionQueueDelete(Rm_Inst *rmInst, uint32_t transactionId);
181 uint32_t Rm_transactionGetSequenceNum(Rm_Inst *rmInst);
183 Rm_Allocator *Rm_allocatorFind(Rm_Inst *rmInst, char *resourceName);
185 void Rm_transactionResponder (Rm_Inst *rmInst, Rm_Transaction *transaction);
186 void Rm_transactionForwarder (Rm_Inst *rmInst, Rm_Transaction *transaction);
187 void Rm_transactionProcessor (Rm_Inst *rmInst, Rm_Transaction *transaction);
189 /**********************************************************************
190  ******************* Red-Black Tree BBST Defines **********************
191  **********************************************************************/
193 /* Declare the tree structure nodes */
194 typedef struct Rm_AllocatedTo_s {
195     void                    *instNameNode;
196     struct Rm_AllocatedTo_s *nextAllocatedTo;
197 } Rm_AllocatedTo;
199 typedef struct _Rm_ResourceNode {
200     RB_ENTRY(_Rm_ResourceNode)  linkage;
201     uint32_t                    base;
202     uint32_t                    length;
203     uint16_t                    allocationCount;
204     Rm_AllocatedTo             *allocatedTo;
205 } Rm_ResourceNode;
207 /* Declare the tree head structure.  A structure of type Rm_ResourceTree will need to be
208  * malloc'd for each tree that is to be created. */
209 typedef RB_HEAD(_Rm_ResourceTree, _Rm_ResourceNode) Rm_ResourceTree;
211 Rm_ResourceNode *Rm_newResourceNode(uint32_t resourceBase, uint32_t resourceLength);
212 void Rm_freeResourceNode(Rm_ResourceNode *node);
213 /* Prototype for tree node comparison function
214  * element1 < element2 --> return < 0
215  * element1 = element2 --> return 0
216  * element1 > element2 --> return > 0 */
217 int Rm_ResourceNodeCompare(Rm_ResourceNode *element1, Rm_ResourceNode *element2); 
219 /* Generate the tree prototypes */
220 RB_PROTOTYPE(_Rm_ResourceTree, _Rm_ResourceNode, linkage, Rm_ResourceNodeCompare);
222 #ifdef __cplusplus
224 #endif
226 #endif /* RMLOC_H_ */