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