Add Hardware Troubleshooting

doc.md

@@ -111,7 +111,6 @@ Core documentation for Qubes users.
  * [Making Any File Persistent Using `bind-dirs`](/doc/bind-dirs/)
  * [GUI Configuration](/doc/gui-configuration/)
  * [Resizing Disk Images](/doc/resize-disk-image/)
- * [Troubleshooting Newer Hardware](/doc/newer-hardware-troubleshooting/)
  * [Mounting and Decrypting Qubes Partitions from Outside Qubes](/doc/mount-from-other-os/)
  * [KDE](/doc/kde/)
  * [i3 Window Manager](/doc/i3/)
@@ -131,6 +130,7 @@ Core documentation for Qubes users.
  * [GUI Troubleshooting](/doc/gui-troubleshooting/)
  * [Media Troubleshooting](/doc/media-troubleshooting/)
  * [Firewall Troubleshooting](/doc/firewall/#firewall-troubleshooting)
+ * [Hardware Troubleshooting](/doc/hardware-troubleshooting/)
 
 ### Reference Pages
 

introduction/faq.md

@@ -454,23 +454,7 @@ For details, see the qubes-users mailing list threads [here](https://groups.goog
 
 ### My keyboard layout settings are not behaving correctly. What should I do?
 
-The best approach is to choose the right keyboard layout during the installation process.
+See [Hardware Troubleshooting](/doc/hardware-troubleshooting/#keyboard-layout-settings-not-behaving-correctly).
-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 issue][layout_issue].
 
 ### My dom0 and/or TemplateVM update stalls when attempting to update via the GUI tool. What should I do?
 
@@ -784,8 +768,6 @@ There is also the unofficial [ansible-qubes toolkit][ansible].
 [intro1]: https://en.wikibooks.org/wiki/Fedora_And_Red_Hat_System_Administration/Shell_Basics
 [intro2]: https://en.wikibooks.org/wiki/A_Quick_Introduction_to_Unix
 [intro3]: https://en.wikibooks.org/wiki/Bash_Shell_Scripting
-[layout_discussion]: https://groups.google.com/d/topic/qubes-devel/d8ZQ_62asKI/discussion
-[layout_issue]: https://github.com/QubesOS/qubes-issues/issues/1396
 [LUKS]: https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup
 [Markdown]: /doc/doc-guidelines/#markdown-conventions
 [network]: /doc/networking/

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

@@ -79,4 +79,13 @@ In this case, you may want to consider replacing it with a network card of a dif
 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.
+
+[hardware-reqs]: /doc/installation-guide/#hardware-requirements