RISC-V Assembly Programmming

While someone with no programming experience could probably learn RISC-V from this book, it is definitely preferable to have at least some experience in a higher level imperative programming language. I say imperative, because programming in assembly is the antithesis of functional programming; everything is about state, with each line changing the state of the CPU and sometimes memory. Given that, experience in functional languages like Lisp, Scheme etc. are less helpful than experience in C/C++, Java, Python, Javascript etc.

Of all of the latter, C is the best, with C++ being a close second because at least all of C exists in C++. There are many reasons C is the best prior experience when learning assembly (any assembly, not just RISC-V), including the following:

There is some overlap between those and there are probably more, but you can see that most other languages that are commonly taught as first languages are missing most, if not all of those things.

Even C++, which technically has all of them being a superset of C, is usually taught in a way that mostly ignores all of those things. They teach C++ as if it’s Java, never teaching the fundamentals. In any case this is getting into my problems with CS pedagogy of the last 20 years based on my experience as a CS major myself ('12) and as a programming tutor helping college students across the country since 2016, and I should save it for a proper essay/rant sometime.

Long story short, I use C code and C syntax to help explain and teach RISC-V. I’ll try to provide enough explanation regardless of past experience as best I can.

As I tell all of my tutoring students, if you’re majoring in CS or anything related I highly recommend you use Linux. It’s easier in every way to do dev work on Linux vs Windows or Mac. Many assignments require it, which often necessitates using a virtual machine (which is painful, especially on laptops) and/or ssh-ing into a school Linux server, which is also less than ideal. In general, you’ll have to learn how to use the Unix terminal eventually and will probably use it to some extent in your career so it also makes sense to get used to it asap.

That being said, Windows does now have WSL so you can get the full Ubuntu or Debian or Fedora etc. terminal based system on Windows without having to setup a real virtual machine (or dealing with the slowdown that would cause). I’ve even heard that they’ll get support for Linux GUI programs soon.

MacOS on the other hand, is technically a Unix based system and you can use their terminal and install virtually any program from there using Macports or Homebrew or similar.

There are a few RISC-V simulators that I know of and have used:

Of those three, RARS is by far the most full featured and user friendly for learning since it forked from the venerable MARS MIPS simulator. It is also the most commonly used by students outside of Berkeley. Given that, this book will focus primarily on RARS, though most of it applies equally well to Venus. Appendix A: Venus covers the differences between RARS and Venus.

You can download/access both at the following links:

There are a few references that you should bookmark (or download) before you get started. The first is the RISC-V Greensheet. It’s possible you already have a physical copy of this as it’s actually the tearout from the Patterson and Hennessey textbook Computer Architecture and Design that is commonly used in college courses. Berkeley provides a similar reference sheet with the same information.

There is also a large format of the greensheet.

The second thing is the list of environment calls (aka ecalls, system calls, syscalls) from the RARS wiki.

I recommend you download/bookmark both and keep them open while working because you’ll be referencing them often to remind yourself which instructions and ecalls you have available and how they work.

Let’s start with the classic hello world program, first in C, then in RISC-V, and go over all the pieces in overview. You can copy paste these into your editor of choice (mine being neovim), or use the files in the associated repo to follow along.

It is pretty self explanatory. You have to include stdio.h so you can use the function printf (though in the real world I’d use puts here), the function main is the start of any C/C++ program, which is a function that returns an int. We call printf to display the string "Hello World!\n" to the user and then return 0 to exit. Returning 0 indicates success and there were no errors.

You can compile and run it in a linux/unix terminal as shown below. You can substitute clang or another compiler for gcc if you want.

Now, the same program in RISC-V:

The .data section is where you declare global variables, which includes string literals as in this case. We’ll cover them in more detail later.

The .text section is where any code goes. Here we declare a single label main:, indicating the start of our main function.

We then put the number 4 in the a7 register to select the print string system call. The print string system call takes one argument, the address of the string to print, in the a0 register. We do that on the next line. On line 8, we call the system call using the ecall instruction.

Finally we call the exit system call which takes no arguments and exits the program.

Again, we’ll cover system calls in a later chapter. This is just an intro/overview so don’t worry if some things aren’t completely clear. This chapter is about getting you up and running, not really about teaching anything specific yet.

Now that we have our hello world RISC-V program, how do we run it? Well the easiest and quickest^[1] way is of course to do it on the command line, which can be done like this:

The name of your RARS jar file may be different^[2], so be sure to use the correct name and path. For myself, I keep the jar file in my home directory so I can use tilde to access it no matter where I am. You can also copy it into your working directory (ie wherever you have your source code) so you don’t have to specify a path at all. There are lots of useful command line options that you can use^[3], some of which we’ll touch on later.

Running the jar directly on the command line works even in the Windows/DOS command line though I’ve never done it and it’s probably not worth it.

Alternatively, you can start up RARS like a normal GUI application and then load your source file. RARS requires you to hit "assemble" and then "run".

Well, there you have it, you have written and run your first RISC-V program. Another few chapters and you will have no trouble with almost anything you would want to do in RISC-V, whether for a class, or on your own for fun.

You can support the book and purchase the chapter exercise solutions here.

purposes of learning and actually using assembly directly, there’s no reason to make your life harder than necessary.]

