Easy RISC-V

As we’ve seen above, you can get a RISC-V machine to add numbers
together.

The addi
instruction adds the value in rs1 to the immediate value
imm, and puts the result in rd.

addi rd, rs1, imm

The add instruction
adds the value in rs1 to the value in rs2, and
puts the result in rd.

add rd, rs1, rs2

The opposite of addition is subtraction. The sub instruction subtracts the
value in rs2 from the value in rs1
(i.e. rs1 - rs2), and puts the result in rd.
There’s no corresponding subi instruction — Just use
addi with a negative number.

sub rd, rs1, rs2

Step through this demo program and try writing your own additions and
subtractions:

addi x10, x0, 0x123
addi x11, x0, 0x555

addi x12, x10, 0x765
add x13, x10, x11
sub x14, x11, x10

addi x10, x10, 1
addi x10, x10, 1
addi x10, x10, -1
addi x10, x10, -1

ebreak

One thing you should note is that the immediate value has a limited
range, namely [-2048, 2047], the range of a 12-bit two’s
complement signed integer. This limitation is because RV32I uses fixed
32-bit i.e. 4-byte instructions, and only the top 12 bits are available
to encode an immediate value. You can see the hexadecimal value encoded
in the instruction from the ‘Dump’. This article will not go into much
further detail about instruction encodings.

 0x40000000: 12300513  addi x10, x0, 0x123
 0x40000004: 55500593  addi x11, x0, 0x555

Even instructions as simple as addition and subtraction have other
interesting uses. We have already used addi x10, x0, 0x123
to put 0x123 in the register x10. When writing
in assembly, we can use a little shortcut called pseudoinstructions. The
li (“load immediate”)
pseudoinstruction is a convenient way to put a small value in a
register. It expands to addi rd, x0, imm when
imm is in the range [-2048, 2047].

li rd, imm

When imm is 0, addi copies the
value without changing it because adding zero is the same as doing
nothing. The mv (“move”)
pseudoinstruction copies the value from rs1 to
rd. It expands to addi rd, rs1, 0.

mv rd, rs1

Using the pseudoinstruction is exactly equivalent to using the “real”
instruction. You can see in the dump that the two are assembled exactly
the same way.

addi x10, x0, 0x123
li x10, 0x123

addi x11, x10, 0
mv x11, x10

ebreak

Subtracting from zero is negation. What’s the negative of
0x123?

li x10, 0x123
sub x11, x0, x10

ebreak

Hmm, we get 0xfffffccd. That’s the 32-bit two’s complement
representation of -291, or -0x123. There’s
plenty of tutorials on this out there, so we’ll just note that whenever
something is “signed”, RISC-V uses two’s complement representation. The
benefit of this is that there are fewer instructions for separate signed
and unsigned instructions — both signed and unsigned numbers have the
same overflow wrap-around behavior.

Speaking of overflow wrap-around, what happens if we add something
too much and it overflows? We’ll use add to repeatedly
double 0x123 and see what happens:

li x10, 0x123
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10
add x10, x10, x10

ebreak

As 0x123 crawls up to the upper bits and eventually we
get to 0x9180_0000, in the next iteration it turns into
0x2300_0000. There was an overflow! Doubling of
0x9180_0000 gives 0x1_2300_0000, but that
needs 33 bits in binary, so the highest bit can’t be put in the result.
Since RISC-V doesn’t have flag bits for carry or overflow, it’s simply
gone. The programmer is expected to deal with this.

While we’re talking about bits, another thing we can do with bits is
performing bitwise logical operations on them.

The and instruction
performs a bitwise-“and” between the bits of rs1 and
rs2 and puts the result in rd. The or and xor instructions similarly
performs bitwise-“or” and bitwise-“xor”, respectively.

and rd, rs1, rs2
or rd, rs1, rs2
xor rd, rs1, rs2

Immediate operand versions of the three, namely andi, ori, xori also exist.

andi rd, rs1, imm
ori rd, rs1, imm
xori rd, rs1, imm

Here are some random bit operation examples you can play with:

li x10, 0x5a1
xori x10, x10, 0xf0
xori x10, x10, -1

li x11, 0x5a1
addi x12, x11, -1
and x11, x11, x12
addi x12, x11, -1
and x11, x11, x12
addi x12, x11, -1
and x11, x11, x12

li x13, 0x5a1
ori x14, x13, 0xf
ori x14, x13, 0xff
ori x14, x13, 0xf0

ebreak

Remember that the immediate value is in the range
[-2048, 2047]. For negative values, the two’s complement
representation used means that the high bits are all ones. For example,
using -1 as imm means the second operand is
binary all ones, or 0xffff_ffff. This allows us to use
xori rd, rs1, -1 as bitwise-“not”.

li x10, 0x5a1
xori x11, x10, -1

or x12, x10, x11
add x13, x10, x11

ebreak

Another interesting operation you can do is to round/align something up or down to a multiple
of a power of two. For example, if you want to find the closest multiple
of 16 below a, in binary that would be clearing the lowest
4 bits, or a & ~0b1111. Conveniently, that’s
a & -16 in two’s complement.

Aligning up is less intuitive, but one idea would be adding 16 first.
However that gives an incorrect result for multiples of 16. It’s easy
enough to fix though: adding one less works exactly right:
(a + 15) & -16

li x10, 0x123
andi x11, x10, -16

addi x12, x10, 15
andi x12, x12, -16
ebreak

Usually when you write a comparison of some sort like
a == b or a >= b, it’s used as a condition
for some if or loop, but… those things are complicated!
We’ll get to it later.

Sometimes you just want a boolean value out of a comparison. The C
convention uses 1 for true and 0 for false, and since the world runs on
C now, that’s what RISC-V provides.

In C there are six comparison operators:

== != < > <= >=

The values being compared can also be both signed or both
unsigned.

How many comparison instructions do we have at our disposal? Let’s
see…

The slt (“set less
than”) instruction compares rs1 and rs2 as
signed 32-bit integers, and sets rd to 1 if
rs1 < rs2, and 0 otherwise
(rs1 >= rs2). The sltu instruction is similar
but it treats the operands as unsigned values. slti and sltiu are similar but the
second operand is an immediate value.

slt rd, rs1, rs2
sltu rd, rs1, rs2
slti rd, rs1, imm
sltiu rd, rs1, imm

(Of particular note is sltiu, where the immediate
operand still has the range [-2048, 2047] but is sign
extended to 32 bits and then treated as an unsigned value, like what
would happen in C with a < (unsigned)-1.)

That’s… one of the six comparisons settled. What about the others? As
it turns out, we can synthesize any of the other five, using up to two
instructions.

Making > from < is easy, as you can
just swap the operands. Using xori with 1 we
can invert the result of a comparison, giving as <= and
>=.

li x10, 0x3
li x11, 0x5

slt x12, x10, x11 # x10 < x11
slt x13, x11, x10 # x10 > x11

xori x14, x12, 1 # x10 >= x11 i.e. !(x10 < x11)
xori x15, x13, 1 # x10 <= x11 i.e. !(x10 > x11)

ebreak

That was signed comparison but unsigned comparison works the same
using sltu instead of slt.

As for == and !=, let’s tackle the easier
case of a == 0 and a != 0 first. We will use
the fact that for unsigned values, a != 0 is equivalent to
a > 0. The negation of that is a <= 0,
which is the same as a < 1.

li x10, 0

sltu x11, x0, x10 # 0 <u x10 i.e. x10 != 0
sltiu x12, x10, 1 # x10 <u 1 i.e. x10 == 0

As a bonus, this is also how we get logical not and converting
integer to boolean.

Now that we have these, a == b is just
(a - b) == 0, and a != b is just
(a - b) != 0.

li x10, 0x3 # a
li x11, 0x5 # b
sub x10, x10, x11 # x10 = a – b

