Docs: Ghaf as library, Lenovo X1 troubleshooting

Signed-off-by: Jenni Nikolaenko <[email protected]>

docs/src/appendices/glossary.md

@@ -159,6 +159,10 @@ Source: <https://www.qemu.org/docs/master/about/index.html>
 _The Server Base System Architecture specifies a hardware system architecture, based on Arm 64-bit architecture, that server system software, for example operating systems, hypervisors, and firmware can rely on._  
 Source: [Arm® Server Base System Architecture 7.1 Platform Design Document](https://developer.arm.com/documentation/den0029/latest)
 
+### SKU
+
+_A stock keeping unit, is a unique code used by sellers to identify and track products._
+
 ### SoC
 
 _A system on chip, a microchip that contains the necessary electronic circuits for a fully functional system on a single integrated circuit (IC)._

docs/src/ref_impl/example_project.md

@@ -38,3 +38,25 @@ Creating the structure that includes all necessary data for the device passthrou
 ```
 
 The fields of that structure are self-explanatory. Use the `lspci -nnk` command to get this data from any Linux OS running on the device.
+
+
+## Troubleshooting for Lenovo X1 Laptop
+
+If after booting you see a black screen, try the following to detect the issue:
+
+1. Add a Wi-Fi network name and password to the *lenovo-x1-carbon.nix* file instead of `#networks."ssid".psk = "psk"`.
+2. Build and run the image. For more information, see [Running Ghaf Image for Lenovo X1](./build_and_run.md#running-ghaf-image-for-lenovo-x1).
+3. Identify an IP address by a MAC address with the `arp` command. If a MAC address is unknown, you can boot into the NixOS image or any other OS to find it, or try the latest addresses that `arp` returns.
+4. Connect using SSH (login/password ghaf/ghaf). Then connect from netvm to the host using `ssh 192.168.101.2` (login/password ghaf/ghaf).
+5. Check running VMs with `microvm -l`.
+6. Check a GUIVM log using `journalctl -u microvm@guivm`.
+7. If GUIVM does not start, you can try to start it manually with `/var/lib/microvms/guivm/current/bin/microvm-run`.
+
+In case when GUIVM did not start with the error message that the device /dev/mouse or /dev/touchpad was not found, it means that the model of the touchpad in the laptop is different since it was bought in another country and has a different SKU (stock keeping unit). To add support for a new touchpad, do the following:
+
+1. On the ghaf host, check the devices in `/dev/input/by-path` that contain “-event-” in the name. Use the command like `udevadm info -q all -a /dev/input/by-path/pci-0000:00:15.0-platform-i2c_designware.0-event-mouse | grep name` for the name of each of these devices.
+
+    > By name you can understand which devices belong to the touchpad. For example, on laptops in Finland they look like “SYNA8016:00 06CB:CEB3 Mouse” and “SYNA8016:00 06CB:CEB3 Touchpad”, and in the UAE they are “ELAN067C:00 04F3:31F9 Mouse” and “ELAN067C:00 04F3:31F9 Touchpad.”
+
+2. If there are no such devices in `/dev/input/by-path`, then you can check the devices /dev/input/event* with a similar command.
+3. When the necessary device names are found, add them to `services.udev.extraRules` in the *lenovo-x1-carbon.nix* file, rebuild the image and test the changes.