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//! * Zifencei (version 2.0)
52//! * Zkn (version 1.0.1)
53//! * Zknd (version 1.0.1)
54//! * Zkne (version 1.0.1)
55//! * Zknh (version 1.0.1)
56//! * Zkr (version 1.0.1)
57//! * Zvbb (version 1.0.0)
58//! * Zvbc (version 1.0.0)
59//! * ZveXx (version 1.0.0), where `X` is anything allowed by the specification like Zve32x or
60//!   Zve64x
61//! * Zvkb (version 1.0.0)
62//! * Zvl*b (version 1.0.0), where `*` is anything allowed by the specification like Zvl128b or
63//!   Zvl512b
64//! * Ssstrict
65//!
66//! All extensions except experimental pass all relevant RISC-V Architectural Certification Tests
67//! (ACTs) using the ACT4 framework.
68//!
69//! Any permutation of compatible extensions is supported.
70//!
71//! Experimental extensions may not have ACT4 tests yet and are not guaranteed to work correctly.
72//!
73//! ## Design choices
74//!
75//! This crate was designed with a blockchain use case in mind, though it is in no way tied to any
76//! particular blockchain and is completely general purpose. As a result, the implementation is
77//! designed to be precise and non-ambiguous.
78//!
79//! A few key points:
80//! * anything "reserved" in the specification is considered to be illegal
81//! * anything "optional" in the specification is considered to be illegal
82//! * anything "implementation-defined" in the specification is selected to be the most natural and
83//!   deterministic
84//! * type system is used to make the majority of invalid invariants impossible to represent in code
85//!   and/or decode
86//!
87//! Examples:
88//! * Zve64x extension instructions are purposefully restricted to what it is required to be capable
89//!   of, although it would be cheaper to support the fuller feature set only required by V
90//!   extension
91
92#![no_std]
93#![expect(incomplete_features, reason = "generic_const_*")]
94#![feature(
95    const_cmp,
96    const_convert,
97    const_default,
98    const_destruct,
99    const_iter,
100    const_ops,
101    const_option_ops,
102    const_trait_impl,
103    const_try,
104    const_try_residual,
105    derive_const,
106    exact_div,
107    generic_const_args,
108    generic_const_items,
109    min_adt_const_params,
110    macroless_generic_const_args,
111    min_generic_const_args,
112    stmt_expr_attributes,
113    trusted_len,
114    try_blocks
115)]
116#![cfg_attr(feature = "no-panic", feature(const_closures))]
117#![cfg_attr(
118    test,
119    expect(
120        clippy::rest_pattern_accessible_field,
121        reason = "Too verbose for tests"
122    )
123)]
124
125pub mod instructions;
126pub mod prelude;
127pub mod privilege;
128pub mod registers;
ab_riscv_primitives/lib.rs

ab_riscv_primitives/
lib.rs
