pexpert/pexpert/device_tree.h

   1
   2 /*
   3  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   4  *
   5  * @APPLE_LICENSE_HEADER_START@
   6  *
   7  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   8  *
   9  * This file contains Original Code and/or Modifications of Original Code
  10  * as defined in and that are subject to the Apple Public Source License
  11  * Version 2.0 (the 'License'). You may not use this file except in
  12  * compliance with the License. Please obtain a copy of the License at
  13  * http://www.opensource.apple.com/apsl/ and read it before using this
  14  * file.
  15  *
  16  * The Original Code and all software distributed under the License are
  17  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  18  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  19  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  20  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  21  * Please see the License for the specific language governing rights and
  22  * limitations under the License.
  23  *
  24  * @APPLE_LICENSE_HEADER_END@
  25  */
  26 #ifndef _PEXPERT_DEVICE_TREE_H_
  27 #define _PEXPERT_DEVICE_TREE_H_
  28
  29 #include <sys/appleapiopts.h>
  30
  31 #ifdef __APPLE_API_PRIVATE
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /*
  38 -------------------------------------------------------------------------------
  39  Foundation Types
  40 -------------------------------------------------------------------------------
  41 */
  42 enum {
  43         kDTPathNameSeparator    = '/'                           /* 0x2F */
  44 };
  45
  46
  47 /* Property Name Definitions (Property Names are C-Strings)*/
  48 enum {
  49         kDTMaxPropertyNameLength=31     /* Max length of Property Name (terminator not included) */
  50 };
  51
  52 typedef char DTPropertyNameBuf[32];
  53
  54
  55 /* Entry Name Definitions (Entry Names are C-Strings)*/
  56 enum {
  57         kDTMaxEntryNameLength           = 31    /* Max length of a C-String Entry Name (terminator not included) */
  58 };
  59
  60 /* length of DTEntryNameBuf = kDTMaxEntryNameLength +1*/
  61 typedef char DTEntryNameBuf[32];
  62
  63
  64 /* Entry*/
  65 typedef struct OpaqueDTEntry* DTEntry;
  66
  67 /* Entry Iterator*/
  68 typedef struct OpaqueDTEntryIterator* DTEntryIterator;
  69
  70 /* Property Iterator*/
  71 typedef struct OpaqueDTPropertyIterator* DTPropertyIterator;
  72
  73
  74 /* status values*/
  75 enum {
  76                 kError = -1,
  77                 kIterationDone = 0,
  78                 kSuccess = 1
  79 };
  80
  81 /*
  82
  83 Structures for a Flattened Device Tree
  84  */
  85
  86 #define kPropNameLength 32
  87
  88 typedef struct DeviceTreeNodeProperty {
  89     char                name[kPropNameLength];  // NUL terminated property name
  90     unsigned long       length;         // Length (bytes) of folloing prop value
  91 //  unsigned long       value[1];       // Variable length value of property
  92                                         // Padded to a multiple of a longword?
  93 } DeviceTreeNodeProperty;
  94
  95 typedef struct OpaqueDTEntry {
  96     unsigned long       nProperties;    // Number of props[] elements (0 => end)
  97     unsigned long       nChildren;      // Number of children[] elements
  98 //  DeviceTreeNodeProperty      props[];// array size == nProperties
  99 //  DeviceTreeNode      children[];     // array size == nChildren
 100 } DeviceTreeNode;
 101
 102
 103 #ifndef __MWERKS__
 104 /*
 105 -------------------------------------------------------------------------------
 106  Device Tree Calls
 107 -------------------------------------------------------------------------------
 108 */
 109
 110 /* Used to initalize the device tree functions. */
 111 /* base is the base address of the flatened device tree */
 112 void DTInit(void *base);
 113
 114 /*
 115 -------------------------------------------------------------------------------
 116  Entry Handling
 117 -------------------------------------------------------------------------------
 118 */
 119 /* Compare two Entry's for equality. */
 120 extern int DTEntryIsEqual(const DTEntry ref1, const DTEntry ref2);
 121
 122 /*
 123 -------------------------------------------------------------------------------
 124  LookUp Entry by Name
 125 -------------------------------------------------------------------------------
 126 */
 127 /*
 128  DTFindEntry:
 129  Find the device tree entry that contains propName=propValue.
 130  It currently  searches the entire
 131  tree.  This function should eventually go in DeviceTree.c.
 132  Returns:    kSuccess = entry was found.  Entry is in entryH.
 133              kError   = entry was not found
 134 */
 135 extern int DTFindEntry(const char *propName, const char *propValue, DTEntry *entryH);
 136
 137 /*
 138  Lookup Entry
 139  Locates an entry given a specified subroot (searchPoint) and path name.  If the
 140  searchPoint pointer is NULL, the path name is assumed to be an absolute path
 141  name rooted to the root of the device tree.
 142 */
 143 extern int DTLookupEntry(const DTEntry searchPoint, const char *pathName, DTEntry *foundEntry);
 144
 145 /*
 146 -------------------------------------------------------------------------------
 147  Entry Iteration
 148 -------------------------------------------------------------------------------
 149 */
 150 /*
 151  An Entry Iterator maintains three variables that are of interest to clients.
 152  First is an "OutermostScope" which defines the outer boundry of the iteration.
 153  This is defined by the starting entry and includes that entry plus all of it's
 154  embedded entries. Second is a "currentScope" which is the entry the iterator is
 155  currently in. And third is a "currentPosition" which is the last entry returned
 156  during an iteration.
 157
 158  Create Entry Iterator
 159  Create the iterator structure. The outermostScope and currentScope of the iterator
 160  are set to "startEntry".  If "startEntry" = NULL, the outermostScope and
 161  currentScope are set to the root entry.  The currentPosition for the iterator is
 162  set to "nil".
 163 */
 164 extern int DTCreateEntryIterator(const DTEntry startEntry, DTEntryIterator *iterator);
 165
 166 /* Dispose Entry Iterator*/
 167 extern int DTDisposeEntryIterator(DTEntryIterator iterator);
 168
 169 /*
 170  Enter Child Entry
 171  Move an Entry Iterator into the scope of a specified child entry.  The
 172  currentScope of the iterator is set to the entry specified in "childEntry".  If
 173  "childEntry" is nil, the currentScope is set to the entry specified by the
 174  currentPosition of the iterator.
 175 */
 176 extern int DTEnterEntry(DTEntryIterator iterator, DTEntry childEntry);
 177
 178 /*
 179  Exit to Parent Entry
 180  Move an Entry Iterator out of the current entry back into the scope of it's parent
 181  entry. The currentPosition of the iterator is reset to the current entry (the
 182  previous currentScope), so the next iteration call will continue where it left off.
 183  This position is returned in parameter "currentPosition".
 184 */
 185 extern int DTExitEntry(DTEntryIterator iterator, DTEntry *currentPosition);
 186
 187 /*
 188  Iterate Entries
 189  Iterate and return entries contained within the entry defined by the current
 190  scope of the iterator.  Entries are returned one at a time. When
 191  int == kIterationDone, all entries have been exhausted, and the
 192  value of nextEntry will be Nil.
 193 */
 194 extern int DTIterateEntries(DTEntryIterator iterator, DTEntry *nextEntry);
 195
 196 /*
 197  Restart Entry Iteration
 198  Restart an iteration within the current scope.  The iterator is reset such that
 199  iteration of the contents of the currentScope entry can be restarted. The
 200  outermostScope and currentScope of the iterator are unchanged. The currentPosition
 201  for the iterator is set to "nil".
 202 */
 203 extern int DTRestartEntryIteration(DTEntryIterator iterator);
 204
 205 /*
 206 -------------------------------------------------------------------------------
 207  Get Property Values
 208 -------------------------------------------------------------------------------
 209 */
 210 /*
 211  Get the value of the specified property for the specified entry.
 212
 213  Get Property
 214 */
 215 extern int DTGetProperty(const DTEntry entry, const char *propertyName, void **propertyValue, int *propertySize);
 216
 217 /*
 218 -------------------------------------------------------------------------------
 219  Iterating Properties
 220 -------------------------------------------------------------------------------
 221 */
 222 /*
 223  Create Property Iterator
 224  Create the property iterator structure. The target entry is defined by entry.
 225 */
 226
 227 extern int DTCreatePropertyIterator(const DTEntry entry,
 228                                         DTPropertyIterator *iterator);
 229
 230 /* Dispose Property Iterator*/
 231 extern int DTDisposePropertyIterator(DTPropertyIterator iterator);
 232
 233 /*
 234  Iterate Properites
 235  Iterate and return properties for given entry.
 236  When int == kIterationDone, all properties have been exhausted.
 237 */
 238
 239 extern int DTIterateProperties(DTPropertyIterator iterator,
 240                                                 char **foundProperty);
 241
 242 /*
 243  Restart Property Iteration
 244  Used to re-iterate over a list of properties.  The Property Iterator is
 245  reset to the beginning of the list of properties for an entry.
 246 */
 247
 248 extern int DTRestartPropertyIteration(DTPropertyIterator iterator);
 249
 250 #ifdef __cplusplus
 251 }
 252 #endif
 253
 254 #endif /* __MWERKS__ */
 255
 256 #endif /* __APPLE_API_PRIVATE */
 257
 258 #endif /* _PEXPERT_DEVICE_TREE_H_ */