sltu x11, x0, x10 # 0 <u x10 i.e. x10 != 0
sltiu x12, x10, 1 # x10 <u 1 i.e. x10 == 0

ebreak

In summary: ([u] means use u for unsigned
comparison and nothing for signed comparison)

• a < b: slt[u]
• a > b: slt[u] reversed
• a <= b: slt[u] reversed ; xori 1
• a >= b: slt[u] ; xori 1
• a == 0: sltu x0
• a != 0: sltiu 1
• a == b: sub ; sltu x0
• a != b: sub ; sltiu 1

There is no way I can do justice to the usage of bit shifts in the
middle of a tutorial on RISC-V assembly. If you’re here, you’ve probably
heard of them. There’s nothing really special to the way they appear in
usage for RISC-V.

There are two variants for right shifting: srl and srli (“shift right logical
(immediate)”) performs “logical” or unsigned right shift where the
leftmost or most significant bits are filled with zeros.

sra and srai (“shift right
arithmetic (immediate)”) performs “arithmetic” or signed right shift
where the leftmost bits are filled with the same of what highest/sign
bit was. So if you shift a negative value, you get a negative result; if
you shift a non-negative value, you get a non-negative result.

srl rd, rs1, rs2
sra rd, rs1, rs2
srli rd, rs1, imm
srai rd, rs1, imm

As before, the ones with the i suffix take an immediate
value as the second operand, and the ones without i take a
register.

li x10, -3
srai x11, x10, 16
srli x12, x10, 16
ebreak

So a means “arithmetic”, l means “logical”.
Got it.

Left shifts have no such distinction. For consistency they are still
“logical”: sll is left
shift, and slli is
left shift with immediate.

sll rd, rs1, rs2
slli rd, rs1, imm

Aha, now we can blow up 0x123 without repeating myself
so much:

li x10, 0x123
slli x10, x10, 10
slli x10, x10, 10
slli x10, x10, 10
ebreak

The immediate value for shift instructions are special: they can only
be in the range of 0 to 31, inclusive, because it doesn’t make sense to
shift by a negative amount, or by more than 31. When the shift amount is
taken from a register, the value is considered modulo 32, or in other
words only the last 5 bits are taken into account:

li x10, 0x444
li x11, 0x81

srl x10, x10, x11 # Same as shifting by 1

ebreak

For some fun, let’s try multiplying a value by 10, something you
would do when parsing decimal numbers: a * 10 can be
rewritten as (a << 1) + (a << 3):

li x10, 0x5

slli x11, x10, 1
slli x12, x10, 3
add x11, x11, x12

ebreak

That’s it?

You may have noticed some glaring omissions. What we’ve learned
doesn’t even cover grade school math: multiplication and division are
missing.

RISC-V is designed with extensions in mind. Remember that
as said in the introduction, RV32I is the barest bones of the barest
bones we’ve got. Forcing everyone to make their processors with
multiplication and division even for tasks that don’t need them would
waste silicon area and money on every chip. Instead those making RISC-V
processors have great freedom to choose, and indeed some would say they
have too much freedom.

For us… Honestly, I’m just glad we’ve been dealt a hand that we can
tackle completely in full. There’s no way I’m finishing writing this
tutorial if RV32I wasn’t so bare boned.

(Operand a is rs1, and b is
rs2 or immediate. In the instruction name [i]
means an immediate variant is available. Subscript u means
unsigned and s means two’s complement signed.)

The addi instruction has limit on the immediate value.
How do we make bigger values?

The lui (“load upper
immediate”) instruction takes an immediate in the range
[0, 1048575] (i.e. up to 220 - 1)
and sets rd to that value left shifted 12 bits:

lui rd, imm20

That was… slightly confusing. Why don’t we give it a try:

lui x10, 1
lui x11, 2
ebreak

Instead of li loading a “low” immediate, we control the
upper 20 bits of what we put in the register. After that, we
can use another addi instruction to fill in the lower bits.
For example, if we want 0x12345:

lui x10, 0x12
addi x10, x10, 0x345
ebreak

For convenience, in assembly you can use %hi() and %lo() to extract the, well,
high 20 and low 10 bits of a value. The previous example could also be
written:

lui x10, %hi(0x12345)
addi x10, x10, %lo(0x12345)
ebreak

Letting lui handle the high 20 bits, and
addi for the low 12 bits, you can make any 32-bit
value.

(A small complication arises if you want to use values with bit 11
set. In that case, the immediate operand to addi will have
to be negative. However %hi understands this and adds one
to compensate, so this %hi/%lo combination
does work for everything.)

So far, everything that we’ve had so far can be done on even the most
basic programmer’s calculator. To truly make a computer… do computer
stuff, we’d want loops and conditionals.

In RISC-V parlance, a branch
is a conditional transfer of control flow, and a jump is an unconditional transfer of
control flow.

I think the branch instructions are slightly simpler, so let’s start
with those.

All the branch instruction follow the form “If some comparison, go to
somewhere.” The conditions are:

• beq:
  rs1 == rs2 (“equal”)
• bne:
  rs1 != rs2 (“not equal”)
• blt:
  rs1 < rs2 signed (“less than”)
• bge:
  rs1 >= rs2 signed (“greater or equal”)
• bltu:
  rs1 < rs2 signed (“less than unsigned”)
• bgeu:
  rs1 >= rs2 signed (“greater or equal unsigned”)

(In case you’re wondering about the confusing choice of ordering
operators here, it’s just that the negation of < is
>=.)

beq rs1, rs2, label
bne rs1, rs2, label
blt rs1, rs2, label
bge rs1, rs2, label
bltu rs1, rs2, label
bgeu rs1, rs2, label

Oh, right, almost forgot to explain what labels are. Labels are
convenience identifiers for addresses at some line of your code. They
are some identifier followed by a colon (like this:). They
can appear on a line of its own, or before any instruction on the line.
You can see which address they point to using the “Dump” button. The
third operand of a branch instruction is a label to jump to if the
condition holds.

Let’s add up all the numbers from 1 to 100:

li x10, 100 # i = 100
li x11, 0 # sum = 0

loop:
add x11, x11, x10 # sum = sum + i
addi x10, x10, -1 # i = i – 1
blt x0, x10, loop # If i > 0: loop again
# Otherwise: done

ebreak

You can try your hands on making your favorite loops, like fibonacci
numbers or something. Speaking of trying your hands, just so we’re
ready, here’s what an infinite loop looks like. Try pausing or stopping
the loop, and single stepping through the instructions.

loop:
addi x10, x10, 1
add x11, x11, x10
beq x0, x0, loop

(If you know a thing or two about JavaScript in the browser, you’ll
know that a real infinite loop in JavaScript makes the whole page
becomes unresponsive, unless it’s in a worker or something. The “Run”
button here just runs the emulator for a certain number of steps,
pausing by giving back control to the event loop in between.)

(This isn’t the preferred way to write an unconditional jump. We’ll
see what is later.)

By the way, there’s no bgt[u] or ble[u]
because you can just swap rs1 and rs2 to get
those.

There are two jump instructions in RISC-V. One of them is jal “jump and link”, which
sets rd to the address of the following instruction, and
then jumps to a label:

jal rd, label

Another is jalr
“jump and link register”, which sets rd to the address of
the following instruction, and then jumps to the address at
imm + rs1.

jalr rd, imm(rs1)

(Actually, the address jumped to is
(imm + rs1) & ~1, i.e. the least significant bit is
cleared. This distinction won’t come up in normal code, like, pretty
much ever.)

Eesh, that’s some funky looking syntax. When you see parentheses like
this, it has something to do with an address. Parens means
address.

That’s… still a lot going on. Let’s take on some simpler cases first:
If rd is x0 then the only thing these
instructions do is jumping. We can use it instead of the branch
instructions for an unconditional jump.

loop:
# Yes this is an infinite loop.
# You can see that we execute
# this one instruction over and over
jal x0, loop

