impl

std › riscv › impl

RISC-V RV32I: its registers, instruction formats, and every base instruction, each emitted as a little-endian 32-bit word.

Import a dialect rather than this module: std.riscv.native for the standard assembly syntax, or std.riscv.c_like. Here every instruction takes its operands in order, lw rd, offset, rs1 rather than lw rd, offset(rs1).

from std.riscv.impl import *

loop:
    addi a0, a0, -1
    bne a0, zero, loop

13 05 f5 ff
e3 1e 05 fe

Immediates are plain ints, truncated to their field, so a negative one becomes its two’s-complement encoding. Branch and jump targets are labels; bitter works out the offset once the program is laid out.

Macros

add

rd = rs1 + rs2.

sub

rd = rs1 - rs2.

sll

rd = rs1 << rs2, shifting by the low 5 bits of rs2.

slt

rd = 1 if rs1 < rs2 as signed numbers, else 0.

sltu

rd = 1 if rs1 < rs2 as unsigned numbers, else 0.

xor

rd = rs1 ^ rs2.

srl

rd = rs1 >> rs2, shifting in zeros, by the low 5 bits of rs2.

sra

rd = rs1 >> rs2, shifting in copies of the sign bit, by the low 5 bits of rs2.

or

rd = rs1 | rs2.

and

rd = rs1 & rs2.

addi

rd = rs1 + imm, with a 12-bit signed imm.

slti

rd = 1 if rs1 < imm as signed numbers, else 0.

sltiu

rd = 1 if rs1 < imm as unsigned numbers, else 0. imm is sign-extended first, so sltiu rd, rs1, 1 tests for zero.

xori

rd = rs1 ^ imm. xori rd, rs1, -1 is bitwise NOT.

ori

rd = rs1 | imm.

andi

rd = rs1 & imm.

slli

rd = rs1 << shamt, for shamt from 0 to 31.

srli

rd = rs1 >> shamt, shifting in zeros, for shamt from 0 to 31.

srai

rd = rs1 >> shamt, shifting in copies of the sign bit, for shamt from 0 to 31.

jalr

Jumps to rs1 + offset (with bit 0 cleared) and puts the address of the next instruction in rd. jalr zero, ra, 0 returns from a function.

ecall

Calls the execution environment, e.g. a Linux system call.

ebreak

Stops in a debugger.

lb

Loads the byte at rs1 + offset into rd, sign-extended.

lh

Loads the 16-bit halfword at rs1 + offset into rd, sign-extended.

lw

Loads the 32-bit word at rs1 + offset into rd.

lbu

Loads the byte at rs1 + offset into rd, zero-extended.

lhu

Loads the 16-bit halfword at rs1 + offset into rd, zero-extended.

sb

Stores the low byte of rs2 at rs1 + offset.

sh

Stores the low 16 bits of rs2 at rs1 + offset.

sw

Stores rs2 at rs1 + offset.

beq

Branches to the label target if rs1 == rs2.

bne

Branches to the label target if rs1 != rs2.

blt

Branches to the label target if rs1 < rs2 as signed numbers.

bge

Branches to the label target if rs1 >= rs2 as signed numbers.

bltu

Branches to the label target if rs1 < rs2 as unsigned numbers.

bgeu

Branches to the label target if rs1 >= rs2 as unsigned numbers.

lui

rd = imm << 12: loads a 20-bit upper immediate.

auipc

rd = pc + (imm << 12): an address relative to this instruction.

jal

Jumps to the label target and puts the address of the next instruction in rd. jal ra, f calls f; jal zero, l just jumps.

li

Loads the constant imm into rd: addi rd, zero, imm when it fits in 12 signed bits, else lui for the upper 20 bits then, unless they’re zero, addi for the rest.

la

Loads the address of the label symbol into rd: auipc for the upper 20 bits of the distance, then addi for the rest.

ascii

A string literal’s UTF-8 bytes, with no terminator: GNU’s .ascii.

Types

Reg

type Reg = bits<5>

A register number, 0 to 31.

Opcode

type Opcode = bits<7>

The 7-bit major opcode, which picks the format and family.

Funct3

type Funct3 = bits<3>

The 3-bit funct3 field, which picks the instruction within a family.

Funct7

type Funct7 = bits<7>

The 7-bit funct7 field of an R-type instruction.

Bit1

type Bit1 = bits<1>

A one-bit field.

Imm4

type Imm4 = bits<4>

A 4-bit immediate field.

Imm5

type Imm5 = bits<5>

A 5-bit immediate field.

Imm6

type Imm6 = bits<6>

A 6-bit immediate field.

Imm7

type Imm7 = bits<7>

A 7-bit immediate field.

Imm8

type Imm8 = bits<8>

An 8-bit immediate field.

Imm10

type Imm10 = bits<10>

A 10-bit immediate field.

Imm12

type Imm12 = bits<12>

A 12-bit immediate field.

Imm20

type Imm20 = bits<20>

A 20-bit immediate field.

RType

struct RType

The R-type format: register-register operations.

IType

struct IType

The I-type format: register-immediate operations, loads, jalr and system calls.

SType

struct SType

The S-type format: stores. The 12-bit offset is split around the registers.

BType

struct BType

The B-type format: conditional branches. The offset’s bits are spread across the word the way the spec lays them out, and resolved by bitter.

UType

struct UType

The U-type format: a 20-bit upper immediate.

JType

struct JType

The J-type format: jal. Like B-type, its offset’s bits are spread across the word, and resolved by bitter.

Byte

type Byte = bits<8>

A byte.

Bytes

struct Bytes<const N: int>

N bytes, packed by bitter in order.

Some of its fields are generated by @for or @if.

Constants