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 41 extern "C" { 42 #endif 43 44 /* 45 * ------------------------------------------------------------------------------- 46 * Foundation Types 47 * ------------------------------------------------------------------------------- 48 */ 49 enum { 50 kDTPathNameSeparator = '/' /* 0x2F */ 51 }; 52 53 54 /* Property Name Definitions (Property Names are C-Strings)*/ 55 enum { 56 kDTMaxPropertyNameLength=31 /* Max length of Property Name (terminator not included) */ 57 }; 58 59 typedef char DTPropertyNameBuf[32]; 60 61 62 /* Entry Name Definitions (Entry Names are C-Strings)*/ 63 enum { 64 kDTMaxEntryNameLength = 63 /* Max length of a C-String Entry Name (terminator not included) */ 65 }; 66 67 /* length of DTEntryNameBuf = kDTMaxEntryNameLength +1*/ 68 typedef char DTEntryNameBuf[kDTMaxEntryNameLength + 1]; 69 70 /* 71 * Structures for a Flattened Device Tree 72 */ 73 74 #define kPropNameLength 32 75 76 typedef 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 83 typedef 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 90 typedef const DeviceTreeNode *RealDTEntry; 91 92 typedef struct DTSavedScope { 93 struct DTSavedScope * nextScope; 94 RealDTEntry scope; 95 RealDTEntry entry; 96 unsigned long index; 97 } *DTSavedScopePtr; 98 99 /* Entry Iterator*/ 100 typedef 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*/ 109 typedef struct OpaqueDTPropertyIterator { 110 RealDTEntry entry; 111 DeviceTreeNodeProperty const *currentProperty; 112 unsigned long currentIndex; 113 } OpaqueDTPropertyIterator, *DTPropertyIterator; 114 115 /* Entry*/ 116 typedef const struct OpaqueDTEntry* DTEntry; 117 118 /* Entry Iterator*/ 119 typedef struct OpaqueDTEntryIterator* DTEntryIterator; 120 121 /* Property Iterator*/ 122 typedef struct OpaqueDTPropertyIterator* DTPropertyIterator; 123 124 125 /* status values*/ 126 enum { 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 */ 142 extern 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. */ 147 extern bool SecureDTIsLockedDown(void); 148 149 /* 150 * ------------------------------------------------------------------------------- 151 * Entry Handling 152 * ------------------------------------------------------------------------------- 153 */ 154 /* Compare two Entry's for equality. */ 155 extern 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 */ 170 extern 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 */ 180 extern 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 */ 201 extern 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 */ 210 extern 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 */ 219 extern 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 */ 228 extern 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 */ 237 extern 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 */ 249 extern int SecureDTGetProperty(const DTEntry entry, const char *propertyName, 250 void const **propertyValue, unsigned int *propertySize); 251 252 extern 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 */ 265 extern 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 273 extern 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 282 extern 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 295 typedef 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