RISC-V Registers

The register files

A RISC-V processor holds three sets of registers: the 32 general purpose ones every instruction works on, the 32 floating point registers the extension adds, and the control and status registers that report on the machine itself. The registers panel of the editor shows each of the three as its own tab.

General purpose registers

RISC-V has 32 general purpose registers, and with one exception the hardware treats them all alike: x0 reads as zero whatever is written to it, and the other 31 are plain 32 bit words, or 64 bit on the RV64 target. Everything else is convention, written down in the ABI and followed by every program that means to call another one.

Each register has a number and a name, and the assembler accepts both: addi t0, zero, 1 and addi x5, x0, 1 assemble to the same instruction. The names are what the panel shows and what a program should use, because the name says what the register is for. The convention divides them into registers a called function may destroy, the temporaries and the arguments, and registers it has to give back unchanged, the saved ones.

zero

x0

Always reads as 0, and writing to it is silently ignored. It is not a wasted register: having a guaranteed zero is what lets one instruction do the work of many, so mv a0, a1 is really add a0, zero, a1, beqz t0, label is beq t0, zero, label, and a store of a constant zero needs no register loaded first.

ra

x1

Return address. jal and jalr write the address of the following instruction here before jumping, and a function returns by executing ret, which is jalr zero, ra, 0. A function that calls another one has to save ra on the stack first, because the inner call overwrites it.

sp

x2

Stack pointer, pointing at the lowest used word of the stack. A function makes room by subtracting from it on entry and gives the room back by adding the same amount before returning. The ABI expects it to stay aligned to 16 bytes at every call.

gp

x3

Global pointer. It is set up once before the program starts and never changed, so that a global variable near it can be reached in a single instruction with a signed 12 bit offset instead of the two an arbitrary address needs.

tp

x4

Thread pointer, the base of the storage private to the running thread. A program here has one thread and no use for it, but the ABI reserves it, so nothing else should be kept in it.

t0 - t2

x5 - x7

Temporaries. A called function may overwrite them freely, so a caller that still needs a value after the call has to save it, or keep it in a saved register instead.

s0, also written fp

x8

The first saved register, and by convention the frame pointer: the fixed handle on the current stack frame for functions whose stack pointer moves while they run. The assembler accepts both spellings for the same register.

s1

x9

A saved register. A function that uses it must put back the value it found, which is what makes it the right place for anything that has to survive a call.

a0 - a1

x10 - x11

The first two arguments of a call, and the registers a result comes back in: a0 carries a single return value and a1 the second half of a pair. The environment calls that this simulator implements also take their argument in a0 and leave their result there.

a2 - a7

x12 - x17

Six more argument registers; anything beyond the eighth argument is passed on the stack. a7 has a second job here: it holds the number of the environment call ecall is about to make.

s2 - s11

x18 - x27

Ten more saved registers, preserved across calls by whoever uses them. A loop whose body calls a function keeps its counter in one of these.

t3 - t6

x28 - x31

Four more temporaries, with the same rule as t0 to t2: free to use, gone after a call.

Floating point registers

The floating point extension adds 32 registers of its own, f0 to f31, with the same kind of ABI names as the general ones. They are a separate file: no arithmetic instruction reads one of each, and a value crosses over only through an explicit instruction. fcvt.s.w ft0, t0 converts the integer in a general register into a single precision number, fcvt.w.s t0, ft0 converts back, and fmv.x.w copies the raw bits of a floating point register into an integer one while fmv.w.x copies them back, neither of them converting anything. The older spellings fmv.x.s and fmv.s.x assemble to the same two instructions. A comparison is the other place the two files meet: feq.s, flt.s and fle.s test two floating point registers and write 1 or 0 into a general register, so a floating point comparison reaches a branch through bnez or beqz rather than through a flag of its own.

Every register here is 64 bits wide, on both the 32 and the 64 bit targets, because that is what a double needs. A single precision value is stored NaN-boxed: it occupies the low 32 bits and the upper 32 are all ones, a pattern that reads as a NaN if a double instruction looks at it. That is deliberate, and it is why the panel shows NaN in the single format for a register holding a genuine double: it is the same protection, running the other way. fadd.s adds singles and fadd.d doubles, flw and fsw load and store a single, fld and fsd a double, and fcvt.d.s widens a single into a double when the two have to meet.

ft0 - ft7

f0 - f7

Floating point temporaries, destroyed by a call like the integer ones. The first eight registers of the file, which is why an example that needs one register usually reaches for ft0.

fs0 - fs1

f8 - f9

The first two floating point saved registers, preserved across calls by the function that uses them.

fa0 - fa7

f10 - f17

The floating point arguments of a call, and in fa0 the floating point return value. They sit beside the integer argument registers rather than counting against them, so a function taking an integer and a double is passed a0 and fa0.

fs2 - fs11

f18 - f27

