RISC-V Registers

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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

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.

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.

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.

The user status register. Only two bits of it are writable here: the one that enables user level interrupts, and the one that remembers whether they were enabled before the current handler was entered, so that uret can put things back as it found them. Entering a handler copies the first into the second and clears the first, which is why a handler is not interrupted by the thing it is handling.

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.

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.

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.

Which user level interrupts are enabled, one bit per source. An interrupt is delivered only when its bit is set here and interrupts are enabled in ustatus.

The address of the user level trap handler: where the machine jumps when an exception or an enabled interrupt happens. A program that means to handle its own traps writes the address of its handler here and also sets the enable bit of ustatus, with csrsi ustatus, 1, because this simulator only enters the handler when that bit is set. A trap taken without both of them stops the program with the usual error message.

A word the handler may use as it likes. The classic use is to give the handler a stack pointer of its own, since the trap arrives with the program halfway through something and no register free to borrow.

The address of the instruction the trap interrupted. uret returns to it, so a handler that has fixed the cause returns unchanged, and a handler that means to skip the offending instruction adds 4 to this register first.

Why the trap happened: a code such as an illegal instruction or a misaligned address, with the top bit set when the cause was an interrupt rather than an exception. A handler serving several causes reads this first.

The detail that goes with the cause: the address a load or store failed on, or the instruction that could not be decoded. Meaningless for causes that carry no such value.

Which interrupts are pending, in the same bit positions as uie. A source can be pending and not enabled, in which case nothing happens until the program enables it.

The three counters, read only: elapsed cycles, elapsed time, and the number of instructions retired. A program times a piece of itself by reading one of them before and after and subtracting.

The high halves of the three counters, for the 32 bit target where a 64 bit count does not fit in one register. Reading the pair safely means reading the high half, then the low, then the high again, and starting over if it changed in between.