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]
/// )]
/// struct Extended<Reg> {
///     A(Reg),
///     B(Reg),
///     C(Reg),
///     #[instruction(
///         if = [OptionalY],
///         if = [OptionalZ1, OptionalZ2],
///     )]
///     D(Reg),
///     E(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
/// struct Extended<Reg> {
///     C(Reg),
///     Add { rd: Reg, rs1: Reg, rs2: Reg },
///     // Any other instructions from `BaseInstruction` that were not mentioned explicitly
///     D(Reg),
///     A(Reg),
///     B(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 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.
///   * `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 create subsets of extensions (`Zmmul` is a multiply-only subset of `M`).
///
/// `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.
///
/// # 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]
/// impl<Reg> const Instruction for Rv64Instruction<Reg>
/// where
///     Reg: [const] Register<Type = u64>,
/// {
///     // ...
/// }
/// ```
///
/// `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.
///
/// # 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> fmt::Display for Rv64Instruction<Reg>
/// where
///     Reg: fmt::Display + Copy,
/// {
///     // ...
/// }
/// ```
/// `fmt()` implementation will end up containing decoding logic for the full extended enum as
/// mentioned above. The three major restrictions are that an enum must be generic over `Reg`
/// register type, 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.
///
/// # [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
/// * `Ok(ControlFlow::Continue(Default::default()))` expression.
///
/// 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()
}