For convenience, a pseudoinstruction is available for you: j (“jump”) is for
jal with rd being x0:

j label

As for why you would want to do this… Well, we only have 32 bits per
instruction, and since the jal instruction only needs one
register number instead of the branch instructions’ two, and it doesn’t
need a condition, the instruction encoding permits jumping over a longer
range. So this is always preferred over something like
beq x0, x0, label for a jump.

As for jalr, you can jump to an address that’s stored in
a register. In C, that would be dealing with function pointers. You’d
need this any time dynamic dispatch is needed. For example, we load the
address of foo into a register first before jumping to
it.

lui x10, %hi(foo)
addi x10, x10, %lo(foo)
jalr x0, 0(x10)

# This isn’t executed
li x12, 1
ebreak

foo:
# This is executed
li x12, 2
ebreak

In case you forgot by now, the lui/addi
combo at the start puts the address of the label foo in
register x10.

Similar to j, jr (“jump register”) is a
psuedoinstruction for jalr with rd being
x0 and imm being 0:

jr rs1

Hmmm… If I didn’t really need the address in x10, that
addi would be unnecessary, since jalr has the
ability to add a low immediate on its own:

lui x10, %hi(foo)
jalr x0, %lo(foo)(x10)

# This isn’t executed
li x12, 1
ebreak

foo:
# This is executed
li x12, 2
ebreak

What’s the advantage of this over jal x0? Since
%hi and %lo can represent any 32-bit value,
this two-instruction combo can jump to any address, free from range
restrictions. You do need a free scratch register for the high part of
the address though, but since RISC-V gives you 31 of them, this
shouldn’t be too much of a problem.

What’s the deal with the destination register then? What do you need
the address of the next instruction for? For jumping back of
course. We can use this functionality to call functions and return
back.

li x10, 1
jal x1, double # Call double
jal x1, double # Call double
ebreak

# Double the value in x10
double:
add x10, x10, x10
jr x1 # Return

Note that I used the register x1 for this, which is the
register for providing the return address by convention. For
convenience, if the destination register is omitted in jal,
it defaults to x1. Meanwhile, ret (“return”) is a
pseudoinstruction that stands for jr x1,
i.e. jalr x0, 0(x1):

jal label
ret

So the example above can be rewritten more conveniently as:

li x10, 1
jal foo
jal foo
ebreak

foo:
add x10, x10, x10
ret

That’s a nice computer we have here. Now we have… all of 31 × 4 = 124
bytes of storage in the form of registers to work with. I want more…

The emulator has 1 MiB of memory starting at address
0x4000_0000. That’s 0x4000_0000 to
0x400f_ffff, inclusive. The assembler starts assembling at
the beginning of memory, as you can see in the dump, starting at address
0x4000_0000.

The .word directive straight up puts a
4-byte/32-bit word into the current position. You can specify multiple
values separated by commas.

.word value [ , value [ , ...  ] ]

The lw (“load word”)
instruction loads a word from the address rs1 + imm and
puts it in rd, in other words it reads the word from
memory:

lw rd, imm(rs1)

As with jalr, you can combine it with lui
to access any address.

lui x10, %hi(foo)
lw x11, %lo(foo)(x10)
ebreak

foo:
# Get it? foo, f00 …
.word 0xf00

The sw (“store word”)
instruction stores rs2 to a word in memory at address
rs2 + imm, in other words it writes the word to memory:

sw rs2, imm(rs1)

lui x10, %hi(foo)
lw x11, %lo(foo)(x10)

li x12, 0x123
sw x12, %lo(foo)(x10)

# Now it’s changed
lw x13, %lo(foo)(x10)
ebreak

foo:
.word 0xf00

Just to make absolutely sure we’re clear on this, load means reading from memory, store means writing to memory. Both
words can be nouns and verbs. Also, a word is 32-bit for RISC-V.

Let’s have some fun. Can we have the program read itself?

here:
lui x10, %hi(here)
lw x10, %lo(here)(x10)
ebreak

Ohh that’s fun. Does this mean I can also write programs with just
.word?

.word 0x40000537 # lui x10, %hi(here)
.word 0x00052503 # lw x10, %lo(here)(x10)
.word 0x00100073 # ebreak

Oh that’s nice. Just a peek into the world of machine code and
instruction encodings… which we will not be getting into.

With memory accesses under our belt, we can address a lot more data
easily. Here’s an example where we find the sum of all the values in an
array. Note how we can access different addresses of memory, whereas
there is no way to address a register by a number in another
register.

lui x10, %hi(array)
addi x10, x10, %lo(array)

li x11, 8 # length

# Get end address
slli x11, x11, 2
add x11, x11, x10

li x12, 0 # sum

loop:
# If current == end, done
beq x10, x11, end
lw x13, 0(x10) # Load from array
add x12, x12, x13 # Add to sum
addi x10, x10, 4 # Bump current pointer
j loop

end:
ebreak

array:
.word 13, 24, 6, 7, 8, 19, 0, 4

The equivalent in C would be something like

uint32_t array[], length;

uint32_t *current = array;
uint32_t *end = array + length;
uint32_t sum = 0;

for (; current != end; current ++) 
    sum += *current;

Note how adding one to a pointer to word bumps the address by 4,
because the addresses are all byte addresses, and one word is four
bytes. In C, the compiler handles the multiplier for you, but in
assembly you have to remember to do it manually.

Not everything in memory is word sized. You’ve already seen an array,
which is multiple-word-sized. There are also stuff smaller than
word-sized.

An obvious one is the byte,
which is, well, 1-byte/8-bit and written [u]int8_t in C. In
the middle is the halfword,
which is 2-byte/16-bit and written [u]int16_t in C. You can
use the directives .byte and .half respectively for those
data types.

.byte value [ , value [ , ...  ] ]
.half value [ , value [ , ...  ] ]

And just in case you don’t remember those, .2byte means the same as
.half, and .4byte means the same as
.word.

.2byte value [ , value [ , ...  ] ] # Same as .half
.4byte value [ , value [ , ...  ] ] # Same as .word

There’s a small problem with loading smaller-than-word sized values
into word-sized registers: What do you do with the rest of the bits?
Obviously the lowest of the bits gets the actual value loaded. There are
two most useful ways to fill the upper bits:

• zero extension: The
  higher bits are filled with zeros
• sign extension: The
  higher bits are filled with copies of the highest bit of the original
  value

Zero extension is easy enough. As the name suggests, sign extension
has something to do with signed values. It’s what happens when you
convert a narrower signed value into a wider one.

(Keeping the rest of the bits unchanged isn’t a good option. It
complicates the implementation for processor, especially of modern high
performance design, to just write parts of a register. It would be
easiest if the new value didn’t depend on the old value.)

For example, the signed byte value -100 is
0x9c. Since the highest bit i.e. the sign bit of it is
1, when we expand it into 32 bits we fill the high 24 bits
with one so the new value, 0xffff_ff9c still represents
-100. This is sign extension.

If we want to convert the unsigned byte value 156, still
0x9c, into an unsigned word, it would have to be
0x0000_009c to preserve its value.

For bytes, the lb
(“load byte”) instruction loads a byte and sign extends the result, and
the lbu (“load byte
unsigned”) instruction does the same but zero extends the result. As
with lw, the address is rs1 + imm.

lb rd, imm(rs1)
lbu rd, imm(rs1)

Similarly for lh
(“load half”) and lhu
(“load half unsigned”), just for unsigned halfwords (two bytes each,
remember):

lh rd, imm(rs1)
lhu rd, imm(rs1)

We can try out the sign extension and zero extension example from
earlier.

# Signed
li x10, -100
lui x11, %hi(test)
lb x11, %lo(test)(x11)

# Unsigned
li x12, 156
lui x13, %hi(test)
lbu x13, %lo(test)(x13)

ebreak

test:
.byte 0x9c

