cranelift_assembler_x64_meta/

dsl.rs

//! Defines a domain-specific language (DSL) for describing x64 instructions.
//!
//! This language is intended to be:
//! - compact--i.e., define an x64 instruction on a single line, and
//! - a close-to-direct mapping of what we read in the x64 reference manual.

mod custom;
mod encoding;
mod features;
pub mod format;

pub use custom::{Custom, Customization};
pub use encoding::{Encoding, ModRmKind, OpcodeMod};
pub use encoding::{Evex, Length, Vex, VexEscape, VexPrefix, evex, vex};
pub use encoding::{
    Group1Prefix, Group2Prefix, Group3Prefix, Group4Prefix, Opcodes, Prefixes, Rex, TupleType, rex,
};
pub use features::{ALL_FEATURES, Feature, Features};
pub use format::{Eflags, Extension, Format, Location, Mutability, Operand, OperandKind, RegClass};
pub use format::{align, fmt, implicit, r, rw, sxl, sxq, sxw, w};

/// Abbreviated constructor for an x64 instruction.
pub fn inst(
    mnemonic: impl Into<String>,
    format: Format,
    encoding: impl Into<Encoding>,
    features: impl Into<Features>,
) -> Inst {
    let encoding = encoding.into();
    encoding.validate(&format.operands);
    Inst {
        mnemonic: mnemonic.into(),
        format,
        encoding,
        features: features.into(),
        alternate: None,
        has_trap: false,
        custom: Custom::default(),
    }
}

/// An x64 instruction.
///
/// Use [`inst`] to construct this within the
/// [`instructions`](super::instructions) module. This structure is designed to
/// represent all of the information for one instruction (a table row) in the
/// x64 _Instruction Set Reference_ or at least enough to generate code to emit
/// the instruction.
pub struct Inst {
    /// The instruction name as represented in the x64 reference manual. This is
    /// the pretty-printed name used for disassembly. Multiple instructions may
    /// have the same mnemonic, though; the combination of this field and the
    /// format name must be unique (see [`Inst::name`]).
    pub mnemonic: String,
    /// The instruction operands, typically represented in the "Instruction"
    /// column of the x64 reference manual.
    pub format: Format,
    /// The instruction encoding, typically represented in the "Opcode" column
    /// of the x64 reference manual.
    pub encoding: Encoding,
    /// The CPU features required to use this instruction; this combines the
    /// "64-bit/32-bit Mode Support" and "CPUID Feature Flag" columns of the x64
    /// reference manual.
    pub features: Features,
    /// An alternate version of this instruction, if it exists.
    pub alternate: Option<Alternate>,
    /// Whether or not this instruction can trap and thus needs a `TrapCode`
    /// payload in the instruction itself.
    pub has_trap: bool,
    /// Whether or not this instruction uses custom, external functions
    /// instead of Rust code generated by this crate.
    pub custom: Custom,
}

impl Inst {
    /// The unique name for this instruction.
    ///
    /// To avoid ambiguity, this name combines the instruction mnemonic and the
    /// format name in snake case. This is used in generated code to name the
    /// instruction `struct` and builder functions.
    ///
    /// In rare cases, this `<mnemonic>_<format>` scheme does not uniquely
    /// identify an instruction in x64 ISA (e.g., some extended versions,
    /// VEX/EVEX). In these cases, we append a minimal identifier to
    /// the format name (e.g., `sx*`) to keep this unique.
    #[must_use]
    pub fn name(&self) -> String {
        format!(
            "{}_{}",
            self.mnemonic.to_lowercase(),
            self.format.name.to_lowercase()
        )
    }

    /// Flags this instruction as being able to trap, so needs a `TrapCode` at
    /// compile time to track this.
    pub fn has_trap(mut self) -> Self {
        self.has_trap = true;
        self
    }

    /// Indicate this instruction as needing custom processing.
    pub fn custom(mut self, custom: impl Into<Custom>) -> Self {
        self.custom = custom.into();
        self
    }

