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