Crate rv_asm 

RISC-V instruction decoder.

The main function is Inst::decode, which will decode an instruction into the Inst enum. The core::fmt::Display impl of Inst provides disassembly functionality (note that the precise output of that implementation is not considered stable).

XLEN (Register size) support

RISC-V calls the parameter of the instruction size XLEN, and this crate refers to it as such.

This crate currenly only supports RV32 instructions. RV64 instructions that are the same between versions will still be decoded successfully, but the user has to be careful around sign-extended immediates to preserve the correct value when extending them to 64 bits.

RV64-specific instructions are not yet implemented, but will be in the future. The immediates will also be switched to u64 in the future to allow for easier usage of RV64.

RV128 is currently not intended to be supported.

Extension support

The decoder currently supports the following instructions:

• Base RV32I instruction set
• M standard extension
• A standard extension
  • Zalrsc standard extension
  • Zaamo standard extension
• C standard extension
• Zihintpause standard extension

More extensions may be implemented in the future.

Examples

// addi sp, sp, -0x20 (compressed)
let x = 0x1101_u32;
let expected = rvdc::Inst::Addi { imm: rvdc::Imm::new_i32(-0x20), dest: rvdc::Reg::SP, src1: rvdc::Reg::SP };

let (inst, is_compressed) = rvdc::Inst::decode(x, rvdc::Xlen::Rv32).unwrap();
assert_eq!(inst, expected);
assert_eq!(is_compressed, rvdc::IsCompressed::Yes);
assert_eq!(format!("{inst}"), "addi sp, sp, -32")

// auipc t1, 0xa
let x = 0x0000a317;
let expected = rvdc::Inst::Auipc { uimm: rvdc::Imm::new_u32(0xa << 12), dest: rvdc::Reg::T1 };

let (inst, is_compressed) = rvdc::Inst::decode(x, rvdc::Xlen::Rv32).unwrap();
assert_eq!(inst, expected);
assert_eq!(is_compressed, rvdc::IsCompressed::No);
assert_eq!(format!("{inst}"), "auipc t1, 10")

no_std

This crate supports no_std without the alloc crate.

Panics

Inst::decode is guaranteed to never panic. This is ensured with a 32-bit exhaustive test.

Testing

This crate is tested by exhaustively going through all 32 bit values that are valid instructions and roundtripping the disassembly through the clang assembler, ensuring it remains the same. This is not yet done for compressed instructions.

Additionally, it’s also tested as part of an emulator, which tests many different kinds of instructions.

MSRV

This crate targets the latest stable as its MSRV.

Structs

DecodeError

The error used for invalid instructions containing information about the instruction and error.

Fence

The details of a RISC-V fence instruction.

FenceSet

The affected parts of a fence.

Imm

An immediate in an instruction. This represents the real value that will be put in the register, so sign extension has been performed if necessary, and for instructions like lui the value will have been shifted.

Reg

A decoded RISC-V integer register.

Enums

AmoOp

An atomic memory operations from the Zaamo extension.

AmoOrdering

An atomic memory ordering for instructions from the A extension.

Inst

A RISC-V instruction.

IsCompressed

Whether the decoded instruction was a compressed instruction or not. If it was compressed, only the first two bytes were used. If it was not compressed, all four bytes are consumed.

Xlen

The register size of the ISA, RV32 or RV64.