andes-riscv

The RISC-V architecture support crate for Andes' RISC-V cores.

This crate has machine-generated code from YAML definitions.

This crate is a supplement to the riscv crate, which provides the core RISC-V support.

CSR code is generated by yaml2pac in rvcsr mode, using upstream chiptool IR.

• yaml2pac: https://github.com/embedded-drivers/yaml2pac
• chiptool: https://github.com/embassy-rs/chiptool

Overview

Series

• Entry Series: D23, N22
• 25 Series
• 27 Series
• 45 Series
• AX60 Series

Known Platform and Chips

• HPMicro's HPM5xxx/HPM6xxx series, D25(F)/D45 core
• BK7256, D25(F) dual core
• Renesas' RZ/Five MPU, AX45MP single core
  • SBC: Tinker V
• Renesas' R9A0 series, N22 or D25(F) core
• Telink's TLSR9 series, D25(F) core
• GOWIN's GW5AST-138, FPGA with Andes A25 RISC-V CPU IP and AE350 subsystem

Project Status

• 32-bit CSRs
• L1C operations
• DSP (P-extension) intrinsics — complete ~190 instructions
• 64-bit platform support

API Style

The CSR API uses module-per-CSR style.

// Read typed CSR
let en = register::mcache_ctl::read().dc_en();

// Single-bit atomic CSR operations (single instruction)
unsafe { register::mcache_ctl::set_dc_en(); }
unsafe { register::mcache_ctl::clear_dc_en(); }

// Multi-bit fields use read-modify-write
unsafe { register::mcache_ctl::set_dc_warnd(0b11); }
unsafe { register::mcache_ctl::modify(|w| w.set_dc_warnd(0b11)); }

Migration Notes (0.1.x -> 0.2.x)

• CSR entrypoints changed from register::foo().read()/modify() to register::foo::read()/modify().
• Raw untyped CSR helpers now use usize in read()/write() for better XLEN alignment.
• Single-bit field operations expose atomic set_xxx()/clear_xxx() helpers.

DSP (P-extension) Intrinsics

The dsp module provides all ~190 Andes V5 DSP instructions, works on stable Rust via core::arch::asm!.

use andes_riscv::dsp;

let r = dsp::kadd16(a, b);             // 2x16-bit saturating add
let m = dsp::smmul(a, b);              // MSW 32x32 multiply
let acc = dsp::smaqa(acc, a, b);       // 4x8-bit multiply-accumulate
let (lo, hi) = dsp::smar64((0, 0), a, b); // 32x32 MAC to 64-bit

Runtime detection:

if andes_riscv::register::mmsc_cfg::read().edsp() {
    // DSP instructions available
}

Performance (HPM6750 benchmark, N=1000)

(cycles/iteration, opt-level="z")

Alternative: core::arch::riscv32 (nightly)

Rust nightly provides built-in P-extension intrinsics via core::arch::riscv32 (feature gate riscv_ext_intrinsics). These are native LLVM intrinsics, so the compiler can do register allocation, instruction scheduling, and constant folding — no .insn limitations.

However, core::arch::riscv32 only covers 105 base SIMD instructions from the RISC-V P-extension draft (opcode 0x77). The Andes V5 DSP extension uses a different opcode (0x7F, custom-3) and includes ~190 instructions — the extra ~85 are Andes-specific extensions not in core::arch:

Missing from core::arch (Andes-only):

• MSW 32x32 multiply family (smmul, kmmac, kmmsb, smmwb, smmwt, ...)
• 32x32 → 64-bit MAC family (smar64, smsr64, kmar64, ...)
• Dual 16x16 multiply family (kmda, kmxda, smds, kmada, ...)
• KDM/KHM saturating double/half multiply (kdmbb, khmbb, ...)
• 64-bit arithmetic (add64, sub64, kadd64, ...)
• Packed multiply to 64-bit (smul16, smul8, mulsr64, ...)
• Misc: bpick, insb, wext, sclip32, uclip32, ...

Recommendation: Use andes_riscv::dsp for the complete instruction set on stable Rust. If you only need the base 105 SIMD instructions and can use nightly, core::arch::riscv32 will give better codegen for register-pair instructions.

Known Limitations (.insn approach)

Since LLVM has no native Andes V5 DSP support, all instructions are emitted via .insn inline assembly. This has two consequences:

1. 64-bit register pair instructions (smar64, smalda, smul16, etc.) are hard-coded to use the a4/a5 register pair. The compiler cannot freely allocate registers, which causes spill/reload overhead — especially when function calls exist in the loop body.

2. The compiler treats DSP instructions as opaque — no constant folding, instruction scheduling, CSE, or auto-vectorization is possible across DSP intrinsics.

Single-register DSP instructions (kadd16, kmda, smaqa, etc.) are #[inline(always)] and have negligible overhead after inlining.

Features

• defmt: enables defmt::Format on generated fieldset/register types.

CSRs

AndeStar V5 machine mode CSRs

Configuration Registers

Crash Debug CSRs

Memory CSRs

Hardware Stack Protection & Recording

Trap related CSR

Control CSRs

Counter related CSRs

Enhanced CLIC CSRs

Physical Memory Attribute CSRs

AndeStar V5 debug mode CSRs

AndeStar V5 supervisor mode CSRs

Supervisor Trap Related

Supervisor Counter Related

Supervisor Control

AndeStar V5 user mode CSRs