ab_riscv_macros_impl/

lib.rs

//! See and use `ab-riscv-macros` crate instead, this is its implementation detail

mod instruction;
mod instruction_execution;

use proc_macro::TokenStream;

// TODO: Support `conflict` (`Zcmp` conflicts with `Zcd` for example)
/// Processes `#[instruction]` attribute on both enum definitions and implementations.
///
/// # Enum definition
///
/// When applied to the enum definition, it will reorder variant fields and expose an enum with
/// instructions as a dependency.
///
/// The fields are reordered as follows: `rs1` > `rs2` > others. This is helpful for
/// high-performance execution implementation. If `rs1` or `rs2` are not present, they will be added
/// automatically, and all implementations annotated with `#[instruction]` or
/// `#[instruction_execution]` will be automatically updated accordingly, but tests and other usages
/// will have to specify those fields explicitly.
///
/// More complex syntax is used when inheriting instructions:
/// ```rust,ignore
/// #[instruction(
///     reorder = [C, Add],
///     ignore = [E],
///     inherit = [BaseInstruction],
///     reorder = [D, A],
///     if = [OptionalX]
/// )]
/// enum Extended<Hart>
/// where
///     Hart: HartConfig,
/// {
///     A(Hart::Reg),
///     B(Hart::Reg),
///     C(Hart::Reg),
///     #[instruction(
///         if = [OptionalY],
///         if = [OptionalZ1, OptionalZ2],
///     )]
///     D(Hart::Reg),
///     E(Hart::Reg),
/// }
/// ```
///
/// This will generate an enum with both `BaseInstruction` and `Extended` instructions, while also
/// reordering them according to the specified order. So the eventual enum will look like this:
/// ```rust,ignore
/// enum Extended<Hart>
/// where
///     Hart: HartConfig,
/// {
///     C(Hart::Reg),
///     Add { rd: Hart::Reg, rs1: Hart::Reg, rs2: Hart::Reg },
///     // Any other instructions from `BaseInstruction` that were not mentioned explicitly
///     D(Hart::Reg),
///     A(Hart::Reg),
///     B(Hart::Reg),
/// }
/// ```
///
/// Note that all attribute parameters can be specified multiple times, and reordering can reference
/// any variant from both the `BaseInstruction` and `Extended` enums.
///
/// This, of course, only works when enums have compatible generics: all instruction enums are
/// generic over hart configuration `Hart` (see `HartConfig`), and implementations have an
/// additional `Reg` generic parameter for its register type (constrained with
/// `Hart: HartConfig<Reg = Reg>`).
///
/// All instruction enums in the project must have unique names. Individual instructions can be
/// repeated between inherited enums, but they must have the same exact variant definition and are
/// assumed to be 100% compatible.
///
/// Here is how the attributes are processed:
/// * first, all own and inherited enum variants are collected into a set
/// * all reordered instructions are isolated from the rest to make sure they are not ignored
/// * then each attribute is processed in order of declaration
///   * `reorder` indicated where the corresponding variant needs to be included
///   * `ignore` removed individual variants or the whole enum from a set mentioned earlier (but
///     instructions that are "reordered" anywhere in the definition will remain). Ignored list may
///     contain any known enum, including those that are not in the list of inherited enums. Ignored
///     instructions don't satisfy `if` conditions of other instructions.
///   * `inherit` includes all remaining variants of the corresponding enum that were not explicitly
///     reordered or ignored anywhere in the definition
///   * own variants that were not explicitly reordered or ignored are placed at the end of the enum
///
/// `reorder` is a niche feature that physically moves the variants, allowing certain variants to be
/// next to each other for more efficient code generation (enum discriminant and execution code
/// locality).
///
/// `inherit` is used both for dependencies (`Zve64x` depends on `Zicsr`) and for direct inclusion
/// during composition (`B` contains `Zba`, `Zbb` and `Zbs`).
///
/// `ignore` can be used to exclude individual instructions or whole enums from a custom instruction
/// set (like `ecall` from an instruction set that doesn't support system calls). An enum ignored as
/// a whole, as well as enums that inherit it, are not implemented extensions of the instruction set
/// (see `Instruction::IMPLEMENTED_EXTENSIONS`), while ignoring individual instructions doesn't
/// change that, unless none of the enum's own instructions are left. It should not be used for
/// modeling relationships between extensions though: an extension that is a subset of another
/// extension according to the specification is inherited by that extension (`M` inherits `Zmmul`),
/// while instructions shared by extensions that are not subsets of each other are extracted into a
/// separate enum, which both extensions inherit (`Zbb` and `Zbkb` both inherit
/// `Rv64ZbbZbkbSharedInstruction`).
///
/// `if` on both enum and variant levels specifies soft optional dependencies on other instructions
/// or variants when this instruction is inherited further up the chain. Variants are always present
/// in the enum where they are defined, such that tests can be written against them without extra
/// effort. In this example above, all instructions require `OptionalX` enum or variant to be
/// included alongside `Extended` itself, while variant `D` specifically requires either `OptionalY`
/// or `OptionalZ1` + `OptionalZ2` to be present.
///
/// These `if` conditions allow modeling things like `Zcf` part of `C` extension only being
/// available when `F` extension is also available or `Zcb`'s `c.sext.b` only present when `Zbb`
/// extension is also available. An enum in `if` condition is satisfied when it is implemented, the
/// same way as in `Instruction::IMPLEMENTED_EXTENSIONS`.
///
/// # Enum decoding implementation
///
/// For enum decoding implementation, the macro is applied to the implementation of `Instruction`
/// trait and affects its `try_decode()` method:
/// ```rust,ignore
/// #[instruction]
/// const impl<Reg, Hart> Instruction for Rv64Instruction<Hart>
/// where
///     Reg: [const] Register<Type = u64>,
///     Hart: [const] HartConfig<Reg = Reg>,
/// {
///     // ...
/// }
/// ```
///
/// `try_decode()` implementation will end up containing decoding logic for the full extended enum
/// as mentioned above. The two major restrictions are that `return` is not allowed in the
/// `try_decode()` method and enum variants must be constructed using `Self::`. The implementation
/// is quite fragile, so if you're calling internal functions, they might have to be re-exported
/// since the macro will simply copy-paste the decoding logic as is. Similarly with missing imports,
/// etc. Compiler should be able to guide you through errors reasonably well.
///
/// Construction of variants that are not present in the instruction set (like ignored ones) is
/// replaced with `None?`. This also allows decoding to construct variants of other enums when they
/// are present, like Zbkb decoding `packw rd, rs1, x0` as Zbb's `zext.h`.
///
/// The macro also generates `IMPLEMENTED_EXTENSIONS` constant (see
/// `Instruction::IMPLEMENTED_EXTENSIONS`), while `OWN_ISA_EXTENSIONS` with ISA extensions of the
/// enum itself must be specified explicitly, like `Ok(&[IsaExtension::new("m", 2, 0)])` for `M`.
/// `ImplementedExtension` must be in scope for this to work.
///
/// # Enum display implementation
///
/// For enum display implementation, the macro is applied to the implementation of
/// `core::fmt::Display` trait and affects its `fmt()` method:
/// ```rust,ignore
/// #[instruction]
/// impl<Reg, Hart> fmt::Display for Rv64Instruction<Hart>
/// where
///     Reg: fmt::Display + Copy,
///     Hart: HartConfig<Reg = Reg>,
/// {
///     // ...
/// }
/// ```
/// `fmt()` implementation will end up containing decoding logic for the full extended enum as
/// mentioned above. The two major restrictions are that field types must have `Copy` bounds on them
/// (like `Reg` in the example above), and the method body must consist of a single `match`
/// statement.
///
/// # `process_instruction_macros()`
///
/// What this macro "does" is impossible to do in Rust macros. So for completeness,
/// `ab_riscv_macros::process_instruction_macros()` must be called from `build.rs` in a
/// crate that uses `#[instruction]` macro to generate a bunch of special filed, which the macro
/// uses to replace the original code with. This is the only way to get the desired ergonomics
/// withing current constraints of what macros are allowed to do.
///
/// `process_instruction_macros()` finds annotated items anywhere in the crate's Rust files,
/// including inline modules, and attributes may be path-qualified like
/// `#[ab_riscv_macros::instruction]`. Attributes must be written in the source code at the start
/// of a line (indentation is fine), ones produced by other macros (like `cfg_attr`) are not seen.
///
/// # [package.links]
///
/// `package` section of `Cargo.toml` must contain `links = "crate-name"` in order for metadata to
/// be successfully exported to dependent crates.
#[proc_macro_attribute]
pub fn instruction(attr: TokenStream, item: TokenStream) -> TokenStream {
    instruction::instruction(attr.into(), item.into())
        .unwrap_or_else(|error| error.to_compile_error())
        .into()
}

