How to Rebuild and Install RISC-V Kernel Cross Compile

To rebuild and install a RISC-V kernel cross-compiled on a Linux host, you must first configure the correct architecture, specify the cross-compilation toolchain prefix, and select an appropriate defconfig for your target hardware. After generating the configuration menu, you compile the kernel image using make with the specified jobs flag, then use make modules_install to deploy the kernel and modules to the target root filesystem or emulated environment.

Preparing the Cross-Compilation Environment

The foundation of any successful embedded Linux build is a properly configured toolchain. For RISC-V, you generally need a GCC compiler that targets the specific ISA extension (such as RV64GC) and supports the target’s ABI. Most modern distributions provide these packages in their repositories. On Debian-based systems like Ubuntu, you can install the necessary tools by running:

sudo apt update
sudo apt install gcc-riscv64-linux-gnu make bison flex libssl-dev bc

Ensure that the installed compiler matches the bit-width of your target system. If you are targeting a 32-bit RISC-V core, you would use gcc-riscv32-linux-gnu instead. Verify the installation by checking the version string of the compiler binary. The output should clearly indicate it is targeting the RISC-V architecture. This step prevents subtle linking errors later during the compilation phase.

Acquiring and Extracting the Kernel Source

You should obtain the Linux kernel source code from the official repository. Using Git allows you to track updates and switch between stable branches easily. Clone the mainline kernel tree into a dedicated directory:

git clone https://github.com/torvalds/linux.git
cd linux

Navigate to the root of the extracted source tree. It is crucial to clean any previous build artifacts if you are switching configurations frequently. Run make mrproper to remove all generated files, including configuration backups and object files. This ensures a pristine starting point for your new build. Without this cleanup, residual files from previous builds might interfere with dependency tracking, leading to incorrect binaries.

Configuring the Kernel Build

Configuration is the most critical step where you define what features are included in the kernel. For cross-compilation, you must explicitly set the architecture variable. Instead of relying on auto-detection, which assumes the host architecture, you force the build system to target RISC-V by exporting the ARCH variable.

export ARCH=riscv
export CROSS_COMPILE=riscv64-linux-gnu-

Note that the CROSS_COMPILE variable must include the trailing hyphen. This prefix is appended to standard commands like gcc, resulting in riscv64-linux-gnu-gcc. Once exported, you can launch the configuration interface. Running make defconfig generates a default configuration suitable for generic RISC-V hardware. However, for specific boards, you might prefer a board-specific defconfig located in arch/riscv/configs/. You can list available configs by running make list-defconfigs. If you need to tweak settings, such as enabling specific drivers or adjusting memory limits, use make menuconfig. This text-based interface allows you to navigate through subsystems. Ensure that the "Kernel Features" section has the correct page size and virtual memory layout for your target. Save the configuration when finished. The resulting .config file will be used in subsequent build steps.

Compiling the Kernel Image

With the configuration finalized, you can initiate the compilation process. Use the make command with the -j flag to parallelize the build across multiple CPU cores, significantly reducing build time. Replace N with the number of cores available on your machine plus one.

make -j$(nproc)

This command compiles the kernel modules and links the final kernel image. For RISC-V, the primary bootable image is typically Image.gz or Image located in arch/riscv/boot/. The exact filename depends on whether you enabled compression options in the configuration. Monitor the build log for any warnings or errors. Common issues often stem from missing dependencies or incompatible toolchain versions. If the build succeeds, you will see a summary indicating the location of the generated image.

Installing Modules and Deploying

After compiling the kernel, you usually need to install the loadable kernel modules. These modules contain drivers for hardware components that are not built directly into the kernel image. Run the following command to install them into a designated directory:

make INSTALL_MOD_STRIP=1 INSTALL_MOD_PATH=/path/to/target/rootfs modules_install

The INSTALL_MOD_PATH variable directs the installer to place modules into your target root filesystem rather than the host system. This is essential for embedded deployments where the target device has its own separate filesystem structure. The INSTALL_MOD_STRIP=1 option removes debug symbols from the modules, reducing their size and storage footprint. Finally, copy the compiled kernel image to your deployment medium. Whether you are flashing an SD card, uploading to a QEMU emulator, or transferring via TFTP, ensure the image is placed in the expected boot partition. Update your bootloader configuration (such as GRUB or U-Boot) to point to the new kernel image. Reboot the target system to verify that the new kernel loads correctly and initializes the hardware as expected.

Frequently Asked Questions

What happens if I forget the trailing hyphen in CROSS_COMPILE?

The build system will fail to find the compiler because it will look for a binary named exactly "riscv64-linux-gnu" without the expected suffix. This results in immediate errors stating that the cross-compiler was not found. Always double-check the variable definition before starting the build.

How do I know which defconfig to use for my specific board?

You should consult the documentation provided by your board manufacturer or look for a matching config in the arch/riscv/configs/ directory. Generic defconfigs may lack specific driver support required for your hardware peripherals. Using the wrong config can lead to a kernel that boots but cannot access essential devices.

Can I use the same toolchain for both 32-bit and 64-bit RISC-V?

No, you must use distinct toolchains tailored to the specific instruction set architecture and ABI of your target. A 64-bit toolchain cannot generate valid binaries for a 32-bit core due to differences in register sizes and calling conventions. Mixing them up will result in runtime crashes or illegal instruction exceptions.

Why does the build fail with "cannot find linker script"?

This error typically occurs when the configuration is incomplete or corrupted, causing the build system to miss critical assembly files. Running make mrproper followed by regenerating the configuration usually resolves the issue. Ensure that your toolchain is fully installed and accessible in your PATH.

Is it safe to strip debug symbols from the kernel image?

Stripping debug symbols reduces the kernel size and speeds up loading times, which is beneficial for embedded systems with limited storage. However, it makes debugging difficult if the system crashes or behaves unexpectedly. You should only enable stripping in production environments where diagnostic capabilities are handled externally.