Upstream
/
CloverBootloader
mirror of https://github.com/CloverHackyColor/CloverBootloader.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
CloverBootloader/Include/IndustryStandard/AppleRtc.h

401 lines
16 KiB
C
Raw Permalink Blame History

/** @file
Copyright (C) 2020, vit9696. All rights reserved.
All rights reserved.
This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
http://opensource.org/licenses/bsd-license.php
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
#ifndef APPLE_RTC_H
#define APPLE_RTC_H
/**
Sample RTC memory dump from MBP12,1 running 10.15.4:
00: 33 02 01 00 12 22 04 16 04 20 26 02 70 80 FF FF
10: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
20: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
30: 01 FE 20 FF FF FF FF FF F8 11 FF FF FF 00 1A 7C
40: 00 00 00 00 FE 00 00 00 00 00 00 00 00 00 00 00
50: 00 00 00 00 00 00 00 FF 0B D1 80 00 05 00 00 00
60: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
70: 00 00 00 00 00 00 00 00 FF FF FF FF FF FF FF FF
80: 44 45 41 44 00 00 00 00 00 00 00 00 00 00 00 00
90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
A0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
B0: 76 CF 85 13 00 00 00 00 00 00 00 00 00 00 00 00
C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
E0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
**/
/**
APPLE_RTC_BG_COLOR_ADDR - background colour.
APPLE_RTC_BG_COMPLEMENT_ADDR - complementary byte to background colour.
0x00 - Grey background (applies to 10.9 and older).
0x01 - Black background (applies to 10.10 and newer).
Valid pair gives APPLE_RTC_BG_COLOR_ADDR ^ APPLE_RTC_BG_COMPLEMENT_ADDR == 0xFF.
Otherwise background colour should be treated as 0, grey.
Prior to rebooting to MacEFI firmare upgrade /usr/libexec/efiupdater
removes DefaultBackgroundColor NVRAM variable and resets background to black.
When performing hibernate wake OSInfo writes chooses the background colour
based on reported macOS version (grey for 10.9 and below, black otherwise).
**/
#define APPLE_RTC_BG_COLOR_ADDR 0x30
#define APPLE_RTC_BG_COMPLEMENT_ADDR 0x31
/**
APPLE_RTC_BG_COLOR_ADDR values.
**/
#define APPLE_RTC_BG_COLOR_GRAY 0x00
#define APPLE_RTC_BG_COLOR_BLACK 0x01
/**
By default masked out with 0xF8.
Connected thunderbolt devices can set 3 lower bits.
BIT3 seems to be set when InstallWindowsUEFI was present at boot.
See ThunderboltNhi and PchInitDxe.
**/
#define APPLE_RTC_FIRMWARE_STATE_ADDR 0x38
/**
Used by ApplePlatformInit, 1 byte.
**/
#define APPLE_RTC_FIRMWARE_3D_ADDR 0x3D
/**
Bitmask of started test indices.
Little endian 32-bit number.
Note: memory testing statuses are a bit more complicated,
but we do not need too much detail atm.
**/
#define APPLE_RTC_MEM_TEST_ACCEPT_ADDR 0x44
/**
Bitmask of request test indices.
Little endian 32-bit number.
**/
#define APPLE_RTC_MEM_TEST_REQUEST_ADDR 0x48
/**
Bitmask of performed test indices.
Little endian 32-bit number.
**/
#define APPLE_RTC_MEM_TEST_RESULT_ADDR 0x4C
/**
Another unknown reserved address.
**/
#define APPLE_RTC_FIRMWARE_57_ADDR 0x57
/**
Firmware boot progress, mostly maintained by AppleBds.
0x00, 0x01, 0x02 - Set by RomIntegrityPei.
0x04 - Normal boot started. At this step AppleBds will process hibernation,
enable video output, check battery state, perform memory test, etc.
0x05 - Exit Boot Services called. Set in AppleBds event handler.
**/
#define APPLE_RTC_FIRMWARE_PROGRESS_ADDR 0x5C
/**
Apple RTC reserved memory area for unclear purposes, normally filled with FF.
Should not be erased during PRAM reset (CMD+OPT+P+R).
**/
#define APPLE_RTC_RESERVED_ADDR 0x78
/**
Apple RTC reserved memory size.
**/
#define APPLE_RTC_RESERVED_LENGTH 8
/**
Hibernation image encryption data, a copy of IOHibernateRTCVariables.
See AppleRTCHibernateVars type in AppleHibernate.h for the definition.
- Valid hibernation image encryption data starts with "AAPL" magic.
- Erased hibernation image encryption data starts with "DEAD" magic.
Normally handled by AppleBds prior to transfering control to the bootloader.
**/
#define APPLE_RTC_HIBERNATION_KEY_ADDR 0x80
/**
Effectively equals to sizeof (AppleRTCHibernateVars).
**/
#define APPLE_RTC_HIBERNATION_KEY_LENGTH 0x2C
/**
Firmware upgrade control and status byte.
0x00 - Normal boot. AppleBds resets to this value upon BOOT_ON_FLASH_UPDATE
prior to running BootRomFlash. BootRomFlash may itself reset to this
value on successful(?) flashing. Mirrored to NOBP SMC key.
0x01 - Alternative unsuccessful (?) result of firmware flashing written
by BootRomFlash. Mirrored to NOBP SMC key. Also set in ApplePlatformInit.
0x02 - Schedule firmware upgrade. Closed-source bless part writes this value
when intending to upgrade MacEFI firmware.
0x03 - Peform firmware upgrade. BootRomFlash writes this value prior to
rebooting into BOOT_ON_FLASH_UPDATE mode. Might be needed due to region
unlock.
**/
#define APPLE_RTC_FIRMWARE_UPGRADE_ADDR 0xAC
/**
AppleBds zeroes this byte at the same time it reaches normal booting phase (0x4)
in APPLE_RTC_FIRMWARE_PROGRESS_ADDR. This may be set to non-zero value by ApplePlatformInit.
**/
#define APPLE_RTC_FIRMWARE_CHECK_ADDR 0xAF
/**
Data contained in RTC allowing to trace various power management events.
Called via AppleRTC::rtcRecordTracePoint and also used for EfiBoot wake log.
**/
#define APPLE_RTC_TRACE_POINT_ADDR 0xB0
/**
Trace point data contains a total of 8 bytes, but they seem to have varying purpose.
**/
#define APPLE_RTC_TRACE_POINT_LENGTH 8
/**
Trace data is a 32-bit value, which format depends on the phase
(APPLE_RTC_TRACE_PHASE_ADDR) the platform is currently in.
For the kernel this may e.g. contain PCI device index currently put
in sleep or being awoken (kIOPMTracePointSleepPowerPlaneDrivers
or kIOPMTracePointWakePowerPlaneDrivers).
For EfiBoot this is named hibernatin wake log. It is also written to
wake-failure NVRAM variable (and later DeviceTree).
**/
#define APPLE_RTC_TRACE_DATA_ADDR 0xB0
/**
Trace data length.
**/
#define APPLE_RTC_TRACE_DATA_LENGTH 4
/**
Mask of events, which happened during booting.
These events are appended during the boot progress.
Note, unlike APPLE_RTC_WL_EVENT_ADDR/APPLE_RTC_WL_EVENT_EXTRA_ADDR,
which only get updated in hibernate wake, this value is always written
when a non-zero event is supplied.
**/
#define APPLE_RTC_WL_MASK_ADDR 0xB1
/**
Known event bits.
**/
#define APPLE_RTC_WL_MASK_BOOT_STARTED BIT0 ///< Called early at boot.efi startup.
#define APPLE_RTC_WL_MASK_BOOT_FAILED BIT1 ///< gBS->Exit: Boot failed; will sleep for 10 seconds before exiting.
#define APPLE_RTC_WL_MASK_BOOT_KERNEL BIT2 ///< Called right before jumping to the kernel code.
#define APPLE_RTC_WL_MASK_CS_UNLOCKED BIT3 ///< Set along with APPLE_RTC_WL_CS_VOLUME_UNLOCKED.
#define APPLE_RTC_WL_MASK_HIB_CLEAR_KEYS BIT4 ///< Removed boot-image-key, EFI_STATUS in EXTRA.
#define APPLE_RTC_WL_MASK_HIB_CLEAR_IMG BIT5 ///< Removed boot-image, will reboot now.
#define APPLE_RTC_WL_MASK_BOOT_RESET BIT6 ///< gBS->Reset was called.
/**
Event index that happened last during booting.
0xB2 is the event type and 0xB3 is its subtype.
**/
#define APPLE_RTC_WL_EVENT_ADDR 0xB2
#define APPLE_RTC_WL_EVENT_EXTRA_ADDR 0xB3
/**
Known events.
**/
#define APPLE_RTC_WL_EVENT_DEFAULT 0 ///< For everything.
#define APPLE_RTC_WL_INIT_DEVICE_TREE 2 ///< Before first "Start InitDeviceTree".
#define APPLE_RTC_WL_KERNEL_ALLOC_CALL_GATE 3 ///< After "End InitDeviceTree".
#define APPLE_RTC_WL_INIT_MEMORY_CONFIG 4 ///< Before "Start InitMemoryConfig".
#define APPLE_RTC_WL_HIB_CHECK 5 ///< Before "Start CheckHibernate".
#define APPLE_RTC_WL_CS_LOAD_CONFIGURATION 6 ///< Before "Start LoadCoreStorageConfiguration".
#define APPLE_RTC_WL_GET_FDE_KEY 7 ///< Before reading HBKP key.
#define APPLE_RTC_WL_HIB_WAKE_START 8 ///< Before reading FACP table.
#define APPLE_RTC_WL_HIB_GET_MMAP 9 ///< Before GetMemoryMap for hibernation.
#define APPLE_RTC_WL_HIB_HWSIG_VALID 10 ///< After confirming FACP signature validity with the image.
#define APPLE_RTC_WL_HIB_MEM_ALLOC 11 ///< Before restore1CodePhysPage / runtimePages allocation.
#define APPLE_RTC_WL_HIB_SPLASH 12 ///< Before "Start OpenBootGraphics".
#define APPLE_RTC_WL_HIB_READ 13 ///< After "Start hibernate read".
#define APPLE_RTC_WL_HIB_HANDOFF 14 ///< Before adjusting IOHibernateImageHeader and booting kernel.
#define APPLE_RTC_WL_HIB_EXIT_BOOT_SERVICES 15 ///< Done ExitBootServices for hibernate, EFI_STATUS in EXTRA.
#define APPLE_RTC_WL_HIB_KERNEL_START 16 ///< Calling kernel entry point for hibernate.
#define APPLE_RTC_WL_HIB_FINISH_FDE 17 ///< After "Start FinishFDEHibernate".
#define APPLE_RTC_WL_HIB_WIRED_KEY_VALID 18 ///< Before APPLE_RTC_WL_HIBERNATE_WAKE_START with valid FDE key.
#define APPLE_RTC_WL_RECOVERY_OS_FOUND 19 ///< After detecting com.apple.recovery.boot in boot path.
#define APPLE_RTC_WL_CS_VOLUME_UNLOCKED 20 ///< After "End UnlockCoreStorageVolumeKey" with EFI_STATUS in EXTRA.
#define APPLE_RTC_WL_KERNEL_LOAD_CACHE_FAIL 22 ///< Failed to load kernel cache, EFI_STATUS in EXTRA.
#define APPLE_RTC_WL_HIB_BS_MISSING 23 ///< Missing boot-signature, EFI_STATUS in EXTRA.
#define APPLE_RTC_WL_HIB_BIK_MISSING 24 ///< Missing boot-image-key, EFI_STATUS in EXTRA.
#define APPLE_RTC_WL_RECOVERY_OS_REBOOT 25 ///< Before rebooting into recovery with APPLE_RTC_WL_MASK_BOOT_RESET.
#define APPLE_RTC_WL_LOGIN_WINDOW_PWRESET 26 ///< Requested FDE password recovery.
#define APPLE_RTC_WL_LOGIN_WINDOW_GUEST 27 ///< Chose guest in FV2 login window, will gBS->Reset now.
#define APPLE_RTC_WL_LOGIN_WINDOW_RESET 28 ///< Chose reset in FV2 login window, will gBS->Reset now.
#define APPLE_RTC_WL_LOGIN_WINDOW_HIB 29 ///< Will save hibernation data after FV2 login window and shutdown.
#define APPLE_RTC_WL_LOGIN_WINDOW_SHUTDOWN 30 ///< Chose shutdown in FV2 login window, will gBS->Reset now.
#define APPLE_RTC_WL_LOGIN_WINDOW_FAIL 31 ///< After "End LoginWindow Initialize", EFI_STATUS in EXTRA.
#define APPLE_RTC_WL_HIB_ABORT_SAFE_MODE 32 ///< Hibernation aborted due to safe mode, after "Start CheckHibernate".
#define APPLE_RTC_WL_HIB_BI_ALLOC 33 ///< Failed to allocate memory for boot-image, EFI_STATUS in EXTRA.
#define APPLE_RTC_WL_HIB_BI_MISSING 34 ///< Missing boot-image variable or 0 size, EFI_STATUS in EXTRA.
#define APPLE_RTC_WL_HIB_BI_INVALID 35 ///< Did not find valid data in boot-image.
#define APPLE_RTC_WL_HIB_BI_DP_ALLOC 36 ///< Failed to allocate boot-image device path(?).
#define APPLE_RTC_WL_HIB_BI_DP_ZERO 37 ///< boot-image contains empty DP(?).
#define APPLE_RTC_WL_HIB_BI_DP_MISSING 38 ///< Failed to locate boot-image device path, EFI_STATUS in EXTRA.
#define APPLE_RTC_WL_HIB_BI_DP_NO_DISK_IO 39 ///< Failed to find Disk I/O protocol, EFI_STATUS in EXTRA.
#define APPLE_RTC_WL_HIB_BI_DP_NI_BLOCK_IO 40 ///< Failed to find Block I/O protocol, EFI_STATUS in EXTRA.
/**
Certain components have the ability to log their wake progress
directly via RTC. See XNU IOPMPrivate.h for more details.
LoginWindow - 4 bits
CoreDisplay - 8 bits
CoreGraphics - 8 bits
Apparently these look mostly unused, at least in release builds.
CoreDisplay is known to report 0 (very helpful) on screen wake.
I guess we can abuse them if we want.
**/
#define APPLE_RTC_TRACE_LOGIN_WINDOW_ADDR 0xB4
#define APPLE_RTC_TRACE_CORE_DISPLAY_ADDR 0xB5
#define APPLE_RTC_TRACE_CORE_GRAPHICS_ADDR 0xB6
/**
Trace point power phase e.g. kIOPMTracePointSystemUp.
See XNU IOPMPrivate.h for more details.
**/
#define APPLE_RTC_TRACE_PHASE_ADDR 0xB7
/**
256-bit full disk encryption (FDE) key used for authenticated restart.
AppleRTC and other kexts name it key stash.
Written by AppleRTC at the request of IOHibernateSMCVariables I/O registry
entry submitted either by XNU kernel or AppleFDEKeyStore.kext. The variable
itself is a pair of 64-bit values: key size and key address in kernel memory.
This was replaced with HBKP SMC key in modern Macs.
*** VirtualSMC addendum ***
Since this value is no longer used due to HBKP present in almost every Mac
we badly abuse this area when vertualising SMC.
When HBKP SMC key is written VirtualSMC AES-128 encrypts the submitted value
with a unique key and writes the result to an NVRAM variable (vsmc-key).
The AES encryption key goes to RTC at this addrress instead.
Afterwards the EFI module implementing SMC protocol performs the decryption.
TODO: Replace AES with one-time pad, i.e. increase the temporary key size
to 256 bits and just XOR the value. This will break old VirtualSmc.efi
module, but we do not care anymore.
**/
#define APPLE_RTC_FDE_KEY_ADDR 0xD0
/**
FDE key maximum and default, as AES-256-XTS has 256-bit key.
For smaller keys remaining bytes are zeroed.
**/
#define APPLE_RTC_FDE_KEY_LENGTH 0x20
/**
FDE key state. Normally written by ApplePlatformInit.
0x00 - The key is either present or not.
0x41 - The key is not present, and should be copied to RTC from HBKP
SMC key prior to transfering control to the bootloader. After the
copying succeeds this value is overwritten with 0x00. Normally
this is done by AppleBds.
**/
#define APPLE_RTC_FDE_STATE_ADDR 0xF0
/**
Known values for APPLE_RTC_FDE_STATE_ADDR.
**/
#define APPLE_RTC_FDE_STATE_DEFAULT 0x00
#define APPLE_RTC_FDE_STATE_NEED_KEY 0x41
/**
Checksum is calculated starting from this address.
**/
#define APPLE_RTC_CHECKSUM_START 0x0E
/**
First 64 bytes are RTC core and are hashed separately.
**/
#define APPLE_RTC_CORE_SIZE 0x40
/**
All Apple hardware cares about 256 bytes of RTC memory.
**/
#define APPLE_RTC_TOTAL_SIZE 0x100
/**
Apple checksum custom CRC polynomial.
Apple checksum is a modified version of ANSI CRC16 in REFIN mode (0xA001 poly).
See http://zlib.net/crc_v3.txt for more details.
Effective poly is 0x2001 due to a bitwise OR with BIT15.
The change turns CRC16 into CRC14, making BIT14 and BIT15 always zero.
This modification is commonly found in legacy Phoenix firmwares,
where it was used for password hashing as found by dogbert:
http://sites.google.com/site/dogber1/blag/pwgen-5dec.py
**/
#define APPLE_RTC_CHECKSUM_POLYNOMIAL 0x2001
/**
Apple checksum rounds.
Only 7 shifts per byte are performed instead of the usual 8.
This might improve checksum quality against specific data, but the exact
reasons are unknown. The algorithm did not change since its introduction
in 10.4.x, and since Apple Developer Transition Kit was based on Phoenix
firmware, this could just be a quick change to get a different checksum.
**/
#define APPLE_RTC_CHECKSUM_ROUNDS 7
/**
Checksum for Apple RTC with core part of the memory hashed:
[APPLE_RTC_CHECKSUM_SART, APPLE_RTC_CORE_SIZE).
**/
#define APPLE_RTC_CORE_CHECKSUM_ADDR1 0x3E
#define APPLE_RTC_CORE_CHECKSUM_ADDR2 0x3F
/**
Apple RTC core checksum to byte convertion macros.
BYTE1 BIT0~BIT7 = CHECKSUM BIT0~BIT7
BYTE2 BIT1~BIT7 = CHECKSUM BIT8~BIT14
**/
#define APPLE_RTC_CORE_CHECKSUM_BYTE1(Checksum) ((UINT8) ((UINT32) (Checksum) & 0xFFU))
#define APPLE_RTC_CORE_CHECKSUM_BYTE2(Checksum) ((UINT8) (((UINT32) (Checksum) >> 7U) & 0xFEU))
/**
Checksum for Apple RTC with all the memory hashed:
[APPLE_RTC_CHECKSUM_SART, APPLE_RTC_TOTAL_SIZE).
**/
#define APPLE_RTC_MAIN_CHECKSUM_ADDR1 0x58
#define APPLE_RTC_MAIN_CHECKSUM_ADDR2 0x59
/**
Apple RTC main checksum to byte convertion macros.
BYTE1 BIT0~BIT7 = CHECKSUM BIT0~BIT7
BYTE2 BIT0~BIT7 = CHECKSUM BIT8~BIT15
**/
#define APPLE_RTC_MAIN_CHECKSUM_BYTE1(Checksum) ((UINT8) (((UINT32) (Checksum) >> 8U) & 0xFFU))
#define APPLE_RTC_MAIN_CHECKSUM_BYTE2(Checksum) ((UINT8) ((UINT32) (Checksum) & 0xFFU))
#endif // APPLE_RTC_H
Reference in New Issue View Git Blame Copy Permalink