iokit/IOKit/IOPlatformExpert.h

   1 /*
   2  * Copyright (c) 1998-2019 Apple 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 /*
  29  * Copyright (c) 1998 Apple Computer, Inc.  All rights reserved.
  30  *
  31  * HISTORY
  32  *
  33  */
  34
  35
  36 #ifndef _IOKIT_IOPLATFORMEXPERT_H
  37 #define _IOKIT_IOPLATFORMEXPERT_H
  38
  39 #ifdef __cplusplus
  40 #include <IOKit/IOLib.h>
  41 #include <IOKit/IOService.h>
  42 #include <IOKit/IOInterrupts.h>
  43 #include <IOKit/IOInterruptController.h>
  44
  45 extern "C" {
  46 #endif
  47
  48 #include <libkern/OSTypes.h>
  49
  50 typedef enum {
  51         kCoprocessorVersionNone    =   0x00000000,
  52         kCoprocessorVersion1       =   0x00010000,
  53         kCoprocessorVersion2       =   0x00020000,
  54 } coprocessor_type_t;
  55
  56
  57 extern boolean_t PEGetMachineName( char * name, int maxLength );
  58 extern boolean_t PEGetModelName( char * name, int maxLength );
  59 extern int PEGetPlatformEpoch( void );
  60
  61 enum {
  62         kPEHaltCPU,
  63         kPERestartCPU,
  64         kPEHangCPU,
  65         kPEUPSDelayHaltCPU,
  66         kPEPanicRestartCPU,
  67         kPEPanicSync,
  68         kPEPagingOff,
  69         kPEPanicBegin,
  70         kPEPanicEnd,
  71         kPEPanicDiskShutdown,
  72         kPEPanicRestartCPUNoPanicEndCallouts,
  73         kPEPanicRestartCPUNoCallouts
  74 };
  75 extern int (*PE_halt_restart)(unsigned int type);
  76 extern int PEHaltRestart(unsigned int type);
  77
  78 #ifdef XNU_KERNEL_PRIVATE
  79 enum {
  80         kIOSystemShutdownNotificationStageProcessExit = 0,
  81         kIOSystemShutdownNotificationStageRootUnmount = 1,
  82 };
  83 extern void IOSystemShutdownNotification(int stage);
  84
  85 extern uint32_t gEnforceQuiesceSafety;
  86 #endif /* XNU_KERNEL_PRIVATE */
  87
  88 #ifdef KERNEL_PRIVATE
  89 extern boolean_t IOPMRootDomainGetWillShutdown(void);
  90 #endif /* KERNEL_PRIVATE */
  91
  92 // Save the Panic Info.  Returns the number of bytes saved.
  93 extern UInt32 PESavePanicInfo(UInt8 *buffer, UInt32 length);
  94 extern void PESavePanicInfoAction(void *buffer, UInt32 offset, UInt32 length);
  95
  96 /*
  97  * SMC requires that all data is flushed in multiples of 16 bytes at 16 byte
  98  * boundaries.
  99  */
 100 #define PANIC_FLUSH_BOUNDARY 16
 101
 102 extern long PEGetGMTTimeOfDay( void );
 103 extern void PESetGMTTimeOfDay( long secs );
 104 extern void PEGetUTCTimeOfDay( clock_sec_t * secs, clock_usec_t * usecs );
 105 extern void PESetUTCTimeOfDay( clock_sec_t secs, clock_usec_t usecs );
 106
 107 /* unless it's a "well-known" property, these will read/write out the value as raw data */
 108
 109 extern boolean_t PEWriteNVRAMBooleanProperty(const char *symbol, boolean_t value);
 110 extern boolean_t PEWriteNVRAMProperty(const char *symbol, const void *value, const unsigned int len);
 111 extern boolean_t PEWriteNVRAMPropertyWithCopy(const char *symbol, const void *value, const unsigned int len);
 112
 113 extern boolean_t PEReadNVRAMProperty(const char *symbol, void *value, unsigned int *len);
 114
 115 extern boolean_t PERemoveNVRAMProperty(const char *symbol);
 116
 117 extern coprocessor_type_t PEGetCoprocessorVersion( void );
 118
 119 #ifdef __cplusplus
 120 } /* extern "C" */
 121
 122 #define kIOPlatformMapperPresentKey "IOPlatformMapperPresent"
 123
 124
 125
 126
 127 extern OSSymbol *               gPlatformInterruptControllerName;
 128
 129 /*
 130  * IOPlatformSleepAction
 131  *
 132  * Sleep is called after power management has finished all of the power plane
 133  * driver power management notifications and state transitions and has
 134  * committed to sleep, but before the other CPUs are powered off.
 135  * The scheduler is still active.
 136  */
 137 extern const OSSymbol *gIOPlatformSleepActionKey;
 138
 139 /*
 140  * IOPlatformWakeAction
 141  *
 142  * Wake is called with the scheduler enabled, but before
 143  * powering on other CPUs, so try to minimize work done in this path to speed
 144  * up wake time.
 145  */
 146 extern const OSSymbol *gIOPlatformWakeActionKey;
 147
 148 /*
 149  * IOPlatformQuiesceAction
 150  *
 151  * Quiesce is called after all CPUs are off, scheduling is disabled,
 152  * and the boot CPU is about to pull the plug.
 153  * Mutexes and blocking are disallowed in this context and will panic.
 154  * Do not pass this action to super() (incl. IOService, IOPlatformExpert)
 155  */
 156 extern const OSSymbol *gIOPlatformQuiesceActionKey;
 157
 158 /*
 159  * IOPlatformActiveAction
 160  *
 161  * Active is called very early in the wake path before enabling the scheduler
 162  * on the boot CPU.
 163  * Mutexes and blocking are disallowed in this context and will panic.
 164  * Do not pass this action to super() (incl. IOService, IOPlatformExpert)
 165  */
 166 extern const OSSymbol *gIOPlatformActiveActionKey;
 167
 168 /*
 169  * IOPlatformHaltRestartAction
 170  *
 171  * Halt/Restart is called after the kernel finishes shutting down the
 172  * system and is ready to power off or reboot.
 173  *
 174  * It is not guaranteed to be called in non-graceful shutdown scenarios.
 175  */
 176 extern const OSSymbol *gIOPlatformHaltRestartActionKey;
 177
 178 /*
 179  * IOPlatformPanicAction
 180  *
 181  * Panic is called when the system is panicking before it records a core file
 182  * (if it is configured to do so)
 183  *
 184  * It can be called at any time, in any context, in any state.  Don't depend
 185  * on anything being powered on in a useful state.
 186  *
 187  * Mutexes and blocking are disallowed in this context and will fail.
 188  *
 189  * If you hang or panic again in this callout, the panic log may not be recorded,
 190  * leading to the loss of field reports about customer issues.
 191  */
 192 extern const OSSymbol *gIOPlatformPanicActionKey;
 193
 194 class IORangeAllocator;
 195 class IONVRAMController;
 196 class IOPMrootDomain;
 197
 198 class IOPlatformExpert : public IOService
 199 {
 200         OSDeclareDefaultStructors(IOPlatformExpert);
 201
 202 private:
 203         long _peBootROMType;
 204         long _peChipSetType;
 205         long _peMachineType;
 206
 207 protected:
 208         IOPMrootDomain * root;
 209         int _pePMFeatures;
 210         int _pePrivPMFeatures;
 211         int _peNumBatteriesSupported;
 212         OSArray  * thePowerTree;
 213
 214         bool       searchingForAdditionalParents;
 215         OSNumber * multipleParentKeyValue;
 216         int        numInstancesRegistered;
 217
 218         struct ExpansionData { };
 219         ExpansionData *iope_reserved __unused;
 220
 221         virtual void setBootROMType(long peBootROMType);
 222         virtual void setChipSetType(long peChipSetType);
 223         virtual void setMachineType(long peMachineType);
 224
 225         virtual bool CheckSubTree(OSArray * inSubTree, IOService * theNub, IOService * theDevice, OSDictionary * theParent);
 226         virtual bool RegisterServiceInTree(IOService * theService, OSDictionary * theTreeNode, OSDictionary * theTreeParentNode, IOService * theProvider);
 227
 228         virtual void PMInstantiatePowerDomains( void );
 229
 230 public:
 231         virtual bool attach( IOService * provider ) APPLE_KEXT_OVERRIDE;
 232         virtual bool start( IOService * provider ) APPLE_KEXT_OVERRIDE;
 233         virtual bool configure( IOService * provider );
 234         virtual IOService * createNub( OSDictionary * from );
 235
 236         virtual bool compareNubName( const IOService * nub, OSString * name,
 237             OSString ** matched = NULL ) const;
 238         virtual IOReturn getNubResources( IOService * nub );
 239
 240         virtual long getBootROMType(void);
 241         virtual long getChipSetType(void);
 242         virtual long getMachineType(void);
 243
 244         virtual bool getModelName( char * name, int maxLength );
 245         virtual bool getMachineName( char * name, int maxLength );
 246
 247         virtual int haltRestart(unsigned int type);
 248         virtual void sleepKernel(void);
 249
 250         virtual long getGMTTimeOfDay( void );
 251         virtual void setGMTTimeOfDay( long secs );
 252
 253         virtual IOReturn getConsoleInfo( PE_Video * consoleInfo );
 254         virtual IOReturn setConsoleInfo( PE_Video * consoleInfo, unsigned int op );
 255
 256         virtual void registerNVRAMController( IONVRAMController * nvram );
 257
 258         virtual IOReturn registerInterruptController(OSSymbol *name, IOInterruptController *interruptController);
 259         virtual LIBKERN_RETURNS_NOT_RETAINED IOInterruptController *
 260         lookUpInterruptController(OSSymbol *name);
 261
 262         virtual void setCPUInterruptProperties(IOService *service);
 263         virtual bool atInterruptLevel(void);
 264
 265         virtual IOReturn callPlatformFunction(const OSSymbol *functionName,
 266             bool waitForFunction,
 267             void *param1, void *param2,
 268             void *param3, void *param4) APPLE_KEXT_OVERRIDE;
 269
 270         virtual IORangeAllocator * getPhysicalRangeAllocator(void);
 271
 272         virtual bool platformAdjustService(IOService *service);
 273
 274         virtual void PMRegisterDevice(IOService * theNub, IOService * theDevice);
 275         virtual void PMLog( const char *, unsigned long, unsigned long, unsigned long );
 276
 277         virtual bool hasPMFeature(unsigned long featureMask);
 278         virtual bool hasPrivPMFeature(unsigned long privFeatureMask);
 279         virtual int  numBatteriesSupported(void);
 280
 281         virtual IOByteCount savePanicInfo(UInt8 *buffer, IOByteCount length);
 282
 283         virtual OSString* createSystemSerialNumberString(OSData* myProperty);
 284
 285         virtual IOReturn deregisterInterruptController(OSSymbol *name);
 286
 287         virtual void getUTCTimeOfDay( clock_sec_t * secs, clock_nsec_t * nsecs );
 288         virtual void setUTCTimeOfDay( clock_sec_t secs, clock_nsec_t nsecs );
 289
 290         OSMetaClassDeclareReservedUsed(IOPlatformExpert, 0);
 291         OSMetaClassDeclareReservedUsed(IOPlatformExpert, 1);
 292         OSMetaClassDeclareReservedUsed(IOPlatformExpert, 2);
 293         OSMetaClassDeclareReservedUsed(IOPlatformExpert, 3);
 294         OSMetaClassDeclareReservedUsed(IOPlatformExpert, 4);
 295         OSMetaClassDeclareReservedUnused(IOPlatformExpert, 5);
 296         OSMetaClassDeclareReservedUnused(IOPlatformExpert, 6);
 297         OSMetaClassDeclareReservedUnused(IOPlatformExpert, 7);
 298         OSMetaClassDeclareReservedUnused(IOPlatformExpert, 8);
 299         OSMetaClassDeclareReservedUnused(IOPlatformExpert, 9);
 300         OSMetaClassDeclareReservedUnused(IOPlatformExpert, 10);
 301         OSMetaClassDeclareReservedUnused(IOPlatformExpert, 11);
 302 };
 303
 304 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 305
 306 class IODTNVRAM;
 307
 308 class IODTPlatformExpert : public IOPlatformExpert
 309 {
 310         OSDeclareAbstractStructors(IODTPlatformExpert);
 311
 312 private:
 313         IODTNVRAM *dtNVRAM;
 314
 315         struct ExpansionData { };
 316         ExpansionData *iodtpe_reserved;
 317
 318 public:
 319         virtual IOService * probe(  IOService *     provider,
 320             SInt32    *     score ) APPLE_KEXT_OVERRIDE;
 321         virtual bool configure( IOService * provider ) APPLE_KEXT_OVERRIDE;
 322
 323         virtual void processTopLevel( IORegistryEntry * root );
 324         virtual const char * deleteList( void ) = 0;
 325         virtual const char * excludeList( void ) = 0;
 326         virtual IOService * createNub( IORegistryEntry * from );
 327         virtual bool createNubs( IOService * parent, LIBKERN_CONSUMED OSIterator * iter );
 328
 329         virtual bool compareNubName( const IOService * nub, OSString * name,
 330             OSString ** matched = NULL ) const APPLE_KEXT_OVERRIDE;
 331
 332         virtual IOReturn getNubResources( IOService * nub ) APPLE_KEXT_OVERRIDE;
 333
 334         virtual bool getModelName( char * name, int maxLength ) APPLE_KEXT_OVERRIDE;
 335         virtual bool getMachineName( char * name, int maxLength ) APPLE_KEXT_OVERRIDE;
 336
 337         virtual void registerNVRAMController( IONVRAMController * nvram ) APPLE_KEXT_OVERRIDE;
 338
 339         virtual int haltRestart(unsigned int type) APPLE_KEXT_OVERRIDE;
 340
 341 /* virtual */ IOReturn readXPRAM(IOByteCount offset, UInt8 * buffer,
 342             IOByteCount length);
 343
 344 /* virtual */ IOReturn writeXPRAM(IOByteCount offset, UInt8 * buffer,
 345             IOByteCount length);
 346
 347         virtual IOReturn readNVRAMProperty(
 348                 IORegistryEntry * entry,
 349                 const OSSymbol ** name, OSData ** value );
 350
 351         virtual IOReturn writeNVRAMProperty(
 352                 IORegistryEntry * entry,
 353                 const OSSymbol * name, OSData * value );
 354
 355 // This returns a dictionary describing all the NVRAM partitions.
 356 // The keys will be the partitionIDs of the form "0x52,nvram".
 357 // The values will be OSNumbers of the partition's byte count.
 358 /* virtual */ OSDictionary *getNVRAMPartitions(void);
 359
 360 /* virtual */ IOReturn readNVRAMPartition(const OSSymbol * partitionID,
 361             IOByteCount offset, UInt8 * buffer,
 362             IOByteCount length);
 363
 364 /* virtual */ IOReturn writeNVRAMPartition(const OSSymbol * partitionID,
 365             IOByteCount offset, UInt8 * buffer,
 366             IOByteCount length);
 367
 368         virtual IOByteCount savePanicInfo(UInt8 *buffer, IOByteCount length) APPLE_KEXT_OVERRIDE;
 369         virtual OSString* createSystemSerialNumberString(OSData* myProperty) APPLE_KEXT_OVERRIDE;
 370
 371         OSMetaClassDeclareReservedUnused(IODTPlatformExpert, 0);
 372         OSMetaClassDeclareReservedUnused(IODTPlatformExpert, 1);
 373         OSMetaClassDeclareReservedUnused(IODTPlatformExpert, 2);
 374         OSMetaClassDeclareReservedUnused(IODTPlatformExpert, 3);
 375         OSMetaClassDeclareReservedUnused(IODTPlatformExpert, 4);
 376         OSMetaClassDeclareReservedUnused(IODTPlatformExpert, 5);
 377         OSMetaClassDeclareReservedUnused(IODTPlatformExpert, 6);
 378         OSMetaClassDeclareReservedUnused(IODTPlatformExpert, 7);
 379 };
 380
 381 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 382
 383 /* generic root nub of service tree */
 384
 385 class IOPlatformExpertDevice : public IOService
 386 {
 387         OSDeclareDefaultStructors(IOPlatformExpertDevice);
 388
 389 private:
 390         IOWorkLoop *workLoop;
 391
 392         struct ExpansionData { };
 393         ExpansionData *ioped_reserved __unused;
 394
 395 public:
 396         virtual bool initWithArgs( void * p1, void * p2,
 397             void * p3, void *p4 );
 398         virtual bool compareName( OSString * name, OSString ** matched = NULL ) const APPLE_KEXT_OVERRIDE;
 399
 400         virtual IOWorkLoop *getWorkLoop() const APPLE_KEXT_OVERRIDE;
 401         virtual IOReturn setProperties( OSObject * properties ) APPLE_KEXT_OVERRIDE;
 402
 403         virtual void free() APPLE_KEXT_OVERRIDE;
 404
 405         virtual IOReturn newUserClient( task_t owningTask, void * securityID,
 406             UInt32 type, OSDictionary * properties,
 407             IOUserClient ** handler) APPLE_KEXT_OVERRIDE;
 408
 409
 410         OSMetaClassDeclareReservedUnused(IOPlatformExpertDevice, 0);
 411         OSMetaClassDeclareReservedUnused(IOPlatformExpertDevice, 1);
 412         OSMetaClassDeclareReservedUnused(IOPlatformExpertDevice, 2);
 413         OSMetaClassDeclareReservedUnused(IOPlatformExpertDevice, 3);
 414 };
 415
 416 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 417
 418 /* generic nub for motherboard devices */
 419
 420 class IOPlatformDevice : public IOService
 421 {
 422         OSDeclareDefaultStructors(IOPlatformDevice);
 423
 424         struct ExpansionData { };
 425         ExpansionData *iopd_reserved;
 426
 427 public:
 428         virtual bool compareName( OSString * name, OSString ** matched = NULL ) const APPLE_KEXT_OVERRIDE;
 429         virtual IOService * matchLocation( IOService * client ) APPLE_KEXT_OVERRIDE;
 430         virtual IOReturn getResources( void ) APPLE_KEXT_OVERRIDE;
 431
 432         OSMetaClassDeclareReservedUnused(IOPlatformDevice, 0);
 433         OSMetaClassDeclareReservedUnused(IOPlatformDevice, 1);
 434         OSMetaClassDeclareReservedUnused(IOPlatformDevice, 2);
 435         OSMetaClassDeclareReservedUnused(IOPlatformDevice, 3);
 436 };
 437
 438 #endif /* __cplusplus */
 439
 440 #endif /* ! _IOKIT_IOPLATFORMEXPERT_H */