Correspondingly, the sb (“store byte”) and sh (“store half”) do the
opposite of lb and lh, storing bytes and
halfwords to memory. Instead of widening small values to register size,
these take the lowest order bits from rs1 and stores it to
memory. (There’s no sbu and shu because stores
are narrowing instead of widening operations.)

sb rs2, imm(rs1)
sh rs2, imm(rs1)

While we’re at it, here’s two more minor details. Firstly, endianness. While theoretically big
endian RISC-V machines can exist, I’ve never seen one… and this emulator
is little endian, meaning that the four bytes in a word are laid out in
memory lowest first. So, .byte 0x1, 0x2, 0x3, 0x4 would be
the same as .word 0x04030201.

lui x10, %hi(test)
lw x10, %lo(test)(x10)
ebreak

test:
.byte 0x1, 0x2, 0x3, 0x4

Secondly, memory accesses should be aligned for maximum efficiency. This
means that the address for a halfword/2byte should be a multiple of two,
and the address for a word/4byte should be a multiple of four.
Misaligned accesses (meaning, well, when the address is not aligned) may
not work as expected.

For user programs running on a rich operating systems, misaligned
accesses are supported but may be slow. In embedded application running
on microcontrollers and such, it might not work at all.

This emulator supports misaligned memory accesses.

lui x10, %hi(test)
addi x10, x10, %lo(test)

lw x11, 0(x10)
lw x12, 1(x10)
lw x13, 3(x10)

test:
.byte 1, 2, 3, 4, 5, 6, 7, 8

Now you can try translating some basic C code into RISC-V assembly.
Functions are… still out of the question for now. Variables have to be
either global or put in registers. What else are we missing…

Is it Hello World time? I think it’s Hello World time…

For a computer to not just be a space heater, we need some way for it
to at least generate output and take input. While other architectures
may have dedicated I/O instructions, RISC-V uses memory mapped I/O.
Essentially, this means that loads and stores to special addresses
communicate with other devices.
They do not work like normal memory, and you should only use the
supported widths to access them.

One output device we have here is at address
0x1000_0000. Any 32-bit writes to it appends the lowest 8
bits as a byte to the text in the output pane. In other words, a
sw to that address writes a byte of output.

(The output pane uses UTF-8 encoding.)

lui x11, %hi(0x10000000)
li x10, 0x48 # ‘H’
sw x10, 0(x11)
li x10, 0x69 # ‘i’
sw x10, 0(x11)
li x10, 0x21 # ‘!’
sw x10, 0(x11)
li x10, 0x0a # ‘\n’
sw x10, 0(x11)
ebreak

Eh, close enough to greeting the entire world. We could refactor it a
bit to use a loop, or whatever… Now that we think about it, how about
going one step further and organize our code into some functions?

We already know how to call a function and return back. Namely,
jal calls a function, and ret returns. Usually
functions take arguments, uses local variables, and returns results.
Since there’s no real difference between the 31 general purpose
registers, on account of them being, well, general purpose, we could
just use any of them as we wish. Usually though, there are some standard
conventions to follow

This whole time you probably have noticed that registers are listed
with two names each, and indeed both work identically in assembly.

li x10, 1
li a0, 1
ebreak

These register
aliases are named after their uses:

• s0 through
  s11 are saved registers
• t0 through
  t6 are temporary registers
• a0 through
  a7 are argument registers
• zero is the,
  well, zero register
• ra is for the
  return address, by convention, as we’ve seen
• sp … we’ll talk
  about sp later
• (The use of tp
  and gp is out of the
  scope of this document.)

(Yeah it’s… all placed in a weird order. The reason is out of the
scope of this tutorial.)

When you call a function, you put up to eight arguments in the… well,
argument registers, in the order a0, a1, …,
a7. After that you use jal or something, which
puts the return address in ra, and jumps to the
function.

Inside, the function, if it wishes to use the call-saved registers
s0 through s11, it must save their values at
the start of the function, and restore them before returning. The non
call-saved registers a0 through a7,
t0 through t6 and ra may be
modified without restoring their values.

When the called function is done, it would, as mentioned, restore any
used call-saved registers, and jump back to the return address, resuming
the calling code.

Here’s a basic-ish example:

int memcmp(const void *a, const void *b, size_t n)

The parameter a is passed in a0,
b is passed in a1, and n is
passed in a2. The return value will be in a0.
Here’s an implementation and test run:

# memcmp(test1, test2, 4)

lui a0, %hi(test1)
addi a0, a0, %lo(test1)
lui a1, %hi(test2)
addi a1, a1, %lo(test2)
li a2, 4
jal memcmp
ebreak

# int memcmp(const void *a, const void *b, size_t n);
memcmp:
add a3, a0, a2 # a3 = a + n
li t0, 0

memcmp_loop:
beq a0, a3, memcmp_done # No more bytes

lb t0, 0(a0)
lb t1, 0(a1)
sub t0, t0, t1 # t0 = *a – *b

bne t0, zero, memcmp_done # If different, done

addi a0, a0, 1 # a ++
addi a1, a1, 1 # b ++

j memcmp_loop

memcmp_done:
mv a0, t0
ret

test1:
.byte 1, 2, 3, 4
test2:
.byte 1, 2, 2, 4

Here’s a slightly better-organized “Hello World”, using a
puts function:

lui a0, %hi(msg)
addi a0, a0, %lo(msg)
jal puts
ebreak

# void puts(const char *);
puts:
lui t1, %hi(0x10000000)
puts_loop:
lb t0, 0(a0)
beq t0, zero, puts_done
sw t0, 0(t1)
addi a0, a0, 1
j puts_loop

puts_done:
ret

msg:
.byte 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x2c, 0x20, 0x77
.byte 0x6f, 0x72, 0x6c, 0x64, 0x21, 0x0a, 0x00

Although we can write some very basic functions now, there are still
a few problems:

• You can’t call a function within another function because if you do
  so ra would be overwritten, and then you can’t return back
  from the outer function anymore.
• We still don’t know how “saving” registers work.

Clearly, both would require using memory somehow. We can feed two
birds with one scone by using memory in a structured way: The stack.

Unlike some other architectures, the sp register is not
really special in any way. But just like how we can designate how
a0 is used, we can have some conventions about how
sp is supposed to be used:

• The register is call-saved, which means that when you return from a
  function, sp needs to have the same value as when the
  function was entered
• sp always points to somewhere in an area of
  memory called the “stack”, and it is always 16-byte
  aligned.

And, for the stack itself:

• On RISC-V, the stack grows to lower addresses, meaning that the
  memory where address >= sp are “in the stack”, and
  address < sp are free space that the stack can grow
  into.
• Code can allocate space on the stack by decrementing
  sp, and deallocate space by incrementing sp.
  Of course, allocations and deallocations must be balanced properly.
• You can only freely use space that you have allocated.

An example is in order. Let’s say you have a function
foo which just calls bar twice.

void foo() 
    bar();
    bar();

Inside foo, it would need to save the initial
ra, so it can return back later. Even though
ra takes only 4 bytes, sp needs to be 16-byte
aligned at all times, so we round that up to 16 bytes. Decrementing
sp by 16 we allocate the space:

foo:
    addi sp, sp, -16

Now, in addition to all of the non call-saved registers, we have 16
bytes of scratch space at sp through sp + 15.
We can backup the value of ra here

    ...
    sw ra, 0(sp)

Then we just call bar twice, which overwrites
ra:

    ...
    jal bar
    jal bar

At the end of the function, we just need to get back the return
address, deallocate the stack space, and return. Although using any
register would suffice for the return address, since it is the backed up
value of ra after all, we load it back to
ra.

    ...
    lw ra, 0(sp)
    addi sp, sp, 16
    ret

In a similar way you can save and restore the s
(remember, call-saved) registers. Usually, the most convenient way to
manage this is to put values that need to be preserved across inner
function calls in the s registers, and then add code at the
beginning to save them, and add code at the end to restore them.

