Complete Gathering Files conversion!

royalgraphx · Jun 26, 2023 · 6407de0 · 6407de0
1 parent d946d54
commit 6407de0
Show file tree

Hide file tree

Showing 7 changed files with 124 additions and 12 deletions.
diff --git a/DiskProvision/README.md b/DiskProvision/README.md
@@ -39,7 +39,7 @@ Open a terminal and navigate to the directory containing the script files.
 example output:
 
 ```
-[royalgraphx@hypervisor OpenCore]$ ./init.sh 
+[royalgraphx@hypervisor DiskProvision]$ ./init.sh 
 Formatting 'OpenCore.img', fmt=raw size=1073741824
 OpenCore Image created!
 Mounting and formatting...
@@ -52,7 +52,7 @@ Created 'mnt' directory.
 Image mounted to 'mnt' directory with desired ownership successfully.
 Do you want to unmount the image? (y/n): n
 Image kept mounted. Remember to unmount it later when you're done.
-[royalgraphx@hypervisor OpenCore]$
+[royalgraphx@hypervisor DiskProvision]$
 ```
 
 ## Mounting to edit OC EFI
@@ -66,7 +66,7 @@ As expected, the tools do as described. Here is some example output.
 example output:
 
 ```
-[royalgraphx@hypervisor OpenCore]$ ./mount.sh 
+[royalgraphx@hypervisor DiskProvision]$ ./mount.sh 
 nbd module is already loaded. Proceeding...
 /dev/nbd0 is already connected. Disconnecting...
 /dev/nbd0 disconnected
@@ -81,7 +81,7 @@ drwxr-xr-x 2 royalgraphx royalgraphx       4096 Dec 31  1969 mnt
 -rw-r--r-- 1 royalgraphx royalgraphx 1073741824 Jun 17 21:04 OpenCore.img
 -rw-r--r-- 1 royalgraphx royalgraphx        564 Jun 17 20:48 README.md
 -rwxr-xr-x 1 royalgraphx royalgraphx        269 Jun 17 19:54 unmount.sh
-[royalgraphx@hypervisor OpenCore]$
+[royalgraphx@hypervisor DiskProvision]$
 ```
 
 2. Unmounting the OpenCore.img:
@@ -91,19 +91,19 @@ drwxr-xr-x 2 royalgraphx royalgraphx       4096 Dec 31  1969 mnt
 Example output:
 
 ```
-[royalgraphx@hypervisor OpenCore]$ ./unmount.sh 
+[royalgraphx@hypervisor DiskProvision]$ ./unmount.sh 
 Image unmounted.
 /dev/nbd0 disconnected
 NBD device disconnected.
 Directory 'mnt' removed.
-[royalgraphx@hypervisor OpenCore]$ ls -l
+[royalgraphx@hypervisor DiskProvision]$ ls -l
 total 2084
 -rwxr-xr-x 1 royalgraphx royalgraphx       1920 Jun 17 20:09 init.sh
 -rwxr-xr-x 1 royalgraphx royalgraphx        820 Jun 17 20:04 mount.sh
 -rw-r--r-- 1 royalgraphx royalgraphx 1073741824 Jun 17 21:05 OpenCore.img
 -rw-r--r-- 1 royalgraphx royalgraphx        564 Jun 17 20:48 README.md
 -rwxr-xr-x 1 royalgraphx royalgraphx        269 Jun 17 19:54 unmount.sh
-[royalgraphx@hypervisor OpenCore]$
+[royalgraphx@hypervisor DiskProvision]$
 ```
 
 # Example usecases

