asm: prepare docs for publishing (#10178)

This change is motivated by staring at the output of `cargo doc` for the
`cranelift-assembler-x64` crate. In order to write a sensible top-level
example, I felt it was best to refactor how we construct the
instructions: this removes the `build` module and adds conventional
`<inst_name>::new` functions to each instruction. Also, a generated
`From` implementation makes it easier to convert to an `Inst`.

This change has other doc-related refactorings and tweaks, but should
not change any functionality.

Author: abrown

cranelift/assembler-x64/README.md

@@ -10,9 +10,9 @@ Like `cranelift-codegen`, using this assembler starts with `enum Inst`. For
 convenience, a `main.rs` script prints the path to this generated code:
 
 ```console
-$ cat $(cargo run)
-#[derive(arbitrary::Arbitrary, Debug)]
-pub enum Inst {
+$ cat $(cargo run) | head
+...
+pub enum Inst<R:Registers> {
     andb_i(andb_i),
     andw_i(andw_i),
     andl_i(andl_i),

cranelift/assembler-x64/meta/src/generate.rs

@@ -18,14 +18,14 @@ pub fn rust_assembler(f: &mut Formatter, insts: &[dsl::Inst]) {
     generate_inst_encode_impl(f, insts);
     generate_inst_visit_impl(f, insts);
     generate_inst_features_impl(f, insts);
-    generate_inst_constructor_impl(f, insts);
 
     // Generate per-instruction structs.
     f.empty_line();
     for inst in insts {
         inst.generate_struct(f);
         inst.generate_struct_impl(f);
         inst.generate_display_impl(f);
+        inst.generate_from_impl(f);
         f.empty_line();
     }
 
@@ -69,6 +69,7 @@ pub fn isle_definitions(f: &mut Formatter, insts: &[dsl::Inst]) {
 
 /// `enum Inst { ... }`
 fn generate_inst_enum(f: &mut Formatter, insts: &[dsl::Inst]) {
+    fmtln!(f, "#[doc(hidden)]");
     generate_derive(f);
     generate_derive_arbitrary_bounds(f);
     fmtln!(f, "pub enum Inst<R: Registers> {{");
@@ -174,15 +175,3 @@ fn generate_inst_features_impl(f: &mut Formatter, insts: &[dsl::Inst]) {
     });
     fmtln!(f, "}}");
 }
-
-/// `pub mod build { pub fn <inst>... }`
-fn generate_inst_constructor_impl(f: &mut Formatter, insts: &[dsl::Inst]) {
-    fmtln!(f, "pub mod build {{");
-    f.indent(|f| {
-        fmtln!(f, "use super::*;");
-        for inst in insts {
-            inst.generate_variant_constructor(f);
-        }
-    });
-    fmtln!(f, "}}");
-}

cranelift/assembler-x64/meta/src/generate/features.rs

@@ -9,7 +9,9 @@ impl dsl::Feature {
     /// This function recreates the `Feature` struct itself in the generated
     /// code.
     pub fn generate_enum(f: &mut Formatter) {
+        fmtln!(f, "#[doc(hidden)]");
         generate_derive(f);
+        fmtln!(f, "#[derive(Copy, PartialEq)]"); // Add a couple more helpful derives.
         fmtln!(f, "pub enum Feature {{");
         f.indent(|f| {
             for feature in dsl::ALL_FEATURES {

cranelift/assembler-x64/meta/src/generate/inst.rs

@@ -51,9 +51,25 @@ impl dsl::Inst {
         }
     }
 
-    // `fn <inst>(<params>) -> Inst { ... }`
-    pub fn generate_variant_constructor(&self, f: &mut Formatter) {
-        let variant_name = self.name();
+    /// `impl <inst> { ... }`
+    pub fn generate_struct_impl(&self, f: &mut Formatter) {
+        let impl_block = self.generate_impl_block_start();
+        let struct_name = self.struct_name_with_generic();
+        fmtln!(f, "{impl_block} {struct_name} {{");
+        f.indent(|f| {
+            self.generate_new_function(f);
+            f.empty_line();
+            self.generate_encode_function(f);
+            f.empty_line();
+            self.generate_visit_function(f);
+            f.empty_line();
+            self.generate_features_function(f);
+        });
+        fmtln!(f, "}}");
+    }
+
+    // `fn new(<params>) -> Self { ... }`
+    pub fn generate_new_function(&self, f: &mut Formatter) {
         let params = comma_join(
             self.format
                 .operands
@@ -69,29 +85,13 @@ impl dsl::Inst {
         );
 
         fmtln!(f, "#[must_use]");
-        fmtln!(f, "pub fn {variant_name}<R: Registers>({params}) -> Inst<R> {{");
+        fmtln!(f, "pub fn new({params}) -> Self {{");
         f.indent(|f| {
-            fmtln!(f, "Inst::{variant_name}({variant_name} {{ {args} }})",);
+            fmtln!(f, "Self {{ {args} }}",);
         });
         fmtln!(f, "}}");
     }
 
-    /// `impl <inst> { ... }`
-    pub fn generate_struct_impl(&self, f: &mut Formatter) {
-        let impl_block = self.generate_impl_block_start();
-        let struct_name = self.struct_name_with_generic();
-        fmtln!(f, "{impl_block} {struct_name} {{");
-
-        f.indent_push();
-        self.generate_encode_function(f);
-        f.empty_line();
-        self.generate_visit_function(f);
-        f.empty_line();
-        self.generate_features_function(f);
-        f.indent_pop();
-        fmtln!(f, "}}");
-    }
-
     /// `fn encode(&self, ...) { ... }`
     fn generate_encode_function(&self, f: &mut Formatter) {
         let off = if self.format.uses_memory().is_some() {
@@ -191,23 +191,35 @@ impl dsl::Inst {
         let impl_block = self.generate_impl_block_start();
         let struct_name = self.struct_name_with_generic();
         fmtln!(f, "{impl_block} std::fmt::Display for {struct_name} {{");
-        f.indent_push();
-        fmtln!(f, "fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {{");
-
-        f.indent_push();
-        for op in &self.format.operands {
-            let location = op.location;
-            let to_string = location.generate_to_string(op.extension);
-            fmtln!(f, "let {location} = {to_string};");
-        }
-
-        let inst_name = &self.mnemonic;
-        let ordered_ops = self.format.generate_att_style_operands();
-        fmtln!(f, "write!(f, \"{inst_name} {ordered_ops}\")");
-        f.indent_pop();
+        f.indent(|f| {
+            fmtln!(f, "fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {{");
+            f.indent(|f| {
+                for op in &self.format.operands {
+                    let location = op.location;
+                    let to_string = location.generate_to_string(op.extension);
+                    fmtln!(f, "let {location} = {to_string};");
+                }
+                let inst_name = &self.mnemonic;
+                let ordered_ops = self.format.generate_att_style_operands();
+                fmtln!(f, "write!(f, \"{inst_name} {ordered_ops}\")");
+            });
+            fmtln!(f, "}}");
+        });
         fmtln!(f, "}}");
+    }
 
-        f.indent_pop();
+    /// `impl From<struct> for Inst { ... }`
+    pub fn generate_from_impl(&self, f: &mut Formatter) {
+        let struct_name_r = self.struct_name_with_generic();
+        let variant_name = self.name();
+        fmtln!(f, "impl<R: Registers> From<{struct_name_r}> for Inst<R> {{");
+        f.indent(|f| {
+            fmtln!(f, "fn from(inst: {struct_name_r}) -> Self {{",);
+            f.indent(|f| {
+                fmtln!(f, "Self::{variant_name}(inst)");
+            });
+            fmtln!(f, "}}");
+        });
         fmtln!(f, "}}");
     }
 
@@ -245,7 +257,7 @@ impl dsl::Inst {
         // TODO: parameterize CraneliftRegisters?
         fmtln!(f, "fn x64_{struct_name}(&mut self, {params}) -> {ret_ty} {{",);
         f.indent(|f| {
-            fmtln!(f, "let inst = cranelift_assembler_x64::build::{struct_name}({args});");
+            fmtln!(f, "let inst = cranelift_assembler_x64::inst::{struct_name}::new({args}).into();");
             fmtln!(f, "self.lower_ctx.emit(MInst::External {{ inst }});");
             fmtln!(f, "{ret_val}");
         });

cranelift/assembler-x64/src/inst.rs

@@ -0,0 +1,19 @@
+//! Expose all known instructions as Rust `struct`s; this is generated in
+//! `build.rs`.
+//!
+//! See also: [`Inst`], an `enum` containing all these instructions.
+
+use crate::api::{AsReg, CodeSink, KnownOffsetTable, RegisterVisitor, Registers};
+use crate::imm::{Extension, Imm16, Imm32, Imm8};
+use crate::mem::{emit_modrm_sib_disp, GprMem};
+use crate::reg::{self, Gpr, Size};
+use crate::rex::{self, emit_simm, RexFlags};
+
+// Include code generated by the `meta` crate.
+include!(concat!(env!("OUT_DIR"), "/assembler.rs"));
+
+/// Helper function to make code generation simpler.
+fn emit_modrm(buffer: &mut impl CodeSink, enc_reg_g: u8, rm_e: u8) {
+    let modrm = rex::encode_modrm(0b11, enc_reg_g & 7, rm_e & 7);
+    buffer.put1(modrm);
+}

cranelift/assembler-x64/src/lib.rs

@@ -1,11 +1,47 @@
-//! A Cranelift-specific x64 assembler; see the `README.md` for more
-//! information.
+//! A Cranelift-specific x64 assembler.
+//!
+//! All instructions known to this assembler are listed in the [`inst`] module.
+//! The [`Inst`] enumeration contains a variant for each, allowing matching over
+//! all these instructions. All of this is parameterized by a [`Registers`]
+//! trait, allowing users of this assembler to plug in their own register types.
+//!
+//! ```
+//! # use cranelift_assembler_x64::{Feature, Imm8, inst, Inst, Registers};
+//! // Tell the assembler the type of registers we're using; we can always
+//! // encode a HW register as a `u8` (e.g., `eax = 0`).
+//! pub struct Regs;
+//! impl Registers for Regs {
+//!     type ReadGpr = u8;
+//!     type ReadWriteGpr = u8;
+//! }
+//!
+//! // Then, build one of the `AND` instructions; this one operates on an
+//! // implicit `AL` register with an immediate. We can collect a sequence of
+//! // instructions by converting to the `Inst` type.
+//! let and = inst::andb_i::new(Imm8::new(0b10101010));
+//! let seq: Vec<Inst<Regs>> = vec![and.into()];
+//!
+//! // Now we can encode this sequence into a code buffer, checking that each
+//! // instruction is valid in 64-bit mode.
+//! let mut buffer = vec![];
+//! let offsets = vec![];
+//! for inst in seq {
+//!     if inst.features().contains(&Feature::_64b) {
+//!         inst.encode(&mut buffer, &offsets);
+//!     }
+//! }
+//! assert_eq!(buffer, vec![0x24, 0b10101010]);
+//! ```
+//!
+//! With an [`Inst`], we can encode the instruction into a code buffer; see the
+//! [example](Inst).
 
 // All of the generated struct names use snake case.
 #![allow(non_camel_case_types)]
 
 mod api;
 mod imm;
+pub mod inst;
 pub mod isle;
 mod mem;
 mod reg;
@@ -14,25 +50,33 @@ mod rex;
 #[cfg(feature = "arbitrary")]
 mod arbitrary_impls;
 
+/// An assembly instruction; contains all instructions known to the assembler.
+///
+/// This wraps all [`inst`] structures into a single enumeration for collecting
+/// instructions.
+#[doc(inline)]
+// This re-exports, and documents, a module that is more convenient to use at
+// the library top-level.
+pub use inst::Inst;
+
+/// A CPU feature.
+///
+/// This is generated from the `dsl::Feature` enumeration defined in the `meta`
+/// crate (i.e., an exact replica). It describes the CPUID features required by
+/// an instruction; see [`Inst::features`].
+#[doc(inline)]
+// Like `Inst` above, a convenient re-export.
+pub use inst::Feature;
+
 pub use api::{
-    AsReg, CodeSink, Constant, KnownOffsetTable, Label, RegisterVisitor, Registers, TrapCode,
+    AsReg, CodeSink, Constant, KnownOffset, KnownOffsetTable, Label, RegisterVisitor, Registers,
+    TrapCode,
 };
 pub use imm::{Extension, Imm16, Imm32, Imm8, Simm32, Simm32PlusKnownOffset};
 pub use mem::{Amode, DeferredTarget, GprMem, Scale};
 pub use reg::{Gpr, NonRspGpr, Size};
 pub use rex::RexFlags;
 
-// Include code generated by the `meta` crate.
-use mem::emit_modrm_sib_disp;
-use rex::emit_simm;
-include!(concat!(env!("OUT_DIR"), "/assembler.rs"));
-
-/// Helper function to make code generation simpler.
-fn emit_modrm(buffer: &mut impl CodeSink, enc_reg_g: u8, rm_e: u8) {
-    let modrm = rex::encode_modrm(0b11, enc_reg_g & 7, rm_e & 7);
-    buffer.put1(modrm);
-}
-
 /// List the files generated to create this assembler.
 pub fn generated_files() -> Vec<std::path::PathBuf> {
     env!("ASSEMBLER_BUILT_FILES")