RISC-V Base Integer Instruction Set

0.0 - Table of Contents

• 0.0 - Table of Contents
• 0.1 - Using This Document
• 1.0 - About RISC-V
• 2.0 - RV32I Specifications
• 2.1 - Memory
• 2.2 - Registers
• 2.3 - Program Counter
• 2.4 - Instruction Formats
• 2.5 - Immediate Encoding
• 3.0 - RV32I Instructions
• 3.1 - Integer Register-Register
• ADD   SUB   AND   OR   XOR   SLL   SRL   SRA   SLT   SLTU
• 3.2 - Integer Register-Immediate
• ADDI   ANDI   ORI   XORI   SLTI   SLTIU   SLLI   SRLI   SRAI
• 3.3 - Upper Immediate
• LUI   AUIPC
• 3.4 - Loads
• LW   LH   LB   LHU   LBU
• 3.5 - Stores
• SW   SH   SB
• 3.6 - Branches
• BEQ   BNE   BLT   BGE   BLTU   BGEU
• 3.7 - Jumps
• JAL   JALR
• 3.8 - System
• ECALL   EBREAK
• 4.0 - Opcode Map
• 5.0 - Emulator Implementation Notes
• 5.1 - Fetch-Decode-Execute Loop
• 5.2 - Field Extraction in C
• 5.3 - Sign Extension

0.1 - Using This Document [TOC]

This document is a technical reference for the RISC-V RV32I base integer instruction set, written specifically for people building an emulator in C. It covers only the 32-bit base integer ISA (RV32I). Extensions such as M (multiply/divide), A (atomics), F (float), and D (double) are not covered here.

Throughout this document, the following notation is used:

• x[rd] — the destination register
• x[rs1] — the first source register
• x[rs2] — the second source register
• imm — a sign-extended immediate value
• PC — the Program Counter
• M[addr] — memory at address addr
• sext(x) — sign-extend x to 32 bits
• All integer values are in hexadecimal unless otherwise stated

1.0 - About RISC-V [TOC]

RISC-V (pronounced "risk five") is a free and open instruction set architecture (ISA) developed at UC Berkeley, first released in 2010. Unlike x86 or ARM, the RISC-V ISA specification is publicly available and not encumbered by patents or licensing fees, making it ideal for education, research, and custom hardware design.

RISC-V follows the Reduced Instruction Set Computer (RISC) philosophy: a small number of simple instructions that execute in one cycle, fixed-width instruction encoding, and a large register file. The base integer ISA, called RV32I, contains only 47 instructions. This makes it the ideal architecture for building a first CPU emulator.

The RISC-V ISA is modular. The base integer ISA (I) can be extended with standard extensions:

This document covers RV32I only. Implement this base set first before adding any extensions.

2.0 - RV32I Specifications [TOC]

This section describes the memory model, register file, program counter, and instruction encoding of RV32I.

2.1 - Memory [TOC]

RV32I uses a flat, byte-addressable memory space of 2³² bytes (4 GB). Addresses are 32-bit unsigned integers. All memory accesses are performed through load and store instructions — there are no memory-to-memory operations.

For an emulator, memory is implemented as a simple byte array:

#define MEM_SIZE (1024 * 1024)   /* 1 MB is enough to run small programs */
uint8_t memory[MEM_SIZE];

A typical memory layout when loading a program looks like this:

+---------------------------+= 0xFFFFFFFF  top of address space
|                           |
|       (unmapped)          |
|                           |
+---------------------------+
|                           |
|        Stack              |  grows downward from high address
|           |               |
|           v               |
|                           |
|           ^               |
|           |               |
|        Heap               |  grows upward
|                           |
+---------------------------+= depends on program
|       .data / .bss        |  initialized and uninitialised globals
+---------------------------+
|       .text               |  program instructions (read-only)
+---------------------------+= entry point (from ELF header, e.g. 0x00010000)
|                           |
|      (reserved)           |
|                           |
+---------------------------+= 0x00000000  bottom of address space

RISC-V is a little-endian architecture. The least-significant byte of a multi-byte value is stored at the lowest address. On an x86 or x86-64 host, this matches the host byte order, so you can read multi-byte values with a direct pointer cast.

2.2 - Registers [TOC]

RV32I has 32 general-purpose integer registers, each 32 bits wide, named x0 through x31. Register x0 is special: it is hardwired to the value zero. Any write to x0 is silently discarded. Any read from x0 always returns 0x00000000.

Each register also has an ABI (Application Binary Interface) name used in assembly language. The ABI names reflect the register's conventional purpose when calling functions:

In your emulator, implement two wrapper functions for register access that enforce the x0 rule:

uint32_t reg_read(CPU *cpu, uint32_t r)              { return (r == 0) ? 0 : cpu->regs[r]; }
void     reg_write(CPU *cpu, uint32_t r, uint32_t v) { if (r != 0) cpu->regs[r] = v; }

2.3 - Program Counter [TOC]

The Program Counter (PC) is a separate 32-bit register, not part of the general-purpose register file. It holds the address of the instruction currently being executed.

After most instructions the PC advances by 4 (one instruction = 4 bytes). Branch and jump instructions set the PC to a computed target address instead. The PC must always be aligned to a 4-byte boundary. Misaligned PC values cause an instruction-address-misaligned exception (which you can ignore in a basic emulator).

2.4 - Instruction Formats [TOC]

Every RV32I instruction is exactly 32 bits wide. There are six instruction formats. The opcode field is always in bits [6:0] regardless of format. The other fields change position depending on the format.

Field sizes:

2.5 - Immediate Encoding [TOC]

Immediate values are embedded in the instruction word. The sign bit of every immediate is always placed at bit 31 of the instruction, which allows for fast sign extension in hardware. Some formats (B and J) have their immediate bits shuffled to simplify hardware layout — you must reassemble them in the correct order in your emulator.

Immediate extraction in C for each format:

/* I-type: 12-bit signed immediate, bits [31:20], sign-extended */
int32_t imm_i = (int32_t)instr >> 20;

/* S-type: 12-bit signed immediate, split across [31:25] and [11:7] */
int32_t imm_s = ((int32_t)instr >> 20 & ~0x1F) | ((instr >> 7) & 0x1F);

/* B-type: 13-bit signed immediate, bit 0 always 0 (halfword aligned) */
/*   bit[12] = instr[31]   bit[11] = instr[7]                          */
/*   bit[10:5] = instr[30:25]   bit[4:1] = instr[11:8]                 */
int32_t imm_b = ((int32_t)(instr & 0x80000000) >> 19)
              | ((instr & 0x00000080) << 4)
              | ((instr >> 20) & 0x7E0)
              | ((instr >> 7)  & 0x1E);

/* U-type: 20-bit immediate in upper bits, lower 12 bits are zero */
uint32_t imm_u = instr & 0xFFFFF000;

/* J-type: 21-bit signed immediate, bit 0 always 0                     */
/*   bit[20] = instr[31]   bit[19:12] = instr[19:12]                   */
/*   bit[11] = instr[20]   bit[10:1] = instr[30:21]                    */
int32_t imm_j = ((int32_t)(instr & 0x80000000) >> 11)
              | (instr & 0x000FF000)
              | ((instr >> 9)  & 0x800)
              | ((instr >> 20) & 0x7FE);

3.0 - RV32I Instructions [TOC]

All 47 base RV32I instructions are described below, grouped by instruction type. Each entry shows the assembly syntax, the opcode and function codes needed to identify it, and the operation it performs.

3.1 - Integer Register-Register [TOC]

These instructions take two source registers and write a result to a destination register. All use opcode 0x33 (R-type). The funct3 field selects the operation; funct7 distinguishes ADD/SUB and SRL/SRA.

3.2 - Integer Register-Immediate [TOC]

These instructions take one source register and a 12-bit signed immediate. All use opcode 0x13 (I-type). The immediate is sign-extended to 32 bits before the operation.

3.3 - Upper Immediate [TOC]

These two instructions load a 20-bit immediate into the upper 20 bits of a register. They are used together with I-type instructions to construct 32-bit constants and addresses.

/* Load 0xDEADB000 into x5 */
LUI  x5, 0xDEADB     /* x5 = 0xDEADB000 */
ADDI x5, x5, 0x000   /* optionally set low 12 bits */

3.4 - Loads [TOC]

Load instructions read from memory at address x[rs1] + sext(imm) and write the result to rd. All use opcode 0x03 (I-type). The funct3 field selects the width and sign treatment.

3.5 - Stores [TOC]

Store instructions write a register value to memory at address x[rs1] + sext(imm). All use opcode 0x23 (S-type). There is no destination register. The S-type immediate is split across two fields — see Section 2.5 for how to reassemble it.

3.6 - Branches [TOC]

Branch instructions compare two registers and conditionally add a signed offset to the PC. All use opcode 0x63 (B-type). The branch target is PC + sext(imm), where imm is a 13-bit signed offset. The offset is always even (bit 0 is implied zero). If the branch is not taken, execution continues at PC + 4 as normal.

