pexpert/pexpert/device_tree.h

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