    /// Sets the alternate version of this instruction, if it exists.
    pub fn alt(mut self, feature: Feature, alternate: impl Into<String>) -> Self {
        self.alternate = Some(Alternate {
            feature,
            name: alternate.into(),
        });
        self
    }

    /// The mnemonics XED prints for this encoding: `(register form, memory
    /// form)`. XED picks a different spelling than we do in three systematic
    /// ways, all handled here:
    ///
    /// 1. it drops the AT&T operand-size suffix we carry (`addl` -> `add`);
    /// 2. it prefers a different condition-code alias (`cmovae` -> `cmovnb`);
    /// 3. it appends a width marker when an operand is *memory*, sized by that
    ///    operand (`addsd` -> `addsdq`, `cmovnb` -> `cmovnbl`).
    ///
    /// The two forms differ only when (3) applies, which is why this returns a
    /// pair: the choice is made at runtime from the `r/m` operand.
    #[must_use]
    pub fn xed_mnemonics(&self) -> (String, String) {
        // `lock_addb` is printed `lock addb`; see `custom::mnemonic`.
        let mut base = match self.mnemonic.strip_prefix("lock_") {
            Some(rest) => format!("lock {rest}"),
            None => self.mnemonic.clone(),
        };

        // (1) Drop our size suffix when it matches the width of some operand.
        // Mnemonics XED spells differently outright keep their suffix (it is
        // part of the name), as do condition-code mnemonics whose trailing
        // letter is the condition itself (`setb`) rather than a size.
        if !is_exception(&base) && !is_condition_family(&base) && !keeps_suffix(&base, &self.format)
        {
            let widths: Vec<_> = self
                .format
                .locations()
                .map(|l| width_marker(l.bits()))
                .collect();
            if base.len() > 2 && widths.iter().any(|w| base.ends_with(w)) {
                base.truncate(base.len() - 1);
            }
        }

        // (2) XED's preferred spelling for the families that have aliases.
        base = rename(&base);

        // (3) A width marker is appended when the operand is memory, sized by
        // that operand. `lea` names an address rather than accessing it, so
        // never takes one; `push`/`pop` always do, even for registers; and for
        // mnemonics that already name their width the marker repeats it
        // (`pextrb` -> `pextrbb`).
        if matches!(base.as_str(), "push" | "pop") {
            let bits = self.format.locations().next().map_or(64, Location::bits);
            let m = format!("{base}{}", width_marker(bits));
            return (m.clone(), m);
        }
        let mem = match self.format.uses_memory() {
            Some(_) if base == "lea" => base.clone(),
            Some(_) if keeps_suffix(&base, &self.format) => {
                // The mnemonic already names its width; XED repeats it using
                // its own letter (`pextrd` is 32-bit, so `pextrdl`).
                let named = match &base[base.len() - 1..] {
                    "b" => 8,
                    "w" => 16,
                    "d" => 32,
                    _ => 64,
                };
                format!("{base}{}", width_marker(named))
            }
            Some(loc) => format!("{base}{}", width_marker(loc.bits())),
            None => base.clone(),
        };
        (base, mem)
    }
}

/// XED's single-letter marker for an operand width.
fn width_marker(bits: u16) -> &'static str {
    match bits {
        8 => "b",
        16 => "w",
        32 => "l",
        64 => "q",
        128 => "x",
        256 => "y",
        512 => "z",
        b => unreachable!("no XED width marker for {b} bits"),
    }
}

/// Mnemonics XED spells differently outright.
const XED_RENAMES: &[(&str, &str)] = &[
    ("cbtw", "data16 cbw"),
    ("cltd", "cdq"),
    ("cltq", "cdqe"),
    ("cqto", "cqo"),
    ("cwtd", "data16 cwd"),
    ("cwtl", "cwde"),
    ("movabsq", "mov"),
    ("movslq", "movsxd"),
];

fn is_exception(m: &str) -> bool {
    XED_RENAMES.iter().any(|(o, _)| *o == m)
}

/// The sixteen x64 condition codes, as spelled in our mnemonics.
const CONDITIONS: &[&str] = &[
    "a", "ae", "b", "be", "e", "g", "ge", "l", "le", "ne", "no", "np", "ns", "o", "p", "s",
];

/// Whether `m` is a `cmov`/`set`/`j` mnemonic carrying a valid condition code.
fn is_condition_family(m: &str) -> bool {
    ["cmov", "set", "j"]
        .iter()
        .filter_map(|p| m.strip_prefix(p))
        .any(|cc| CONDITIONS.contains(&cc))
}

/// Mnemonics whose trailing size letter names the instruction (`pextrb`
/// extracts a *byte*) rather than decorating it in the AT&T style.
fn keeps_suffix(m: &str, format: &Format) -> bool {
    const INTRINSIC: &str =
        "pextr pinsr vpextr vpinsr vpbroadcast pmovsxd pmovzxd vpmovsxd vpmovzxd";
    INTRINSIC.split(' ').any(|p| m.starts_with(p))
        // `movq` is a GPR move (suffix) or an XMM move (name) by operand type.
        || (matches!(m, "movq" | "vmovq") && format.locations().any(|l| l.bits() == 128))
}

/// Rewrite a suffix-stripped mnemonic into XED's preferred spelling.
fn rename(base: &str) -> String {
    if let Some((_, x)) = XED_RENAMES.iter().find(|(o, _)| *o == base) {
        return (*x).to_string();
    }

    // `movzbl`/`movswq`/... collapse to plain `movzx`/`movsx`; after the size
    // suffix is stripped a single source-width letter remains.
    for (prefix, xed) in [("movz", "movzx"), ("movs", "movsx")] {
        if let Some(rest) = base.strip_prefix(prefix) {
            if rest.len() == 1 && "bwlq".contains(rest) {
                return xed.to_string();
            }
        }
    }

    // Condition-code families: XED prefers the negated spelling for six of the
    // sixteen conditions.
    for prefix in ["cmov", "set", "j"] {
        if let Some(cc) = base.strip_prefix(prefix) {
            let renamed = match cc {
                "a" => "nbe",
                "ae" => "nb",
                "e" => "z",
                "g" => "nle",
                "ge" => "nl",
                "ne" => "nz",
                _ => return base.to_string(),
            };
            return format!("{prefix}{renamed}");
        }
    }

    base.to_string()
}

impl core::fmt::Display for Inst {
    fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
        let Inst {
            mnemonic: name,
            format,
            encoding,
            features,
            alternate,
            has_trap,
            custom,
        } = self;
        write!(f, "{name}: {format} => {encoding}")?;
        write!(f, " [{features}]")?;
        if let Some(alternate) = alternate {
            write!(f, " (alternate: {alternate})")?;
        }
        if *has_trap {
            write!(f, " has_trap")?;
        }
        if !custom.is_empty() {
            write!(f, " custom({custom})")?;
        }
        Ok(())
    }
}

/// An alternate version of an instruction.
///
/// Some AVX-specific context: some instructions have the same semantics in
/// their SSE and AVX encodings. In these cases, we use this structure to record
/// the name of the upgraded version of the instruction, allowing us to replace
/// the SSE instruction with its AVX version during lowering. For AVX, using the
/// VEX-encoded instruction is typically better than its legacy SSE version:
/// - VEX can encode three operands
/// - VEX allows unaligned memory access (avoids additional `MOVUPS`)
/// - VEX can compact byte-long prefixes into the VEX prefix
/// - VEX instructions zero the upper bits of XMM registers by default
pub struct Alternate {
    /// Indicate the feature check to use to trigger the replacement.
    pub feature: Feature,
    /// The full name (see [`Inst::name`]) of the instruction used for
    /// replacement.
    pub name: String,
}

impl core::fmt::Display for Alternate {
    fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
        write!(f, "{} => {}", self.feature, self.name)
    }
}