Why Cross-Compilation Matters for Linux Kernel Modules

When you build a kernel module for your own x86 laptop, you compile it right there on the machine — the same machine that runs it. This is called native compilation. Simple and straightforward.

But in embedded Linux development, your target device (a small ARM board, for example) has very little CPU power, limited RAM, and sometimes no compiler installed at all. Building the kernel module on the target itself would take forever — or simply not be possible.

The solution is cross-compilation: you compile the kernel module on your powerful x86 development machine (called the host), but you produce an output binary that runs on the ARM device (called the target). A special cross-compiler tool understands both worlds and produces the correct ARM binary from your x86 host.

Setting Up Your Cross-Compilation Toolchain on Linux 6.x

On a modern Ubuntu host, installing a cross-compiler for ARM is straightforward. For 32-bit ARM targets (like many older Raspberry Pi, BeagleBone, or custom boards):

sudo apt update
sudo apt install gcc-arm-linux-gnueabihf binutils-arm-linux-gnueabihf

For 64-bit ARM (ARM64 / AArch64) targets, which is the standard for modern SBCs and SoCs running Linux 6.x:

sudo apt install gcc-aarch64-linux-gnu binutils-aarch64-linux-gnu

Verify your cross-compiler is installed correctly:

# For ARM32
arm-linux-gnueabihf-gcc --version

# For ARM64
aarch64-linux-gnu-gcc --version

You also need the kernel source or headers for the exact kernel version running on your target. This is critical. The host must compile the module against the same kernel version that runs on the device — otherwise the kernel will refuse to load the module.

For a custom embedded board, you typically clone your board vendor’s Linux 6.x kernel tree and build it first. For Raspberry Pi 5 (which runs Linux 6.x), you use the official Raspberry Pi kernel source.

# Example: clone the Raspberry Pi Linux 6.x kernel tree
git clone --depth=1 https://github.com/raspberrypi/linux --branch rpi-6.6.y rpi-linux

# Set up the default ARM64 configuration for RPi 5
cd rpi-linux
ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- make bcm2711_defconfig

Writing a Cross-Compilation Makefile for Your Kernel Module

The kernel build system (kbuild) is what actually compiles your module. Your job is to write a Makefile that tells kbuild two things: what architecture to target, and which cross-compiler to use. Here is a proper Makefile for a module targeting ARM64 running Linux 6.x:

# Makefile for cross-compiling an LKM for ARM64 (Linux 6.x)

# Name of your module (change this to your module name)
obj-m += my_module.o

# Path to the kernel source tree built for your ARM target
KDIR ?= /path/to/your/rpi-linux

# Target architecture
ARCH := arm64

# Cross-compiler prefix
CROSS_COMPILE := aarch64-linux-gnu-

all:
	$(MAKE) -C $(KDIR) M=$(PWD) ARCH=$(ARCH) CROSS_COMPILE=$(CROSS_COMPILE) modules

clean:
	$(MAKE) -C $(KDIR) M=$(PWD) ARCH=$(ARCH) CROSS_COMPILE=$(CROSS_COMPILE) clean

For a 32-bit ARM target, change the two lines to:

ARCH := arm
CROSS_COMPILE := arm-linux-gnueabihf-

Building and Transferring the Cross-Compiled Kernel Module

Once your Makefile is ready, run make from your module directory on the host:

cd my_module/
make

If everything is set up correctly, you will see kbuild output and end up with a my_module.ko file. This is an ARM ELF binary — you cannot run it on your x86 host directly, but it is exactly what your ARM target needs.

Check what the module was compiled for using file:

file my_module.ko
# Expected output for ARM64:
# my_module.ko: ELF 64-bit LSB relocatable, ARM aarch64, version 1 (SYSV), not stripped

Now transfer the module to your ARM device. The usual tool is scp:

# Replace 192.168.1.100 with your device's IP address
scp my_module.ko user@192.168.1.100:/home/user/

On the ARM device, insert and test the module:

sudo insmod ./my_module.ko
dmesg | tail -20
sudo rmmod my_module
dmesg | tail -5

Understanding vermagic and Kernel Version Matching in Linux 6.x

The vermagic string is one of the most important concepts to understand when cross-compiling kernel modules. Every .ko file embeds a vermagic string at compile time. The kernel checks this on every insmod call.

You can inspect the vermagic of your compiled module with modinfo:

modinfo ./my_module.ko

You will see output like this on a Linux 6.x ARM64 system:

filename:       /home/user/my_module.ko
license:        GPL
description:    My first cross-compiled LKM
author:         Your Name
srcversion:     A1B2C3D4E5F6
depends:
name:           my_module
vermagic:       6.6.20-v8+ SMP preempt mod_unload aarch64

The vermagic line tells you everything: kernel version (6.6.20-v8+), SMP support, preempt config, and architecture (aarch64). This must match the running kernel on the device exactly.

Common Cross-Compilation Errors and How to Fix Them

Best Practices for Cross-Compiling Linux Kernel Modules

• Always match kernel versions exactly. Use the same kernel tree to build both the kernel image and your modules. Even a kernel config difference can cause a vermagic mismatch.
• Use environment variables in your Makefile. Make ARCH and CROSS_COMPILE overridable from the command line so the same Makefile works for both native and cross builds.
• Keep a separate build directory. Do not mix your host-native module builds with cross-compiled builds. Use separate output directories.
• Test with modinfo before deploying. Always run modinfo on the .ko before transferring to the device to confirm the vermagic and architecture.
• Use sparse and checkpatch.pl. Run kernel code static analysis tools from the kernel source tree before building. Catch bugs before they get to the device.
• In Linux 6.x, prefer GPL-licensed modules. Many kernel symbols are only exported to GPL-licensed modules. Declare MODULE_LICENSE("GPL") in your module to avoid symbol access errors.

Frequently Asked Questions