Ten more floating point saved registers. Note that the ABI names run out of order against the numbers: fs2 is f18, well after fa7. The reason is the compressed encoding, the 16 bit form of the instruction set that this simulator does not assemble but that the ABI was written around: an instruction that short has only three bits for a register, which reaches f8 to f15 and no further, so the ABI put the registers a program uses most there, fs0, fs1 and fa0 to fa5, and the saved registers that were left over landed at f18 and above.

ft8 - ft11

f28 - f31

Four more floating point temporaries, closing the file. They follow the same rule as ft0 to ft7, and as t3 to t6 on the integer side: free to use, and gone after a call.

Control and status registers

Control and status registers (CSRs) hold floating point settings, trap state and counters. Read one with csrr t0, fcsr. In RARS syntax, write one with csrw t0, fcsr: the general register comes first. In GNU assembly, including Files linked to C, the write order is csrw fcsr, t0. Immediate forms put the CSR first in both syntaxes, as in csrsi ustatus, 1.

These are short forms of the csrr* instructions, which read an old value and write a new one in one step. csrr uses csrrs with zero as the value to set, leaving the CSR unchanged. csrw uses csrrw with zero as the destination, discarding the old value.

This simulator implements the seventeen registers below, a user-level subset. On RV32, a 64-bit counter uses the plain name for its low half and a name ending in h for its high half. On RV64, the plain name reads the whole counter.

ustatus

0x000

Bit 0, UIE, enables user interrupts. Bit 4, UPIE, saves the previous UIE value. These are the only writable bits here. Entering a handler copies UIE to UPIE and clears UIE, preventing another interrupt while the handler runs. uret restores UIE from UPIE.

fflags

0x001

The five floating point exception flags: invalid operation, divide by zero, overflow, underflow and inexact. Arithmetic sets them and nothing clears them, so they say what has happened since the program started, or since it last wrote a zero here. This is not a separate register but the low five bits of fcsr under their own name.

frm

0x002

The rounding mode the floating point instructions use when they are not given one: round to nearest with ties to even by default, with truncation and the two directed roundings selectable. Like fflags, it is a window onto fcsr, bits 5 to 7.

fcsr

0x003

The floating point control and status register, which is the two registers above in one place: fflags is its low five bits and frm the three above them. Writing it writes both, which is how a program resets the flags and chooses a rounding mode in a single instruction.

uie

0x004

The source mask: bit 0 enables software interrupts, bit 4 the timer, and bit 8 external interrupts from the keyboard and display. Delivery also requires UIE in ustatus. See Interrupts and the timer for complete programs.

utvec

0x005

The address of the handler shared by exceptions and enabled interrupts. Write the handler address here and set UIE with csrsi ustatus, 1. This simulator requires UIE for exception entry too. An exception without a usable handler and UIE stops the program with an error.

uscratch

0x040

A register for the handler to use freely. It can hold a separate handler stack pointer or a spare value while saving the interrupted program's registers.

uepc

0x041

The return address used by uret. After an interrupt, it points to the next instruction, which has not run: leave it unchanged. After an exception, it points to the failed instruction. Leave it unchanged to retry after repairing the cause, or add 4 to deliberately skip that instruction.

ucause

0x042

The trap cause. Its top bit distinguishes interrupts from exceptions: bit 31 on RV32, bit 63 on RV64. The RV32 timer interrupt is 0x80000004 and an external interrupt is 0x80000008. On RV64 these are 0x8000000000000004 and 0x8000000000000008. With the top bit clear, the remaining bits give an exception code, such as illegal instruction or misaligned address. A shared handler reads this first.

utval

0x043

Extra detail for the cause: the address a load or store failed on, the instruction that could not be decoded, or the external device requesting an interrupt (0x40 keyboard, 0x80 display). Read it only for causes that define a value.

uip

0x044

Pending interrupt requests, using the same bits as uie. A disabled source can remain pending until enabled. Timer and external bits follow their devices and ignore writes. Set bit 0 with csrsi uip, 1 to request a software interrupt. Taking that interrupt clears the bit.

cycle, time, instret

0xC00 - 0xC02

Three read-only 64-bit counters. In this simulator, cycle and instret each increase by one per executed instruction. Read before and after a section and subtract to count its instructions.

The time CSR reads calendar milliseconds since 1970-01-01 UTC, the same clock as service 30. In interactive use it continues while paused, at breakpoints and between Steps. In a Testcase it starts at 2000-01-01 UTC and advances through virtual waits. This differs from memory-mapped time at 0xffff0018, which measures elapsed run time from 0 and stops while paused. Use that memory register for timer deadlines (see Interrupts and the timer).

cycleh, timeh, instreth

0xC80 - 0xC82

The high 32 bits of cycle, time and instret for RV32. To read a 64-bit value safely, read high, then low, then high again. If the two high readings differ, repeat the sequence. On RV64, read the plain counter name for all 64 bits.