Improve troubleshooting

docs/TROUBLESHOOTING.md

@@ -0,0 +1,62 @@
+# Troubleshooting
+
+This document lists known error codes, their meaning, and how to resolve them.
+
+Error codes are stable identifiers intended to help diagnose problems in
+different environments such as bare metal, systemd services, and containers.
+
+---
+
+## How to use this document
+
+1. Locate the error code printed by the application
+2. Search for it in this document
+3. Follow the diagnostic steps
+4. Apply the suggested resolution
+
+Error messages may change over time; error codes do not.
+
+---
+
+## Error Code Index
+
+| Code | Area | Summary |
+|------|------|--------|
+| VUI-UDEV-001 | udev | udev control socket not reachable |
+
+---
+
+## Error Codes
+
+---
+
+### VUI-UDEV-001 — /run/udev/control/ not available. Keyboard or mouse might be unusable.
+
+**Symptoms**
+
+* No keyboard or mouse usable
+
+**Cause**
+This might be a problem when an application that uses libinput has already been started, because libinput only checks the file existance at startup. 
+
+**How to diagnose**
+
+Check in container for file existence:
+```sh
+ls -l /run/udev/control
+```
+
+**Resolution**
+
+* Create /run/udev/data directory and /run/udev/control file during startup. See [USAGE.md](USAGE.md).
+
+---
+
+## Reporting Issues
+
+When reporting an issue, please include:
+
+* The error code(s)
+* Full command-line invocation
+* Execution environment (host, container, systemd)
+* Relevant debug logs (see [DEBUG.md](DEBUG.md))

vuinputd/src/actions/runtime_data.rs

@@ -6,9 +6,11 @@ use std::fs::{self, File};
 use std::io::{self, Write};
 use std::path::Path;
 
+use log::{info, warn};
+
 /// Ensure required udev directories and files exist
 pub fn ensure_udev_structure() -> io::Result<()> {
-    // TODO: this _must_ exist, before a service using libinput is run. The time of device creation might be too late
+    // Note that this structure _must_ exist, before a service using libinput is run. The time of device creation might be too late.
 
     let data_dir = Path::new("/run/udev/data");
     let control_file = Path::new("/run/udev/control");
@@ -20,6 +22,11 @@ pub fn ensure_udev_structure() -> io::Result<()> {
 
     // Ensure /run/udev/control exists, create empty if not
     if !control_file.exists() {
+        warn!(
+            "VUI-UDEV-001 — /run/udev/control/ not available. Keyboard or mouse might be unusable."
+        );
+        warn!("Visit https://github.com/joleuger/vuinputd/blob/main/docs/TROUBLESHOOTING.md for details");
+        info!("Creating file /run/udev/control anyway for subsequent runs.");
         File::create(control_file)?;
     }