Obligatory recursive Fibonacci time!

li a0, 10
jal fib
ebreak

fib:
li t0, 2

# If n < 2, then return n
bge a0, t0, fib_large
ret

fib_large:
# Otherwise, n >= 2

# Save stuff to stack
addi sp, sp, -16
sw ra, 0(sp)
sw s0, 4(sp)
sw s1, 8(sp)

mv s0, a0 # s0 = n
addi a0, a0, -1 # a0 = n – 1

jal fib
mv s1, a0 # s1 = fib(n – 1)

addi a0, s0, -2
jal fib # fib(n – 2)

add a0, a0, s1

# Restore stuff from stack and return
lw ra, 0(sp)
lw s0, 4(sp)
lw s1, 8(sp)
addi sp, sp, 16
ret

The algorithm should be fairly straightforward:

fibonacci(n) 
    if (n < 2)  return n; 
    else  return fib(n - 1) + fib(n - 2); 

What’s worth noting here is the fairly symmetric pattern of saving
registers at the start:

    addi sp, sp, -16
    sw ra, 0(sp)
    sw s0, 4(sp)
    sw s1, 8(sp)

And restoring them at the end:

    lw ra, 0(sp)
    lw s0, 4(sp)
    lw s1, 8(sp)
    addi sp, sp, 16
    ret

A little thing to also note that the s registers are
only saved in the more complex branch, where as the simpler branch just
returns directly. This is also acceptable from a calling convention
perspective.

(Note: In the emulator, the sp register is initialized
to an address that would be convenient for you for use as a stack, as a,
well, convenience.)

Let’s go back to this example:

    # void puts(const char *);
puts:
    lui t1, %hi(0x10000000)
puts_loop:
    lb t0, 0(a0)
    beq t0, zero, puts_done
    sw t0, 0(t1)
    addi a0, a0, 1
    j puts_loop

puts_done:
    ret

Having to name things like puts_loop,
puts_done is a bit annoying. There’s a shorter way: numeric labels.

A numeric label is one with a name of a decimal number. To refer to a
numeric label, use the number and a f suffix for “forward”,
and b for “backward”, and it will correspond to the nearest
numeric label with that number, searching forwards or backwards,
respectively.

So, the puts example from earlier can be rewritten:

    # void puts(const char *);
puts:
    lui t1, %hi(0x10000000)
1:
    lb t0, 0(a0)
    beq t0, zero, 2f
    sw t0, 0(t1)
    addi a0, a0, 1
    j 1b

2:
    ret

Yeah I don’t really like this syntax either, but it is what we’ve
got.

Remember that oddball instruction I mentioned way back,
auipc?

I don’t know about your experience, but the first time I saw RISC-V
disassembly, this is the one instruction that caught my eye. And this
memory has stuck with me ever since. It’s a rather common occurrence in
real RISC-V programs, and somehow I’ve been hiding it from you this
whole time. If you take a sneak peek at the next section’s title, you’ll
see how far we’ve come without auipc.

So what does it do?

The auipc (“add
upper immediate to pc”) instruction is very similar to lui.
Instead of setting rd to imm20 << 12, it
sets it to pc + (imm20 << 12), where pc
is the address of the auipc instruction itself.

auipc rd, imm20

It works very similarly to lui. You can think of them as
a pair: the “base” of lui is 0, whereas the
“base” of auipc is the address of the auipc
instruction. So this code:

start:
    auipc a0, 3
    addi a0, a0, 4

Gives you 0x3004, whereas this:

start:
    auipc a0, 3
    addi a0, a0, 4

Gives you start + 0x3004.

Why would you need this? On modern systems, it’s often desirable to
have machine code that can be moved around in address space. For
example, a shared library i.e. dynamically linked library can be loaded
into any program, at any address. It would be helpful if the machine
code does not need to be patched every time. This is called position independent
code (PIC).

Some instructions already exhibit position independence. For example,
as mentioned earlier when we talked about using lui and
jalr as a pair, the branch instructions and
jal are encoded, as with all RV32I instructions, into
32-bit instruction words, so they can’t possibly be able to encode every
possible address. Instead, the jump destination is pc plus
some offset (pc being, as before, the jump/branch
instruction itself), and the offset itself is encoded.

You can see these are three different instructions that jump to
itself. Since the offset is 0 in each case, the encoding is
the same. Use the “Dump” button to see for yourself.

ebreak

test1:
j test1

test2:
j test2

test3:
j test3

The auipc instruction allows for very flexible position
independence. You can make arbitrary calculations based on the address
at which code is located. The immediate-bit operand mirroring
lui means that it is well suited for two-instruction pairs,
just like lui. These kind of “pc plus
something” calculations are known as pc-relative
addressing.

The syntax for getting the assembler to generate the immediate values
for pc-relative addressing a bit arcane but hear me out:

1:
auipc a0, %pcrel_hi(foo)
addi a0, a0, %pcrel_lo(1b)
ebreak

foo:
.word 0x12345

Like %hi() and %lo(), %pcrel_hi() and %pcrel_lo() gives you
the immediate values needed for pc-relative addressing. You pass the
label you want to address to %pcrel_hi(), but pass a label
to the auipc instruction to
%pcrel_lo().

Unlike %lo(), We need the address of the
auipc instruction itself to calculate the immediate value,
and this is why you need to pass a label to it. You don’t need to write
foo again, since the assembler will look at the
auipc instruction and see it’s supposed to be for
foo.

If you hate writing that, you can also use the convenience
pseudoinstruction la:

la rd, label

Just like a lui + jalr pair, an
auipc + jalr can be used to jump to somewhere
farther away than one jal can reach in position-independent
code.

One very common case is to call a function that might not be within
reach of jal. You can use the pseudoinstruction call for that.

call label

This expands to:

1:
    auipc ra, %pcrel_hi(label)
    jalr ra, %pcrel_lo(1b)(ra)

Notice how ra is used as a temporary register to store
the intermediate result, which is immediately overwritten by
jalr.

In fact, there really isn’t any reason to prefer lui
over auipc when using a label. This is why you if you
disassemble a real RISC-V program, you see it everywhere, even in
non-position-independent code.

Now would be a good time to take a break, since we’re ready to head
into…

We’re going to write an extremely bare bones operating
system.

One of the tasks an operating system performs is to control what
programs can and cannot do. On RISC-V, the most basic of this control is
implemented using privilege
levels. RISC-V defines… let’s just say, several privilege
levels, but we’re only going to use two here:

• “Machine”, number 3
• “User”, number 0

The lower the privilege level number goes, the less privileged that
level is. Higher privilege levels treat lower privilege levels as
generally completely unreliable and untrusted, and must isolate
themselves from adversarial software and failures of lower privilege
levels.

(However, we won’t be talking about all of the features that make
this full isolation possible, and the emulator you’ve been seeing does
not have enough features for that anyway. Therefore, the operating
system we’ll be building will leave itself unprotected in various
ways.)

The privilege levels are sometimes called “modes” for short. And, if that’s not
short enough, we can shorten the level names themselves, ending up with
M-mode and U-mode. All of the ways to refer to
these privilege levels are interchangable.

When a RISC-V machine starts (This is known as “reset”), it begins execution in Machine
mode. On a typical “embedded” system where only Machine mode and User
mode are implemented, execution begins in the initialization code read
from flash memory. This code can either perform what needs to be done
itself, or it can be an operating system that manages some tasks, each
executing in User mode.

The former design is used for simpler programs, and is analogous to
the programs we’ve seen and run so far. The latter is more complicated.
We’ll see the basics of how to achieve that soon.

The control and
status registers (CSRs)
deal with various features that are in some sense “special”. No I don’t
have a better explanation of what “special” means.

Six instructions are available for manipulating CSRs.

