Merge branch 'hardware-troubleshooting' of https://github.com/PROTechThor/qubes-doc into PROTechThor-hardware-troubleshooting

user/advanced-configuration/newer-hardware-troubleshooting.md

@@ -1,29 +0,0 @@
----
-layout: doc
-title: Troubleshooting newer hardware
-permalink: /doc/newer-hardware-troubleshooting/
----
-
-Troubleshooting newer hardware
-==============================
-
-By default, the kernel that is installed in dom0 comes from the `kernel` package, which is an older Linux LTS kernel.
-For most cases this works fine since the Linux kernel developers backport fixes to this kernel, but for some newer hardware, you may run into issues.
-For example, the audio might not work if the sound card is too new for the LTS kernel.
-To fix this, you can try the `kernel-latest` package -- though be aware that it's less tested!
-(See [here][dom0-kernel-upgrade] for more information about upgrading kernels in dom0.)
-In dom0:
-
-~~~
-sudo qubes-dom0-update kernel-latest
-~~~
-
-Reboot when it's done installing.
-You can double-check that the boot used the newer kernel with `uname -r`, which prints the version of the currently-running kernel.
-Compare this with the output of `rpm -q kernel`.
-If the start of `uname -r` matches one of the versions printed by `rpm`, then you're still using the Linux LTS kernel, and you'll probably need to manually fix your boot settings.
-If `uname -r` reports a higher version number, then you've successfully booted with the kernel shipped by `kernel-latest`.
-
-
-[dom0-kernel-upgrade]: /doc/software-update-dom0/#kernel-upgrade
-

user/troubleshooting/hardware-troubleshooting.md

@@ -0,0 +1,59 @@
+---
+layout: doc
+title: Hardware Troubleshooting
+permalink: /doc/hardware-troubleshooting/
+redirect_from:
+- /doc/newer-hardware-troubleshooting/
+---
+
+# Troubleshooting hardware-related issues
+
+## Audio doesn't work / Troubleshooting newer hardware
+
+By default, the kernel that is installed in dom0 comes from the `kernel` package, which is an older Linux LTS kernel.
+For most cases this works fine since the Linux kernel developers backport fixes to this kernel, but for some newer hardware, you may run into issues.
+For example, the audio might not work if the sound card is too new for the LTS kernel.
+To fix this, you can try the `kernel-latest` package -- though be aware that it's less tested!
+(See [here][dom0-kernel-upgrade] for more information about upgrading kernels in dom0).
+In dom0:
+
+~~~
+sudo qubes-dom0-update kernel-latest
+~~~
+
+Reboot when it's done installing.
+You can double-check that the boot used the newer kernel with `uname -r`, which prints the version of the currently-running kernel.
+Compare this with the output of `rpm -q kernel`.
+If the start of `uname -r` matches one of the versions printed by `rpm`, then you're still using the Linux LTS kernel, and you'll probably need to manually fix your boot settings.
+If `uname -r` reports a higher version number, then you've successfully booted with the kernel shipped by `kernel-latest`.
+
+## "Unsupported Hardware Detected" error
+
+See [Installation Troubleshooting](/doc/installation-troubleshooting/#unsupported-hardware-detected-error).
+
+## Keyboard layout settings not behaving correctly
+
+The best approach is to choose the right keyboard layout during the installation process.
+But if you want to change things afterwards, you can try this workaround.
+
+Assuming XFCE desktop: in `Q` → `System Tools` → `Keyboard` → `Layout`, leave the checkbox "`Use system defaults`" checked. Do not customize the keyboard layout here.
+
+Set the system-wide layout and options for `xorg` with the `localectl` command in `dom0`. You can use `localectl --help` as a starting point.
+
+Example: `localectl set-x11-keymap us dell ,qwerty compose:caps`.
+
+This generates the appropriate configuration in `/etc/X11/xorg.conf.d/00-keyboard.conf`.
+This file is auto-generated.
+Do not edit it by hand, unless you know what you are doing.
+
+Restarting `xorg` is required.
+The most straightforward way is to reboot the system.
+
+More information in [this discussion][layout_discussion] and [this GitHub issue][layout_issue].
+
+
+[dom0-kernel-upgrade]: /doc/software-update-dom0/#kernel-upgrade
+[hardware-reqs]: /doc/installation-guide/#hardware-requirements
+[layout_discussion]: https://groups.google.com/d/topic/qubes-devel/d8ZQ_62asKI/discussion
+[layout_issue]: https://github.com/QubesOS/qubes-issues/issues/1396
+

user/troubleshooting/installation-troubleshooting.md

@@ -77,6 +77,19 @@ If installing the available drivers does not help, disable the network card in t
 If this solves the issue, it confirms the PCI card is incompatible with Qubes. 
 In this case, you may want to consider replacing it with a network card of a different brand. 
 Broadcom cards are notoriously problematic with Qubes.
- 
 
 
+## "Unsupported Hardware Detected" error ##
+
+During Qubes installation, you may come across the error message which reads "Unsupported Hardware Detected. 
+Missing features: IOMMU/VT-d/AMD-Vi, Interrupt Remapping. Without these features, Qubes OS will not function normally". 
+
+This error message indicates that IOMMU-virtualization hasn’t been activated in the BIOS. 
+Return to the [hardware requirements][hardware-reqs] section to learn how to activate it. 
+If the setting is not configured correctly, it means that your hardware won’t be able to leverage some Qubes security features, such as a strict isolation of the networking and USB hardware.
+
+In Qubes 4.0, the default installation won't function properly without IOMMU, as default sys-net and sys-usb qubes require IOMMU. It is possible to configure them to reduce isolation and not use IOMMU by changing virtualization mode of these two VMs to "PV".
+
+In Qubes 4.1, IOMMU is strictly required, even when the virtualization mode of a VM is changed to "PV"; it is not possible to use Qubes on a system without IOMMU.
+
+[hardware-reqs]: /doc/installation-guide/#hardware-requirements