Posted on by patrick

Kernel Driver Compilation: Concepts and Troubleshooting

Overview

Kernel driver compilation is the process of creating loadable kernel modules (.ko files) that allow hardware to communicate with the Linux kernel. This involves several stages of compilation and linking.

Major Concepts

1. Source Code Compilation

  • Concept: Converting human-readable C source code (.c files) into machine code
  • Process: C compiler (gcc) compiles each .c file into an object file (.o)
  • Purpose: Create intermediate files containing compiled code that can be linked together
  • Example: rtw_cmd.c → rtw_cmd.o

2. Object Files (.o)

  • Concept: Intermediate compiled files containing machine code but not yet executable
  • Characteristics:
  • Contain compiled code from individual source files
  • Need to be linked together to create final executable
  • Cannot be loaded directly into kernel
  • Example: rtw_cmd.o, rtw_security.o, rtw_debug.o

3. Linking Process

  • Concept: Combining multiple object files into a single executable module
  • Process: Linker combines all .o files using linker scripts
  • Purpose: Create a cohesive module from individual compiled components
  • Requirements: Linker scripts (like module.lds) define how to organize the code

4. Kernel Modules (.ko)

  • Concept: Loadable kernel modules that can be inserted into running kernel
  • Characteristics:
  • Final product of compilation process
  • Can be loaded/unloaded without rebooting
  • Contains all necessary code and symbols
  • Example: 8812au.ko (final WiFi driver module)

5. Kernel Headers and Build System

  • Concept: Infrastructure needed to compile kernel modules
  • Components:
  • Kernel headers (function declarations, data structures)
  • Build scripts and Makefiles
  • Linker scripts (module.lds)
  • Module build tools (modprobe, depmod)

The Compilation Pipeline

text

Apply to AWUS036ACH_w…

Source Files (.c) → Object Files (.o) → Kernel Module (.ko)

     ↓                    ↓                    ↓

   Compile            Link with           Load into

   with gcc           module.lds          kernel

What Was Failing in Your Case

Stage 1: Source Compilation ✅

  • Status: Working correctly
  • Evidence: All .o files were being created successfully
  • Output: CC [M] /home/pi/8812au_src/core/rtw_cmd.o, etc.

Stage 2: Linking ❌

  • Status: Failing at final linking step
  • Root Cause: Missing module.lds linker script
  • Error: No rule to make target ‘8812au.ko’
  • Impact: Could not create final .ko file

Stage 3: Module Creation ❌

  • Status: Never reached due to linking failure
  • Expected: Creation of 8812au.ko file
  • Reality: Build process terminated before completion

The Missing Piece: module.lds

What is module.lds?

  • Purpose: Linker script that defines how to organize compiled code
  • Location: /lib/modules/$(uname -r)/build/scripts/module.lds
  • Function: Tells linker how to combine .o files into .ko file

Why it was missing:

  • Incomplete kernel source: rpi-source downloaded kernel source but missing build infrastructure
  • Missing build tools: The kernel source was missing essential linker scripts
  • Incomplete setup: Kernel headers symlink was pointing to incomplete source

The Fix:

AWUS036ACH_w…Run# Create the missing linker scriptcat > /lib/modules/$(uname -r)/build/scripts/module.lds << ‘EOF’SECTIONS{  . = ALIGN(4096);  .text : { (.text) }  .rodata : { (.rodata) }  .data: { (.data) }  .bss : { (.bss) }}EOF

Key Takeaways

  1. Compilation vs Linking: Two distinct phases – compilation creates .o files, linking creates .ko files
  2. Infrastructure Dependencies: Kernel module compilation requires complete build infrastructure
  3. Linker Scripts: Essential for final module creation, often overlooked in troubleshooting
  4. Debugging Approach: Check each stage separately – compilation, linking, and module creation
  5. Common Failure Points: Missing headers, incomplete kernel source, missing build tools

Diagnostic Questions for Future Issues

  • Compilation failing? → Check kernel headers, compiler, source code
  • Linking failing? → Check linker scripts, build infrastructure, kernel source completeness
  • Module loading failing? → Check module format, kernel compatibility, dependencies

This systematic approach helps isolate where in the pipeline the failure occurs and what infrastructure is missing.