pexpert/pexpert/device_tree.h

   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
  37 extern "C" {
  38 #endif
  39
  40 /*
  41 -------------------------------------------------------------------------------
  42  Foundation Types
  43 -------------------------------------------------------------------------------
  44 */
  45 enum {
  46         kDTPathNameSeparator    = '/'                           /* 0x2F */
  47 };
  48
  49
  50 /* Property Name Definitions (Property Names are C-Strings)*/
  51 enum {
  52         kDTMaxPropertyNameLength=31     /* Max length of Property Name (terminator not included) */
  53 };
  54
  55 typedef char DTPropertyNameBuf[32];
  56
  57
  58 /* Entry Name Definitions (Entry Names are C-Strings)*/
  59 enum {
  60         kDTMaxEntryNameLength           = 31    /* Max length of a C-String Entry Name (terminator not included) */
  61 };
  62
  63 /* length of DTEntryNameBuf = kDTMaxEntryNameLength +1*/
  64 typedef char DTEntryNameBuf[32];
  65
  66
  67 /* Entry*/
  68 typedef struct OpaqueDTEntry* DTEntry;
  69
  70 /* Entry Iterator*/
  71 typedef struct OpaqueDTEntryIterator* DTEntryIterator;
  72
  73 /* Property Iterator*/
  74 typedef struct OpaqueDTPropertyIterator* DTPropertyIterator;
  75
  76
  77 /* status values*/
  78 enum {
  79                 kError = -1,
  80                 kIterationDone = 0,
  81                 kSuccess = 1
  82 };
  83
  84 /*
  85
  86 Structures for a Flattened Device Tree
  87  */
  88
  89 #define kPropNameLength 32
  90
  91 typedef struct DeviceTreeNodeProperty {
  92     char                name[kPropNameLength];  // NUL terminated property name
  93     unsigned long       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
  98 typedef struct OpaqueDTEntry {
  99     unsigned long       nProperties;    // Number of props[] elements (0 => end)
 100     unsigned long       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 */
 115 void DTInit(void *base);
 116
 117 /*
 118 -------------------------------------------------------------------------------
 119  Entry Handling
 120 -------------------------------------------------------------------------------
 121 */
 122 /* Compare two Entry's for equality. */
 123 extern 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 */
 138 extern 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 */
 146 extern 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 */
 167 extern int DTCreateEntryIterator(const DTEntry startEntry, DTEntryIterator *iterator);
 168
 169 /* Dispose Entry Iterator*/
 170 extern 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 */
 179 extern 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 */
 188 extern 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 */
 197 extern 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 */
 206 extern 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 */
 218 extern int DTGetProperty(const DTEntry entry, const char *propertyName, void **propertyValue, 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
 230 extern int DTCreatePropertyIterator(const DTEntry entry,
 231                                         DTPropertyIterator *iterator);
 232
 233 /* Dispose Property Iterator*/
 234 extern 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
 242 extern 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
 251 extern 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_ */