csrrw rd, csr, rs1
csrrs rd, csr, rs1
csrrc rd, csr, rs1
csrrwi rd, csr, uimm5
csrrsi rd, csr, uimm5
csrrci rd, csr, uimm5

To refer to a CSR in these instructions, use its name in assembly
code. We’ll get to those in a bit.

The pattern works like this. Each of the instructions
atomically reads the old value of the CSR, and writes the new
value based on some operation performed on the old value and the last
operand. The possible operations are:

• csrrw (“CSR read
  write”): csr = rs1; rd = csr_old;
• csrrs (“CSR read
  set”): rs1; rd = csr_old;
• csrrc (“CSR read
  clear”): csr = csr & ~rs1; rd = csr_old;

Where &, |, ~ are bitwise
“and”, “or”, “not” respectively.

Specifically, note that rd and rs1 can be
the same. For example, this instruction swaps the value in
a0 and mscratch:

csrrw a0, mscratch, a0

For the “immediate” variants, instead of a register, they take an
“unsigned”/zero-extended 5-bit immediate value, i.e. an immediate value
0 through 31, inclusive. This is represented using uimm5 in
the assembly syntax description. The operation is the same
otherwise.

• csrrwi (“CSR
  read write immediate”): csr = uimm5; rd = csr_old;
• csrrsi (“CSR
  read set immediate”):
  csr = csr
• csrrci (“CSR
  read clear immediate”):
  csr = csr & ~uimm5; rd = csr_old;

The full feature set of these instructions are designed for
manipulating bit fields in CSRs, which we will not be doing that much of
in this tutorial. Still, this orthogonal design should be fairly
intuitive to remember.

CSRs and fields in CSRs do not behave like general purpose registers:
Some of them are read/write, some are read-only. Also, invalid values
have special behaviors. We will touch on more details as we introduce
the individual CSRs themselves, but one thing you may have noticed is
that we don’t seem to have read-only CSR instructions. Read-only access
is achieved using special cases in the instruction encodings:

• csrrs and csrrc do not write to the CSR if
  rs1 is x0 (a.k.a. zero) (Note
  that just the value of rs1 being 0 is not enough.)
• csrrsi and csrrci do not write to the CSR
  if uimm5 is 0.

While we’re at it:

• csrrw and csrrwi do not read the CSR if
  rd is x0 (a.k.a. zero). (Note
  that writing to x0 has no effect anyway, since it’s
  constant 0.)

(No standard RISC-V CSR is write-only, or has side effects on
read.)

As a convenience, the pseudoinstructions csrr (“CSR read”) and csrw (“CSR write”) are
available. csrw csr, rs1 expands to
csrrw x0, csr, rs1. Meanwhile, csrr rd, csr
expands specifically to csrrs rd, csr, x0, just so we can
agree on an encoding.

csrw csr, rs1
csrr rd, csr

You may have seen these CSR things if you’ve scrolled down on the
register view. Yes, we’re finally getting into those.

An example of CSRs is counters. Two basic read-only
counters are cycle and
instret. These
counters, well, count the number of “cycles” and “instructions
retired”. “Retired” is a technical term basically meaning “successfully
completed”.

Since a 32-bit counter will overflow quite fast, on RV32, the
counters have “high” counterparts: cycleh and instreth. So, for
example, the full cycle counter has 64 bits, with the lower 32 bits in
the CSR cycle and higher 32 bits in the CSR
cycleh.

While the emulator is running, scroll down on the register view
panel, and on the bottom you’ll see the values of these counters. For
convenience, they’re shown combined, so,
cycle = 0x11223344_55667788 means cycleh is
0x11223344, and cycle is
0x55667788.

On real hardware cycle is coupled to the clock cycle. In
this emulator, every time you press “Step”, it counts as a cycle. When
you press “Run” and it starts, well, running, a certain number of cycles
happen periodically.

Let’s look at a really simple example:

addi a0, a0, 1
addi a0, a0, 1
addi a0, a0, 1
ebreak

It takes 4 cycles for this program to stop, but instret
ends up at only 3 because the final ebreak instruction
never actually completes.

(Do not confuse “retired” with “retried”.)

A program can read its own counters. For example, this fun little
program loops until the cycle count is over 1000, assuming the low 32
bits doesn’t overflow before it has time to react:

li t1, 1000
loop:
csrr t0, cycle
blt t0, t1, loop

ebreak

Technically cycle and instret are not part
of the privileged architecture. The real fun begins now.

The emulator shows the current privilege level as
(priv). It is in parentheses to remind you of a very
important fact:

There is no CSR for the current privilege level.

A fundamental way an operating system does its job is through
handling exceptions. In general, exceptions occur when there’s a
problem with a specific instruction, and execution cannot continue. For
example, since cycle is a read-only CSR, writing to it is
an illegal instruction:

csrw cycle, x0

Since we have no exception handling in the program, we’ll have to
inspect what happened manually in the emulator. Indeed, a lot has
happened:

Firstly, this message tells you that an exception happened:

[ Exception: Illegal instruction (2) | tval = 0xc0001073, epc = 0x4000000c ]

The same information is now also available in the CSRs, as
follows:

• mcause (“M-mode
  trap cause”): The kind of exception.
• mepc (“M-mode
  exception pc”): The address of the instruction that caused the
  exception.
• mtval (“M-mode
  trap value”): Extra information about the exception.
• mstatus (“M-mode
  status”): It is set to 0x00001800. The two bits in the
  middle, mstatus[12:11] (In C syntax,
  (mstatus >> 11) & 0x3) is the
  mstatus.MPP (“M-mode previous privilege level”) field,
  which contains 3, meaning that the exception occurred while running in
  Machine mode.

When an exception happens, in addition to recording the exception
information in these CSR fields, pc is set to
mtvec, which is supposed to be the handler address. Let’s
write ourselves an exception handler that simply prints a message and
stops the emulator, and see the handling in action:

la t0, handler
csrw mtvec, t0

# Now cause an exception
csrw cycle, x0

# Rest of the main program is never executed
addi a0, a0, 1
addi a0, a0, 1

handler:
la a0, msg
call puts
ebreak

msg:
.byte 0x4f, 0x68, 0x20, 0x6e, 0x6f, 0x21, 0x0a, 0x00

# void puts(const char *);
puts:
lui t1, %hi(0x10000000)
1:
lb t0, 0(a0)
beq t0, zero, 2f
sw t0, 0(t1)
addi a0, a0, 1
j 1b

2:
ret

Yeah it just prints Oh no! on error. Baby steps…

The checkboxes “Pause on exc.” and “Print on exc.” control whether
the emulator should pause or print a message, respectively, when an
exception occurs. You can uncheck those if you want the exception
handler set in the program to run without interference.

(Another case that will cause a jump to mtvec is interrupts. However, this feature
does not exist in the emulator. The two cases are collectively called
traps.)

These are the exceptions possible in this emulator, and their
respective numeric codes:

“Instruction address misaligned” happens when attempting to jump to
an instruction that is not 4-byte aligned. The exception happens on the
jump or branch instruction, not the target.

“Load access fault” and “Store/AMO access fault” happens when
accessing an invalid memory address, or accessing a memory address in an
invalid way.

(“AMO” stands for “atomic memory operation”, which we will not talk
about and is not featured in the emulator.)

“Illegal instruction” happens not only in the self explanatory way
when an invalid instruction is executed, but also when accessing a CSR
in an invalid way, or from too low a privilege level.

“Breakpoint”, “Environment call from User mode” and “Environment call
from Machine mode” will be explained in a future section.

The mret (“M-mode
return”) instruction performs the reverse of part of what happens when
an exception occurs. To be precise, what happens is:

• The current privilege levels is set back to
  mstatus.MPP
• mstatus.MPP is set to 0
• pc is set to mepc

(You can think of the privilege mode bits as shifting in a chain
0 → MPP → priv. And, to be even more precise,
mstatus.MPP is set to the lowest supported privilege mode
since it’s not supposed to contain unsupported modes.)

