ab_riscv_primitives/
lib.rs

1//! Composable RISC-V primitives (instructions, registers) and abstractions around them.
2//!
3//! The primitives are designed to be generic over the number of general purpose registers, and a
4//! macro system allows composing base ISA like RV32/RV64 with a desired set of standard or custom
5//! extensions/instructions. Trait abstractions are designed to allow expressing generic APIs
6//! without hardcoding specific types whenever possible.
7//!
8//! The immediate needs dictate the current set of available instructions and extensions. Consider
9//! contributing if you need something not yet available.
10//!
11//! `ab-riscv-interpreter` crate contains a complementary interpreter implementation, but these
12//! primitives are completely independent.
13//!
14//! `ab-riscv-act4-runner` crate in the repository contains a complementary RISC-V Architectural
15//! Certification Tests runner for <https://github.com/riscv-non-isa/riscv-arch-test> that ensures
16//! correct implementation.
17//!
18//! Does not require a standard library (`no_std`) or an allocator, never panics, almost 100% of the
19//! API is usable in const.
20//!
21//! ## Supported ISA variants and extensions
22//!
23//! ISA variants:
24//! * RV32I (version 2.1)
25//! * RV32E (version 2.0)
26//! * RV64I (version 2.1)
27//! * RV64E (version 2.0)
28//!
29//! Extensions:
30//! * A (version 2.1)
31//! * M (version 2.0)
32//! * B (version 1.0.0)
33//! * Zaamo (version 1.0.0)
34//! * Zabha (version 1.0.0)
35//! * Zacas (version 1.0.0)
36//! * (experimental) Zalasr (version 1.0.0)
37//! * Zalrsc (version 1.0.0)
38//! * Zawrs (version 1.0.0)
39//! * Zba (version 1.0.0)
40//! * Zbb (version 1.0.0)
41//! * Zbc (version 1.0.0)
42//! * Zbkb (version 1.0.1)
43//! * Zbkc (version 1.0.1)
44//! * Zbkx (version 1.0.1)
45//! * Zbs (version 1.0.0)
46//! * Zca (version 1.0.0)
47//! * Zcb (version 1.0.0)
48//! * (experimental) Zcmp (version 1.0.0)
49//! * Zicond (version 2.0)
50//! * Zicsr (version 2.0)
51//! * Zkn (version 1.0.1)
52//! * Zknd (version 1.0.1)
53//! * Zkne (version 1.0.1)
54//! * Zknh (version 1.0.1)
55//! * Zkr (version 1.0.1)
56//! * Zvbb (version 1.0.0)
57//! * Zvbc (version 1.0.0)
58//! * ZveXx (version 1.0.0), where `X` is anything allowed by the specification like Zve32x or
59//!   Zve64x
60//! * Zvkb (version 1.0.0)
61//! * Zvl*b (version 1.0.0), where `*` is anything allowed by the specification like Zvl128b or
62//!   Zvl512b
63//!
64//! All extensions except experimental pass all relevant RISC-V Architectural Certification Tests
65//! (ACTs) using the ACT4 framework.
66//!
67//! Any permutation of compatible extensions is supported.
68//!
69//! Experimental extensions may not have ACT4 tests yet and are not guaranteed to work correctly.
70//!
71//! ## Design choices
72//!
73//! This crate was designed with a blockchain use case in mind, though it is in no way tied to any
74//! particular blockchain and is completely general purpose. As a result, the implementation is
75//! designed to be precise and non-ambiguous.
76//!
77//! A few key points:
78//! * anything "reserved" in the specification is considered to be illegal
79//! * anything "optional" in the specification is considered to be illegal
80//! * anything "implementation-defined" in the specification is selected to be the most natural and
81//!   deterministic
82//! * type system is used to make the majority of invalid invariants impossible to represent in code
83//!   and/or decode
84//!
85//! Examples:
86//! * Zve64x extension instructions are purposefully restricted to what it is required to be capable
87//!   of, although it would be cheaper to support the fuller feature set only required by V
88//!   extension
89
90#![no_std]
91#![expect(incomplete_features, reason = "generic_const_*")]
92#![feature(
93    const_cmp,
94    const_convert,
95    const_default,
96    const_destruct,
97    const_ops,
98    const_option_ops,
99    const_trait_impl,
100    const_try,
101    const_try_residual,
102    derive_const,
103    exact_div,
104    generic_const_args,
105    generic_const_items,
106    min_adt_const_params,
107    macroless_generic_const_args,
108    min_generic_const_args,
109    never_type,
110    stmt_expr_attributes,
111    try_blocks
112)]
113#![cfg_attr(feature = "no-panic", feature(const_closures))]
114
115pub mod instructions;
116pub mod prelude;
117pub mod privilege;
118pub mod registers;
ab_riscv_primitives/lib.rs

ab_riscv_primitives/
lib.rs
