From 09b5c5cafd4203f3a7816a835be81b72db01d81f Mon Sep 17 00:00:00 2001
From: RoyalGraphX <39929362+royalgraphx@users.noreply.github.com>
Date: Mon, 26 Jun 2023 16:06:09 -0500
Subject: [PATCH] DarwinKVM Docs Base Guide finished!
---
.../06-InstallingmacOS/00-ImportingXML.md | 25 +++-
.../06-InstallingmacOS/01-ConfigDisplay.md | 19 ++-
.../06-InstallingmacOS/02-ConfigDrives.md | 36 ++++-
docs/docs/06-InstallingmacOS/03-ConfigNIC.md | 19 ++-
docs/docs/06-InstallingmacOS/04-Review.md | 11 +-
.../06-InstallingmacOS/05-Installation.md | 83 ++++++++++++
docs/docs/06-InstallingmacOS/index.md | 9 +-
.../01-Installation.md | 43 +++++-
.../02-HookModification.md | 19 ++-
.../07-SingleGPUPassthrough/03-VManUpdate.md | 125 ++++++++++++++++++
10 files changed, 381 insertions(+), 8 deletions(-)
diff --git a/docs/docs/06-InstallingmacOS/00-ImportingXML.md b/docs/docs/06-InstallingmacOS/00-ImportingXML.md
index 34023ae..94faa41 100644
--- a/docs/docs/06-InstallingmacOS/00-ImportingXML.md
+++ b/docs/docs/06-InstallingmacOS/00-ImportingXML.md
@@ -3,4 +3,27 @@ layout: default
title: Part 0 - Importing XML
parent: Installing macOS
nav_order: 1
----
\ No newline at end of file
+---
+
+# Importing XML
+#### This imports a blank Virtual Machine titled "DarwinKVM" ready to be used for macOS Guests.
+
+Run the following command in the root directory of DarwinKVM:
+
+``virsh --connect qemu:///system define DarwinKVM.xml``
+
+Which will now allow you to view it in Virt-Manager.
+
+
+ 
+
+
+Notice this template is missing a few things you must set up.
+
+- Has no default Display
+- Has no drives configured
+- Has no NIC configured
+
+Let's go through these steps quickly.
+
+## You can now continue to the next page.
\ No newline at end of file
diff --git a/docs/docs/06-InstallingmacOS/01-ConfigDisplay.md b/docs/docs/06-InstallingmacOS/01-ConfigDisplay.md
index 18bbd86..c4c40d1 100644
--- a/docs/docs/06-InstallingmacOS/01-ConfigDisplay.md
+++ b/docs/docs/06-InstallingmacOS/01-ConfigDisplay.md
@@ -3,4 +3,21 @@ layout: default
title: Part 1 - Configure Display for recoveryOS
parent: Installing macOS
nav_order: 2
----
\ No newline at end of file
+---
+
+# Configuring Virtio Display
+#### This is required to have a display.
+
+Select the "Add Hardware" button and navigate to Graphics. Select the ``Listen Type:`` to None. then select the "Finish" button.
+
+
+ 
+
+
+Select the Video tab on the left-hand side, and choose the ``Virtio`` model.
+
+
+ 
+
+
+## You can now continue to the next page.
\ No newline at end of file
diff --git a/docs/docs/06-InstallingmacOS/02-ConfigDrives.md b/docs/docs/06-InstallingmacOS/02-ConfigDrives.md
index 67114b6..686c90d 100644
--- a/docs/docs/06-InstallingmacOS/02-ConfigDrives.md
+++ b/docs/docs/06-InstallingmacOS/02-ConfigDrives.md
@@ -3,4 +3,38 @@ layout: default
title: Part 2 - Configure Storage Drives
parent: Installing macOS
nav_order: 3
----
\ No newline at end of file
+---
+
+# Configure VirtIO Drives
+#### This is required to boot OpenCore.
+
+## Adding OpenCore Drive
+
+Select the "Add Hardware" button to bring up the Storage prompt. Select the OpenCore image via the "Manage..." button. The ``Bus type:`` should be set to VirtIO. Cache mode set to none, and Discard mode is set to unmap.
+
+
+ 
+
+
+
+
+ 
+
+
+Don't forget to set it as your boot drive.
+
+
+ 
+
+
+## Creating a Virtual SSD for installation
+
+If you're not going to passthrough an NVME drive to install macOS on, then this is the step to make a disk image. You can choose any size you'd like but I suggest the standard 128G, 256GB, 500GB, 1000GB.
+
+Here you can see me creating the disk image I'll be installing macOS on.
+
+
+ 
+
+
+## You can now continue to the next page.
\ No newline at end of file
diff --git a/docs/docs/06-InstallingmacOS/03-ConfigNIC.md b/docs/docs/06-InstallingmacOS/03-ConfigNIC.md
index 9438105..2614da7 100644
--- a/docs/docs/06-InstallingmacOS/03-ConfigNIC.md
+++ b/docs/docs/06-InstallingmacOS/03-ConfigNIC.md
@@ -3,4 +3,21 @@ layout: default
title: Part 3 - Configure NIC for Virtual Machine
parent: Installing macOS
nav_order: 4
----
\ No newline at end of file
+---
+
+# Configure Virtual Machine NIC
+#### This is required to download macOS via RecoveryOS, as well as will be the general ethernet connection in the Virtual Machine.
+
+## Using the Bridge Interface
+
+Select the "Add Hardware" button and choose the Network category on the left-hand side. You can now see your network source can be set to Bridge device. The device name given by the script is ``br0``. Of course don't forget to set the Device model as ``VirtIO``.
+
+
+ 
+
+
+## Using the Default Network
+
+If you didn't choose to set up a Bridge Interface, you can still use the regular NAT type default network created by libvirt in your Virtual Machine! Follow the same steps but select the defaults.
+
+## You can now continue to the next page.
\ No newline at end of file
diff --git a/docs/docs/06-InstallingmacOS/04-Review.md b/docs/docs/06-InstallingmacOS/04-Review.md
index f0a1183..feaaea1 100644
--- a/docs/docs/06-InstallingmacOS/04-Review.md
+++ b/docs/docs/06-InstallingmacOS/04-Review.md
@@ -3,4 +3,13 @@ layout: default
title: Part 4 - Finished Example
parent: Installing macOS
nav_order: 5
----
\ No newline at end of file
+---
+
+# Review
+#### Notice the display, drives, and NIC added.
+
+
+ 
+
+
+## You can now continue to the next page.
\ No newline at end of file
diff --git a/docs/docs/06-InstallingmacOS/05-Installation.md b/docs/docs/06-InstallingmacOS/05-Installation.md
index 3e1b4fe..0d51ede 100644
--- a/docs/docs/06-InstallingmacOS/05-Installation.md
+++ b/docs/docs/06-InstallingmacOS/05-Installation.md
@@ -5,4 +5,87 @@ parent: Installing macOS
nav_order: 6
---
+# Installing macOS via recoveryOS
+#### You should now be ready to install macOS!
+
+OpenCore Menu, shows RecoveryOS detected.
+
+
+ 
+
+
+macOS Ventura RecoveryOS booting
+
+
+ 
+
+
+macOS Ventura Disk Utility showing OpenCore drive.
+
+
+ 
+
+
+{: .highlight }
+From here on out, the screenshots will show macOS Sonoma because I had the USB prepared nearby and wanted to test everything working still even in Sonoma. This won't make a difference for you, it's the same for macOS Ventura.
+
+
+ 
+
+
+Open Disk Utility, and format the target drive to APFS.
+
+
+ 
+
+
+
+ 
+
+
+
+ 
+
+
+You are now ready to proceed to the installation!
+
+
+ 
+
+
+
+ 
+
+
+Second Boot Phase
+
+
+ 
+
+
+Third Boot Phase, further unpacking.
+
+
+ 
+
+
+{: .note }
+You may get a fourth reboot, if not, eventually, you will the proper name of your drive:
+
+
+ 
+
+
+Here we are at the desktop of our Virtual Machine.
+
+
+ 
+
+
+Our OpenCore image is mounted easily and recognized by macOS. Allowing easy modification within and out of the Virtual Machine. Any changes made here, can easily be viewed by mounting on the host. This can be useful for moving small files.
+
+
+ 
+
+
\ No newline at end of file
diff --git a/docs/docs/06-InstallingmacOS/index.md b/docs/docs/06-InstallingmacOS/index.md
index 89020af..bc7c85b 100644
--- a/docs/docs/06-InstallingmacOS/index.md
+++ b/docs/docs/06-InstallingmacOS/index.md
@@ -7,4 +7,11 @@ has_children: true
-
\ No newline at end of file
+
+
+# Installing macOS via recoveryOS
+
+{: .note }
+This example will show the installation of macOS Sonoma. This applies for Monterey and Ventura as well, you can follow it just the same.
+
+## You can now continue to the next page.
\ No newline at end of file
diff --git a/docs/docs/07-SingleGPUPassthrough/01-Installation.md b/docs/docs/07-SingleGPUPassthrough/01-Installation.md
index 3e39310..cc1c367 100644
--- a/docs/docs/07-SingleGPUPassthrough/01-Installation.md
+++ b/docs/docs/07-SingleGPUPassthrough/01-Installation.md
@@ -3,4 +3,45 @@ layout: default
title: Part 1 - Script Installation
parent: Single GPU Passthrough
nav_order: 1
----
\ No newline at end of file
+---
+
+# Installation of Scripts
+#### Script Installation thanks to RisingPrism!
+
+{: .important }
+If the RisingPrism scripts do not work, use the akshaycodes scripts instead.
+
+We'll start by doing a ``git clone`` command to fetch the scripts.
+
+``git clone https://gitlab.com/risingprismtv/single-gpu-passthrough.git``
+
+In the newly created single-gpu-passthrough folder, run the installation as root:
+
+``sudo chmod +x install_hooks.sh``
+
+``sudo ./install_hooks.sh``
+
+Verify that the files are installed correctly. You should have files in the following location:
+
+```
+/etc/systemd/system/libvirt-nosleep@.service
+/bin/vfio-startup.sh
+/bin/vfio-teardown.sh
+/etc/libvirt/hooks/qemu
+```
+
+Because we previously set logs to output, you can find them here:
+
+```
+DarwinKVM.log => /var/log/libvirt/qemu
+custom_hooks.log => /var/log/libvirt/
+libvirtd.log => /var/log/libvirt/
+```
+
+But if the RisingPrism scripts aren't working well for you and you end up using akshaycodes, you can find the logs at:
+
+```
+custom_hooks.log => /var/tmp/vfio-script.log
+```
+
+## You can now continue to the next page.
\ No newline at end of file
diff --git a/docs/docs/07-SingleGPUPassthrough/02-HookModification.md b/docs/docs/07-SingleGPUPassthrough/02-HookModification.md
index d62f5ce..c74b7d3 100644
--- a/docs/docs/07-SingleGPUPassthrough/02-HookModification.md
+++ b/docs/docs/07-SingleGPUPassthrough/02-HookModification.md
@@ -3,4 +3,21 @@ layout: default
title: Part 2 - Hook Modification
parent: Single GPU Passthrough
nav_order: 2
----
\ No newline at end of file
+---
+
+# Hook Modification
+#### Use your favorite terminal text editor!
+
+Modify the following file to add `` $OBJECT == "DarwinKVM" `` to the if statement. This will allow the hook to now pay attention to the DarwinKVM Virtual Machine. If for any reason you need to use the Virtual Machine without GPU passthrough, you should remove this modification to allow proper usage of the VirtIO Display when not doing passthrough willingly or for debugging reasons.
+
+```
+sudo nano /etc/libvirt/hooks/qemu
+```
+
+Example modified file:
+
+
+ 
+
+
+## You can now continue to the next page.
\ No newline at end of file
diff --git a/docs/docs/07-SingleGPUPassthrough/03-VManUpdate.md b/docs/docs/07-SingleGPUPassthrough/03-VManUpdate.md
index b96e17d..04ec36d 100644
--- a/docs/docs/07-SingleGPUPassthrough/03-VManUpdate.md
+++ b/docs/docs/07-SingleGPUPassthrough/03-VManUpdate.md
@@ -5,4 +5,129 @@ parent: Single GPU Passthrough
nav_order: 3
---
+# Virt-Manager Modifications
+#### How to properly use GPU Passthrough.
+
+## Removing the virt-manager Display
+
+First things first, we must remove the ``Spice Display`` and ``Video Virtio`` from the left hand side in our Virt-Manager window for DarwinKVM. As you can see here, they are now removed.
+
+
+ 
+
+
+## Removing recoveryOS Keyboard & Mouse
+
+Now let's go ahead and remove the recoveryOS Keyboard and Mouse as we'll now be passing through our actual USB controllers later. You'll have to select the ``Overview`` tab on your left-hand side, and swap to the XML tab at the top. Scroll to the very bottom and delete and save this change.
+
+
+ 
+
+
+## Enabling Topoext / SVM for Multithreading
+
+Depending on your CPU, you should enable either Topoext or SVM for your host OS. Here it is on an AMD host.
+
+
+ 
+
+
+## IOMMU Groups
+
+Now here's the tricky bit. You'll need to check your IOMMU groups. This can be done within the DarwinKVM repository by simply issuing the command ``./iommu-check.sh``
+
+Sample Output, this is a host using [Zen Kernel](https://github.com/zen-kernel/zen-kernel) and [ACS Patches](https://wiki.archlinux.org/title/PCI_passthrough_via_OVMF#Bypassing_the_IOMMU_groups_(ACS_override_patch)):
+
+Note that you will not get this output, you will see multiple devices within groups, you can only pass through devices in a group, if you can pass the entire group. This means that if your GPU and Ethernet are in the same group, you must pass through the entire group. This is where many people will run into issues. I do not want to go into great detail about it because I feel like it's common sense when reading the documentation I've linked above. If your IOMMU groups are not great, then consider the Zen Kernel, and ACS Patch.
+
+And remember for later, DO NOT ADD BRIDGES to your VM, that means devices like PCI bridge [0604] in your groups.
+
+```
+IOMMU Group 24:
+ 08:00.0 PCI bridge [0604]: Advanced Micro Devices, Inc. [AMD/ATI] Navi 10 XL Upstream Port of PCI Express Switch [1002:1478] (rev c7)
+IOMMU Group 25:
+ 09:00.0 PCI bridge [0604]: Advanced Micro Devices, Inc. [AMD/ATI] Navi 10 XL Downstream Port of PCI Express Switch [1002:1479]
+IOMMU Group 26:
+ 0a:00.0 VGA compatible controller [0300]: Advanced Micro Devices, Inc. [AMD/ATI] Navi 23 [Radeon RX 6600/6600 XT/6600M] [1002:73ff] (rev c7)
+IOMMU Group 27:
+ 0a:00.1 Audio device [0403]: Advanced Micro Devices, Inc. [AMD/ATI] Navi 21/23 HDMI/DP Audio Controller [1002:ab28]
+IOMMU Group 28:
+ 0b:00.0 Non-Essential Instrumentation [1300]: Advanced Micro Devices, Inc. [AMD] Starship/Matisse PCIe Dummy Function [1022:148a]
+IOMMU Group 29:
+ 0c:00.0 Non-Essential Instrumentation [1300]: Advanced Micro Devices, Inc. [AMD] Starship/Matisse Reserved SPP [1022:1485]
+```
+
+If everything seems fine, if you think that you can pass your USB controllers, and Graphics card + it's audio without issues, you can move on.
+
+## Adding GPU + Audio
+
+Let's go ahead and add the GPU and its Audio to our Virtual Machine.
+
+
+ 
+
+
+
+ 
+
+
+## Correcting GPU Multifunction + Audio Bus
+
+Here's what a lot of people don't check. This will be required here as on macOS if you want your HDMI/DP Audio to work, this must be configured correctly. Windows doesn't care so it's not an issue.
+
+Essentially, your GPU and Audio must be on the same ``Bus`` in the Virtual Machine, but your Audio must be a ``Function`` of the Virtual Machines GPU. Thus creating a multifunction GPU in the VM which has an accompanying Audio device. This displays the GPU as a single unit. Allowing for HDMI/DP Audio in macOS.
+
+
+Go Ahead and select your GPU from the left-hand side. Note the Bus assigned.
+
+
+ 
+
+
+Go Ahead and select your Audio from the left-hand side. Note the Bus assigned does not line up with that which was assigned to the GPU. We will now correct it to the same value. You must also switch the ``0x0`` to ``0x1`` to assign the Audio as a ``Function`` of the GPU device.
+
+
+ 
+
+
+The corrected Audio device:
+
+
+ 
+
+
+Now you can see the GPU is a multifunction device.
+
+
+ 
+
+
+## Adding USB Controllers
+
+Go ahead and add your USB Controllers as you'll need to use your Keyboard and Mouse now.
+
+
+ 
+
+
+
+ 
+
+
+## Adding NVME (Optional)
+
+If you have two NVMEs in your system, and you'd like to dedicate one completely to the installation of macOS for maximum performance, you can add your NVME drive now. It still needs to be supported by macOS, or at least not reported to be problematic with macOS. I won't be adding it, but here it is for the example.
+
+
+ 
+
+
+## Example VM ready to start
+
+If you've gone ahead and verified everything, your IOMMU groups, and your multifunction GPU, you are now ready! Here's an example of what a completed GPU Passthrough Virt-Manager will look like.
+
+
+ 
+
+
You can now proceed to the Finish! page.
\ No newline at end of file