From 6407de081c89b4870396bed159a153c0d775ad40 Mon Sep 17 00:00:00 2001 From: RoyalGraphX <39929362+royalgraphx@users.noreply.github.com> Date: Mon, 26 Jun 2023 13:52:09 -0500 Subject: [PATCH] Complete Gathering Files conversion! --- DiskProvision/README.md | 14 +++---- README.md | 2 +- .../03-GatheringFiles/00-ImageCreation.md | 38 ++++++++++++++++++- docs/docs/03-GatheringFiles/01-ACPITables.md | 34 ++++++++++++++++- docs/docs/03-GatheringFiles/02-Drivers.md | 19 +++++++++- docs/docs/03-GatheringFiles/03-Kexts.md | 20 +++++++++- docs/docs/03-GatheringFiles/04-Tools.md | 9 +++++ 7 files changed, 124 insertions(+), 12 deletions(-) diff --git a/DiskProvision/README.md b/DiskProvision/README.md index 3518e00..539a013 100644 --- 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 index b0f3e2b..7437c58 100644 --- 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.

Part 1: ACPI Tables

diff --git a/docs/docs/03-GatheringFiles/00-ImageCreation.md b/docs/docs/03-GatheringFiles/00-ImageCreation.md index d2c3382..922c2cc 100644 --- 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 ---- \ No newline at end of file +--- + +# OpenCore Image Creation +#### Creation of the OpenCore .img for your DKVM. +#### This section has been derived from the DiskProvision 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 + +

+ +

+ +## You can now continue to the next page. \ No newline at end of file diff --git a/docs/docs/03-GatheringFiles/01-ACPITables.md b/docs/docs/03-GatheringFiles/01-ACPITables.md index fe479d9..b890ddc 100644 --- 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 ---- \ No newline at end of file +--- + +# ACPI Tables +#### This section has been derived from the Getting Started with ACPI 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 page. \ No newline at end of file diff --git a/docs/docs/03-GatheringFiles/02-Drivers.md b/docs/docs/03-GatheringFiles/02-Drivers.md index 808ed0c..d5bc0d9 100644 --- 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 ---- \ No newline at end of file +--- + +# Drivers +#### This section has been derived from the Adding The Base OpenCore Files 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 page. \ No newline at end of file diff --git a/docs/docs/03-GatheringFiles/03-Kexts.md b/docs/docs/03-GatheringFiles/03-Kexts.md index 8de74c5..ca1a619 100644 --- 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 ---- \ No newline at end of file +--- + +# Kexts +#### This section has been derived from the Kexts section via Gathering files. 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 page. \ No newline at end of file diff --git a/docs/docs/03-GatheringFiles/04-Tools.md b/docs/docs/03-GatheringFiles/04-Tools.md index fae5ac6..0e17cb7 100644 --- 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 Adding The Base OpenCore Files. 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. | +

You can now proceed to the Configs section!

\ No newline at end of file