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
37extern "C" {
38#endif
39
40/*
41-------------------------------------------------------------------------------
42 Foundation Types
43-------------------------------------------------------------------------------
44*/
45enum {
46 kDTPathNameSeparator = '/' /* 0x2F */
47};
48
49
50/* Property Name Definitions (Property Names are C-Strings)*/
51enum {
52 kDTMaxPropertyNameLength=31 /* Max length of Property Name (terminator not included) */
53};
54
55typedef char DTPropertyNameBuf[32];
56
57
58/* Entry Name Definitions (Entry Names are C-Strings)*/
59enum {
60 kDTMaxEntryNameLength = 63 /* Max length of a C-String Entry Name (terminator not included) */
61};
62
63/* length of DTEntryNameBuf = kDTMaxEntryNameLength +1*/
64typedef char DTEntryNameBuf[kDTMaxEntryNameLength+1];
65
66/*
67Structures for a Flattened Device Tree
68 */
69
70#define kPropNameLength 32
71
72typedef 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
79typedef 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
86typedef DeviceTreeNode *RealDTEntry;
87
88typedef struct DTSavedScope {
89 struct DTSavedScope * nextScope;
90 RealDTEntry scope;
91 RealDTEntry entry;
92 unsigned long index;
93} *DTSavedScopePtr;
94
95/* Entry Iterator*/
96typedef 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*/
105typedef struct OpaqueDTPropertyIterator {
106 RealDTEntry entry;
107 DeviceTreeNodeProperty *currentProperty;
108 unsigned long currentIndex;
109} OpaqueDTPropertyIterator, *DTPropertyIterator;
110
111/* Entry*/
112typedef struct OpaqueDTEntry* DTEntry;
113
114/* Entry Iterator*/
115typedef struct OpaqueDTEntryIterator* DTEntryIterator;
116
117/* Property Iterator*/
118typedef struct OpaqueDTPropertyIterator* DTPropertyIterator;
119
120
121/* status values*/
122enum {
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 */
138void DTInit(void *base);
139
140/*
141-------------------------------------------------------------------------------
142 Entry Handling
143-------------------------------------------------------------------------------
144*/
145/* Compare two Entry's for equality. */
146extern 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*/
161extern 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*/
169extern 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*/
190extern 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*/
199extern 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*/
208extern 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*/
217extern 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*/
226extern 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*/
238extern 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*/
249extern 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
257extern 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
266extern 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