{"id":22,"date":"2019-11-06T08:03:00","date_gmt":"2019-11-06T13:03:00","guid":{"rendered":"https:\/\/www.vociferousvoid.org\/?p=22"},"modified":"2023-07-01T21:40:02","modified_gmt":"2023-07-02T01:40:02","slug":"risc-v-bare-metal-programming-chapter-2-opcodes-assemble","status":"publish","type":"post","link":"https:\/\/www.vociferousvoid.org\/index.php\/2019\/11\/06\/risc-v-bare-metal-programming-chapter-2-opcodes-assemble\/","title":{"rendered":"RISC-V Bare Metal Programming Chapter 2: OpCodes Assemble!"},"content":{"rendered":"\n

The previous chapter<\/a> of this tutorial went over the steps required to setup a RISC-V development environment to create a program that runs on a bare metal VirtIO board using QEMU. Even though the example program \u2013 which calculates the sum two integers \u2013 was written in RISC-V assembly, no prior knowledge was required to follow along. This chapter will dive into the details of RISC-V assembly language as well as expand on what exactly is happening at each step of the development. The topics covered in this chapter will include an overview of the RISC-V architecture, its assembly instructions, pseudo-instructions, and directives.<\/p>\n\n\n\n

The following listing illustrates the assembly code of the add.s<\/code> program from the previous chapter:<\/p>\n\n\n\n

1:         .text\n2:         .global _start\n3: _start:\n4:         li      a0, 5\n5:         li      a1, 4\n6:         add     a0, a0, a1\n7: stop:   j       stop<\/code><\/pre>\n\n\n\n
The code was changed a little to use a different set of registers. This program when assembled results in an object file which can then be linked to create the file that will be loaded onto the board. In this scenario, only the one object file is used, however, more complex programs may required more than one object file. The linker’s job is to put all of these files together into a single executable program.<\/p>\n\n\n\n
This add.s<\/code> program is composed of one instruction (6<\/a>), three pseudo-instructions (4<\/a> 5<\/a>, and 7<\/a>), and two directives (1<\/a>, 2<\/a>). Moreover, the instructions and pseudo-instructions have operands comprised of either registers or immediates. Understanding each of these entities will help when creating more complex programs in RISC-V assembly.<\/p>\n\n\n\n
Registers<\/h1>\n\n\n\n
RISC-V systems will have a base set of 32 registers x0-x31<\/code>. The x0<\/code> register is read-only with a value fixed to zero. The rest will have varying content. The application binary interface (ABI) prescribes conventions for the name and usage of the various registers. These are listed in the following table:<\/p>\n\n\n\n
Register(s)<\/th>ABI Name(s)<\/th>Description<\/th>Saved by<\/th><\/tr><\/thead>
x0<\/td>zero<\/td>Hard-wired zero<\/td>N\/A<\/td><\/tr>
x1<\/td>ra<\/td>Function return address<\/td>Caller<\/td><\/tr>
x2<\/td>sp<\/td>Stack pointer<\/td>Callee<\/td><\/tr>
x3<\/td>gp<\/td>Global pointer<\/td>N\/A<\/td><\/tr>
x4<\/td>tp<\/td>Thread pointer<\/td>N\/A<\/td><\/tr>
x5<\/td>t0<\/td>Temporary\/alternate link register<\/td>Caller<\/td><\/tr>
x6-x7<\/td>t1-t2<\/td>Temporary values<\/td>Caller<\/td><\/tr>
x8<\/td>s0\/fp<\/td>Saved register\/Frame pointer<\/td>Callee<\/td><\/tr>
x9<\/td>s1<\/td>Saved register<\/td>Callee<\/td><\/tr>
x10-x11<\/td>a0-a1<\/td>Function arguments\/Return values<\/td>Caller<\/td><\/tr>
x12-x17<\/td>a2-a7<\/td>Function arguments<\/td>Caller<\/td><\/tr>
x18-x27<\/td>s2-s11<\/td>Saved registers<\/td>Callee<\/td><\/tr>
x28-x31<\/td>t3-t6<\/td>Temporary values<\/td>Caller<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Registers can be referred by their ABI names or their actual names in assembly programs; the two are interchangeable.<\/p>\n\n\n\n
When a function is invoked, it may modify the values of some of these registers. For this reason it is advisable to save the contents of those registers in memory in order to be able to restore them when the function completes. The ABI convention prescribes which party in a function call (the caller or the callee) is responsible for saving these values. This convention is described in the “Saved by” column of the table.<\/p>\n\n\n\n
If a register is to be saved by the caller, its value should be stored in a frame of the stack, that was allocated for that purpose, prior to calling the function. This ensures that the values can be restored when the function returns. In general, it is a good idea to save all of the registers if the caller does not know which registers may be modified by the callee.<\/p>\n\n\n\n
Registers to be saved by the callee only need to be saved to memory if the function uses those registers. Functions must not leave a trace, the state of the machine must be the same as it was prior to the function being invoked (with the exception of the desired function result).<\/p>\n\n\n\n
A function implementation defined in RISC-V assembly should use the following prologue before doing any of its work:<\/p>\n\n\n\n
function_label:\n        addi    sp, sp, -framesize      # The stack grows downward\n        sd      ra,framesize-8(sp)      # Save the return address\n        # Save registers owned by the callee as needed to memory.<\/code><\/pre>\n\n\n\n
This will ensure that the function can return to the point where it was called, and that any register state will be saved.<\/p>\n\n\n\n
Before a function returns, the saved register values must be restored. This is achieved by the following epilogue which should end a function call.<\/p>\n\n\n\n
# restore registers from the stack if needed\n        ld      ra, framesize-8(sp)     # Restore the return address register\n        addi    sp, sp, framesize       # Pop the stack\n        ret     # return to the caller<\/code><\/pre>\n\n\n\n
This will restore the saved registers, set the return address and de-allocate the stack frame that was used to save this information.<\/p>\n\n\n\n
The add.s<\/code> program can be enhanced to use the function prologue and epliogue to define a function that calculates the sum its arguments in registers a0<\/code> and a1<\/code>. This new program is illustrated in the listing that follows:<\/p>\n\n\n\n
        .text\n        .align 2\n        .global sum\nsum:\n        addi    sp, sp, -32     # Stack frames must be 16-bit aligned\n        sd      ra, 24(sp)      # Save the return address\n        add     a0, a0, a1      # Add the function operands\n        ld      ra, 24(sp)      # restore return address\n        addi    sp, sp, 32      # De-allocate the stack frame\n        ret<\/code><\/pre>\n\n\n\n
The sum <\/code>function can be called by name from a different assembler program. Create a main.s<\/code> program with the following content:<\/p>\n\n\n\n
        .text\n        .align 2\n        .global _start\n_start:\n        li      a0, 5\n        li      a1, 4\n        call    sum\nstop:   j       stop<\/code><\/pre>\n\n\n\n
This will load the values 5 and 4 into the registers used for arguments to the the sum function and call it. This can be assembled and linked as follows:<\/p>\n\n\n\n
$ riscv64-unknown-elf-as -o add.o add.s\n$ riscv64-unknown-elf-as -o main.o main.s\n$ riscv64-unknown-elf-ld -Ttext=0x80000000 -o sum.elf main.o add.o<\/code><\/pre>\n\n\n\n
If this program is assembled, linked, and run in QEMU, it will call the sum<\/code> function to calculate the sum of the operands. This can be verified by inspecting the value of register a0<\/code> which should be 9.<\/p>\n\n\n\n
\n
NOTE<\/strong>: The order in which the object files are supplied to the linker is important. If the add.o<\/code> file is supplied first, the program will not run because its content will be located at the reset address.<\/p>\n<\/blockquote>\n\n\n\n
Instructions<\/h1>\n\n\n\n
Instructions are mnemonics that map directly to machine codes. For example the add<\/code> instruction in the sum<\/code> function corresponds with the op-code 0x33<\/code> (or b0110011<\/code>).<\/p>\n\n\n\n
When the add<\/code> instruction is combined with its operands, the result is a single machine instruction. In RISC-V, all machine instructions are 32-bits long (unless you’re using the compressed extension, but for now we’ll just deal with 32-bit operations).<\/p>\n\n\n\n
The add<\/code> instruction is what’s known as an R-type instruction because its operands are all registers. This type of instruction has the following form:<\/p>\n\n\n\n
BITS<\/th>31:25<\/th>24:20<\/th>19:15<\/th>14:12<\/th>11:7<\/th>6:0<\/th><\/tr><\/thead>
R-Type<\/td>func7<\/td>rs2<\/td>rs1<\/td>func3<\/td>rd<\/td>opcode<\/td><\/tr><\/tbody><\/table>
Structure of the R-Type op-codes<\/figcaption><\/figure>\n\n\n\n
In this table, the operation’s function is a combination of func7<\/strong> and func3<\/strong>. For the add<\/code> instruction, this is b0000000<\/code> and b000<\/code>. The rs2<\/strong> and rs1<\/strong> field are the source registers whose value will be added. The rd<\/strong> field will be the destination register for the result. Notice that the register fields are 5-bits wide. This allows the instruction to reference any of the 32 base registers (i.e. 25<\/sup> registers). The add<\/code> instruction from the previous example will be constructed as follows:<\/p>\n\n\n\n