What is Cross-Compilation and Why Does it Matter for Linux Kernel Module Development?

In a typical software development scenario, you write code on your laptop or desktop and compile it on the same machine where it will run. The compiler produces code for the processor architecture of your own machine. This is called native compilation.

Cross-compilation is the opposite: you compile code on one machine (the host), but the resulting binary runs on a completely different machine with a different processor architecture (the target). The host is almost always a fast x86_64 desktop or laptop. The target is typically an embedded device with an ARM processor — something like a Raspberry Pi, a BeagleBone, an STM32MP1 evaluation board, or a custom industrial controller.

For embedded Linux device driver development, cross-compilation is not optional — it is the standard workflow. Embedded target devices are often not powerful enough to compile code themselves, or they may not even have a C compiler installed. More importantly, the kernel module you build must match the exact kernel version and configuration running on the target device. Getting this wrong causes the module to refuse to load with a version mismatch error.

Understanding the Two Key Environment Variables: ARCH and CROSS_COMPILE

The Linux kernel build system (called kbuild) uses two special environment variables to know that it is doing a cross-compilation rather than a native build. Understanding these two variables is the most important conceptual step in cross-compiling kernel modules.

ARCH — The Target Architecture

The ARCH variable tells kbuild which processor architecture the output code should target. This determines which architecture-specific header files and build rules are used. For ARM 32-bit targets, you set ARCH=arm. For ARM 64-bit targets (like Raspberry Pi 4, NVIDIA Jetson), you set ARCH=arm64. For RISC-V targets, it is ARCH=riscv.

If you do not set ARCH, kbuild defaults to the architecture of the host machine (x86_64 on a standard developer laptop). This is correct for native builds but wrong for cross-compilation.

CROSS_COMPILE — The Toolchain Prefix

The CROSS_COMPILE variable tells kbuild which compiler to use. It is a prefix — a string that gets prepended to tool names like gcc, ld, objcopy, etc. For example, if you set CROSS_COMPILE=arm-linux-gnueabihf-, then kbuild will call arm-linux-gnueabihf-gcc to compile C code, arm-linux-gnueabihf-ld to link, and so on.

The toolchain prefix follows a standardized naming convention that tells you exactly what it targets:

Common Cross-Toolchain Prefixes for Embedded Linux in 2025

How to Get a Cross-Compilation Toolchain

You have several options for obtaining a cross-compiler toolchain. The easiest approach on Ubuntu/Debian is using the package manager:

# For ARM 32-bit (arm-linux-gnueabihf-*)
sudo apt-get install gcc-arm-linux-gnueabihf binutils-arm-linux-gnueabihf

# For ARM 64-bit (aarch64-linux-gnu-*)
sudo apt-get install gcc-aarch64-linux-gnu binutils-aarch64-linux-gnu

# Verify installation
arm-linux-gnueabihf-gcc --version
aarch64-linux-gnu-gcc --version

You can also use toolchains from Arm Ltd (formerly Linaro) or build your own with tools like Buildroot or Yocto. For this tutorial, the apt-installed toolchain is sufficient.

Why Cross-Compiling a Kernel Module Is More Complex Than Cross-Compiling a Regular Program

Cross-compiling a regular user-space C program is straightforward: set the compiler, compile, done. Cross-compiling a kernel module is harder because a kernel module is not a standalone program — it is a piece of code that plugs into a running kernel. This creates a strict requirement: the module must be built against the exact kernel source tree of the kernel it will run on.

When you build a kernel module, the module build system (kbuild) needs to find the right kernel headers and configuration for the target kernel. If you point it at the wrong place — for example, at the kernel headers of your host machine — the module will be built for the wrong kernel version and will be rejected when you try to load it with insmod.

Writing a Cross-Compilation-Ready Makefile for Linux 6.x

The solution is to write a Makefile that uses a KDIR variable pointing to the correct kernel source tree for the target. Here is a production-quality Makefile pattern that supports both native and cross-compiled builds cleanly:

# Makefile for a cross-compilation-ready Linux kernel module
# Supports both native (x86_64) and cross-compiled (ARM/ARM64) builds
# Compatible with Linux 6.x

# Module name - change this to match your module
MODULE_NAME := my_driver

# -------------------------------------------------------
# KDIR: Path to the target kernel source tree
# Override this when cross-compiling:
#   make KDIR=/path/to/arm-kernel-src ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf-
# For native builds, this defaults to the running kernel's headers
# -------------------------------------------------------
KDIR ?= /lib/modules/$(shell uname -r)/build

# Object files that make up this module
obj-m := $(MODULE_NAME).o

# -------------------------------------------------------
# Build targets
# -------------------------------------------------------
all:
	$(MAKE) -C $(KDIR) M=$(shell pwd) modules

clean:
	$(MAKE) -C $(KDIR) M=$(shell pwd) clean

# Install the module (native only)
install:
	$(MAKE) -C $(KDIR) M=$(shell pwd) modules_install

.PHONY: all clean install

With this Makefile, a native build (for the same machine you are compiling on) requires no extra arguments:

make

A cross-compiled ARM 32-bit build requires three additional pieces of information:

