Added Evdev documentation (#13)

Co-authored-by: = <=>

docs/_writeups/07-EvdevKBM/01-Prerequisites.md

@@ -1,11 +1,59 @@
 ---
 layout: default
-title: Prerequisites
-parent: KBM Via Evdev
+title: Getting our input devices
+parent: KB/M sharing with Evdev
 nav_order: 1
 ---
 
-# Step Name
-#### Placeholder caption
+# Prerequisites
+#### What is Evdev, and what does it do?
+**Evdev**, short for "**ev**ent **dev**ice", is a Linux input driver that supports almost all input devices, including keyboards, mice, game controllers, tablets, etc. It takes the raw input events from these devices and turns them into accessible files in the ``/dev/input/`` directory. These files can be then accessed to get input from such input devices. It is considered a type of **character device driver**, which turns raw data (in bytes) into files.
 
-Placeholder text
+**Evdev** is how Linux communicates with and gets the raw data from these input devices. In our use case, we will use **evdev** to passthrough these input devices into our virtual machine and configure a keyboard shortcut to allow sharing of our mouse and keyboard.
+<br><br>
+
+#### Finding our keyboard and mouse
+Make sure your keyboard and mouse are plugged in and detected in Linux.
+
+Let's check the input devices currently in use. Enter the following command into the terminal (on Linux):
+
+```bash
+ls /dev/input/by-id
+```
+
+Example output:
+
+```txt
+usb-30fa_USB_Optical_Mouse-event-mouse
+usb-30fa_USB_Optical_Mouse-mouse
+usb-EVGA_Z12_Gaming_Keyboard-event-if01
+usb-EVGA_Z12_Gaming_Keyboard-event-kbd
+usb-EVGA_Z12_Gaming_Keyboard-if01-event-mouse
+usb-EVGA_Z12_Gaming_Keyboard-if01-mouse
+usb-EVGA_Z12_Gaming_Keyboard-if02-event-kbd
+```
+
+Only devices that have ``event`` in their names can be passed through. In the example output, the only devices that could be passed through would be
+
+```txt
+usb-30fa_USB_Optical_Mouse-event-mouse
+usb-EVGA_Z12_Gaming_Keyboard-event-if01
+usb-EVGA_Z12_Gaming_Keyboard-event-kbd
+usb-EVGA_Z12_Gaming_Keyboard-if01-event-mouse
+usb-EVGA_Z12_Gaming_Keyboard-if02-event-kbd
+```
+
+Now, we need to figure out which devices should be passed through. For each file in the output, check the contents via ``cat``. For instance,
+
+```bash
+cat /dev/input/by-id/usb-30fa_USB_Optical_Mouse-event-mouse
+```
+
+Move your cursor or type something on your keyboard. If the terminal spits out garbled characters, that is the correct device. If not, try the other devices in the list.
+
+> [!NOTE]
+> Remember to Control-C out of the process after!
+
+Now that you have the two devices, note the paths of these input devices. These will be the devices that we will pass through to our virtual machine.
+
+## You can now continue to the next <a href="./02-EditingConfig">page</a>.

docs/_writeups/07-EvdevKBM/02-EditingConfig.md

@@ -0,0 +1,57 @@
+---
+layout: default
+title: Editing config files
+parent: KB/M sharing with Evdev
+nav_order: 2
+---
+
+# Editing Config Files
+
+Use your favorite text editor to make the following changes to:
+
+```bash
+/etc/libvirt/qemu.conf
+```
+
+``Security - uncomment the following line of code and change the value:``
+```bash
+security_default_confined = 0
+```
+
+``Add these lines to the bottom of the file:``
+```bash
+cgroup_device_acl = [
+    "/dev/null", "/dev/full", "/dev/zero",
+    "/dev/random", "/dev/urandom",
+    "/dev/ptmx", "/dev/kvm", "/dev/kqemu",
+    "/dev/rtc", "/dev/hpet", "/dev/vfio/vfio",
+    # Your devices go here
+]
+
+clear_emulator_capabilities = 0
+```
+
+**Inside ``cgroup_device_acl``**, add the paths to your keyboard and mouse.
+
+#### Sample configuration:
+
+```bash
+cgroup_device_acl = [
+	"/dev/null", "/dev/full", "/dev/zero",
+	"/dev/random", "/dev/urandom",
+	"/dev/ptmx", "/dev/kvm", "/dev/kqemu",
+	"/dev/rtc","/dev/hpet", "/dev/vfio/vfio",
+    # Your devices go here
+	"/dev/input/by-id/usb-30fa_USB_Optical_Mouse-event-mouse",
+	"/dev/input/by-id/usb-EVGA_Z12_Gaming_Keyboard-event-kbd",
+]
+
+clear_emulator_capabilities = 0
+```
+
+Save the file, then restart the libvirtd service.
+```bash
+systemctl restart libvirtd
+```
+
+## You can now continue to the next <a href="./03-AddingToXML">page</a>.

docs/_writeups/07-EvdevKBM/03-XML.md

@@ -0,0 +1,69 @@
+---
+layout: default
+title: XML Modifications
+parent: KB/M sharing with Evdev
+nav_order: 3
+---
+
+# XML Modifications
+
+> [!WARNING]
+> In order to use ``evdev``, we will need to **remove the USB controller from our machine**. Otherwise, the controller will capture the USB (and input) devices first, thus removing the files from ``/dev/input/by-id/``.
+>
+> If you really want to pass in USB devices, try passing in the USB devices directly via USB passthrough, or utilize a secondary USB controller for passthrough.
+
+First, let's remove the USB controller from the virtual machine.
+
+<p align="center">
+    <img src="../../assets/VManRemoveUSBController.png"/>
+</p>
+
+Now, we need to edit the XML of the virtual machine. Go to Overview > XML, and scroll down until you see the following lines:
+
+```xml
+<input type="mouse" bus="ps2"/>
+<input type="keyboard" bus="ps2"/>
+```
+
+Now, **before** the mouse and keyboard XML, copy and paste the following XML to add our mouse and keyboard (replacing the paths with the actual paths to the keyboard and mouse):
+
+```xml
+<input type="evdev">
+  <source dev="/dev/input/by-id/(mouse-path)">
+</input>
+<input type="evdev">
+  <source dev="/dev/input/by-id/(keyboard-path)" grab="all" grabToggle="ctrl-ctrl" repeat="on">
+</input>
+```
+
+> [!NOTE]
+> The ``grabToggle`` option will be the keyboard shortcut to switch the keyboard and mouse focus from host (Linux) and guest (macOS). This can be configured to the keyboard shortcut that you prefer. By default, it will be ``'ctrl-ctrl'``, but this option can be configured to the following options:
+> - ``'alt-alt'``
+> - ``'shift-shift'``
+> - ``'meta-meta'``
+> - ``'scrolllock'``
+> - ``'ctrl-scrolllock'``
+
+
+<p align="center">
+    <img src="../../assets/VManAddingEvdevDevices.png"/>
+</p>
+
+> [!NOTE]
+> Remember to **'Apply'** when you finish!
+
+You should then see two 'Input' devices in the sidebar!
+
+Sample configuration for the mouse (should be similar for keyboard as well):
+
+<p align="center">
+    <img src="../../assets/VManEvdevInputDetails.png"/>
+</p>
+
+<p align="center">
+    <img src="../../assets/VManEvdevInputXML.png"/>
+</p>
+
+**Do not boot into DarwinKVM yet! We still need to configure the driver/kext for KB/M!**
+
+## You can now continue to the next <a href="./04-AddingToKext">page</a>.

docs/_writeups/07-EvdevKBM/04-AddingToKext.md

@@ -0,0 +1,23 @@
+---
+layout: default
+title: Adding the required kexts
+parent: KB/M sharing with Evdev
+nav_order: 4
+---
+# Adding the Required Kexts
+
+Start by downloading the latest release version of ``VoodooPS2`` from <a href="https://github.com/acidanthera/VoodooPS2/releases/">here</a> (for macOS 10.12 Sierra and higher).
+
+> [!NOTE]
+> For **OSX 10.11** (El Capitan) and lower, you will instead need to download the original PS2 driver by **RehabMan** <a href="https://bitbucket.org/RehabMan/os-x-voodoo-ps2-controller/downloads/">here</a>. Note that these older drivers are built for x64 systems, but you can manually build the x32 versions in Xcode with the source code <a href="https://github.com/RehabMan/OS-X-Voodoo-PS2-Controller/">here</a>.
+
+Add the kext to the OC folder, and remember to ``OC Snapshot`` the ``config.plist`` when finished. The necessary kexts (``VoodooPS2Keyboard, VoodooPS2Mouse``) will be installed automatically for you.
+
+Now, boot up macOS, and enjoy switching your keyboard and mouse from macOS to Linux!
+
+> [!NOTE]
+>  Usually, the **Option (⌥)** and **Command (⌘)** keys on the keyboard maps to the **Alt** and the **Windows (⊞)** keys respectively. The original PS2 driver (by RehabMan) will swap these keymaps, however.
+> <br/> <br/>
+> You can change this behavior is to go to **Settings > Keyboard > Keyboard Shortcuts > Modifier Keys** (or something equivalent) in macOS, and swap the action keys for Option (⌥) and Command (⌘).
+
+#### Thanks for reading!

docs/_writeups/07-EvdevKBM/index.md

@@ -1,13 +1,12 @@
 ---
 layout: default
-title: KBM Via Evdev
+title: KB/M sharing with Evdev
 nav_order: 7
 has_children: true
 ---
 
 <p align="center">
-  <img width="650" height="200" src="../../../assets/HeaderEvdevKBM.png">
+  <img width="650" height="200" src="../../assets/HeaderEvdevKBM.png">
 </p>
 
-{: .warning }
-This section is under construction. It may have missing or incomplete information! Wait until this warning is no longer present, to follow the writeup.
+This guide will show you how to configure Evdev to allow the host (Linux) and the guest (OS X/macOS) to share a mouse and keyboard with a simple keyboard shortcut!