Obviously strings are special cases that can be handled with .ascii or .asciz (or the alias .string) for literals, but for other types or user inputed strings how do we do it?

The first way, which was demonstrated in the snippet above is to use .space to declare an array of the necessary byte size. Keep in mind that the size is specified in bytes not elements, so it only matches for character arrays. For arrays of ints/words, floats, doubles etc. you’d have to multiply by the sizeof(type).

"But, .space only lets you declare uninitialized arrays, how do I do initialized ones?"

Actually, it appears .space initializes everything to 0 similar to global/static data in C and C++, though I can’t find that documented anywhere.

Aside from that, there are two ways depending on whether you want to initialize every element to the same value or not.

For different values, the syntax is an extension of declaring a single variable of that type. You specify all the values, comma separated. This actually gives you another way to declare a string or a character array, though I can’t really think of a reason you’d want to. You could declare a .byte array and list all the characters individually.

However, if you want an array with all elements initialized to the same value there is a more convenient option. After the type you put the value you want, a colon, and then the number of elements. So a: .word 123 : 10 would declare a 10 integer array with all elements set to 123. Note, Venus does not support this syntax.

Given what we just covered, this:

becomes

For more examples of array declarations, see array_decls.s. You don’t have to understand the rest of the code, just that it prints out each of the arrays.

You can support the book and purchase the chapter exercise solutions here.

I’m using fgets() instead of scanf("%s", name) because fgets works the same as the read string ecall (8).

There a few things to note from the example.

We don’t declare global variables for age or height. We could, but there’s no reason to since we need them in registers to perform the addition anyway. Instead, we copy/save age to t0 so we can use a0 for 2 more ecalls, then add height to t0.

This is generally how it works. Use registers for local variables unless required to do otherwise. We’ll cover more about register use when we cover the RISC-V calling convention.

Another thing is when we print their name, we don’t put 4 in a7 again because it is still/already 4 from the lines above.

Lastly, many people will declare a string "\n" and use print string to print a newline, but it’s easier to use the print char ecall as we do right before exiting.

You can support the book and purchase the chapter exercise solutions here.

The rest of this chapter will be going over many examples, looking at snippets of code in C and translating them to RISC-V.

Branching and logic and learning to translate from higher level code to assembly is something that takes a lot of practice, but eventually it’ll become second nature. We’ll get more practice in the chapter on looping which naturally also involves branching.

One final note, there’s rarely any reason to use the slt family of opcodes unless your professor requires it for some strange reason. Even if your professor says you can’t use pseudoinstructions, that would still leave you with beq, bne, blt, bge, which covers every possibility even if you sometimes have to switch the order of the operands.