make KDIR=/path/to/raspberry-pi-linux-src \
     ARCH=arm \
     CROSS_COMPILE=arm-linux-gnueabihf-

And an ARM 64-bit cross-compiled build looks like this:

make KDIR=/path/to/arm64-kernel-src \
     ARCH=arm64 \
     CROSS_COMPILE=aarch64-linux-gnu-

Setting Environment Variables Persistently

Typing the ARCH and CROSS_COMPILE variables on every make command gets tedious quickly. You can export them as shell environment variables for your current terminal session:

# Set for the current shell session (ARM 32-bit example)
export ARCH=arm
export CROSS_COMPILE=arm-linux-gnueabihf-
export KDIR=/home/ravi/raspberry-pi-linux

# Now a plain 'make' uses these values
make

# Verify the variables are set correctly
echo "ARCH=$ARCH"
echo "CROSS_COMPILE=$CROSS_COMPILE"
echo "KDIR=$KDIR"

What the Target Kernel Source Directory Must Contain

The KDIR path you provide cannot be just any directory — it must be the configured and built kernel source tree for the exact kernel running on your target device. Specifically, it must contain:

If you are building for a Raspberry Pi, you need to download the Raspberry Pi kernel source for the exact kernel version running on your Pi (check with uname -r on the Pi) and build it at least to the point where the kernel headers are prepared. The official Raspberry Pi OS documentation describes this process.

Step-by-Step: Cross-Compiling a Kernel Module for ARM in Linux 6.x

arm-linux-gnueabihf-gcc
# Expected output: arm-linux-gnueabihf-gcc: fatal error: no input files

# Also check the version
arm-linux-gnueabihf-gcc --version
# Example: arm-linux-gnueabihf-gcc (Ubuntu 13.2.0-4ubuntu3) 13.2.0

# Example: Clone Linux 6.6 LTS (a common choice for embedded in 2025)
git clone --depth 1 --branch v6.6 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git

cd linux

# Configure for ARM (use a defconfig that matches your target)
make ARCH=arm multi_v7_defconfig

# Prepare the headers and scripts (faster than a full kernel build)
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- modules_prepare

/* my_driver.c - A simple test module for cross-compilation */
#include <linux/module.h>
#include <linux/kernel.h>
#include <linux/init.h>

MODULE_LICENSE("GPL");
MODULE_AUTHOR("EmbeddedPathashala");
MODULE_DESCRIPTION("Cross-compilation test module for Linux 6.x");

static int __init my_driver_init(void)
{
    pr_info("my_driver: module loaded on target\n");
    return 0;
}

static void __exit my_driver_exit(void)
{
    pr_info("my_driver: module unloaded\n");
}

module_init(my_driver_init);
module_exit(my_driver_exit);

make KDIR=~/linux \
     ARCH=arm \
     CROSS_COMPILE=arm-linux-gnueabihf-

file my_driver.ko

# Expected output for ARM 32-bit cross-compiled module:
# my_driver.ko: ELF 32-bit LSB relocatable, ARM, EABI5 version 1 (SYSV), not stripped

# For ARM64 (AArch64):
# my_driver.ko: ELF 64-bit LSB relocatable, ARM aarch64, version 1 (SYSV), not stripped

# Copy to Raspberry Pi (replace with your Pi's IP)
scp my_driver.ko pi@192.168.1.100:/home/pi/

# On the Raspberry Pi:
sudo insmod /home/pi/my_driver.ko

# Verify it loaded
lsmod | grep my_driver

# Check the kernel log for the module's printk output
dmesg | tail -5

# Remove the module
sudo rmmod my_driver

Cross-Compilation Troubleshooting Guide

Cross-compilation failures have very specific causes. Here are the errors you will most likely encounter and exactly how to fix them:

Native vs. Cross-Compiled Kernel Module Build: Side-by-Side Comparison

Cross-Compilation Changes in Linux 6.x vs Older Kernels

If you are following older tutorials written for Linux 4.x or 5.x kernels, there are some important differences to be aware of in Linux 6.x:

Best Practices for Cross-Compiling Kernel Modules in Professional Embedded Linux Development

• Always use an explicit KDIR variable in your Makefile rather than relying on defaults — this prevents accidentally building against the wrong kernel headers.
• Match your cross-compiler version to what the target distribution uses. If your Raspberry Pi OS was built with GCC 12, use a GCC 12 cross-compiler on your host.
• Keep your kernel source tree in a known, documented location (like ~/kernel-src/rpi-linux-6.6) and document the exact kernel version in your project’s README.
• Use file my_module.ko after every cross-compilation to verify the output architecture before transferring to the target.
• Use ssh and scp to work with a networked target, or rsync for efficient incremental transfers of multiple modules.
• When working with Yocto or Buildroot-based embedded distributions, use the SDK or toolchain they provide, not a generic distribution toolchain — this ensures ABI compatibility.

Frequently Asked Questions

References and Further Reading

• Linux Kernel Documentation: Kernel Build System (kbuild) Makefiles
• Linux Kernel Documentation: Building External Modules
• Linux Kernel Documentation: Building Linux with Clang/LLVM
• Buildroot Manual: Toolchain Configuration