/// Processes `#[instruction_execution]` attribute on enum execution implementation.
///
/// It must be applied to implementation of traits `ExecutableInstructionOperands`,
/// `ExecutableInstructionCsr` and `ExecutableInstruction`, whose definition is already annotated
/// with `#[instruction]` macro.
///
/// Similarly to that macro, this macro will process the contents of trait implementations.
///
/// `ExecutableInstructionOperands::get_rs1_rs2_operands()` method will be generated from scratch.
///
/// `ExecutableInstruction::execute()`, `ExecutableInstructionCsr::prepare_csr_read()` and
/// `ExecutableInstructionCsr::prepare_csr_write()` methods will end up containing both inherited
/// and own execution logic according to the ordering set in `#[instruction]`.
///
/// There are constraints on the `ExecutableInstruction::execute()` method body, it must have one or
/// both (but nothing else) of the following:
/// * matching in the following style: `match self { Self::Variant { .. } }`
///   * note that `Self` must be used instead of the explicit type name, such that it works when
///     inherited
/// * `ExecutionResult::ContinueNoWrite` expression.
///
/// The composed `execute()` body is not kept as one large `match`. Instead, each `match` arm
/// (both own and inherited) is turned into its own `#[inline(always)]` free function, generated
/// right next to `execute()`, and `execute()` itself is reduced to a lean `match` that dispatches
/// to those functions (with the impl's generic parameters specified explicitly via turbofish,
/// since a free function has no `Self` for them to be inferred from). This is purely an
/// implementation detail; those functions are not meant to be used or referred to directly.
///
/// Alongside `execute()`, an implementation of `ThreadedExecutableInstruction` is generated for the
/// same enum, out of the very same arms. It is done in a somewhat opaque way here with the hopes
/// that it would become possible to move the `ThreadedExecutableInstruction::execute_threaded()`
/// method into `ExecutableInstruction` trait at some point. Right now it is not possible to mix
/// const and non-const methods in the same trait.
///
/// If `execute()` carries `#[cfg_attr(feature = "no-panic", no_panic_const::no_panic(..))]`, it
/// is stripped from `execute()` itself (which becomes a plain dispatcher, so the attribute would
/// no longer serve its purpose there) and placed on every one of those generated functions
/// instead, so each variant's execution logic is checked for panics individually. Since this
/// depends on `execute()` in the implementation currently being processed specifically carrying
/// this attribute, an implementation that inherits from a lower-level one that has it, but does
/// not itself repeat it will not get it applied to its own generated functions either.
///
/// Also requires `process_instruction_macros()` in `build.rs` to function, see `#[instruction]`
/// macro documentation.
///
/// `ExecutableInstructionCsr::prepare_csr_read()` and
/// `ExecutableInstructionCsr::prepare_csr_write()` methods can't contain `return` in them,
/// similarly to instruction decoding implementation processed by `#[instruction]` macro.
#[proc_macro_attribute]
pub fn instruction_execution(attr: TokenStream, item: TokenStream) -> TokenStream {
    instruction_execution::instruction_execution(attr.into(), item.into())
        .unwrap_or_else(|error| error.to_compile_error())
        .into()
}