You can support the book and purchase the chapter exercise solutions here.

Looping and arrays go together like peanut butter and jam. An array is a sequence of variables of the same type, almost always related in some way. Naturally, you want to operate on them all together in various ways; sorting, searching, accumulating, etc. Given that the only way to do that is with loops, in this section we’ll cover different ways of looping through arrays, including multidimensional arrays.

Hopefully after those examples you have a more solid understanding of looping in RISC-V and how to transform various loops and array accesses into the form that makes your life the easiest. There is more we could cover here, like looping through a linked list, but I think that’s beyond the scope of what we’ve covered so far. Perhaps in a later chapter.

You can support the book and purchase the chapter exercise solutions here.

In assembly, a function is simply a label with a return instruction associated with it; because this is far more ambiguous than a function in a higher level language, it is good practice to only have a single return instruction associated with a function.^[8] A comment above the label is also helpful. Together those help you quickly see the start and end of the function.

would be

As you can see my policy is to put a single line comment of the C prototype above label.

But how do you call a function in assembly? You use the instruction Jump and Link: jal func_label. Let’s change the hello world program from chapter 0 to call a function:

What jal actually does, is save the address of the next instruction to ra and then do an unconditional jump to the function label. So you could achieve the same results with the following:

That would get tiring and ugly fast though, having to come up with unique labels for the next instruction every time. You also might be confused about why the greensheet says jal saves PC+4 in an arbitrary register R[rd] instead of ra specifically (which would be R[1]). The instruction does actually take a register argument but since it’s most commonly used to call a function if you don’t specify a register it will use ra as if you did jal ra, func. This works in conjunction with the pseudoinstruction ret which does PC=R[1] using the instruction jalr (specifically jalr x0, ra, 0) to easily return from functions. You might also see another way of returning using jr which stands for "Jump Register" and jumps to the address in the register, so to return from a function you’d do jr ra. It is also a pseudoinstruction that uses jalr. Unless your professor insists on something else, prefer ret; not only is it the shortest, returning from functions is its sole purpose.

We’ve gone as far as we can without starting to talk about registers and their purposes in functions. You can think of registers as variables^[9] that are part of the CPU. In this case, since we’re dealing with a 32-bit RISC-V architecture, they are 32-bit (aka 4 bytes, 1 word) variables.^[10] Since they’re part of the CPU, they exist for the life of the program and the whole program shares the same registers.

But how does that work? If all parts of the program use the same 32 registers, how does one function not stomp all over what another was doing when it uses them? In fact, how do functions communicate at all? How do they pass arguments or return results? All these questions are solved by deciding on a "Calling Convention". It’s different for different architectures and even different operating systems on the same architecture. This is because different architectures have different numbers of registers, and some registers like ra have semi-hardcoded uses. The the pseudoinstruction ret uses ra, and x0 is a constant 0 and there’s no way to change either of those facts. That still leaves a lot of flexibility when designing a calling convention. While they mostly match, you can probably find several variations of RISC-V calling conventions online. They usually differ in how they setup a stack frame. The convention covered in this chapter is consistent with, and sufficient for, almost every college course I’ve ever heard of.

Regardless, what matters is that the calling convention works by setting rules (and guidelines) for register use, and when/how to use the stack.

If you’re unfamiliar with the runtime stack, it’s exactly what it sounds like. It’s a Last-In-First-Out (LIFO) data structure that you can use to store smaller values in a program. It grows in a negative direction, so to allocate 12 bytes, you would subtract 12 from the stack pointer (in RISC-V that’s sp).

RISC-V specifically designates certain registers to be used for passing arguments (at least the first 8), a couple for return values, and others for misc. temporary or saved values. The rest are special use registers like ra.

The quickest way to summarize is to look at the table on the greensheet which is reproduced below:

To summarize, you have 15 registers that can be used anytime for temporary values, though some have special uses too (the a and t registers). You have 12 s registers that have to be saved on the stack if you use them, plus ra as well. The zero register is obviously a special case.

The sp register is technically preserved but not in the same way. Basically what you allocate (subtract) you have to deallocate (add) before returning from a function, thus preserving the original value.

You can ignore gp, tp, and most of the time fp too. Also, with 8 registers to pass arguments, you’ll almost never need to pass arguments on the stack.

While grasping the basics of a calling convention is not too difficult, it takes practice to get used to it. There are many things that we haven’t covered in this chapter, like how to pass more than 8 arguments, or use fp, or handle floating point arguments or return values. The latter at least, will be covered in the next chapter.

You can support the book and purchase the chapter exercise solutions here.

The greensheet contains all the floating point registers and their uses but you can also see them in the table below:

Likewise, you can look to the greensheet to see all the floating point instructions but here are the most important/useful ones:

Anywhere you see a [sd], use s or d for single or double precisision.

You only get equal, less than, and less than equal, but it’s easy enough to flip the operands or test for the opposite result to cover the others.

We’re going to briefly go over some of the more different aspects of dealing with floating point numbers, but since most of it is the same but with a new set of registers and calling convention, we won’t be rehashing most concepts.

The first thing to know when dealing with floats is how to get float (or double) literals into registers where you can actually operate on them.

There are two ways. The first, and simpler way, is to declare them as globals and then use the flw and fld instructions:

The second way is to use the regular registers and convert the values. Of course this means unless you want an integer value, you’d have to actually do it twice and divide, and even that would limit you to rational numbers. It looks like this:

As you can see, other than 0 which is a special case, it requires at least 2 instructions.

Branching based on floating point values is slightly different than normal. Instead of being able to test and jump in a single convenient instruction, you have to test first and then jump in a second instruction if the test was true or not. This is similar to the way x86 and MIPS (for floats) do it. For them, the test sets a special control/flag register (or a certain bit or bits in the register) and then all jumps are based on its state.

With RISC-V there is no special control register. The float comparisons are like the slt instructions where you choose a destination register to set to 1 (true) or 0 (false).

Using them looks like this:

Finally, lets do a simple example of writing a function that takes a float and returns a float. I’m not going to bother doing one for doubles because it’d be effectively the same, or doing one that requires the stack, because the only differences from normal are a new set of registers and knowing which ones to save or not from the table above.

So, how about a function to convert a fahrenheit temperature to celsius:

You can see we follow the convention with the argument coming, and the result being returned, in fa0. In this function we use both methods for getting a value into float registers; one we load from memory and the other, being an integer, we convert directly.

As I said before, it is rare for courses to even bother covering floating point instructions or assign any homework or projects that use them. Venus doesn’t even support floating point instructions. Hopefully this brief overview, combined with the knowledge of previous chapters is sufficient if you do need or want to work with floating point values.

There are also 2 example programs conversions.s and calc_pi.s for you to study.

You can support the book and purchase the chapter exercise solutions here.

You may have noticed I have a general format I like to follow when writing RISC-V (or any) assembly. The guidelines I use are the following

One of the easiest things you can do to make your programs more readable is to use defined constants in your programs. RARS has a way of defining constants similar to how C defines macro constants; ie they aren’t "constant variables" that take up space in memory, it’s as if a search+replace was done on them right before assembling the program.

Let’s look at our Hello World program using constants:

RARS supports function style macros that can shorten your code and improve readability in some cases (though I feel it can also make it worse or be a wash).

The syntax looks like this:

Some common examples are using them to print strings:

You can see an example program in macros.s.

It is relatively common in programming to compare an integral type variable (ie basically any built-in type but float and double) against a bunch of different constants and do something different based on what it matches or if it matches none.

This could be done with a long if-else-if chain, but the longer the chain the more likely the programmer is to choose a switch-case statement instead.

