The RISC-V Linux User's Manual

Quan Nguyen

March 21, 2013

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.

Proposed cover of the RISC-V Linux User's Manual

Introduction

The purpose of this page is to document the assumptions made during the development of the RISC-V 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.

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.

History

A full description of the history can be found in Volume I of the RISC-V Instruction Set Manual. While the architecture intends to be a clean break, its implementation contains many remnants of predecessor architectures. In particular, the port of gcc and glibc derive from MIPS; as a result, architectural decisions that were not explicitly made by the RISC-V ISA have been inherited from MIPS. The RISC-V port of Linux itself is also inspired by parts of the Linux-MIPS codebase; however, careful considerations were made to rely as little on MIPS conventions as possible.

Therefore, when this document is unclear, referring to the MIPS specification for the corresponding topic may yield insight.

The RISC-V Instruction Set Architecture (ISA)

Register Conventions

The RISC-V ISA makes visible:

• 32 general-purpose registers (XPRs)
• 32 floating-point registers (FPRs)
• 32 privileged control registers (PCRs)

For 64-bit versions of RISC-V, the XPRs are 64-bits wide, and for 32-bit versions of RISC-V, the XPRs are 32-bits wide. The privileged control registers may have different widths, depending on the nature of the register.

General-purpose Registers

The RISC-V port of the Linux kernel uses the following conventions for its registers.

MIPS convention note: The pipe2 system call is specially handled by MIPS implementations, but the RISC-V port of glibc has been patched to remove this behavior.

The RISC-V port of the Linux kernel does not use any floating-point hardware. There are no assumptions made about the values of the floating-point registers, or the status register fsr.

Privileged Control Registers

The privileged control registers (PCRs) are used by the processor in Supervisor mode to complete tasks such as memory management and exception handling. These are not accessible from userspace.

Simulator implementation note: The tosim and fromsim registers are magical PCRs that do special commands based on the packet whose physical address is written to these registers.

The status PCR

The status register has been subject to many changes in the RISC-V ISA. However, the RISC-V port of Linux uses the following configuration:

Shown are the values that are known at processor startup. Other than the obvious 0 and 1, a ? is undefined and X as "don't care."

Simulator implementation note: The simulator sets the the interrupt mask (IM) to all 1, previous-supervisor (PS) to 0, and all EC/EV/EF to 0.

Interrupts and Exceptions

All interrupts (and exceptions) enter through one exception handler, the address of which is located in the evec PCR.

Interrupts

RISC-V provides eight interrupt lines for timers and other devices. They are level triggered, and masked with the IM field in the status PCR. The interrupts in use in the RISC-V port of Linux are as follows:

Interrupt priority decreases as the interrupt number increases; in this case, the timer interrupt is always taken last. Each interrupt is associated with an exception number, to be placed in the cause PCR.

Simulator implementation note: The ISA functional simulator differs from this behavior by setting the topmost bit of the cause register if it is an interrupt.

Exceptions

Exceptions are taken as the faulting instruction is executed. The behavior of each exception is different, particularly in the semantics of how error values are saved. The list is not comprehensive, but covers the most useful registers.

If an exception is not handled by Linux, the kernel will panic.

ISA oddity note: Most exceptions that can be handled by Linux return to exactly epc to repeat the instruction. However, this behavior is not desirable for system calls or breakpoints. The functional simulator does not distinguish system calls or breakpoints from other exceptions, and any use of the eret instruction will repeatedly jump on the syscall or break instructions. Therefore, for these two exceptions, the Linux exception handler will manually increment epc by one instruction forward (epc <- epc + 0x4) before returning to the program that triggered the exception.

The RISC-V Application Binary Interface (ABI)

MIPS convention note: The RISC-V ABI, in both its forms, RV32 and RV64, share many commonalites with their respective MIPS counterparts; MIPS O32 and MIPS64. Yunsup notes that RISC-V also takes cues from the MIPS Embedded ABI (EABI). However, it is the conclusion of the author that some ABI decisions made by MIPS developers were brain-damaged unsuitable for RISC-V to make a "clean break" from previous architectures.

System Call (syscall) conventions

Entering a syscall

The number of the syscall can be found in arch/riscv/asm/include/unistd.h, but it includes the file include/linux/asm-generic/unistd.h, so users may refer to that instead.

• Load the syscall number into v0.

Syscalls currently may have up to six arguments to be used. RISC-V provides eight argument registers, so all arguments may be passed via registers a0 through a7.

• Load the syscall arguments into a0 through a7.
• Issue the syscall instruction.

This invokes the kernel handler for syscalls.

Returning from a syscall

Linux returns the result of the syscall in register v0.

MIPS covention note: MIPS convention also specifies that register a3 contains the error status of the syscall: 0 if successful and less than zero otherwise. This error status is set by the architecture-dependent portion of the kernel; however, glibc seems to expect register a3 to be clobbered. (Why a3? MIPS has only four argument registers, but this notion was not preserved when RISC-V was designed with eight argument registers.)

To recover the result,

• Load the result from v0
• Check the error status in a3

Again, this stipulates that a3 is clobbered.

Function calling conventions

As with MIPS, the following registers must be saved by the caller:

• ra
• v0, v1
• a0, a1, a2, a3, a4, a5, a6, a7
• t0, t1, t2, t3, t4, t5, t6, t7

And these registers must be saved by the callee:

• s0, s1, s2, s3, s4, s5, s6, s7
• s8 (gp), s9 (fp)

The author presumes that twiddling with sp or tp will be very bad ideas.

Error Codes

Various things provide error codes for failed system calls or kernel functions. The field below provides a lookup table for the error values for the RISC-V port of Linux. The file can also be found at include/asm-generic/errno-base.h and include/asm-generic/errno.h.

Kernal Internals

Context Switching

When the processor enters kernel mode, it must save the entire state of the user process. The struct task_struct pointer of the current process is always located in the k0 PCR. When the processor needs to save the user process's state, it saves the following registers, in this order:

1. sp (the user stack pointer)
2. all user registers except sp
3. status PCR
4. epc PCR

The registers are saved into the kernel-mode stack for the process, located at current->stack, where current also refers to the k0 PCR.