Completed and tested routines that automatically reserve linux resources
[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_policy.h>
50 #include <ti/drv/rm/rm_transport.h>
52 /* AVL BBST includes */
53 #include <ti/drv/rm/include/tree.h>
55 /** String stored for resource elements that are not currently allocated to anyone.  If the
56  *  resource is allocated the allocatedTo field will be populated with the RM instance
57  *  name it was allocated to. */
58 #define RM_NOT_ALLOCATED_STRING "\0"
59 /** String stored for resource elements that are reserved by the Linux kernel.  These
60  *  resources will be in use for the lifetime of the system */
61 #define RM_ALLOCATED_TO_LINUX "Linux-Kernel"
63 /** Maximum size of a transmittable RM policy in bytes */
64 #define RM_MAX_POLICY_SIZE_BYTES (64)  // Placeholder: This will change 
65                                        // during development
67 /** Pointer to RM instance's transport routing map */
68 typedef void *Rm_TransportRouteMap;
70 /** Pointer to RM instance's transaction queue */
71 typedef void *Rm_TransactionQueue;
73 /** Pointer to the RM instance's allocators */
74 typedef void *Rm_Allocators;
76 /**
77  * @brief RM transaction details values.  Details values provide more fine-grained
78  *        information regarding a transaction request or response
79  */
80 typedef enum {
81     /** Transaction is being processed */
82     Rm_transactionState_PROCESSING = 0,
83     /** Transaction has been approved */
84     Rm_transactionState_TRANSACTION_APPROVED = 1,
85     /** Transaction has been denied */
86     Rm_transactionState_TRANSACTION_DENIED = 2  
87 } Rm_TransactionState;
89 /**
90  * @brief RM protocol packet resource information
91  */
92 typedef struct {
93     /** Resource name of resource affected by command */
94     char name[RM_RESOURCE_NAME_MAX_CHARS];
95     /** If applicable, start of resource range affected by command.  If
96      *  RM_RESOURCE_UNSPECIFIED is assigned the higher level RM agent*/
97     int32_t base;
98     /** If applicable, number of specified resource, starting from base, affected by command */
99     uint32_t length;
100     /** If applicable, the alignment of the resource affected by the command */
101     int32_t alignment;
102     /** If applicable, the NameServer name assigned to the specified
103      *  resource.  Used for commands centering on RM NameServer actions */
104     char nsName[RM_RESOURCE_NAME_MAX_CHARS];
105 } Rm_ResourceInfo;
107 /**
108  * @brief RM transactions are the internalized version of service requests received 
109  *        from components and RM commands received from other RM instances.
110  *        Transactions that cannot immediately be serviced are placed in the RM
111  *        instance's transaction queue.  The transactions track all service
112  *        requests within the RM infrastructure.
113  */
114 typedef struct {
115     /** Transaction service type */
116     Rm_ServiceType type;
117     /** Local ID of the transaction. */
118     uint32_t localId;
119     /** ID of transaction on lower level RM instance that generated the
120      *  packet that resulted in the creation of the transaction.  The
121      *  originating ID will be placed in the transaction's response packet
122      *  to the lower level RM instance.  The lower level RM instance will 
123      *  match the response packet with the originating request using the ID */
124     uint32_t remoteOriginatingId;
125     /** Name of the RM instance the transaction originated from */
126     char sourceInstName[RM_INSTANCE_NAME_MAX_CHARS];
127     /** Transaction's associated callback function */
128     Rm_ServiceCallback callback;
129     /** Transaction state.  The codes are externally visible and tracked
130      *  in rmservices.h */
131     int32_t state;
132     /** Resource information */
133     Rm_ResourceInfo resourceInfo;
134     /** Link to the next transaction in the queue */
135     void *nextTransaction;    
136 } Rm_Transaction;
138 typedef struct {
139     const void *allocatorData;
140     int32_t allocatorLen;
141     const void *rangeData;
142     int32_t rangeLen;
143     const void *nsAssignData;
144     int32_t nsAssignLen;
145     const void *linuxAliasData;
146     int32_t linuxAliasLen;
147 } Rm_ResourceProperties;
149 typedef enum {
150     Rm_allocatorType_INTEGER = 0,
151     Rm_allocatorType_TREE = 1,
152 } Rm_AllocatorType;
154 typedef enum {
155     Rm_allocatorOp_ALLOCATE = 0,
156     Rm_allocatorOp_FREE = 1,
157     Rm_allocatorOp_PRE_ALLOCATE = 2,
158 } Rm_AllocatorOp;
160 typedef struct {
161     char *srcInstName;
162     Rm_AllocatorOp operation;
163     /* When pre-allocating, the policy's ranges and alignment for the resource
164      * for the RM instance will be copied to the following three variables.  These
165      * variables will be used as the basis for pre-allocating a resource. */
166     uint32_t policyBase;
167     uint32_t policyLength;
168     uint32_t policyAlignment;
169     /* Will contain the actual allocation/free values */
170     Rm_ResourceInfo *resourceInfo;
171 } Rm_AllocatorOpInfo;
173 typedef struct {
174     uint32_t value;
175     char allocatedTo[RM_INSTANCE_NAME_MAX_CHARS];
176 } Rm_IntegerEntry;
178 typedef struct {
179     uint32_t numResourceElements;
180     Rm_IntegerEntry *resourceArrayBase;
181 } Rm_IntegerAllocatorRootEntry;
183 typedef struct {
184     char resourceName[RM_RESOURCE_NAME_MAX_CHARS];
185     Rm_AllocatorType type;
186     /** Pointer to the first resource entry in the allocator */
187     void *allocatorRootEntry;
188     /** Pointer to next resource allocator */
189     void *nextAllocator;
190 } Rm_Allocator;
192 typedef struct {
193     char name[RM_INSTANCE_NAME_MAX_CHARS];
194     Rm_InstType instType;
195     bool registeredWithDelegateOrServer;
196     Rm_PolicyHandle policyDtb;
197     Rm_Allocators allocators;
198     /* RM instance transport parameters */
199     Rm_TransportRouteMap routeMap;
200     /* RM Transaction sequence number counter */
201     uint32_t transactionSeqNum;
202     /* RM transaction queue */
203     Rm_TransactionQueue transactionQueue;
204     /* Transport API function pointers - not global in case application wants to
205       * hook up different transports to RM */
206     Rm_TransportCallouts transport;
207 } Rm_Inst;
209 Rm_Transaction *Rm_transactionQueueAdd(Rm_Inst *rmInst);
210 Rm_Transaction *Rm_transactionQueueFind(Rm_Inst *rmInst, uint32_t transactionId);
211 int32_t Rm_transactionQueueDelete(Rm_Inst *rmInst, uint32_t transactionId);
212 uint32_t Rm_transactionGetSequenceNum(Rm_Inst *rmInst);
214 void Rm_transactionProcessor (Rm_Inst *rmInst, Rm_Transaction *transaction);
216 /**********************************************************************
217  ******************* Red-Black Tree BBST Defines **********************
218  **********************************************************************/
220 /* Declare the tree structure nodes */
221 typedef struct _Rm_ResourceTreeNode {
222     RB_ENTRY(_Rm_ResourceTreeNode) linkage;
223     uint32_t base;
224     uint32_t length;
225     char allocatedTo[RM_INSTANCE_NAME_MAX_CHARS];
226 } Rm_ResourceTreeNode;
228 /* Declare the tree head structure.  A structure of type Rm_ResourceTree will need to be
229  * malloc'd for each tree that is to be created. */
230 typedef RB_HEAD(_Rm_ResourceTree, _Rm_ResourceTreeNode) Rm_ResourceTree;
232 /* Prototype for function that allocates new tree nodes */
233 Rm_ResourceTreeNode *Rm_newResourceTreeNode(uint32_t resourceBase, uint32_t resourceLength, 
234                                             char *allocatedTo);
235 /* Prototype for function that frees new tree nodes */
236 void Rm_freeResourceTreeNode(Rm_ResourceTreeNode *treeNode);
237 /* Prototype for tree node comparison function
238  * element1 < element2 --> return < 0
239  * element1 = element2 --> return 0
240  * element1 > element2 --> return > 0 */
241 int Rm_ResourceTreeNodeCompare(Rm_ResourceTreeNode *element1, Rm_ResourceTreeNode *element2); 
243 /* Generate the tree prototypes */
244 RB_PROTOTYPE(_Rm_ResourceTree, _Rm_ResourceTreeNode, linkage, Rm_ResourceTreeNodeCompare);
246 #ifdef __cplusplus
248 #endif
250 #endif /* RMLOC_H_ */