1 | |
2 | /* |
3 | * Copyright (c) 2000 Apple Computer, Inc. All rights reserved. |
4 | * |
5 | * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ |
6 | * |
7 | * This file contains Original Code and/or Modifications of Original Code |
8 | * as defined in and that are subject to the Apple Public Source License |
9 | * Version 2.0 (the 'License'). You may not use this file except in |
10 | * compliance with the License. The rights granted to you under the License |
11 | * may not be used to create, or enable the creation or redistribution of, |
12 | * unlawful or unlicensed copies of an Apple operating system, or to |
13 | * circumvent, violate, or enable the circumvention or violation of, any |
14 | * terms of an Apple operating system software license agreement. |
15 | * |
16 | * Please obtain a copy of the License at |
17 | * http://www.opensource.apple.com/apsl/ and read it before using this file. |
18 | * |
19 | * The Original Code and all software distributed under the License are |
20 | * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER |
21 | * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, |
22 | * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, |
23 | * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. |
24 | * Please see the License for the specific language governing rights and |
25 | * limitations under the License. |
26 | * |
27 | * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ |
28 | */ |
29 | #ifndef _PEXPERT_DEVICE_TREE_H_ |
30 | #define _PEXPERT_DEVICE_TREE_H_ |
31 | |
32 | #include <sys/appleapiopts.h> |
33 | |
34 | #ifdef __APPLE_API_PRIVATE |
35 | |
36 | #ifdef __cplusplus |
37 | extern "C" { |
38 | #endif |
39 | |
40 | /* |
41 | ------------------------------------------------------------------------------- |
42 | Foundation Types |
43 | ------------------------------------------------------------------------------- |
44 | */ |
45 | enum { |
46 | kDTPathNameSeparator = '/' /* 0x2F */ |
47 | }; |
48 | |
49 | |
50 | /* Property Name Definitions (Property Names are C-Strings)*/ |
51 | enum { |
52 | kDTMaxPropertyNameLength=31 /* Max length of Property Name (terminator not included) */ |
53 | }; |
54 | |
55 | typedef char DTPropertyNameBuf[32]; |
56 | |
57 | |
58 | /* Entry Name Definitions (Entry Names are C-Strings)*/ |
59 | enum { |
60 | kDTMaxEntryNameLength = 63 /* Max length of a C-String Entry Name (terminator not included) */ |
61 | }; |
62 | |
63 | /* length of DTEntryNameBuf = kDTMaxEntryNameLength +1*/ |
64 | typedef char DTEntryNameBuf[kDTMaxEntryNameLength+1]; |
65 | |
66 | /* |
67 | Structures for a Flattened Device Tree |
68 | */ |
69 | |
70 | #define kPropNameLength 32 |
71 | |
72 | typedef struct DeviceTreeNodeProperty { |
73 | char name[kPropNameLength]; // NUL terminated property name |
74 | uint32_t length; // Length (bytes) of folloing prop value |
75 | // unsigned long value[1]; // Variable length value of property |
76 | // Padded to a multiple of a longword? |
77 | } DeviceTreeNodeProperty; |
78 | |
79 | typedef struct OpaqueDTEntry { |
80 | uint32_t nProperties; // Number of props[] elements (0 => end) |
81 | uint32_t nChildren; // Number of children[] elements |
82 | // DeviceTreeNodeProperty props[];// array size == nProperties |
83 | // DeviceTreeNode children[]; // array size == nChildren |
84 | } DeviceTreeNode; |
85 | |
86 | typedef DeviceTreeNode *RealDTEntry; |
87 | |
88 | typedef struct DTSavedScope { |
89 | struct DTSavedScope * nextScope; |
90 | RealDTEntry scope; |
91 | RealDTEntry entry; |
92 | unsigned long index; |
93 | } *DTSavedScopePtr; |
94 | |
95 | /* Entry Iterator*/ |
96 | typedef struct OpaqueDTEntryIterator { |
97 | RealDTEntry outerScope; |
98 | RealDTEntry currentScope; |
99 | RealDTEntry currentEntry; |
100 | DTSavedScopePtr savedScope; |
101 | unsigned long currentIndex; |
102 | } OpaqueDTEntryIterator, *DTEntryIterator; |
103 | |
104 | /* Property Iterator*/ |
105 | typedef struct OpaqueDTPropertyIterator { |
106 | RealDTEntry entry; |
107 | DeviceTreeNodeProperty *currentProperty; |
108 | unsigned long currentIndex; |
109 | } OpaqueDTPropertyIterator, *DTPropertyIterator; |
110 | |
111 | /* Entry*/ |
112 | typedef struct OpaqueDTEntry* DTEntry; |
113 | |
114 | /* Entry Iterator*/ |
115 | typedef struct OpaqueDTEntryIterator* DTEntryIterator; |
116 | |
117 | /* Property Iterator*/ |
118 | typedef struct OpaqueDTPropertyIterator* DTPropertyIterator; |
119 | |
120 | |
121 | /* status values*/ |
122 | enum { |
123 | kError = -1, |
124 | kIterationDone = 0, |
125 | kSuccess = 1 |
126 | }; |
127 | |
128 | |
129 | #ifndef __MWERKS__ |
130 | /* |
131 | ------------------------------------------------------------------------------- |
132 | Device Tree Calls |
133 | ------------------------------------------------------------------------------- |
134 | */ |
135 | |
136 | /* Used to initalize the device tree functions. */ |
137 | /* base is the base address of the flatened device tree */ |
138 | void DTInit(void *base); |
139 | |
140 | /* |
141 | ------------------------------------------------------------------------------- |
142 | Entry Handling |
143 | ------------------------------------------------------------------------------- |
144 | */ |
145 | /* Compare two Entry's for equality. */ |
146 | extern int DTEntryIsEqual(const DTEntry ref1, const DTEntry ref2); |
147 | |
148 | /* |
149 | ------------------------------------------------------------------------------- |
150 | LookUp Entry by Name |
151 | ------------------------------------------------------------------------------- |
152 | */ |
153 | /* |
154 | DTFindEntry: |
155 | Find the device tree entry that contains propName=propValue. |
156 | It currently searches the entire |
157 | tree. This function should eventually go in DeviceTree.c. |
158 | Returns: kSuccess = entry was found. Entry is in entryH. |
159 | kError = entry was not found |
160 | */ |
161 | extern int DTFindEntry(const char *propName, const char *propValue, DTEntry *entryH); |
162 | |
163 | /* |
164 | Lookup Entry |
165 | Locates an entry given a specified subroot (searchPoint) and path name. If the |
166 | searchPoint pointer is NULL, the path name is assumed to be an absolute path |
167 | name rooted to the root of the device tree. |
168 | */ |
169 | extern int DTLookupEntry(const DTEntry searchPoint, const char *pathName, DTEntry *foundEntry); |
170 | |
171 | /* |
172 | ------------------------------------------------------------------------------- |
173 | Entry Iteration |
174 | ------------------------------------------------------------------------------- |
175 | */ |
176 | /* |
177 | An Entry Iterator maintains three variables that are of interest to clients. |
178 | First is an "OutermostScope" which defines the outer boundry of the iteration. |
179 | This is defined by the starting entry and includes that entry plus all of it's |
180 | embedded entries. Second is a "currentScope" which is the entry the iterator is |
181 | currently in. And third is a "currentPosition" which is the last entry returned |
182 | during an iteration. |
183 | |
184 | Initialize Entry Iterator |
185 | Fill out the iterator structure. The outermostScope and currentScope of the iterator |
186 | are set to "startEntry". If "startEntry" = NULL, the outermostScope and |
187 | currentScope are set to the root entry. The currentPosition for the iterator is |
188 | set to "nil". |
189 | */ |
190 | extern int DTInitEntryIterator(const DTEntry startEntry, DTEntryIterator iter); |
191 | |
192 | /* |
193 | Enter Child Entry |
194 | Move an Entry Iterator into the scope of a specified child entry. The |
195 | currentScope of the iterator is set to the entry specified in "childEntry". If |
196 | "childEntry" is nil, the currentScope is set to the entry specified by the |
197 | currentPosition of the iterator. |
198 | */ |
199 | extern int DTEnterEntry(DTEntryIterator iterator, DTEntry childEntry); |
200 | |
201 | /* |
202 | Exit to Parent Entry |
203 | Move an Entry Iterator out of the current entry back into the scope of it's parent |
204 | entry. The currentPosition of the iterator is reset to the current entry (the |
205 | previous currentScope), so the next iteration call will continue where it left off. |
206 | This position is returned in parameter "currentPosition". |
207 | */ |
208 | extern int DTExitEntry(DTEntryIterator iterator, DTEntry *currentPosition); |
209 | |
210 | /* |
211 | Iterate Entries |
212 | Iterate and return entries contained within the entry defined by the current |
213 | scope of the iterator. Entries are returned one at a time. When |
214 | int == kIterationDone, all entries have been exhausted, and the |
215 | value of nextEntry will be Nil. |
216 | */ |
217 | extern int DTIterateEntries(DTEntryIterator iterator, DTEntry *nextEntry); |
218 | |
219 | /* |
220 | Restart Entry Iteration |
221 | Restart an iteration within the current scope. The iterator is reset such that |
222 | iteration of the contents of the currentScope entry can be restarted. The |
223 | outermostScope and currentScope of the iterator are unchanged. The currentPosition |
224 | for the iterator is set to "nil". |
225 | */ |
226 | extern int DTRestartEntryIteration(DTEntryIterator iterator); |
227 | |
228 | /* |
229 | ------------------------------------------------------------------------------- |
230 | Get Property Values |
231 | ------------------------------------------------------------------------------- |
232 | */ |
233 | /* |
234 | Get the value of the specified property for the specified entry. |
235 | |
236 | Get Property |
237 | */ |
238 | extern int DTGetProperty(const DTEntry entry, const char *propertyName, void **propertyValue, unsigned int *propertySize); |
239 | |
240 | /* |
241 | ------------------------------------------------------------------------------- |
242 | Iterating Properties |
243 | ------------------------------------------------------------------------------- |
244 | */ |
245 | /* |
246 | Initialize Property Iterator |
247 | Fill out the property iterator structure. The target entry is defined by entry. |
248 | */ |
249 | extern int DTInitPropertyIterator(const DTEntry entry, DTPropertyIterator iter); |
250 | |
251 | /* |
252 | Iterate Properites |
253 | Iterate and return properties for given entry. |
254 | When int == kIterationDone, all properties have been exhausted. |
255 | */ |
256 | |
257 | extern int DTIterateProperties(DTPropertyIterator iterator, |
258 | char **foundProperty); |
259 | |
260 | /* |
261 | Restart Property Iteration |
262 | Used to re-iterate over a list of properties. The Property Iterator is |
263 | reset to the beginning of the list of properties for an entry. |
264 | */ |
265 | |
266 | extern int DTRestartPropertyIteration(DTPropertyIterator iterator); |
267 | |
268 | #ifdef __cplusplus |
269 | } |
270 | #endif |
271 | |
272 | #endif /* __MWERKS__ */ |
273 | |
274 | #endif /* __APPLE_API_PRIVATE */ |
275 | |
276 | #endif /* _PEXPERT_DEVICE_TREE_H_ */ |
277 | |