mret takes no operands, so the assembly syntax is
simply:

mret

If we do mret after getting an exception, then we simply
go back to retrying the same instruction again. This is useful for more
featureful implementations, where for example, after handling a page
fault the correct course of action is to retry the faulting
instruction.

However, mstatus and mepc are also
writable. This gives us more flexibility in the use of
mret. As an analogy, the same jr instruction
(really jalr instruction) can be used to return from a
call, and also can be used to jump to any address. Similarly,
mret not only lets us return from an exception, but also
lets us jump to any address and switch to any privilege
level.

Even though mret is named “return”, it is in fact the
only way to lower the privilege level to enter User mode.
Here’s an example of entering User mode, with a User mode program that
does something bad:

la t0, handler
csrw mtvec, t0

lui t0, %hi(0x1800)
addi t0, t0, %lo(0x1800)

# Clear MPP to 0
csrrc zero, mstatus, t0

la t0, user_entry
csrw mepc, t0
mret

handler:
ebreak # Just stop the emulator

user_entry:
# Try to access an M-mode CSR
csrr a0, mstatus

As you can see, after we enter User mode, all of the CSRs used for
exception handling become completely inaccessible, not even readable. As
with writing a read-only CSR, accessing an CSR without permission also
causes an illegal instruction exception.

Moreover, when an exception happens, we go back to Machine mode, so
the exception handler runs in Machine mode. Here the handler does
nothing except stopping the emulator.

Sometimes, a program may wish to intentionally cause an exception.
There are several well-defined way to do that:

• The pseudoinstruction unimp has the same encoding
  as csrrw zero, cycle, zero, and it is the canonical RV32I
  illegal instruction. It causes causes an “Illegal instruction”
  exception.
• The instruction ebreak causes a
  “Breakpoint” exception
• The instruction ecall causes an
  “Environment call from User mode” exception when executed in User mode,
  and “Environment call from Machine mode” exception when executed in
  Machine mode.

Give those exceptions a try here:

la t0, handler
csrw mtvec, t0

lui t0, %hi(0x1800)
addi t0, t0, %lo(0x1800)

# Clear MPP to 0
csrrc zero, mstatus, t0

la t0, user_entry
csrw mepc, t0
mret

handler:
ebreak # Just stop the emulator

user_entry:
ebreak
# ecall
# unimp

As the names suggest, ebreak is used for debugging
breakpoints. As a special case, in this emulator ebreak in
Machine mode stops the emulator. You can think of it as the emulator
being a debugger, and the debugger catching the breakpoint.

unimp can be used to intentionally crash a program upon
detection of some unrecoverable error.

Meanwhile, ecall is used for things like system calls.
“Environment call from User mode” is a distinct exception cause code to
make it easy to check specifically for this case.

One thing that you would want in your trap handler is to not trust or
disturb any general purpose registers in the code that the trap
occurred in, unless you intentionally want to do so, for example to
return a value from a system call. So you’d want to save all the
registers to memory, before doing anything else. However, accessing
memory requires a general purpose register.

The mscratch
(“M-mode scratch”) CSR can help with this. This register, unlike all the
others, have no special functionality. It can hold any 32-bit value.
However, like all the other M-mode CSRs, it can only be accessed in
Machine mode. User mode code cannot change the value of it.

So for example, you can stash the operating system stack pointer in
mscratch before switching to User mode, and it will stay in
mscratch untouched in User mode. At the top of the handler,
csrrw sp, mscratch, sp to swap from the user stack pointer
to the operating system stack pointer.

handler:
    csrrw sp, mscratch, sp
    # Save registers except sp
    csrr t0, mscratch
    # t0 = user sp, save it
    # Save user pc
    ...

And, to restore:

    lw t0, ... # Load user pc
    csrw mepc, t0
    lw t0, ... # Load user sp
    csrw mscratch, t0
    # Restore registers except sp
    csrrw sp, mscratch, sp
    mret

We’ll see the full code for this in the following section.

We have enough of to write a very very bare bones operating system.
It will support these features:

• System calls:
  • a7 = 1: putchar, a0 is the byte to
    write
  • a7 = 2: exit
• Exception handling: Print error message and exit

We design the exception handling as follows:

• During most of the time in M-mode, mscratch is 0.
• While in U-mode, mscratch points to the operating
  system stack pointer
• At trap handler, if mscratch is 0, the exception came
  from M-mode, which we cannot handle, so we report a fatal
  exception.
• If it did come from U-mode, allocate 128 bytes on the stack to save
  the U-mode registers, and call trap_main, which manipulates
  U-mode registers in memory
• After trap_main, we restore registers from memory,
  deallocate the space from the stack, and go back to U-mode, as outlined
  in the previous section.

The structure to save registers in is fairly simple:

struct regs 
  unsigned long pc;
  unsigned long ra; // x1
  unsigned long sp; // x2
  ...
  unsigned long t6; // x31
;

Basically you can think of it as an array where element 0 is
pc, and elements 1 through 31 are registers x1 through
x31.

Inside trap_main, we check mcause to see if
it’s a system call. If it is, we dispatch based on a7. If
it’s not, we report an exception from U-mode.

At the beginning, we simply initialize the struct regs
structure on stack, initialize user sp and pc
in it, and jump to the same code that handles returning to U-mode.

Here’s the assembly code with User mode code at the bottom. You may
want to uncheck “Pause on exc.” and “Print on exc.” for convenience.

Do not be too hard on yourself if you have trouble understanding the
code fully. This is, after all, a fairly complete OS kernel entry and
exit implementation. Really, the most important part I’m showing you
here is that it is possible.

# Reserve 256 bytes for OS stack
# User stack starts 256 bytes lower
addi t2, sp, -256

la t0, handler
csrw mtvec, t0

# Prepare struct reg
addi sp, sp, -128

mv a0, sp # struct regs *

# Set user pc to user_entry
la t0, user_entry
sw t0, 0(a0)

# Set user sp
sw t2, 8(a0)

j enter_user

# void trap_main(struct regs *regs)
trap_main:
# Save regs based on calling convention
addi sp, sp, -16
sw s0, (sp)
sw ra, 4(sp)

mv s0, a0
csrr a1, mcause
li t1, 8 # “Environment call from User mode”
bne a1, t1, do_bad_exception # Not ecall, that’s bad

# Call do_syscall with args from ecall

lw a0, 40(s0)
lw a1, 44(s0)
lw a2, 48(s0)
lw a3, 52(s0)
lw a4, 56(s0)
lw a5, 60(s0)
lw a6, 64(s0)
lw a7, 68(s0)
call do_syscall

sw a0, 40(s0) # Set user a0 return value

# Bump user pc by 4
# Skip over ecall instruction
lw t0, 0(s0)
addi t0, t0, 4
sw t0, 0(s0)

# Restore regs based on calling convention
lw s0, (sp)
lw ra, 4(sp)
addi sp, sp, 16
ret

# a0 = arg0, a7 = syscall number
do_syscall:
# Dispatch based on syscall number
li t0, 1
beq a7, t0, sys_putchar
li t0, 2
beq a7, t0, sys_exit

# Bad syscall
li a0, -1
ret

# int sys_putchar(char c)
sys_putchar:
# Save regs based on calling convention
addi sp, sp, -16
sw s0, (sp)
sw ra, 4(sp)

call kputchar
li a0, 0

# Restore regs based on calling convention
lw s0, (sp)
lw ra, 4(sp)
addi sp, sp, 16
ret

# [[noreturn]] void sys_exit()
sys_exit:
# Just stop the emulator
ebreak

# [[noreturn]] void do_bad_exception(struct regs *regs, long cause)
# Print message about bad U-mode exception, then stop
do_bad_exception:
mv s0, a1

# Equivalent of printf(“Exception 0x%x”, cause);
la a0, msg_exception
call kputs

