Added policy permission to exclude resource ranges from UNSPECIFIED base allocation...
[keystone-rtos/rm-lld.git] / include / rm_treeloc.h
1 /*
2  *  file  rm_treeloc.h
3  *
4  *  Prototypes and data structures for the various RM Trees.
5  *
6  *  ============================================================================
7  *      (C) Copyright 2012-2015, 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_TREELOC_H_
41 #define RM_TREELOC_H_
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
47 /* Standard includes */
48 #include <stdint.h>
50 /* RM external includes */
51 #include <ti/drv/rm/rm.h>
53 /* Tree algorithm includes */
54 #include <ti/drv/rm/util/tree.h>
56 /**********************************************************************
57  *************** Tree Node Data Structure Definitions *****************
58  **********************************************************************/
60 /* NameServer node configuration structure */
61 typedef struct {
62     /* Name to assign to the resource values */
63     char     *objName;
64     /* Resource name assigned to the NameServer name */
65     char     *resourceName;
66     /* Resource base value assigned to the NameServer name */
67     uint32_t  resourceBase;
68     /* Resource length value (starting from base) assigned to the NameServer
69      * name */
70     uint32_t  resourceLength;
71 } Rm_NameServerNodeCfg;
73 /* NameServer node */
74 typedef struct _Rm_NameServerNode {
75     /* Tree algorithm data structure */
76     RB_ENTRY(_Rm_NameServerNode) linkage;
77     /* Name string */
78     char                         objName[RM_NAME_MAX_CHARS];
79     /* Resource name */
80     char                         resourceName[RM_NAME_MAX_CHARS];
81     /* Resource base value */
82     uint32_t                     resourceBase;
83     /* Resource length value */
84     uint32_t                     resourceLength;
85 } Rm_NameServerNode;
87 /* NameServer tree root entry type definition */
88 typedef RB_HEAD(_Rm_NameServerTree, _Rm_NameServerNode) Rm_NameServerTree;
90 /* Valid instance node */
91 typedef struct _Rm_PolicyValidInstNode {
92     /* Tree algorithm data structure */
93     RB_ENTRY(_Rm_PolicyValidInstNode) linkage;
94     /* Valid instance name string */
95     char                              name[RM_NAME_MAX_CHARS];
96     /* Number of existing resource allocations the instance is
97      * reference in.  Resource frees involving the instance
98      * will decrement this count.  A valid instance node cannot
99      * be deleted until this value is zero */
100     uint32_t                          allocRefCount;
101     /* TRUE: Delete this valid instance node once the allocRefCount
102      *       reaches zero
103      * FALSE: Do not delete */
104     int32_t                           deletePending;
105     /* Instance index used in policy permission assignments */
106     int32_t                           instIdx;
107 } Rm_PolicyValidInstNode;
109 /* Valid instance tree root entry type definition */
110 typedef RB_HEAD(_Rm_PolicyValidInstTree,
111                 _Rm_PolicyValidInstNode) Rm_PolicyValidInstTree;
113 /* Resource node owner linked list node */
114 typedef struct Rm_Owner_s {
115     /* Pointer to the valid instance node that currently
116      * owns or partially owns the resource */
117     Rm_PolicyValidInstNode *instNameNode;
118     /* Number of times this owner has allocated the resource it is
119      * linked to. */
120     uint16_t                refCnt;
121     /* Link to the next owner of the resoruce if the resource is shared */
122     struct Rm_Owner_s      *nextOwner;
123 } Rm_Owner;
125 /* Resource node */
126 typedef struct _Rm_ResourceNode {
127     /* Tree algorithm data structure */
128     RB_ENTRY(_Rm_ResourceNode) linkage;
129     /* Resource base value */
130     uint32_t                   base;
131     /* Resource length value.  With base this node covers a resource's values
132      * from base to base+length-1 */
133     uint32_t                   length;
134     /* Number of times this resource node has been allocated to a valid
135      * instance.  This value will decrement for each free operation */
136     uint16_t                   allocationCount;
137     /* Linked list of existing owners.  Will be NULL if no owners exist
138      * for the resource node */
139     Rm_Owner                   *ownerList;
140 } Rm_ResourceNode;
142 /* Resource tree root entry type definition */
143 typedef RB_HEAD(_Rm_AllocatorResourceTree, _Rm_ResourceNode) Rm_ResourceTree;
145 /* Policy permission bit storage definition for Rm_PolicyPermBits
146  * Bit : Description
147  *-----------------------------
148  *  0  : Init         (i) - RM instance has initialization permission for
149  *                          resource
150  *  1  : Use          (u) - RM instance has usage permission for resource
151  *  2  : Exclusive    (x) - RM instance has exclusive allocation privilege for
152  *                          resource i.e. No other RM instance can reserve the
153  *                          resource if a RM instance with exclusive privilege
154  *                          reserves the resource
155  *  3  : Shared Linux (s) - Resource has been reserved by the Linux kernel but
156  *                          can be allocated by the specified RM instances
157  */
159 /* Maximum number of bits used to represent all permissions.  Must be
160  * changed as new permissions are added */
161 #define RM_POLICY_PERM_MAX_BITS                5
163 /* Initialization permission characters */
164 #define RM_POLICY_PERM_INIT_LOWER             'i'
165 #define RM_POLICY_PERM_INIT_UPPER             'I'
166 /* Initialization permission bit shift */
167 #define RM_POLICY_PERM_INIT_SHIFT              0
168 /* Usage permission characters */
169 #define RM_POLICY_PERM_USE_LOWER              'u'
170 #define RM_POLICY_PERM_USE_UPPER              'U'
171 /* Usage permission bit shift */
172 #define RM_POLICY_PERM_USE_SHIFT               1
173 /* Exclusive permission characters */
174 #define RM_POLICY_PERM_EXCLUSIVE_LOWER        'x'
175 #define RM_POLICY_PERM_EXCLUSIVE_UPPER        'X'
176 /* Exclusive permission bit shift */
177 #define RM_POLICY_PERM_EXCLUSIVE_SHIFT         2
178 /* Shared Linux permission characters */
179 #define RM_POLICY_PERM_SHARED_LINUX_LOWER     's'
180 #define RM_POLICY_PERM_SHARED_LINUX_UPPER     'S'
181 /* Shared Linux permission bit shift */
182 #define RM_POLICY_PERM_SHARED_LINUX_SHIFT      3
183 /* UNSPECIFIED allocation exclusion permission characters */
184 #define RM_POLICY_PERM_UNSPEC_EXCLUSION_LOWER 'e'
185 #define RM_POLICY_PERM_UNSPEC_EXCLUSION_UPPER 'E'
186 /* UNSPECIFIED allocation exclusion permission bit shift */
187 #define RM_POLICY_PERM_UNSPEC_EXCLUSION_SHIFT  4
189 /* Permissions subgroup start character */
190 #define RM_POLICY_PERM_SUBGROUP_START         '('
191 /* Permissions subgroup end character */
192 #define RM_POLICY_PERM_SUBGROUP_END           ')'
193 /* Permissions subgroup terminator */
194 #define RM_POLICY_PERM_TERMINATOR             '&'
195 /* Permissions assignment character */
196 #define RM_POLICY_PERM_ASSIGNMENT             '='
198 /* Policy permission bit storage type */
199 typedef uint32_t Rm_PolicyPermBits;
201 /* Policy node */
202 typedef struct _Rm_PolicyNode {
203     /* Tree algorithm data structure */
204     RB_ENTRY(_Rm_PolicyNode)  linkage;
205     /* Policy base value */
206     uint32_t                  base;
207     /* Policy length value.  With base this node covers a policy's values
208      * from base to base+length-1 */
209     uint32_t                  len;
210     /* Pointer to array containing permission bitfields for the node's 
211      * resource range */
212     Rm_PolicyPermBits        *perms;
213     /* Size of permissions array in bytes pointed to by the perms pointer */
214     uint32_t                  permsLen;
215     /* Allocation alignment.  Allocations must be aligned to a base that is a
216      * multiple of the allocation alignment */
217     uint32_t                  allocAlign;
218     /* Client Delegate allocation block size */
219     uint32_t                  cdAllocSize;
220 } Rm_PolicyNode;
222 /* Policy tree root entry type definition */
223 typedef RB_HEAD(_Rm_AllocatorPolicyTree, _Rm_PolicyNode) Rm_PolicyTree;
225 /* Allocator node */
226 typedef struct _Rm_AllocatorNode {
227     /* Tree algorithm data structure */
228     RB_ENTRY(_Rm_AllocatorNode)  linkage;
229     /* Resource name for which the allocator was created.  The resource name
230      * must match a resource node defined in both the GRL and the Policy */
231     char                         resourceName[RM_NAME_MAX_CHARS];
232     /* Pointer to root entry of allocator's resource tree */
233     Rm_ResourceTree             *resourceRoot;
234     /* Pointer to root entry of allocator's policy tree */
235     Rm_PolicyTree               *policyRoot;
236 } Rm_AllocatorNode;
238 /* Allocator tree root entry type definition */
239 typedef RB_HEAD(_Rm_AllocatorTree, _Rm_AllocatorNode) Rm_AllocatorTree;
241 /**********************************************************************
242  ****************** Tree Node Function Definitions ********************
243  **********************************************************************/
245 void rmNameServerTreeInv(Rm_NameServerTree *treeRoot);
246 void rmNameServerTreeWb(Rm_NameServerTree *treeRoot);
247 Rm_NameServerNode *rmNameServerNodeNew(Rm_NameServerNodeCfg *nodeCfg);
248 void rmNameServerNodeFree(Rm_NameServerNode *node);
249 int rmNameServerNodeCompare(Rm_NameServerNode *node1,
250                             Rm_NameServerNode *node2);
251 void rmNameServerNodeInv(Rm_NameServerNode *node);
253 void rmPolicyValidInstTreeInv(Rm_PolicyValidInstTree *treeRoot);
254 void rmPolicyValidInstTreeWb(Rm_PolicyValidInstTree *treeRoot);
255 Rm_PolicyValidInstNode *rmPolicyValidInstNodeNew(const char *instName,
256                                                  const int32_t instIdx);
257 void rmPolicyValidInstNodeFree(Rm_PolicyValidInstNode *node);
258 int rmPolicyValidInstNodeCompare(Rm_PolicyValidInstNode *node1,
259                                  Rm_PolicyValidInstNode *node2);
260 void rmPolicyValidInstNodeInv(Rm_PolicyValidInstNode *node);
262 void rmResourceTreeInv(Rm_ResourceTree *treeRoot);
263 void rmResourceTreeWb(Rm_ResourceTree *treeRoot);
264 Rm_ResourceNode *rmResourceNodeNew(uint32_t resourceBase,
265                                    uint32_t resourceLength);
266 void rmResourceNodeFree(Rm_ResourceNode *node);
267 int rmResourceNodeCompare(Rm_ResourceNode *node1, Rm_ResourceNode *node2);
268 void rmResourceNodeInv(Rm_ResourceNode *node);
270 void rmPolicyTreeInv(Rm_PolicyTree *treeRoot);
271 void rmPolicyTreeWb(Rm_PolicyTree *treeRoot);
272 Rm_PolicyNode *rmPolicyNodeNew(uint32_t resourceBase, uint32_t resourceLength);
273 void rmPolicyNodeFree(Rm_PolicyNode *node);
274 int rmPolicyNodeCompare(Rm_PolicyNode *node1, Rm_PolicyNode *node2);
275 void rmPolicyNodeInv(Rm_PolicyNode *node);
277 void rmAllocatorTreeInv(Rm_AllocatorTree *treeRoot);
278 void rmAllocatorTreeWb(Rm_AllocatorTree *treeRoot);
279 Rm_AllocatorNode *rmAllocatorNodeNew(const char *resourceName);
280 void rmAllocatorNodeFree(Rm_AllocatorNode *node);
281 int rmAllocatorNodeCompare(Rm_AllocatorNode *node1, Rm_AllocatorNode *node2);
282 void rmAllocatorNodeInv(Rm_AllocatorNode *node);
284 /**********************************************************************
285  ******************** Tree Prototype Generation ***********************
286  **********************************************************************/
287  
288 RB_PROTOTYPE(_Rm_NameServerTree, _Rm_NameServerNode, linkage,
289              rmNameServerNodeCompare, rmNameServerNodeInv)
290 RB_PROTOTYPE(_Rm_PolicyValidInstTree, _Rm_PolicyValidInstNode, linkage,
291              rmPolicyValidInstNodeCompare, rmPolicyValidInstNodeInv)
292 RB_PROTOTYPE(_Rm_AllocatorResourceTree, _Rm_ResourceNode, linkage,
293              rmResourceNodeCompare, rmResourceNodeInv)
294 RB_PROTOTYPE(_Rm_AllocatorPolicyTree, _Rm_PolicyNode, linkage,
295              rmPolicyNodeCompare, rmPolicyNodeInv)
296 RB_PROTOTYPE(_Rm_AllocatorTree, _Rm_AllocatorNode, linkage,
297              rmAllocatorNodeCompare, rmAllocatorNodeInv)
299 #ifdef __cplusplus
301 #endif
303 #endif /* RM_TREELOC_H_ */