3.7 - Jumps [TOC]

Jump instructions unconditionally transfer control to a target address. They also write the return address (PC + 4) into a register, enabling function calls. Like branches, jump handlers must set the PC themselves and return without adding 4.

3.8 - System [TOC]

4.0 - Opcode Map [TOC]

Quick reference: opcode → instruction group. Use this as your switch statement guide.

5.0 - Emulator Implementation Notes [TOC]

This section contains practical notes for implementing the emulator in C.

5.1 - Fetch-Decode-Execute Loop [TOC]

The CPU executes one instruction per call to cpu_step(). The main loop calls this function repeatedly until a halt condition is reached.

void cpu_step(CPU *cpu) {

    /* 1. FETCH — read 4 bytes from memory at current PC */
    uint32_t instr = mem_read32(cpu, cpu->pc);

    /* 2. DECODE — extract common fields */
    uint32_t opcode = instr        & 0x7F;
    uint32_t rd     = (instr >> 7) & 0x1F;
    uint32_t funct3 = (instr >> 12) & 0x7;
    uint32_t rs1    = (instr >> 15) & 0x1F;
    uint32_t rs2    = (instr >> 20) & 0x1F;
    uint32_t funct7 = (instr >> 25) & 0x7F;

    /* 3. EXECUTE — dispatch to handler */
    switch (opcode) {
        case 0x33: exec_rtype (cpu, rd, rs1, rs2, funct3, funct7); break;
        case 0x13: exec_itype (cpu, rd, rs1, funct3, instr);       break;
        case 0x03: exec_load  (cpu, rd, rs1, funct3, instr);       break;
        case 0x23: exec_store (cpu, rs1, rs2, funct3, instr);      break;
        case 0x63: exec_branch(cpu, rs1, rs2, funct3, instr);      return;
        case 0x6F: exec_jal   (cpu, rd, instr);                    return;
        case 0x67: exec_jalr  (cpu, rd, rs1, instr);               return;
        case 0x37: exec_lui   (cpu, rd, instr);                    break;
        case 0x17: exec_auipc (cpu, rd, instr);                    break;
        case 0x73: exec_ecall (cpu);                               return;
        default:
            printf("Unknown opcode 0x%02X at PC=0x%08X\n", opcode, cpu->pc);
            return;
    }

    /* 4. ADVANCE PC (branches/jumps return early and skip this) */
    cpu->pc += 4;
}

5.2 - Field Extraction in C [TOC]

All instruction fields are extracted with two operations: right-shift to bring the field down to bit 0, then AND with a mask to clear all bits above the field.

/* Pattern: (instr >> START_BIT) & MASK */
/* Mask for N bits = (1 << N) - 1       */

/* 7-bit mask  = 0x7F  (bits 6:0)  — used for opcode, funct7  */
/* 5-bit mask  = 0x1F  (bits 4:0)  — used for rd, rs1, rs2    */
/* 3-bit mask  = 0x7   (bits 2:0)  — used for funct3           */

uint32_t opcode = instr        & 0x7F;   /* bits [6:0]   */
uint32_t rd     = (instr >> 7) & 0x1F;  /* bits [11:7]  */
uint32_t funct3 = (instr >> 12) & 0x7;  /* bits [14:12] */
uint32_t rs1    = (instr >> 15) & 0x1F; /* bits [19:15] */
uint32_t rs2    = (instr >> 20) & 0x1F; /* bits [24:20] */
uint32_t funct7 = (instr >> 25) & 0x7F; /* bits [31:25] */

5.3 - Sign Extension [TOC]

RISC-V immediates are signed. A 12-bit immediate can represent values from -2048 to +2047. When you use it in a 32-bit addition, you must first sign-extend it — that is, fill the upper 20 bits with copies of the immediate's sign bit (bit 11).

The simplest way to sign-extend in C is to cast the instruction to int32_t before shifting right. Arithmetic right shift on a signed type replicates the sign bit:

/* Sign-extend a 12-bit I-type immediate */
int32_t imm = (int32_t)instr >> 20;
/* The cast to int32_t makes >> an arithmetic shift.     */
/* This replicates bit 31 (originally bit 31 of instr,   */
/* which is the sign bit of the 12-bit immediate) into   */
/* all upper bits automatically.                          */

/* Example: instr = 0xFFF00013  (ADDI x0, x0, -1) */
/* (int32_t)0xFFF00013 >> 20  =  0xFFFFFFFF  =  -1 */