From 304d459ddb8b40ebc032ed6bc76031f2fae9c11c Mon Sep 17 00:00:00 2001 From: Phil Clifford Date: Tue, 14 May 2024 13:06:31 +0100 Subject: [PATCH] docs: include documentation updates from wiki to man pages --- build-docs | 2 +- docs/quickemu.1 | 19 +++++++++---------- docs/quickemu.1.md | 18 +++++++++--------- docs/quickemu_conf.1 | 39 ++++++++++++++++++++++++++++++++++++++- docs/quickemu_conf.1.md | 25 +++++++++++++++++++++++-- docs/quickget.1 | 19 +++++++++---------- docs/quickget.1.md | 18 +++++++++--------- 7 files changed, 98 insertions(+), 42 deletions(-) diff --git a/build-docs b/build-docs index b565cef..ad5e626 160000 --- a/build-docs +++ b/build-docs @@ -1 +1 @@ -Subproject commit b565cefbfc9a94cd699da6c5fa9c59c1c1646dbb +Subproject commit ad5e62630e999fa03cc8289bba2351f7fd758703 diff --git a/docs/quickemu.1 b/docs/quickemu.1 index c960bd6..72cebdf 100644 --- a/docs/quickemu.1 +++ b/docs/quickemu.1 @@ -818,8 +818,8 @@ check the Discussions creates a virtual machine configuration. .IP .EX -quickget macos catalina -quickemu \-\-vm macos\-catalina.conf +quickget macos big\-sur +quickemu \-\-vm macos\-big\-sur.conf .EE .PP macOS \f[CR]mojave\f[R], \f[CR]catalina\f[R], \f[CR]big\-sur\f[R], @@ -920,15 +920,15 @@ The default macOS configuration looks like this: .IP .EX guest_os=\[dq]macos\[dq] -img=\[dq]macos\-catalina/RecoveryImage.img\[dq] -disk_img=\[dq]macos\-catalina/disk.qcow2\[dq] -macos_release=\[dq]catalina\[dq] +img=\[dq]macos\- big\-sur/RecoveryImage.img\[dq] +disk_img=\[dq]macos\- big\-sur/disk.qcow2\[dq] +macos_release=\[dq] big\-sur\[dq] .EE .IP \[bu] 2 \f[CR]guest_os=\[dq]macos\[dq]\f[R] instructs Quickemu to optimise for macOS. .IP \[bu] 2 -\f[CR]macos_release=\[dq]catalina\[dq]\f[R] instructs Quickemu to +\f[CR]macos_release=\[dq] big\-sur\[dq]\f[R] instructs Quickemu to optimise for a particular macOS release. .RS 2 .IP \[bu] 2 @@ -944,11 +944,9 @@ There are some considerations when running macOS via Quickemu. Supported macOS releases: .RS 2 .IP \[bu] 2 -High Sierra -.IP \[bu] 2 Mojave .IP \[bu] 2 -Catalina \f[B](Recommended)\f[R] +Catalina .IP \[bu] 2 Big Sur .IP \[bu] 2 @@ -1001,7 +999,8 @@ UHCI (USB 2.0) on macOS Catalina and earlier. XHCI (USB 3.0) on macOS Big Sur and newer. .RE .IP \[bu] 2 -Display resolution can only be changed via macOS System Preferences. +Display resolution can be changed via \f[CR]quickemu\f[R] using +\f[CR]\-\-width\f[R] and \f[CR]\-\-height\f[R] command line arguments. .IP \[bu] 2 \f[B]Full Duplex audio requires \c .UR https://github.com/chris1111/VoodooHDA-OC diff --git a/docs/quickemu.1.md b/docs/quickemu.1.md index b344d1c..dde1146 100644 --- a/docs/quickemu.1.md +++ b/docs/quickemu.1.md @@ -552,8 +552,8 @@ for solutions or ask for help there** 🛟 virtual machine configuration. ``` shell -quickget macos catalina -quickemu --vm macos-catalina.conf +quickget macos big-sur +quickemu --vm macos-big-sur.conf ``` macOS `mojave`, `catalina`, `big-sur`, `monterey`, `ventura` and @@ -625,13 +625,13 @@ The default macOS configuration looks like this: ``` shell guest_os="macos" -img="macos-catalina/RecoveryImage.img" -disk_img="macos-catalina/disk.qcow2" -macos_release="catalina" +img="macos- big-sur/RecoveryImage.img" +disk_img="macos- big-sur/disk.qcow2" +macos_release=" big-sur" ``` - `guest_os="macos"` instructs Quickemu to optimise for macOS. -- `macos_release="catalina"` instructs Quickemu to optimise for a +- `macos_release=" big-sur"` instructs Quickemu to optimise for a particular macOS release. - For example VirtIO Network and Memory Ballooning are available in Big Sur and newer, but not previous releases. @@ -643,9 +643,8 @@ macos_release="catalina" There are some considerations when running macOS via Quickemu. - Supported macOS releases: - - High Sierra - Mojave - - Catalina **(Recommended)** + - Catalina - Big Sur - Monterey - Ventura @@ -667,7 +666,8 @@ There are some considerations when running macOS via Quickemu. - USB host and SPICE pass-through is: - UHCI (USB 2.0) on macOS Catalina and earlier. - XHCI (USB 3.0) on macOS Big Sur and newer. -- Display resolution can only be changed via macOS System Preferences. +- Display resolution can be changed via `quickemu` using `--width` and + `--height` command line arguments. - **Full Duplex audio requires [VoodooHDA OC](https://github.com/chris1111/VoodooHDA-OC) or pass-through a USB audio-device to the macOS guest VM**. diff --git a/docs/quickemu_conf.1 b/docs/quickemu_conf.1 index ac3e7db..f9e89a2 100644 --- a/docs/quickemu_conf.1 +++ b/docs/quickemu_conf.1 @@ -228,14 +228,51 @@ So you can generate your own MAC addresses with: .SS USB redirection Quickemu supports USB redirection via SPICE pass\-through and host pass\-through. +Quickemu supports USB redirection via SPICE pass\-through and host +pass\-through. +.PP +\f[B]NOTE!\f[R] When a USB device is redirected from the host, it will +not be usable by host operating system until the guest redirection is +stopped. +Therefore, do not redirect the input devices, such as the keyboard and +mouse, as it will be difficult (or impossible) to revert the situation. .SS SPICE redirection (recommended) Using SPICE for USB pass\-through is easiest as it doesn\[aq]t require any elevated permission: +.PP +Both \f[CR]spicy\f[R] from \c +.UR https://www.spice-space.org/spice-gtk.html +spice\-gtk +.UE \c +\ (\f[I]Input \-> Select USB Devices for redirection\f[R]) and +\f[CR]remote\-viewer\f[R] from \c +.UR https://gitlab.com/virt-viewer/virt-viewer +virt\-viewer +.UE \c +\ (\f[I]File \-> USB device selection\f[R]) support this feature. .IP \[bu] 2 Start Quickemu with \f[CR]\-\-display spice\f[R] and then .IP \[bu] 2 -select \f[CR]Input\f[R] \-> \f[CR]Select USB Device for redirection\f[R] +Select \f[CR]Input\f[R] \-> \f[CR]Select USB Device for redirection\f[R] from the menu to choose which device(s) you want to attach to the guest. +.IP \[bu] 2 +**\f[CR]spicy\f[R] (default) +.RS 2 +.IP \[bu] 2 +**Select \f[CR]Input\f[R] \-> +\f[CR]Select USB Device for redirection\f[R] from the menu to choose +which device(s) you want to attach to the guest. +.RE +.IP \[bu] 2 +**\f[CR]remote\-viewer\f[R] +.RS 2 +.IP \[bu] 2 +**Select \f[CR]File\f[R] \-> \f[CR]USB device selection\f[R] from the +menu to choose which device(s) you want to attach to the guest. +.RE +.PP +To ensure that this functionality works as expected, make sure that you +have installed the necessary SPICE Guest Tools on the virtual machine. .SS Enabling SPICE redirection on NixOS On NixOS, if you encounter this error: .IP diff --git a/docs/quickemu_conf.1.md b/docs/quickemu_conf.1.md index ca8b730..27743ed 100644 --- a/docs/quickemu_conf.1.md +++ b/docs/quickemu_conf.1.md @@ -241,16 +241,37 @@ So you can generate your own MAC addresses with: ### USB redirection Quickemu supports USB redirection via SPICE pass-through and host -pass-through. +pass-through. Quickemu supports USB redirection via SPICE pass-through +and host pass-through. + +**NOTE!** When a USB device is redirected from the host, it will not be +usable by host operating system until the guest redirection is stopped. +Therefore, do not redirect the input devices, such as the keyboard and +mouse, as it will be difficult (or impossible) to revert the situation. #### SPICE redirection (recommended) Using SPICE for USB pass-through is easiest as it doesn't require any elevated permission: +Both `spicy` from +[spice-gtk](https://www.spice-space.org/spice-gtk.html) (*Input -\> +Select USB Devices for redirection*) and `remote-viewer` from +[virt-viewer](https://gitlab.com/virt-viewer/virt-viewer) (*File -\> USB +device selection*) support this feature. + - Start Quickemu with `--display spice` and then -- select `Input` -\> `Select USB Device for redirection` from the menu +- Select `Input` -\> `Select USB Device for redirection` from the menu to choose which device(s) you want to attach to the guest. +- \*\*`spicy` (default) + - \*\*Select `Input` -\> `Select USB Device for redirection` from the + menu to choose which device(s) you want to attach to the guest. +- \*\*`remote-viewer` + - \*\*Select `File` -\> `USB device selection` from the menu to choose + which device(s) you want to attach to the guest. + +To ensure that this functionality works as expected, make sure that you +have installed the necessary SPICE Guest Tools on the virtual machine. ##### Enabling SPICE redirection on NixOS diff --git a/docs/quickget.1 b/docs/quickget.1 index e3ef669..b9db2e9 100644 --- a/docs/quickget.1 +++ b/docs/quickget.1 @@ -384,8 +384,8 @@ check the Discussions creates a virtual machine configuration. .IP .EX -quickget macos catalina -quickemu \-\-vm macos\-catalina.conf +quickget macos big\-sur +quickemu \-\-vm macos\-big\-sur.conf .EE .PP macOS \f[CR]mojave\f[R], \f[CR]catalina\f[R], \f[CR]big\-sur\f[R], @@ -486,15 +486,15 @@ The default macOS configuration looks like this: .IP .EX guest_os=\[dq]macos\[dq] -img=\[dq]macos\-catalina/RecoveryImage.img\[dq] -disk_img=\[dq]macos\-catalina/disk.qcow2\[dq] -macos_release=\[dq]catalina\[dq] +img=\[dq]macos\- big\-sur/RecoveryImage.img\[dq] +disk_img=\[dq]macos\- big\-sur/disk.qcow2\[dq] +macos_release=\[dq] big\-sur\[dq] .EE .IP \[bu] 2 \f[CR]guest_os=\[dq]macos\[dq]\f[R] instructs Quickemu to optimise for macOS. .IP \[bu] 2 -\f[CR]macos_release=\[dq]catalina\[dq]\f[R] instructs Quickemu to +\f[CR]macos_release=\[dq] big\-sur\[dq]\f[R] instructs Quickemu to optimise for a particular macOS release. .RS 2 .IP \[bu] 2 @@ -510,11 +510,9 @@ There are some considerations when running macOS via Quickemu. Supported macOS releases: .RS 2 .IP \[bu] 2 -High Sierra -.IP \[bu] 2 Mojave .IP \[bu] 2 -Catalina \f[B](Recommended)\f[R] +Catalina .IP \[bu] 2 Big Sur .IP \[bu] 2 @@ -567,7 +565,8 @@ UHCI (USB 2.0) on macOS Catalina and earlier. XHCI (USB 3.0) on macOS Big Sur and newer. .RE .IP \[bu] 2 -Display resolution can only be changed via macOS System Preferences. +Display resolution can be changed via \f[CR]quickemu\f[R] using +\f[CR]\-\-width\f[R] and \f[CR]\-\-height\f[R] command line arguments. .IP \[bu] 2 \f[B]Full Duplex audio requires \c .UR https://github.com/chris1111/VoodooHDA-OC diff --git a/docs/quickget.1.md b/docs/quickget.1.md index bfa17e5..5b9a621 100644 --- a/docs/quickget.1.md +++ b/docs/quickget.1.md @@ -286,8 +286,8 @@ for solutions or ask for help there** 🛟 virtual machine configuration. ``` shell -quickget macos catalina -quickemu --vm macos-catalina.conf +quickget macos big-sur +quickemu --vm macos-big-sur.conf ``` macOS `mojave`, `catalina`, `big-sur`, `monterey`, `ventura` and @@ -359,13 +359,13 @@ The default macOS configuration looks like this: ``` shell guest_os="macos" -img="macos-catalina/RecoveryImage.img" -disk_img="macos-catalina/disk.qcow2" -macos_release="catalina" +img="macos- big-sur/RecoveryImage.img" +disk_img="macos- big-sur/disk.qcow2" +macos_release=" big-sur" ``` - `guest_os="macos"` instructs Quickemu to optimise for macOS. -- `macos_release="catalina"` instructs Quickemu to optimise for a +- `macos_release=" big-sur"` instructs Quickemu to optimise for a particular macOS release. - For example VirtIO Network and Memory Ballooning are available in Big Sur and newer, but not previous releases. @@ -377,9 +377,8 @@ macos_release="catalina" There are some considerations when running macOS via Quickemu. - Supported macOS releases: - - High Sierra - Mojave - - Catalina **(Recommended)** + - Catalina - Big Sur - Monterey - Ventura @@ -401,7 +400,8 @@ There are some considerations when running macOS via Quickemu. - USB host and SPICE pass-through is: - UHCI (USB 2.0) on macOS Catalina and earlier. - XHCI (USB 3.0) on macOS Big Sur and newer. -- Display resolution can only be changed via macOS System Preferences. +- Display resolution can be changed via `quickemu` using `--width` and + `--height` command line arguments. - **Full Duplex audio requires [VoodooHDA OC](https://github.com/chris1111/VoodooHDA-OC) or pass-through a USB audio-device to the macOS guest VM**.