Here’s a pretty short/simple example in C:

You could translate this to its eqivalent if-else chain and handle it like we cover in the chapter on branching. However, imagine if this switch statment had a dozen cases, two dozen etc. The RISC-V code for that quickly becomes long and ugly.

So what if we implemented it in RISC-V the same way it is semantically in C? The same way compilers often (but not necessarily) use? Well, before we do that, what is a switch actually doing? It is jumping to a specific case label based on the value in the specified variable. It then starts executing, falling through any other labels, till it hits a break which will jump to the end of the switch block. If the value does not have its own case label, it will jump to the default label.

Compilers handle it by creating what’s called a jump table, basically an array of label addresses, and using the variable to calculate an index in the table to use to jump to.

The C eqivalent of that would look like this:

The && and goto *var syntax are actually not standard C/C++ but are GNU extensions that are supported in gcc (naturally) and clang, possibly others.^[12]

First, notice how the size of the jump table is the value of the highest valued label minus the lowest + 1. That’s why we subtract the lowest value to shift the range to start at 0 for the indexing. Second, any values without labels within that range are filled with the default_label address. Third, there has to be an initial check for values outside the range to jump to default otherwise you could get an error from an invalid access outside of the array’s bounds.

The same program/code in RISC-V would look like this:

You can see we can use the pseudoinstruction jr (jump register) to do the eqivalent of the computed goto statement in C.

This example probably wasn’t worth making switch style, because the overhead and extra code of making the table and preparing to jump balanced out or even outweighed the savings of a branch instruction for every case. However, as the number of options increases, the favor tilts toward using a jump table like this as long as the range of values isn’t too sparse. If the range of values is in the 100’s or 1000’s but you only have cases for a dozen or so, then obviously it isn’t worth creating a table that large only to fill it almost entirely with the default label address.

To reiterate, remember it is not about the magnitude of the actual values you’re looking for, only the difference between the highest and lowest because high - low + 1 is the size of your table.

Command line arguments, also known as program arguments, or command line parameters, are strings that are passed to the program on startup. In high level languages like C, they are accessed through the parameters to the main function (naturally):

As you can see, argc contains the number of parameters and argv is an array of those arguments as C strings. If you run this program you’ll get something like this:

Notice that the first argument is what you actually typed to invoke the program, so you always have at least one argument.

RISC-V works the same way. The number of arguments is in a0 and an array of strings is in a1 when main starts. So the same program in RISC-V looks like this:

Unfortunately, RARS works slightly differently, probably because it’s more GUI focused. It does not pass the program/file name as the first argument, so you can actually get 0 arguments:

You can see that you have to pass "pa" (for "program arguments") to indicate that the following strings are arguments. In the GUI, there is an option in "Settings" called "Program arguments provided to progam" which if selected will add a text box above the Text Segment for you to enter in the arguments to be passed.

One relatively common assignment requirement is forbidding pseudoinstructions, either all of them, or some subset of them. This forces us to explicitly write what those pseudoinstructions are translated into (or could be translated into since there are often several alternatives).

You can see how you use the non-pseudoinstructions to match the same behavior, and there’s often (usually) more than one way.

Another thing I should comment on is the la equivalence. The reason it is a pseudoinstruction in the first place is that an address is 32 bits. That’s also the size of a whole instruction. Clearly there’s no way to represent a whole address and anything else at the same time. The lower right corner of the greensheet has the actual formats of the 6 different types of instructions and even the U and UJ formats still needs 12 bits for the opcode and destination. This is why lui (and auipc) exists, in order to facilitate getting a full address into a register by doing it in two halves, 20 + 12. The lower 12 can be placed with addi or ori after the lui.

That begs the question, what actually goes in the upper half? Well, since we’re dealing with addresses in the .data section, the upper portion should match the upper part of address of the .data section. In RARS the .data section starts at 0x10010000.

