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