pexpert/pexpert/device_tree.h

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