But what about the lower part of the address? This involves counting the bytes from the top of .data to the label you want. If all you have is words, halfs, floats, doubles, or space (with a round number), that’s fairly easy, but the second you have strings between the start and the label you want, it’s a bit more painful. This is why I recommend putting any string declarations at the bottom so at least any other globals will have nice even offsets. Also, if you have a bunch of globals, it doesn’t hurt to count once and put the offsets in comments above each label so you don’t forget. Of course, none of this matters if you’re allowed to just use la which is true the vast majority of the time.

Let’s look at a small example. We’ll convert the args.s from above (reproduced here for convenience) to bare mode:

So we need to change the mv, the li's, the j, and the la.

Following the table, you can see the mv became or, the li became ori, the j became jal with x0 as the destination register, and lastly the la became lui plus an ori if necessary for the byte offset.

You can support the book and purchase the chapter exercise solutions here.

Unlike RARS which seems to have one primary and fairly well maintained stable version, and a few even more updated forks, Venus is less clear. As far as I can tell it was started by kvakil 5 years ago, was forked by ThaumicMekanism, and finally was forked by Berkeley for their cs61c course. While the latter has the most recent commit none of them are what I would call well maintained, with the former 2 seeming to stall in 2018 and 2020 respectively. Venus (all versions) has a web based interface but I don’t know why anyone would prefer that to the standalone JAR version.

As of the end of 2022 you can get Venus jar files from ThaumicMekanism’s github here or from Berkeley’s course website here.

I don’t know what the minor differences are between them but you should use whatever is provided by the course if you’re taking it.

The documentation is sorely lacking and out of date but the most relevant differences from RARS are that it uses .asciiz instead of .asciz and while .float and .double are reserved, Venus doesn’t actually support floating point instructions so you can’t actually do anything with them.

The only documentation I can find is from ThaumicMekanism’s wiki and it doesn’t mention .space even though Venus seems to allow it.^[13] CS61C’s documentation doesn’t mention data directives at all.^[14]

Venus only supports a handful of ecalls and they work differently than they do in RARS. Again, the only documentation I can find is ThaumicMekanism’s.^[15]

There is one that I know of that is not listed in that table. Ecall 5 is basically the C function atoi which converts a string to an integer. It takes the address of the string in a1 and returns the number in a0. If there is any leading or trailing whitespace or the string isn’t a valid number it returns 0.

One thing you might have noticed is that Venus doesn’t support any of the input ecalls. This is extremely limiting since you can’t write any interactive programs and to test a function you have to actually change the program (usually a variable in the data section) and re-run it. The only way to even get variable program behavior is to use the file input capability to read data and do something different based on that input.

But aside from the lack of some basic ecalls, there’s also a behavioral difference in how they work. In RARS, you use a7 to select the ecall leaving the lower a registers for arguments which matches how you would pass arguments to a function. Venus uses a0 to select the ecall which means your argument(s) start in a1. This is probably why they provide wrapper functions for the ecalls to students for their projects, though it took until recently to get them right.

So, what does this look like in practice? Let’s take the simple command line argument program from chapter 7 and convert it for Venus. So the following program:

becomes

Note that we had to save argv beacuse a1 is now used in our ecalls. In addition the behavior is different than RARS:

RARS may have decided not to include the program name/"executable" in its arguments but at least it is consistent in its behavior. In addition, the section on passing arguments in CS 61C’s documentation is inaccurate as of December 2022. Just like with C and RARS, argc comes first in a0 then argv in a1, not the other way around as described.^[16]

Another minor difference from RARS is how you declare constants. In Venus you use the same syntax as C, so the constants example from chapter 7:

becomes

While most of this book applies equally well to both programs (other than chapter 6 of course) and to RISC-V in general, this appendix should clear up any difficulties you might have run into trying to convert the examples to run in Venus. Hopefully Berkeley will decide to switch to RARS eventually.