pexpert/pexpert/device_tree.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. The rights granted to you under the License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28 #ifndef _PEXPERT_DEVICE_TREE_H_
  29 #define _PEXPERT_DEVICE_TREE_H_
  30
  31 #include <stdbool.h>
  32
  33 #include <mach/mach_types.h>
  34 #include <mach/vm_types.h>
  35
  36 #include <sys/appleapiopts.h>
  37
  38 #ifdef __APPLE_API_PRIVATE
  39
  40 #ifdef __cplusplus
  41 extern "C" {
  42 #endif
  43
  44 /*
  45  *  -------------------------------------------------------------------------------
  46  *  Foundation Types
  47  *  -------------------------------------------------------------------------------
  48  */
  49 enum {
  50         kDTPathNameSeparator    = '/'                           /* 0x2F */
  51 };
  52
  53
  54 /* Property Name Definitions (Property Names are C-Strings)*/
  55 enum {
  56         kDTMaxPropertyNameLength=31     /* Max length of Property Name (terminator not included) */
  57 };
  58
  59 typedef char DTPropertyNameBuf[32];
  60
  61
  62 /* Entry Name Definitions (Entry Names are C-Strings)*/
  63 enum {
  64         kDTMaxEntryNameLength           = 63    /* Max length of a C-String Entry Name (terminator not included) */
  65 };
  66
  67 /* length of DTEntryNameBuf = kDTMaxEntryNameLength +1*/
  68 typedef char DTEntryNameBuf[kDTMaxEntryNameLength + 1];
  69
  70 /*
  71  *  Structures for a Flattened Device Tree
  72  */
  73
  74 #define kPropNameLength 32
  75
  76 typedef struct DeviceTreeNodeProperty {
  77         char                name[kPropNameLength];// NUL terminated property name
  78         uint32_t            length;     // Length (bytes) of folloing prop value
  79 //  unsigned long       value[1];       // Variable length value of property
  80         // Padded to a multiple of a longword?
  81 } DeviceTreeNodeProperty;
  82
  83 typedef struct OpaqueDTEntry {
  84         uint32_t            nProperties;// Number of props[] elements (0 => end)
  85         uint32_t            nChildren;  // Number of children[] elements
  86 //  DeviceTreeNodeProperty      props[];// array size == nProperties
  87 //  DeviceTreeNode      children[];     // array size == nChildren
  88 } DeviceTreeNode;
  89
  90 typedef const DeviceTreeNode *RealDTEntry;
  91
  92 typedef struct DTSavedScope {
  93         struct DTSavedScope * nextScope;
  94         RealDTEntry scope;
  95         RealDTEntry entry;
  96         unsigned long index;
  97 } *DTSavedScopePtr;
  98
  99 /* Entry Iterator*/
 100 typedef struct OpaqueDTEntryIterator {
 101         RealDTEntry outerScope;
 102         RealDTEntry currentScope;
 103         RealDTEntry currentEntry;
 104         DTSavedScopePtr savedScope;
 105         unsigned long currentIndex;
 106 } OpaqueDTEntryIterator, *DTEntryIterator;
 107
 108 /* Property Iterator*/
 109 typedef struct OpaqueDTPropertyIterator {
 110         RealDTEntry entry;
 111         DeviceTreeNodeProperty const *currentProperty;
 112         unsigned long currentIndex;
 113 } OpaqueDTPropertyIterator, *DTPropertyIterator;
 114
 115 /* Entry*/
 116 typedef const struct OpaqueDTEntry* DTEntry;
 117
 118 /* Entry Iterator*/
 119 typedef struct OpaqueDTEntryIterator* DTEntryIterator;
 120
 121 /* Property Iterator*/
 122 typedef struct OpaqueDTPropertyIterator* DTPropertyIterator;
 123
 124
 125 /* status values*/
 126 enum {
 127         kError = -1,
 128         kIterationDone = 0,
 129         kSuccess = 1
 130 };
 131
 132
 133 #ifndef __MWERKS__
 134 /*
 135  *  -------------------------------------------------------------------------------
 136  *  Device Tree Calls
 137  *  -------------------------------------------------------------------------------
 138  */
 139
 140 /* Used to initalize the device tree functions. */
 141 /* base is the base address of the flatened device tree */
 142 extern void SecureDTInit(void const *base, size_t size);
 143
 144 /* Whether the device tree is locked down after machine lockdown. */
 145 /* Returns false if there is no meaningful distinction, in */
 146 /* contrast to SecureDTFindEntry. */
 147 extern bool SecureDTIsLockedDown(void);
 148
 149 /*
 150  *  -------------------------------------------------------------------------------
 151  *  Entry Handling
 152  *  -------------------------------------------------------------------------------
 153  */
 154 /* Compare two Entry's for equality. */
 155 extern int SecureDTEntryIsEqual(const DTEntry ref1, const DTEntry ref2);
 156
 157 /*
 158  *  -------------------------------------------------------------------------------
 159  *  LookUp Entry by Name
 160  *  -------------------------------------------------------------------------------
 161  */
 162 /*
 163  *  Find Entry
 164  *  Find the device tree entry that contains propName=propValue.
 165  *  It currently  searches the entire
 166  *  tree.  This function should eventually go in DeviceTree.c.
 167  *  Returns:    kSuccess = entry was found.  Entry is in entryH.
 168  *            kError   = entry was not found
 169  */
 170 extern int SecureDTFindEntry(const char *propName, const char *propValue, DTEntry *entryH);
 171
 172 /*
 173  *  Lookup Entry
 174  *  Locates an entry given a specified subroot (searchPoint) and path name.  If the
 175  *  searchPoint pointer is NULL, the path name is assumed to be an absolute path
 176  *  name rooted to the root of the device tree.
 177  *  Returns:    kSuccess = entry was found.  Entry is in foundEntry.
 178  *            kError   = entry was not found
 179  */
 180 extern int SecureDTLookupEntry(const DTEntry searchPoint, const char *pathName, DTEntry *foundEntry);
 181
 182 /*
 183  *  -------------------------------------------------------------------------------
 184  *  Entry Iteration
 185  *  -------------------------------------------------------------------------------
 186  */
 187 /*
 188  *  An Entry Iterator maintains three variables that are of interest to clients.
 189  *  First is an "OutermostScope" which defines the outer boundry of the iteration.
 190  *  This is defined by the starting entry and includes that entry plus all of it's
 191  *  embedded entries. Second is a "currentScope" which is the entry the iterator is
 192  *  currently in. And third is a "currentPosition" which is the last entry returned
 193  *  during an iteration.
 194  *
 195  *  Initialize Entry Iterator
 196  *  Fill out the iterator structure. The outermostScope and currentScope of the iterator
 197  *  are set to "startEntry".  If "startEntry" = NULL, the outermostScope and
 198  *  currentScope are set to the root entry.  The currentPosition for the iterator is
 199  *  set to "nil".
 200  */
 201 extern int SecureDTInitEntryIterator(const DTEntry startEntry, DTEntryIterator iter);
 202
 203 /*
 204  *  Enter Child Entry
 205  *  Move an Entry Iterator into the scope of a specified child entry.  The
 206  *  currentScope of the iterator is set to the entry specified in "childEntry".  If
 207  *  "childEntry" is nil, the currentScope is set to the entry specified by the
 208  *  currentPosition of the iterator.
 209  */
 210 extern int SecureDTEnterEntry(DTEntryIterator iterator, DTEntry childEntry);
 211
 212 /*
 213  *  Exit to Parent Entry
 214  *  Move an Entry Iterator out of the current entry back into the scope of it's parent
 215  *  entry. The currentPosition of the iterator is reset to the current entry (the
 216  *  previous currentScope), so the next iteration call will continue where it left off.
 217  *  This position is returned in parameter "currentPosition".
 218  */
 219 extern int SecureDTExitEntry(DTEntryIterator iterator, DTEntry *currentPosition);
 220
 221 /*
 222  *  Iterate Entries
 223  *  Iterate and return entries contained within the entry defined by the current
 224  *  scope of the iterator.  Entries are returned one at a time. When
 225  *  int == kIterationDone, all entries have been exhausted, and the
 226  *  value of nextEntry will be Nil.
 227  */
 228 extern int SecureDTIterateEntries(DTEntryIterator iterator, DTEntry *nextEntry);
 229
 230 /*
 231  *  Restart Entry Iteration
 232  *  Restart an iteration within the current scope.  The iterator is reset such that
 233  *  iteration of the contents of the currentScope entry can be restarted. The
 234  *  outermostScope and currentScope of the iterator are unchanged. The currentPosition
 235  *  for the iterator is set to "nil".
 236  */
 237 extern int SecureDTRestartEntryIteration(DTEntryIterator iterator);
 238
 239 /*
 240  *  -------------------------------------------------------------------------------
 241  *  Get Property Values
 242  *  -------------------------------------------------------------------------------
 243  */
 244 /*
 245  *  Get the value of the specified property for the specified entry.
 246  *
 247  *  Get Property
 248  */
 249 extern int SecureDTGetProperty(const DTEntry entry, const char *propertyName,
 250     void const **propertyValue, unsigned int *propertySize);
 251
 252 #if defined(__i386__) || defined(__x86_64__)
 253 // x86 processes device tree fragments outside the normal DT region in
 254 // hibernation. This would not work on ARM.
 255 extern int SecureDTGetPropertyRegion(const DTEntry entry, const char *propertyName,
 256     void const **propertyValue, unsigned int *propertySize,
 257     vm_offset_t const region_start, vm_size_t region_size);
 258 #endif
 259
 260 /*
 261  *  -------------------------------------------------------------------------------
 262  *  Iterating Properties
 263  *  -------------------------------------------------------------------------------
 264  */
 265 /*
 266  *  Initialize Property Iterator
 267  *  Fill out the property iterator structure. The target entry is defined by entry.
 268  */
 269 extern int SecureDTInitPropertyIterator(const DTEntry entry, DTPropertyIterator iter);
 270
 271 /*
 272  *  Iterate Properites
 273  *  Iterate and return properties for given entry.
 274  *  When int == kIterationDone, all properties have been exhausted.
 275  */
 276
 277 extern int SecureDTIterateProperties(DTPropertyIterator iterator,
 278     char const **foundProperty);
 279
 280 /*
 281  *  Restart Property Iteration
 282  *  Used to re-iterate over a list of properties.  The Property Iterator is
 283  *  reset to the beginning of the list of properties for an entry.
 284  */
 285
 286 extern int SecureDTRestartPropertyIteration(DTPropertyIterator iterator);
 287
 288 #ifdef __cplusplus
 289 }
 290 #endif
 291
 292 #endif /* __MWERKS__ */
 293
 294 #endif /* __APPLE_API_PRIVATE */
 295
 296 #endif /* _PEXPERT_DEVICE_TREE_H_ */