iokit/include/DeviceTree.h

   1 /*
   2  * Copyright (c) 1998-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 __DEVICE_TREE__
  23 #define __DEVICE_TREE__
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  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  Device Tree Calls
  76 ------------------------------------------------------------------------------------
  77 */
  78
  79 /*
  80 ------------------------------------------------------------------------------------
  81  Entry Handling
  82 ------------------------------------------------------------------------------------
  83 */
  84 /* Compare two Entry's for equality. */
  85 extern int DTEntryIsEqual(const DTEntry ref1, const DTEntry ref2);
  86
  87 /*
  88 ------------------------------------------------------------------------------------
  89  LookUp Entry by Name
  90 ------------------------------------------------------------------------------------
  91 */
  92 /*
  93  Lookup Entry
  94  Locates an entry given a specified subroot (searchPoint) and path name.  If the
  95  searchPoint pointer is NULL, the path name is assumed to be an absolute path
  96  name rooted to the root of the device tree.
  97 */
  98 extern int DTLookupEntry(const DTEntry searchPoint, const char *pathName, DTEntry *foundEntry);
  99
 100 /*
 101 ------------------------------------------------------------------------------------
 102  Entry Iteration
 103 ------------------------------------------------------------------------------------
 104 */
 105 /*
 106  An Entry Iterator maintains three variables that are of interest to clients.
 107  First is an "OutermostScope" which defines the outer boundry of the iteration.
 108  This is defined by the starting entry and includes that entry plus all of it's
 109  embedded entries. Second is a "currentScope" which is the entry the iterator is
 110  currently in. And third is a "currentPosition" which is the last entry returned
 111  during an iteration.
 112
 113  Create Entry Iterator
 114  Create the iterator structure. The outermostScope and currentScope of the iterator
 115  are set to "startEntry".  If "startEntry" = NULL, the outermostScope and
 116  currentScope are set to the root entry.  The currentPosition for the iterator is
 117  set to "nil".
 118 */
 119 extern int DTCreateEntryIterator(const DTEntry startEntry, DTEntryIterator *iterator);
 120
 121 /* Dispose Entry Iterator*/
 122 extern int DTDisposeEntryIterator(DTEntryIterator iterator);
 123
 124 /*
 125  Enter Child Entry
 126  Move an Entry Iterator into the scope of a specified child entry.  The
 127  currentScope of the iterator is set to the entry specified in "childEntry".  If
 128  "childEntry" is nil, the currentScope is set to the entry specified by the
 129  currentPosition of the iterator.
 130 */
 131 extern int DTEnterEntry(DTEntryIterator iterator, DTEntry childEntry);
 132
 133 /*
 134  Exit to Parent Entry
 135  Move an Entry Iterator out of the current entry back into the scope of it's parent
 136  entry. The currentPosition of the iterator is reset to the current entry (the
 137  previous currentScope), so the next iteration call will continue where it left off.
 138  This position is returned in parameter "currentPosition".
 139 */
 140 extern int DTExitEntry(DTEntryIterator iterator, DTEntry *currentPosition);
 141
 142 /*
 143  Iterate Entries
 144  Iterate and return entries contained within the entry defined by the current
 145  scope of the iterator.  Entries are returned one at a time. When
 146  int == kIterationDone, all entries have been exhausted, and the
 147  value of nextEntry will be Nil.
 148 */
 149 extern int DTIterateEntries(DTEntryIterator iterator, DTEntry *nextEntry);
 150
 151 /*
 152  Restart Entry Iteration
 153  Restart an iteration within the current scope.  The iterator is reset such that
 154  iteration of the contents of the currentScope entry can be restarted. The
 155  outermostScope and currentScope of the iterator are unchanged. The currentPosition
 156  for the iterator is set to "nil".
 157 */
 158 extern int DTRestartEntryIteration(DTEntryIterator iterator);
 159
 160 /*
 161 ------------------------------------------------------------------------------------
 162  Get Property Values
 163 ------------------------------------------------------------------------------------
 164 */
 165 /*
 166  Get the value of the specified property for the specified entry.
 167
 168  Get Property
 169 */
 170 extern int DTGetProperty(const DTEntry entry, const char *propertyName, void **propertyValue, int *propertySize);
 171
 172 /*
 173 ------------------------------------------------------------------------------------
 174  Iterating Properties
 175 ------------------------------------------------------------------------------------
 176 */
 177 /*
 178  Create Property Iterator
 179  Create the property iterator structure. The target entry is defined by entry.
 180 */
 181 extern int DTCreatePropertyIterator(const DTEntry entry, DTPropertyIterator *iterator);
 182
 183 /* Dispose Property Iterator*/
 184 extern int DTDisposePropertyIterator(DTPropertyIterator iterator);
 185
 186 /*
 187  Iterate Properites
 188  Iterate and return properties for given entry.
 189  When int == kIterationDone, all properties have been exhausted.
 190 */
 191 extern int DTIterateProperties(DTPropertyIterator iterator, char **foundProperty);
 192
 193 /*
 194  Restart Property Iteration
 195  Used to re-iterate over a list of properties.  The Property Iterator is reset to
 196  the beginning of the list of properties for an entry.
 197 */
 198 extern int DTRestartPropertyIteration(DTPropertyIterator iterator);
 199
 200 #ifdef __cplusplus
 201 }
 202 #endif
 203
 204 #endif /* __DEVICE_TREE__ */
 205