Merge pull request #9 from ethanaobrien/macos

macOS reorg w/ custom firmware

src/.vuepress/config.js

@@ -137,6 +137,17 @@ export default {
           {
             text: 'Installing MacOS',
             link: '/docs/installing/installing-macos',
+            collapsible: true,
+            children: [
+              {
+                text: 'Custom macOS firmware',
+                link: '/docs/installing/macos-firmware',
+              },
+              {
+                text: 'Fixing hibernation',
+                link: '/docs/installing/macos-hibernation',
+              }
+            ]
           },
           {
             text: 'Post Install',

src/docs/installing/installing-macos.md

@@ -17,23 +17,7 @@ Before we begin, it's important to know whether your Chromebook is even supporte
 * The ability to use a command line
   	* We won't help you if you don't know how to `cd` to a directory.
 
----
-
-## Known Issues
-
-- Broken NVRAM on Comet Lake Devices
-   	- To fix this, **DISABLE** `DevirtualiseMmio`.
-   	::: warning
-   	If your device has a Comet Lake CPU, this MUST be disabled.
-    :::
-
-- Waking from sleep causes:
-   - Blank Electron / Chromium apps
-   - Buggy video playback in web browsers like Firefox or Safari
-   - Display/Wallpaper settings in SysPref/SysSettings
-   - Logging out freezes your system
-
-### Tested Devices
+## Tested Devices
 
 ::: tip
 This list is incomplete. Feel free to improve it.
@@ -70,36 +54,38 @@ This list is incomplete. Feel free to improve it.
 * [LuluMacOS](https://isi95010.github.io/LuluMacOS/)
   * Dell Chromebook 13 7310 (LULU)
 
----
+## Custom Firmware
 
-## Installation
-
-**Getting Started:**
+It is recommended to [flash Coreboot firmware](macos-firmware) with the Management Engine Interface enabled on Skylake and newer.  
+Without the ME interface enabled, the following bugs can occur after waking from sleep:
+- Blank Electron / Chromium apps
+- Buggy video playback in web browsers like Firefox or Safari
+- Display/Wallpaper settings in SysPref/SysSettings
+- Logging out freezes your system
 
-1. Follow the [Dortania guide](https://dortania.github.io/OpenCore-Install-Guide).
-2. Follow the laptop guide for your CPU generation
-	* Amber Lake Chromebooks should follow the Kaby Lake config.plist setup
-3. As necessary, add the following Kexts and SSDTs to your EFI:
+## Installation
 
-- Firmware Fixes:
-    - [croscorebootpatch](https://github.com/meghan06/croscorebootpatch): Fixes freeze during boot when using coreboot 4.20 and newer
+Start by following the [Dortania guide](https://dortania.github.io/OpenCore-Install-Guide) for your CPU generation.
+Amber Lake Chromebooks should follow config.plist setup for Kaby Lake.  
+Add the following SSDTs, kexts and modifications as needed:
 
-- Keyboard:
-	- [VoodooPS2.kext](https://github.com/1Revenger1/VoodooPS2/releases): Fork of Acidanthera's VoodooPS2 which allows mapping keyboard brightness and other useful keys
-	- [Keyboard Map](https://github.com/1Revenger1/Acer-Spin-713-Hackintosh/blob/main/src/ACPI/SSDT-ChromeKeys.dsl): Maps FNx keys to ChromeOS mapping. This is an example, you may need to do your own mapping.
-  	- Will need to be compiled with either `iASL` or `MaciASL`.
+#### Config.plist Fixes
+- Disable `Booter->Quirks->DevirtualiseMmio`: Fixes NVRAM and other runtime EFI services
 
-- Chrome EC:
-	- [CrosEC.kext](https://github.com/1Revenger1/CrosEC/releases): Adds keyboard brightness, tablet mode, and other functionality
-	- [Fake Ambient Light Sensor](https://github.com/acidanthera/OpenCorePkg/blob/master/Docs/AcpiSamples/Source/SSDT-ALS0.dsl): Creates a fake ambient light sensor which is needed by macOS to recognize the keyboard backlight.
-  	  - This is only needed if your device does not come with a light sensor.
-  	  - A pre-compiled version comes in OpenCore's release zip under `Docs/AcpiSamples/Binaries/SSDT-ASL0.aml`
+#### SSDTs and ACPI Fixes:
+- [croscorebootpatch](https://github.com/meghan06/croscorebootpatch): Fixes freeze during boot when using coreboot 4.20 and newer
+- [Keyboard Map](https://github.com/1Revenger1/Acer-Spin-713-Hackintosh/blob/main/src/ACPI/SSDT-ChromeKeys.dsl): Maps FNx keys to ChromeOS mapping. This is an example, you may need to do your own mapping.
+   - Will need to be compiled with either `iASL` or `MaciASL`.
+- [Fake Ambient Light Sensor](https://github.com/acidanthera/OpenCorePkg/blob/master/Docs/AcpiSamples/Source/SSDT-ALS0.dsl): Creates a fake ambient light sensor which is needed by macOS to recognize the keyboard backlight.
+   - This is only needed if your device does not come with a light sensor.
+   - A pre-compiled version comes in OpenCore's release zip under `Docs/AcpiSamples/Binaries/SSDT-ASL0.aml`
 
-- Storage:
-  	- [EmeraldSDHC.kext](https://github.com/acidanthera/EmeraldSDHC/releases): eMMC driver
+#### Kexts
+- [EmeraldSDHC.kext](https://github.com/acidanthera/EmeraldSDHC/releases): eMMC driver
+- [VoodooPS2.kext](https://github.com/1Revenger1/VoodooPS2/releases): Fork of Acidanthera's VoodooPS2 which allows mapping keyboard brightness and other useful keys
+- [CrosEC.kext](https://github.com/1Revenger1/CrosEC/releases): Adds keyboard brightness, tablet mode, and other functionality
 
-4. Take those files you downloaded and put the `.aml` files in the ACPI folder, and the `.kexts` into the kexts folder
-5. Snapshot (cmd +r) or (ctrl + r) your `config.plist`. 
+### Snapshot (cmd + r) or (ctrl + r) your `config.plist` after making modifications.
 
 ::: danger
 If you dualboot with the SSDTs mentioned above, you might run into issues on other OSes. An `OSI_` check is not present in these SSDTs.

src/docs/installing/macos-firmware.md

@@ -0,0 +1,36 @@
+# macOS Firmware
+
+It is recommended to flash coreboot with the Intel Management Engine interface enabled to prevent bugs after waking from sleep.  
+Without the ME interface enabled, the following bugs can occur after waking from sleep:
+- Blank Electron / Chromium apps
+- Buggy video playback in web browsers like Firefox or Safari
+- Display/Wallpaper settings in SysPref/SysSettings
+- Logging out freezes your system
+
+## Custom Firmware
+
+### Prebuilt
+
+Prebuilts can be found at [ethanthesleepy.one](https://ethanthesleepy.one/macos/)
+
+### Building Manually
+
+1. Follow the steps [here](../../advanced/compiling-coreboot.md) to download the toolchain and build the firmware
+    * Continue these steps once `build-uefi.sh <boardname>` has been ran
+1. Run `make menuconfig`. You will be greeted by a menu which looks like the following:
+
+    ![image](/macos/menuconfig.png)
+
+1. Select `Chipset`
+1. Select `Disable HECI1 at the end of boot` then press `N` to disable. The asterik should be gone:
+
+    ![image](/macos/heci1.png)
+
+1. Use the right arrow keys to select `Save` at the bottom, then press `Ok`
+1. Use the right/left arrow keys to select `Exit` until back at the prompt.
+1. Run `make -j$(nproc)` to build the firmware.
+1. The output will be found at `./build/coreboot.rom`
+
+## Flashing Firmware
+
+Follow the steps [here](../../advanced/compiling-coreboot.html) to flash the new firmware

src/docs/installing/macos-hibernation.md

@@ -0,0 +1,50 @@
+# macOS Hibernation
+
+macOS by default will try to use hibernation after sleeping for a predetermined amount of time.  
+Some fixes in the `config.plist` are required in order to take advantage of this:
+
+- Disable `Booter->Quirks->DevirtualiseMmio`
+- Set `Misc->Boot->HibernateMode` to `Auto`
+    - By default, OpenCore will not look for hibernated images of macOS.
+- Set `Misc->Boot->HibernationSkipsPicker` to `True` to skip the picker when resuming from hibernation
+    - While not strictly required, this speeds up resume times and prevents accidently booting another OS and changing hardware state underneath macOS.
+- Create a reserved memory region under `UEFI->ReservedMemory` with the properties:
+
+    | Field   | Type    | Value |
+    | ------- | ------- | ----- |
+    | Comment | String  | Fix black screen on wake from hibernation |
+    | Enabled | Boolean | True |
+    | Address | Number  | 569344 |
+    | Enabled | Boolean | True |
+    | Size    | Number  | 4096 |
+    | Type    | String  | RuntimeCode |
+
+## Testing Hibernation
+
+To test hibernation, it is recommended to run `sudo pmset -a hibernatemode 25`.  
+This will force macOS to hibernate immediately whenever the lid is closed or `Sleep` is selected in the menu at the top left.
+
+### macOS enters S3 sleep instead of shutting down
+
+Some models (such as `KLED`) have drives not marked as internal, which prevents macOS from entering hibernation.  
+To fix this, add the `built-in` property to the PCI device under `DeviceProperties->Add-><storage device path>`:
+
+| Field    | Type | Value      |
+| -------- | ---- | ---------- | 
+| built-in | Data | <01000000> |
+
+You may need to add an ACPI device as well.
+If an ACPI device does not exist to represent the NVMe or eMMC drive, then device properties will not be applied.
+An example SSDT can be found [here](https://github.com/1Revenger1/Acer-Spin-713-Hackintosh/blob/main/src/ACPI/SSDT-Devices.dsl).
+
+## Hibernate Modes
+
+Pmset exposes a few different hibernation modes which can be set through `sudo pmset -a hibernatemode <value>`:
+
+- 0: Disables hibernation
+- 3: Hibernates after either `standbydelaylow` or `standbydelayhigh` seconds of sleep
+    - Which one is used is dependent on the battery percentage. Anything above `highstandbythreshold` will use `standbydelayhigh` instead of `standbydelaylow`.
+- 25: Hibernates instead of S3 sleep
+
+When using hibernate mode 3, macOS may keep sleeping even after the standby time has elapsed.
+[`HibernationFixup.kext`](https://github.com/acidanthera/HibernationFixup) may be required in this case, and provides options to fine tune when the Chromebook is allowed to sleep.