mv a0, s0
la t0, hex_chars
add t0, t0, a0
lbu a0, (t0)
call kputchar

li a0, 0xa # ‘\n’
call kputchar

# Stop the emulator
ebreak

fatal:
# Print message about fatal exception, then stop
la a0, msg_fatal
call kputs
ebreak

msg_exception:
# “Exception 0x”
.byte 0x45, 0x78, 0x63, 0x65, 0x70, 0x74, 0x69, 0x6f, 0x6e, 0x20, 0x30, 0x78, 0x00

msg_fatal:
# “Fatal exception\n”
.byte 0x46, 0x61, 0x74, 0x61, 0x6c, 0x20, 0x65, 0x78, 0x63, 0x65, 0x70, 0x74, 0x69, 0x6f, 0x6e, 0x0a, 0x00

hex_chars:
# “0123456789abcdef”
.byte 0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66, 0x00

.byte 0x00 # Alignment padding
# Otherwise, the next instruction wouldn’t be aligned

# void kputs(const char *);
# Print string by accessing MMIO directly
kputs:
lui t1, %hi(0x10000000)
1:
lb t0, 0(a0)
beq t0, zero, 2f
sw t0, 0(t1)
addi a0, a0, 1
j 1b
2:
ret

# void kputchar(char);
# Print byte by accessing MMIO directly
kputchar:
lui t1, %hi(0x10000000)
sw a0, (t1)
ret

# The big exception handler
handler:
csrrw sp, mscratch, sp

# If mscratch was 0, this is exception from M-mode
# Can’t handle that, it’s a fatal error
beq sp, zero, fatal

# Save all registers
addi sp, sp, -128
sw x1, 4(sp)
# x2/sp handled separately
sw x3, 12(sp)
sw x4, 16(sp)
sw x5, 20(sp)
sw x6, 24(sp)
sw x7, 28(sp)
sw x8, 32(sp)
sw x9, 36(sp)
sw x10, 40(sp)
sw x11, 44(sp)
sw x12, 48(sp)
sw x13, 52(sp)
sw x14, 56(sp)
sw x15, 60(sp)
sw x16, 64(sp)
sw x17, 68(sp)
sw x18, 72(sp)
sw x19, 76(sp)
sw x20, 80(sp)
sw x21, 84(sp)
sw x22, 88(sp)
sw x23, 92(sp)
sw x24, 96(sp)
sw x25, 100(sp)
sw x26, 104(sp)
sw x27, 108(sp)
sw x28, 112(sp)
sw x29, 116(sp)
sw x30, 120(sp)
sw x31, 124(sp)

# Save user sp, also set mscratch to 0 in M-mode
csrrw t0, mscratch, zero
sw t0, 8(sp)

# Save user pc
csrr t0, mepc
sw t0, 0(sp)

mv a0, sp
call trap_main
# … falls through after trap_main …
enter_user:
# Set mstatus.MPP = User
lui t0, %hi(0x1800)
addi t0, t0, %lo(0x1800)
csrrc zero, mstatus, t0

# Set mepc = user pc
# Will actually jump with mret
lw t0, 0(sp)
csrw mepc, t0

# Set mscratch = user sp temporarily
# Will swap right before mret
lw t0, 8(sp)
csrw mscratch, t0

# Restore other registers from stack
lw x1, 4(sp)
# x2/sp handled separately
lw x3, 12(sp)
lw x4, 16(sp)
lw x5, 20(sp)
lw x6, 24(sp)
lw x7, 28(sp)
lw x8, 32(sp)
lw x9, 36(sp)
lw x10, 40(sp)
lw x11, 44(sp)
lw x12, 48(sp)
lw x13, 52(sp)
lw x14, 56(sp)
lw x15, 60(sp)
lw x16, 64(sp)
lw x17, 68(sp)
lw x18, 72(sp)
lw x19, 76(sp)
lw x20, 80(sp)
lw x21, 84(sp)
lw x22, 88(sp)
lw x23, 92(sp)
lw x24, 96(sp)
lw x25, 100(sp)
lw x26, 104(sp)
lw x27, 108(sp)
lw x28, 112(sp)
lw x29, 116(sp)
lw x30, 120(sp)
lw x31, 124(sp)
addi sp, sp, 128

# Actually restore sp
csrrw sp, mscratch, sp
mret # Time to go to user mode!

################

user_entry:
la a0, msg_hello
call puts
call exit

# void puts(const char *);
# Print string using system call
puts:
addi sp, sp, -16
sw s0, (sp)
sw ra, 4(sp)

mv s0, a0
1:
lb a0, 0(s0)
beq a0, zero, 2f
call putchar
addi s0, s0, 1
j 1b
2:

lw s0, (sp)
lw ra, 4(sp)
addi sp, sp, 16
ret

# void putchar(const char *);
# Print byte using system call
putchar:
li a7, 1
ecall
ret

# [[noreturn]] void exit();
exit:
li a7, 2
ecall
# Not supposed to return, just to be safe
unimp

msg_hello:
.byte 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x20, 0x77, 0x6f, 0x72, 0x6c, 0x64, 0x21, 0x0a, 0x00

For reference, here’s some of the OS code in pseudo-C.

void trap_main(struct regs *regs) 
    unsigned long cause = csr_read(mcause);
    if (cause != 8)
        do_bad_exception(regs, cause);

    # Call do_syscall with args from ecall
    unsigned long ret = do_syscall(regs->a0, ..., regs->a7);
    regs->a0 = ret;

    // Bump user pc by 4, skip over ecall instruction
    regs->pc += 4;


unsigned long do_syscall(
    unsigned long a0,
    ...,
    unsigned long a7
) 
    if (a7 == 1)
        sys_putchar(a0);
    else if (a7 == 8)
        sys_exit();
    else
        return -1;


unsigned long sys_putchar(char a) 
    kputchar(a);
    return 0;


[[noreturn]]
unsigned long sys_exit(char a) 
    ebreak();


[[noreturn]]
void do_bad_exception(struct regs *regs, unsigned long cause) 
    kputs("Exception 0x");
    kputchar(hex_chars[cause]);
    kputchar('\n');
    ebreak();


[[noreturn]]
void fatal() 
    kputs("Fatal exception\n");
    ebreak();


void kputs(const char *str) 
    while (*str) 
        u32 val = (u32)*str;
        writel(0x10000000, val); // MMIO write
        str ++;
    


void kputchar(char c) 
    u32 val = (u32)c;
    writel(0x10000000, val); // MMIO write

And here’s the user code, again in pseudo C:

[[noreturn]]
void user_entry() 
    puts(...);
    exit();


void puts(const char *str) 
    while (*str) 
        putchar(*str);
        str ++;
    


void putchar(char c) 
    ecall(a0 = c, a7 = 1);


void exit() 
    ecall(a7 = 2);

As long as this tutorial is, some simplifications have been made.
Here are some of the most egregious lies and omissions, compared to the
“real” RISC-V architecture and “real” RISC-V assembly code found in the
world:

• The assembly syntax resembles the syntax used by LLVM assembler and
  GNU Binutils for RISC-V. However, it is not identical.
• There are a lot more pseudoinstructions and CSRs than what I have
  described.
• The li pseudoinstruction should support a wider range
  of constants.
• mstatus is a lot more complicated than what I have
  described.
• %hi, %lo, %pcrel_hi,
  %pcrel_lo are more complicated than what I have
  described.

There are also very important topics that are common or even
ubiquitous in the RISC-V world, but I chose not to cover:

• 64-bit architecture
• Compressed instructions
• Other privileged architecture and operating systems topics:
  Interrupts, memory protection, virtual memory, …

However, what I’ve taught you should be more than enough to get you
started into learning more on your own, or with further materials.

Here are some references and tutorials I would personally recommend,
if you’re looking to get further into RISC-V low-level development

Other useful resources that I have used while writing this
tutorial:

Thanks to these folks for UI design help and content suggestions: