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