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 **********************************************************************/
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
300 }
301 #endif
303 #endif /* RM_TREELOC_H_ */