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
67/* Entry*/
68typedef struct OpaqueDTEntry* DTEntry;
69
70/* Entry Iterator*/
71typedef struct OpaqueDTEntryIterator* DTEntryIterator;
72
73/* Property Iterator*/
74typedef struct OpaqueDTPropertyIterator* DTPropertyIterator;
75
76
77/* status values*/
78enum {
79		kError = -1,
80		kIterationDone = 0,
81		kSuccess = 1
82};
83
84/*
85
86Structures for a Flattened Device Tree
87 */
88
89#define kPropNameLength	32
90
91typedef struct DeviceTreeNodeProperty {
92    char		name[kPropNameLength];	// NUL terminated property name
93    uint32_t		length;		// Length (bytes) of folloing prop value
94//  unsigned long	value[1];	// Variable length value of property
95					// Padded to a multiple of a longword?
96} DeviceTreeNodeProperty;
97
98typedef struct OpaqueDTEntry {
99    uint32_t		nProperties;	// Number of props[] elements (0 => end)
100    uint32_t		nChildren;	// Number of children[] elements
101//  DeviceTreeNodeProperty	props[];// array size == nProperties
102//  DeviceTreeNode	children[];	// array size == nChildren
103} DeviceTreeNode;
104
105
106#ifndef	__MWERKS__
107/*
108-------------------------------------------------------------------------------
109 Device Tree Calls
110-------------------------------------------------------------------------------
111*/
112
113/* Used to initalize the device tree functions. */
114/* base is the base address of the flatened device tree */
115void DTInit(void *base);
116
117/*
118-------------------------------------------------------------------------------
119 Entry Handling
120-------------------------------------------------------------------------------
121*/
122/* Compare two Entry's for equality. */
123extern int DTEntryIsEqual(const DTEntry ref1, const DTEntry ref2);
124
125/*
126-------------------------------------------------------------------------------
127 LookUp Entry by Name
128-------------------------------------------------------------------------------
129*/
130/*
131 DTFindEntry:
132 Find the device tree entry that contains propName=propValue.
133 It currently  searches the entire
134 tree.  This function should eventually go in DeviceTree.c.
135 Returns:    kSuccess = entry was found.  Entry is in entryH.
136             kError   = entry was not found
137*/
138extern int DTFindEntry(const char *propName, const char *propValue, DTEntry *entryH);
139
140/*
141 Lookup Entry
142 Locates an entry given a specified subroot (searchPoint) and path name.  If the
143 searchPoint pointer is NULL, the path name is assumed to be an absolute path
144 name rooted to the root of the device tree.
145*/
146extern int DTLookupEntry(const DTEntry searchPoint, const char *pathName, DTEntry *foundEntry);
147
148/*
149-------------------------------------------------------------------------------
150 Entry Iteration
151-------------------------------------------------------------------------------
152*/
153/*
154 An Entry Iterator maintains three variables that are of interest to clients.
155 First is an "OutermostScope" which defines the outer boundry of the iteration.
156 This is defined by the starting entry and includes that entry plus all of it's
157 embedded entries. Second is a "currentScope" which is the entry the iterator is
158 currently in. And third is a "currentPosition" which is the last entry returned
159 during an iteration.
160
161 Create Entry Iterator
162 Create the iterator structure. The outermostScope and currentScope of the iterator
163 are set to "startEntry".  If "startEntry" = NULL, the outermostScope and
164 currentScope are set to the root entry.  The currentPosition for the iterator is
165 set to "nil".
166*/
167extern int DTCreateEntryIterator(const DTEntry startEntry, DTEntryIterator *iterator);
168
169/* Dispose Entry Iterator*/
170extern int DTDisposeEntryIterator(DTEntryIterator iterator);
171
172/*
173 Enter Child Entry
174 Move an Entry Iterator into the scope of a specified child entry.  The
175 currentScope of the iterator is set to the entry specified in "childEntry".  If
176 "childEntry" is nil, the currentScope is set to the entry specified by the
177 currentPosition of the iterator.
178*/
179extern int DTEnterEntry(DTEntryIterator iterator, DTEntry childEntry);
180
181/*
182 Exit to Parent Entry
183 Move an Entry Iterator out of the current entry back into the scope of it's parent
184 entry. The currentPosition of the iterator is reset to the current entry (the
185 previous currentScope), so the next iteration call will continue where it left off.
186 This position is returned in parameter "currentPosition".
187*/
188extern int DTExitEntry(DTEntryIterator iterator, DTEntry *currentPosition);
189
190/*
191 Iterate Entries
192 Iterate and return entries contained within the entry defined by the current
193 scope of the iterator.  Entries are returned one at a time. When
194 int == kIterationDone, all entries have been exhausted, and the
195 value of nextEntry will be Nil.
196*/
197extern int DTIterateEntries(DTEntryIterator iterator, DTEntry *nextEntry);
198
199/*
200 Restart Entry Iteration
201 Restart an iteration within the current scope.  The iterator is reset such that
202 iteration of the contents of the currentScope entry can be restarted. The
203 outermostScope and currentScope of the iterator are unchanged. The currentPosition
204 for the iterator is set to "nil".
205*/
206extern int DTRestartEntryIteration(DTEntryIterator iterator);
207
208/*
209-------------------------------------------------------------------------------
210 Get Property Values
211-------------------------------------------------------------------------------
212*/
213/*
214 Get the value of the specified property for the specified entry.
215
216 Get Property
217*/
218extern int DTGetProperty(const DTEntry entry, const char *propertyName, void **propertyValue, unsigned int *propertySize);
219
220/*
221-------------------------------------------------------------------------------
222 Iterating Properties
223-------------------------------------------------------------------------------
224*/
225/*
226 Create Property Iterator
227 Create the property iterator structure. The target entry is defined by entry.
228*/
229
230extern int DTCreatePropertyIterator(const DTEntry entry,
231					DTPropertyIterator *iterator);
232
233/* Dispose Property Iterator*/
234extern int DTDisposePropertyIterator(DTPropertyIterator iterator);
235
236/*
237 Iterate Properites
238 Iterate and return properties for given entry.
239 When int == kIterationDone, all properties have been exhausted.
240*/
241
242extern int DTIterateProperties(DTPropertyIterator iterator,
243						char **foundProperty);
244
245/*
246 Restart Property Iteration
247 Used to re-iterate over a list of properties.  The Property Iterator is
248 reset to the beginning of the list of properties for an entry.
249*/
250
251extern int DTRestartPropertyIteration(DTPropertyIterator iterator);
252
253#ifdef __cplusplus
254}
255#endif
256
257#endif /* __MWERKS__ */
258
259#endif /* __APPLE_API_PRIVATE */
260
261#endif /* _PEXPERT_DEVICE_TREE_H_ */
262