ISA - Instruction Set Architecture

This page documents the instruction set currently implemented by the HarvOS core. It uses RV32I-like 32-bit encodings, but it is not claimed to be a complete standards-compliant RISC-V platform.

Encoding groups

Group	Opcode	Description
LOAD	`0000011`	Byte, halfword and word loads.
FENCE	`0001111`	`FENCE` and `FENCE.I`; `FENCE.I` flushes the HarvOS TLBs.
OP-IMM	`0010011`	Integer immediate operations.
AUIPC	`0010111`	PC-relative U-type value construction.
STORE	`0100011`	Byte, halfword and word stores.
OP	`0110011`	Register-register ALU operations.
LUI	`0110111`	Upper immediate load.
BRANCH	`1100011`	Conditional branches.
JALR	`1100111`	Indirect jump with link.
JAL	`1101111`	PC-relative jump with link.
SYSTEM	`1110011`	ECALL, EBREAK and CSR operations.
CUSTOM-0	`0001011`	HarvOS-specific runtime and security instructions.

RISC-V profile and deviations

Aspect	RISC-V-like	HarvOS-specific
Base encoding	Opcode, `rd`, `rs1`, `rs2`, `funct3` and immediate fields follow familiar layouts for listed instructions.	Unlisted opcode/function combinations are illegal; there is no implicit support for the full RISC-V specification.
Extensions	RV32I-like integer operations.	No `M`, `A`, `C`, floating-point or standard privileged extensions beyond the local CSRs documented here.
Privileges and CSRs	Names `U`, `S` and `M` are inspired by RISC-V.	CSR addresses and semantics are local; the MPU is not PMP and `satp` is not full Sv32.
Memory protection	Load, store and fetch can fault.	Harvard rules, W^X checks, MMU region model and fixed MPU are HarvOS-specific.

Register model

The core has 32 integer registers x0..x31. x0 is permanently zero. The software ABI follows common RISC-V conventions: a0 is used for arguments/return values and a7 carries the syscall number.

ALU and immediate instructions

Mnemonic	Format	Operation	Notes
`ADD`	R	`rd = rs1 + rs2`	`funct7=0000000`.
`SUB`	R	`rd = rs1 - rs2`	`funct7=0100000`.
`SLL`	R/I	Logical left shift.	Shift amount is 5 bits.
`SLT`/`SLTU`	R/I	Signed or unsigned less-than.	Result is `0` or `1`.
`XOR`/`OR`/`AND`	R/I	Bitwise operations.
`SRL`/`SRA`	R/I	Logical or arithmetic right shift.	`SRA` uses `funct7=0100000`.
`ADDI`	I	`rd = rs1 + signext(imm12)`	Common pointer arithmetic.
`LUI`	U	`rd = imm20 << 12`	Upper immediate.
`AUIPC`	U	`rd = pc + (imm20 << 12)`	PC-relative address construction.

Load and store

Mnemonic	Width	Semantics	Fault conditions
`LB`/`LBU`	8 bit	Signed or unsigned byte load.	MMU/MPU fault.
`LH`/`LHU`	16 bit	Signed or unsigned halfword load.	Address must be 2-byte aligned.
`LW`	32 bit	Word load.	Address must be 4-byte aligned.
`SB`	8 bit	Byte store.	MMU/MPU fault.
`SH`	16 bit	Halfword store.	Address must be 2-byte aligned.
`SW`	32 bit	Word store.	Address must be 4-byte aligned.

Control flow

Mnemonic	Semantics	Notes
`BEQ`/`BNE`	Branch on equality or inequality.	Target must be 4-byte aligned.
`BLT`/`BGE`	Signed comparison branches.
`BLTU`/`BGEU`	Unsigned comparison branches.
`JAL`	`rd = pc + 4`, `pc = pc + imm`.	Target must be 4-byte aligned.
`JALR`	`rd = pc + 4`, `pc = (rs1 + imm) & ~1`.	Final target must be 4-byte aligned.

System, CSR and Custom-0

Instruction	Encoding	Description	Privilege
`ECALL`	`0x00000073`	Trap to user or supervisor ecall cause.	User/Supervisor.
`EBREAK`	`0x00100073`	Breakpoint trap.	User/Supervisor.
`CSRRW`/`CSRRS`/`CSRRC`	`opcode=1110011`	Read/write, set or clear local CSRs.	Supervisor only.
`CLRREG rd`	Custom-0, `funct3=000`	Writes zero to `rd`.	User/Supervisor.
`CLRMEM rs1, rs2`	Custom-0, `funct3=001`	Clears `rs2` 32-bit words starting at `rs1`. Address must be aligned; MMIO is forbidden.	Supervisor only.
`ENTROPY rd`	Custom-0, `funct3=010`	`rd = entropy_i ^ csr_srandom`.	User/Supervisor.
`SRET`	`0x10200073`	HarvOS trap return: loads `pc=sepc`, flushes TLBs and returns to user mode.	Supervisor only.

Custom-0 bit layout

word = (rs2 << 20) | (rs1 << 15) | (funct3 << 12) | (rd << 7) | 0x0b

Bits	Name	Meaning
`6:0`	`opcode`	`0001011` / `0x0b`.
`11:7`	`rd`	Destination for `CLRREG` and `ENTROPY`.
`14:12`	`funct3`	`000` = `CLRREG`, `001` = `CLRMEM`, `010` = `ENTROPY`.
`19:15`	`rs1`	Base address for `CLRMEM`.
`24:20`	`rs2`	Word count for `CLRMEM`.
`31:25`	Reserved	Software should set these bits to zero for forward compatibility.

CSRs

CSR	Address	Meaning
`sstatus`	`0x100`	Interrupt enable and fixed status bits; writable mask `0x00000003`.
`stvec`	`0x101`	Trap vector, 4-byte aligned.
`sepc`	`0x102`	Trap PC, 4-byte aligned.
`scause`	`0x103`	Trap cause.
`stval`	`0x104`	Trap value, often an address or instruction word.
`satp`	`0x105`	Translation control; mode bit and ASID-style bits are used locally.
`srandom`	`0x120`	Software mixing value for `ENTROPY`.
`smpuctl`	`0x130`	MPU lock control.
`scaps`	`0x140`	Capability mask for runtime policy.

Trap codes

Name	Code	Trigger
`SCAUSE_INST_ADDR_MISALIGNED`	`0x00000000`	PC or branch/jump target is not 4-byte aligned.
`SCAUSE_INST_ACCESS_FAULT`	`0x00000001`	Fetch MMU/MPU rejects access.
`SCAUSE_ILLEGAL_INSTRUCTION`	`0x00000002`	Unsupported opcode/function or illegal privilege access.
`SCAUSE_BREAKPOINT`	`0x00000003`	`EBREAK`.
`SCAUSE_LOAD_ADDR_MISALIGNED`	`0x00000004`	Misaligned `LH/LHU/LW`.
`SCAUSE_LOAD_ACCESS_FAULT`	`0x00000005`	Load denied.
`SCAUSE_STORE_ADDR_MISALIGNED`	`0x00000006`	Misaligned `SH/SW` or `CLRMEM`.
`SCAUSE_STORE_ACCESS_FAULT`	`0x00000007`	Store denied.
`SCAUSE_ECALL_U`	`0x00000008`	ECALL from user mode.
`SCAUSE_ECALL_S`	`0x00000009`	ECALL from supervisor mode.
`SCAUSE_HARVARD_VIOLATION`	`0x0000000a`	Violation of IMEM/DMEM separation.
`SCAUSE_EXTERNAL_INTERRUPT`	`0x8000000b`	External IRQ, for example USB or HNET.