Troubleshooting Index

This index groups common issues found while building, deploying, and testing the Embedded Linux labs.

Build and Toolchain Issues

Use this section when kernel modules fail to build, cross compilation behaves unexpectedly, or the build directory does not match the target kernel.

• Build Issues
• Cross Compilation
• Kernel Module Build Workflow
• Kernel Version and vermagic

Kernel and Driver Runtime Issues

Use this section when modules fail to load, device nodes are missing, interrupts do not fire, or the kernel driver path does not behave as expected.

• Kernel Issues
• Character Device Basics
• GPIO and IRQ Driver
• Wait Queue and poll Support

Device Tree Issues

Use this section when overlays fail to compile, drivers do not probe, or GPIO mappings cannot be found.

• Device Tree Issues
• Device Tree Overlay Build Workflow
• Device Tree, Driver, and /dev Node Mapping

I2C, SPI, and UART Issues

Use this section for peripheral bus debugging.

• I2C, SPI, and UART Issues
• GPIO and gpiod
• TTY and UART
• hwmon
• IIO

MkDocs and Documentation Issues

Use this section when the documentation site has navigation, YAML, local preview, or deployment issues.

• MkDocs Issues
• Project Maintenance Guide
• Cloudflare Pages Deployment

Quick Debug Checklist

Build fails?
  -> Check KDIR, ARCH, CROSS_COMPILE, and kernel headers.

Module does not load?
  -> Check dmesg, modinfo vermagic, and running kernel version.

Driver probe does not run?
  -> Check Device Tree compatible string and overlay loading.

GPIO or IRQ does not work?
  -> Check pin mapping, interrupt parent, trigger type, and /proc/interrupts.

MkDocs build warns?
  -> Check mkdocs.yml nav paths and YAML syntax.