quan m. nguyen


This document is out-of-date and was never authoritative. This is not an official source for RISC-V information. It is here only historical purposes. Please consult riscv.org for the most up-to-date information.

The Linux/RISC-V Source Code Manual

July 22, 2013


The purpose of this page is to document the directory structure of the RISC-V architectural port of the Linux kernel.

A project with a duration such as this requires adequate documentation to support future development and maintenance. This document is created with the hope of being useful; however, its accuracy is not guaranteed.

We spent a considerable amount of time merely reading the kernel sources. There's really no substitute for that, but when you're awake at 3 AM and wondering what the switch_to macro is supposed to do in your architectural port, something like this can be helpful.

Copyright Information

This document is currently under development. This document is copyrighted by Quan Nguyen, © 2013. All rights reserved. I do intend, however, to release this document to the public freely upon its satisfactory completion.

The Rest of the Kernel Sources

The vast majority of the kernel sources are available at The Linux Kernel Archives. In fact, it's safe to say that our contribution to the kernel may be less than 0.1% of the total (in SLOC). I would like to refer you to Understanding the Linux Kernel for a more comprehensive look at the whole kernel.

There's several directories I would have liked to talk about, like mm, fs, and init, but I would do a much worse job than in ULK3.

Our Kernel Code

As of this writing, I am describing the code of the Linux/RISC-V architectural port as it appears in commit 29739e700338d6f8da298f479c348cfb86fbf486. Of course, it's going to change in the future, and some code may disappear altogether, but the code snippets here will reflect what I'd like to explain.

The README and Friends

You'll find a few crucial files in the root directory of the repository. Because we've designed the repository to be neatly overlaid by the kernel sources, we only have to provide the arch directory.

README - Did you read it?

.gitignore - Instructs Git to ignore the unimportant parts of the Linux/RISC-V architectural port.

modpost.patch - Augments the kernel's symbol post-processing utility so that it works with RISC-V. We had hoped not to change any files outside of arch/riscv, but we were left with no choice.

The arch/riscv Directory

Linux places its architecture-specific files in the appropriately-named files in the arch directory. We've placed our RISC-V specific files in arch/riscv. Device drivers (in our case, for our HTIF virtualized devices), should actually go in the drivers, but we wanted to avoid placing our drivers in a different place. We have not effectively genericized the drivers for mainline driver use.

The directory structure within a particular architecture is actually not required to be the same. However, there exists a loose convention, and that's simply to mirror, as much as possible, the kernel's directory structure. The Makefile is responsible for guiding make through the correct subdirectories.

configs/ - Contains the configuration file passed to the Kconfig system.

htif/ - Contains the drivers to interact with the Host-Target InterFace (HTIF).

include/ - Contains the architecture-specific header files. These headers lay out the essential hardware information as pertinent to the kernel.

kernel/ - Contains C and assembly language files that conduct the interactions between the kernel and the hardware.

lib/ - Contains library routines for handling time and the fast handling of strings.

mm/ - Contains the code that interacts with the virtual memory subsystem. This code also includes the fault-handling code.

Kconfig - A Kconfig script that enumerates the features available to be compiled into the Linux kernel. This file also notes the RISC-V specific configuration options, like which processor to configure for (Platform Type → CPU selection).

initramfs.txt - Describes the files that should be included into the initramfs, a filesystem maintained in the .data section of the kernel code and mounted in the kernel boot process.