iokit/include/DeviceTree.h

   1 /*
   2  * Copyright (c) 1998-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 __DEVICE_TREE__
  26 #define __DEVICE_TREE__
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 /*
  33 ------------------------------------------------------------------------------------
  34  Foundation Types
  35 ------------------------------------------------------------------------------------
  36 */
  37 enum {
  38         kDTPathNameSeparator            = '/'                           /* 0x2F */
  39 };
  40
  41
  42 /* Property Name Definitions (Property Names are C-Strings)*/
  43 enum {
  44         kDTMaxPropertyNameLength        = 31                            /* Max length of Property Name (terminator not included) */
  45 };
  46
  47 typedef char DTPropertyNameBuf[32];
  48
  49
  50 /* Entry Name Definitions (Entry Names are C-Strings)*/
  51 enum {
  52         kDTMaxEntryNameLength           = 31                            /* Max length of a C-String Entry Name (terminator not included) */
  53 };
  54
  55 /* length of DTEntryNameBuf = kDTMaxEntryNameLength +1*/
  56 typedef char DTEntryNameBuf[32];
  57
  58
  59 /* Entry*/
  60 typedef struct OpaqueDTEntry* DTEntry;
  61
  62 /* Entry Iterator*/
  63 typedef struct OpaqueDTEntryIterator* DTEntryIterator;
  64
  65 /* Property Iterator*/
  66 typedef struct OpaqueDTPropertyIterator* DTPropertyIterator;
  67
  68
  69 /* status values*/
  70 enum {
  71                 kError = -1,
  72                 kIterationDone = 0,
  73                 kSuccess = 1
  74 };
  75
  76 /*
  77 ------------------------------------------------------------------------------------
  78  Device Tree Calls
  79 ------------------------------------------------------------------------------------
  80 */
  81
  82 /*
  83 ------------------------------------------------------------------------------------
  84  Entry Handling
  85 ------------------------------------------------------------------------------------
  86 */
  87 /* Compare two Entry's for equality. */
  88 extern int DTEntryIsEqual(const DTEntry ref1, const DTEntry ref2);
  89
  90 /*
  91 ------------------------------------------------------------------------------------
  92  LookUp Entry by Name
  93 ------------------------------------------------------------------------------------
  94 */
  95 /*
  96  Lookup Entry
  97  Locates an entry given a specified subroot (searchPoint) and path name.  If the
  98  searchPoint pointer is NULL, the path name is assumed to be an absolute path
  99  name rooted to the root of the device tree.
 100 */
 101 extern int DTLookupEntry(const DTEntry searchPoint, const char *pathName, DTEntry *foundEntry);
 102
 103 /*
 104 ------------------------------------------------------------------------------------
 105  Entry Iteration
 106 ------------------------------------------------------------------------------------
 107 */
 108 /*
 109  An Entry Iterator maintains three variables that are of interest to clients.
 110  First is an "OutermostScope" which defines the outer boundry of the iteration.
 111  This is defined by the starting entry and includes that entry plus all of it's
 112  embedded entries. Second is a "currentScope" which is the entry the iterator is
 113  currently in. And third is a "currentPosition" which is the last entry returned
 114  during an iteration.
 115
 116  Create Entry Iterator
 117  Create the iterator structure. The outermostScope and currentScope of the iterator
 118  are set to "startEntry".  If "startEntry" = NULL, the outermostScope and
 119  currentScope are set to the root entry.  The currentPosition for the iterator is
 120  set to "nil".
 121 */
 122 extern int DTCreateEntryIterator(const DTEntry startEntry, DTEntryIterator *iterator);
 123
 124 /* Dispose Entry Iterator*/
 125 extern int DTDisposeEntryIterator(DTEntryIterator iterator);
 126
 127 /*
 128  Enter Child Entry
 129  Move an Entry Iterator into the scope of a specified child entry.  The
 130  currentScope of the iterator is set to the entry specified in "childEntry".  If
 131  "childEntry" is nil, the currentScope is set to the entry specified by the
 132  currentPosition of the iterator.
 133 */
 134 extern int DTEnterEntry(DTEntryIterator iterator, DTEntry childEntry);
 135
 136 /*
 137  Exit to Parent Entry
 138  Move an Entry Iterator out of the current entry back into the scope of it's parent
 139  entry. The currentPosition of the iterator is reset to the current entry (the
 140  previous currentScope), so the next iteration call will continue where it left off.
 141  This position is returned in parameter "currentPosition".
 142 */
 143 extern int DTExitEntry(DTEntryIterator iterator, DTEntry *currentPosition);
 144
 145 /*
 146  Iterate Entries
 147  Iterate and return entries contained within the entry defined by the current
 148  scope of the iterator.  Entries are returned one at a time. When
 149  int == kIterationDone, all entries have been exhausted, and the
 150  value of nextEntry will be Nil.
 151 */
 152 extern int DTIterateEntries(DTEntryIterator iterator, DTEntry *nextEntry);
 153
 154 /*
 155  Restart Entry Iteration
 156  Restart an iteration within the current scope.  The iterator is reset such that
 157  iteration of the contents of the currentScope entry can be restarted. The
 158  outermostScope and currentScope of the iterator are unchanged. The currentPosition
 159  for the iterator is set to "nil".
 160 */
 161 extern int DTRestartEntryIteration(DTEntryIterator iterator);
 162
 163 /*
 164 ------------------------------------------------------------------------------------
 165  Get Property Values
 166 ------------------------------------------------------------------------------------
 167 */
 168 /*
 169  Get the value of the specified property for the specified entry.
 170
 171  Get Property
 172 */
 173 extern int DTGetProperty(const DTEntry entry, const char *propertyName, void **propertyValue, int *propertySize);
 174
 175 /*
 176 ------------------------------------------------------------------------------------
 177  Iterating Properties
 178 ------------------------------------------------------------------------------------
 179 */
 180 /*
 181  Create Property Iterator
 182  Create the property iterator structure. The target entry is defined by entry.
 183 */
 184 extern int DTCreatePropertyIterator(const DTEntry entry, DTPropertyIterator *iterator);
 185
 186 /* Dispose Property Iterator*/
 187 extern int DTDisposePropertyIterator(DTPropertyIterator iterator);
 188
 189 /*
 190  Iterate Properites
 191  Iterate and return properties for given entry.
 192  When int == kIterationDone, all properties have been exhausted.
 193 */
 194 extern int DTIterateProperties(DTPropertyIterator iterator, char **foundProperty);
 195
 196 /*
 197  Restart Property Iteration
 198  Used to re-iterate over a list of properties.  The Property Iterator is reset to
 199  the beginning of the list of properties for an entry.
 200 */
 201 extern int DTRestartPropertyIteration(DTPropertyIterator iterator);
 202
 203 #ifdef __cplusplus
 204 }
 205 #endif
 206
 207 #endif /* __DEVICE_TREE__ */
 208