diff --git a/README.md b/README.md
@@ -356,7 +356,7 @@ Skip this if you did set up the br0 interface.
 This tool automates the process of creating and setting up an OpenCore.img disk image for use with QEMU. It also comes with mount.sh and unmount.sh to easily modify the contents.
 ```
 
-Don't skip this section. To continue in this guide you will need an image file that will act as our OpenCore USB, holding all its contents. The fastest way to do this is by changing the directory into the OpenCore folder in this repository. You can quickly generate and mount a 1GB ``.img`` file to add to your Virtual Machine later. If you need any help understanding this section, please refer to the [README.md](https://github.com/royalgraphx/DarwinKVM/tree/main/DiskProvision) for better context. You can now go ahead and transfer the EFI folder from [DarwinOCPkg](https://github.com/royalgraphx/DarwinOCPkg) to the root of the image. The rest of the steps will outline adding the necessary files to build your EFI for your Virtual Machine.
+Don't skip this section. To continue in this guide you will need an image file that will act as our OpenCore USB, holding all its contents. The fastest way to do this is by changing the directory to the DiskProvision folder in this repository. You can quickly generate and mount a 1GB ``.img`` file to add to your Virtual Machine later. If you need any help understanding this section, please refer to the [README.md](https://github.com/royalgraphx/DarwinKVM/tree/main/DiskProvision) for better context. You can now go ahead and transfer the EFI folder from [DarwinOCPkg](https://github.com/royalgraphx/DarwinOCPkg) to the root of the image. The rest of the steps will outline adding the necessary files to build your EFI for your Virtual Machine.
 
 <br>
 <h2 align="center"><b>Part 1:</b> ACPI Tables</h2>

diff --git a/docs/docs/03-GatheringFiles/00-ImageCreation.md b/docs/docs/03-GatheringFiles/00-ImageCreation.md
@@ -3,4 +3,40 @@ layout: default
 title: Part 0 - Image Creation
 parent: Gathering Files
 nav_order: 1
----
+---
+
+# OpenCore Image Creation
+#### Creation of the OpenCore .img for your DKVM.
+#### This section has been derived from the <a href="https://github.com/royalgraphx/DarwinKVM/tree/main/DiskProvision">DiskProvision</a> Submodule.
+
+{: .important }
+This tool automates the process of creating and setting up an OpenCore.img disk image for use with QEMU. It also comes with mount.sh and unmount.sh to easily modify the contents.
+
+Don't skip this section. To continue in this guide you will need an image file that will act as our OpenCore USB, holding all its contents. The fastest way to do this is by changing the directory to the DiskProvision folder in this repository. You can quickly generate and mount a 1GB ``.img`` file to add to your Virtual Machine later. If you need any help understanding this section, please refer to the [README.md](https://github.com/royalgraphx/DarwinKVM/tree/main/DiskProvision) for better context. You can now go ahead and transfer the EFI folder from [DarwinOCPkg](https://github.com/royalgraphx/DarwinOCPkg) to the root of the image. The rest of the steps will outline adding the necessary files to build your EFI for your Virtual Machine.
+
+## Basic Usage
+
+```
+[royalgraphx@hypervisor DiskProvision]$ ./init.sh 
+Formatting 'OpenCore.img', fmt=raw size=1073741824
+OpenCore Image created!
+Mounting and formatting...
+nbd module is already loaded. Proceeding...
+[sudo] password for royalgraphx: 
+/dev/nbd0 disconnected
+mkfs.fat 4.2 (2021-01-31)
+Formatting complete!
+Created 'mnt' directory.
+Image mounted to 'mnt' directory with desired ownership successfully.
+Do you want to unmount the image? (y/n): n
+Image kept mounted. Remember to unmount it later when you're done.
+[royalgraphx@hypervisor DiskProvision]$
+```
+
+## Example
+
+<p align="center">
+  <img src="../../assets/OpenCoreLocalCreation.png">
+</p>
+
+## You can now continue to the next <a href="01-ACPITables.html">page</a>.
diff --git a/docs/docs/03-GatheringFiles/01-ACPITables.md b/docs/docs/03-GatheringFiles/01-ACPITables.md
@@ -3,4 +3,36 @@ layout: default
 title: Part 1 - ACPI Tables
 parent: Gathering Files
 nav_order: 2
----
+---
+
+# ACPI Tables
+#### This section has been derived from the <a href="https://dortania.github.io/Getting-Started-With-ACPI/">Getting Started with ACPI</a> guide. It may be out of date. Please refer to latest documentation when possible.
+
+{: .note }
+So what are DSDTs and SSDTs? Well, these are tables present in your firmware that outline hardware devices like USB controllers, CPU threads, embedded controllers, system clocks and such. A DSDT (Differentiated System Description Table) can be seen as the body holding most of the info with smaller bits of info being passed by the SSDT (Secondary System Description Table). You can think of the DSDT as the building blueprints with SSDTs being sticky notes outlining extra details to the project.
+
+#### You can read more about ACPI and it's specs [here](https://uefi.org/sites/default/files/resources/ACPI_Spec_6_4_Jan22.pdf).
+
+# What would we need?
+
+macOS can be very picky about the devices present in the DSDT and so our job is to correct it. The main devices that need to be corrected for macOS to work properly:
+
+ - Embedded controller (EC)
+   - macOS Catalina+ requires a device named EC to be present, so we create a dummy EC. The USBX devices (See next) also requires an EC device to work.
+ - USBX
+   - This sets the correct USB power properties for charging devices like phones.
+ - Plugin type
+   - This generally allows the use of XCPM providing native CPU power management on Intel CPUs. Our version will enable VMPlatformPlugin XCPM, exactly like a Parallels VM.
+
+For our Virtual Machine use case, we will be emulating an Intel Cascade Lake CPU so regardless of the host architecture, the only ACPI's we require to boot macOS will be SSDT-EC-USBX and SSDT-PLUG.
+
+Thanks to [ExtremeXT](https://github.com/ExtremeXT) for allowing me to include his manually created SSDT-EC-USBX which combines them into a single file, as well as the included SSDT-PLUG file. We've both tested it and it works as expected, and I use it for my daily machine so I'm confident including it, feel free to manually make your own or possibly try the ones from Acidanthera! As long as you complete this ACPI section, you can go ahead to the next step.
+
+You can view the CPU ACPI requirements by generation [here](https://dortania.github.io/Getting-Started-With-ACPI/ssdt-platform.html#desktop).
+
+{: .note }
+Cascade Lake supersedes Skylake although not shown on the chart.
+
+### The required files can be found in the DarwinOCPkg/X64/EFI/OC/ACPI folder.
+
+## You can now continue to the next <a href="02-Drivers.html">page</a>.
diff --git a/docs/docs/03-GatheringFiles/02-Drivers.md b/docs/docs/03-GatheringFiles/02-Drivers.md
@@ -3,4 +3,21 @@ layout: default
 title: Part 2 - Drivers
 parent: Gathering Files
 nav_order: 3
----
+---
+
+# Drivers
+#### This section has been derived from the <a href="https://dortania.github.io/OpenCore-Install-Guide/installer-guide/opencore-efi.html">Adding The Base OpenCore Files</a> guide. It may be out of date. Please refer to latest documentation when possible.
+
+Now something you'll notice is that it comes with a bunch of files in Drivers and Tools folder, we don't want most of these:
+
+- Keep the following from Drivers (if applicable):
+
+| Driver  | Status | Description | 
+| ----- | ----- | ----- |
+| OpenRuntime.efi | Required | Required for fixing NVRAM, power management, RTC, memory mapping etc. |
+| ResetNvramEntry.efi | Required | Required to reset the system's NVRAM |
+| OpenHfsPlus.efi | Optional | Open sourced HFS+ driver, but slower than Apple's proprietary driver |
+
+There are already base files included in the repository. You'll have to check with your hardware to see if you need anything additional. As outlined in [Gathering files -> Firmware Drivers](https://dortania.github.io/OpenCore-Install-Guide/ktext.html#firmware-drivers) you will see a table that states [HfsPlus.efi](https://github.com/acidanthera/OcBinaryData/blob/master/Drivers/HfsPlus.efi) is a required Driver. Personally from my experience, I've been fine using OpenHfsPlus.efi but you should first try with [HfsPlus.efi](https://github.com/acidanthera/OcBinaryData/blob/master/Drivers/HfsPlus.efi), please download and add that to your OpenCore EFI.
+
+## You can now continue to the next <a href="03-Kexts.html">page</a>.
diff --git a/docs/docs/03-GatheringFiles/03-Kexts.md b/docs/docs/03-GatheringFiles/03-Kexts.md
@@ -3,4 +3,22 @@ layout: default
 title: Part 3 - Kexts
 parent: Gathering Files
 nav_order: 4
----
+---
+
+# Kexts
+#### This section has been derived from the <a href="https://dortania.github.io/OpenCore-Install-Guide/ktext.html#kexts">Kexts</a> section via <a href="https://dortania.github.io/OpenCore-Install-Guide/ktext.html">Gathering files</a>. It may be out of date. Please refer to latest documentation when possible.
+
+Here is a basic chart of a Kext, its use, and the status of the requirement. Check with the hardware you'll be passing through if you need any Kexts. For example, Samsung NVMe should be using NVMeFix.kext for better voltage and temperature management by macOS.
+
+| Kext  | Status | Description | 
+| ----- | ----- | ----- |
+| [Lilu](https://github.com/acidanthera/Lilu/releases) | Required | A kext to patch many processes, required for AppleALC, WhateverGreen, VirtualSMC and many other kexts. Without Lilu, they will not work. |
+| [WhateverGreen](https://github.com/acidanthera/WhateverGreen/releases) | Required | Used for graphics patching, DRM fixes, board ID checks, framebuffer fixes, etc; all GPUs benefit from this kext. |
+| [AppleMCEReporterDisabler](https://github.com/acidanthera/bugtracker/files/3703498/AppleMCEReporterDisabler.kext.zip) | Required | Required on macOS 12.3 and later on AMD systems and dual-socket Intel systems, and on KVM. |
+| [VirtualSMC](https://github.com/acidanthera/VirtualSMC/releases) | Optional | Emulates the SMC chip found on real macs, but we are already emulating it from the XML file, this might be useful for kexts that send temperature info to the SMC, like SMCRadeonGPU. |
+| [NVMeFix](https://github.com/acidanthera/NVMeFix/releases) | Optional | NVMeFix is a set of patches for the Apple NVMe storage driver, IONVMeFamily. Its goal is to improve compatibility with non-Apple SSDs. It may be used both on Apple and non-Apple computers. Note: Does not work on Sonoma as of now. |
+| [RestrictEvents](https://github.com/acidanthera/RestrictEvents/releases) | Optional | Lilu plugin for blocking unwanted processes causing compatibility issues on different hardware and unlocking the support for certain features restricted to other hardware. We will mainly use it for changing the name of the CPU cosmetically. |
+| [RadeonSensor](https://github.com/NootInc/RadeonSensor/releases) | Optional | Kext and Gadget to show AMD GPU temperature on macOS. |
+| [AGPMInjector](https://github.com/Pavo-IM/AGPMInjector/releases) | Optional | Injects AGPM (Apple Graphics Power Management) to our non-Apple GPUs. |
+
+## You can now continue to the next <a href="04-Tools.html">page</a>.
diff --git a/docs/docs/03-GatheringFiles/04-Tools.md b/docs/docs/03-GatheringFiles/04-Tools.md
@@ -5,4 +5,13 @@ parent: Gathering Files
 nav_order: 5
 ---
 
+# Tools
+#### This section has been derived from the <a href="https://dortania.github.io/OpenCore-Install-Guide/installer-guide/opencore-efi.html">Adding The Base OpenCore Files</a>. It may be out of date. Please refer to latest documentation when possible.
+
+As far as I'm concerned, you only need OpenShell.efi and even then, that's only for debugging. It's already included within [DarwinOCPkg](https://github.com/royalgraphx/DarwinOCPkg).
+
+| Tool  | Status | Description | 
+| ----- | ----- | ----- |
+| OpenShell.efi | Optional | Recommended for easier debugging. |
+
 <h1>You can now proceed to the <a href="../04-Configs/">Configs</a> section!</h1>