A lightweight WebAssembly runtime that is fast, secure, and standards-compliant
//! A DSL for describing x64 encodings.
//!
//! Intended use:
//! - construct an encoding using an abbreviated helper, e.g., [`rex`]
//! - then, configure the encoding using builder methods, e.g., [`Rex::w`]
//!
//! ```
//! # use cranelift_assembler_x64_meta::dsl::rex;
//! let enc = rex(0x25).w().id();
//! assert_eq!(enc.to_string(), "REX.W + 0x25 id")
//! ```
//!
//! This module references the Intel® 64 and IA-32 Architectures Software
//! Development Manual, Volume 2: [link].
//!
//! [link]: https://software.intel.com/content/www/us/en/develop/articles/intel-sdm.html
use super::{Operand, OperandKind};
use core::fmt;
/// An abbreviated constructor for REX-encoded instructions.
#[must_use]
pub fn rex(opcode: impl Into<Opcodes>) -> Rex {
Rex {
opcodes: opcode.into(),
w: WBit::W0,
modrm: None,
imm: Imm::None,
opcode_mod: None,
}
}
/// An abbreviated constructor for VEX-encoded instructions.
#[must_use]
pub fn vex(length: Length) -> Vex {
Vex {
length,
pp: None,
mmmmm: None,
w: WBit::WIG,
opcode: u8::MAX,
modrm: None,
imm: Imm::None,
is4: false,
}
}
/// An abbreviated constructor for EVEX-encoded instructions.
#[must_use]
pub fn evex(length: Length, tuple_type: TupleType) -> Evex {
Evex {
length,
pp: None,
mmm: None,
w: WBit::WIG,
opcode: u8::MAX,
modrm: None,
imm: Imm::None,
tuple_type,
apx: None,
nd: None,
nf: None,
}
}
/// Enumerate the ways x64 encodes instructions.
pub enum Encoding {
Rex(Rex),
Vex(Vex),
Evex(Evex),
}
impl Encoding {
/// Check that the encoding is valid for the given operands; this can find
/// issues earlier, before generating any Rust code.
pub fn validate(&self, operands: &[Operand]) {
match self {
Encoding::Rex(rex) => rex.validate(operands),
Encoding::Vex(vex) => vex.validate(operands),
Encoding::Evex(evex) => evex.validate(operands),
}
}
/// Return the opcode for this encoding.
pub fn opcode(&self) -> u8 {
match self {
Encoding::Rex(rex) => rex.opcodes.opcode(),
Encoding::Vex(vex) => vex.opcode,
Encoding::Evex(evex) => evex.opcode,
}
}
/// Return whether this encoding sets the APX `ND` ("new data destination")
/// bit, meaning the architectural destination is the `vvvv`-encoded
/// register rather than an operand named by ModRM.
pub fn is_nd(&self) -> bool {
matches!(self, Encoding::Evex(evex) if evex.nd == Some(true))
}
}
impl fmt::Display for Encoding {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self {
Encoding::Rex(rex) => write!(f, "{rex}"),
Encoding::Vex(vex) => write!(f, "{vex}"),
Encoding::Evex(evex) => write!(f, "{evex}"),
}
}
}
#[derive(Clone, Copy, PartialEq)]
pub enum ModRmKind {
/// Models `/digit`.
///
/// From the reference manual: "a digit between 0 and 7 indicates that the
/// ModR/M byte of the instruction uses only the r/m (register or memory)
/// operand. The reg field contains the digit that provides an extension to
/// the instruction's opcode."
Digit(u8),
/// Models `/r`.
///
/// From the reference manual: "indicates that the ModR/M byte of the
/// instruction contains a register operand and an r/m operand."
Reg,
}
impl ModRmKind {
/// Return the digit extending the opcode, if available.
#[must_use]
pub fn digit(&self) -> Option<u8> {
match self {
Self::Digit(digit) => Some(*digit),
_ => None,
}
}
/// Return the digit extending the opcode.
///
/// # Panics
///
/// Panics if not extension was defined.
pub fn unwrap_digit(&self) -> u8 {
self.digit().expect("expected an extension digit")
}
}
impl fmt::Display for ModRmKind {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self {
ModRmKind::Digit(digit) => write!(f, "/{digit}"),
ModRmKind::Reg => write!(f, "/r"),
}
}
}
/// The traditional x64 encoding.
///
/// We use the "REX" name here in a slightly unorthodox way: "REX" is the name
/// for the optional _byte_ extending the number of available registers, e.g.,
/// but we use it here to distinguish this from other encoding formats (e.g.,
/// VEX, EVEX). The "REX" _byte_ is still optional in this encoding and only
/// emitted when necessary.
pub struct Rex {
/// The opcodes for this instruction.
///
/// Multi-byte opcodes are handled by passing an array of opcodes (including
/// prefixes like `0x66` and escape bytes like `0x0f`) to the constructor.
/// E.g., `66 0F 54` (`ANDPD`) is expressed as follows:
///
/// ```
/// # use cranelift_assembler_x64_meta::dsl::rex;
/// let enc = rex([0x66, 0x0f, 0x54]);
/// ```
pub opcodes: Opcodes,
/// Indicates setting the REX.W bit.
///
/// From the reference manual: "Indicates the use of a REX prefix that
/// affects operand size or instruction semantics. The ordering of the REX
/// prefix and other optional/mandatory instruction prefixes are discussed
/// in chapter 2. Note that REX prefixes that promote legacy instructions to
/// 64-bit behavior are not listed explicitly in the opcode column."
pub w: WBit,
/// Indicates modifications to the ModR/M byte.
pub modrm: Option<ModRmKind>,
/// The number of bits used as an immediate operand to the instruction.
pub imm: Imm,
/// Used for `+rb`, `+rw`, `+rd`, and `+ro` instructions, which encode `reg`
/// bits in the opcode byte; if `Some`, this contains the expected bit width
/// of `reg`.
///
/// From the reference manual: "[...] the lower 3 bits of the opcode byte is
/// used to encode the register operand without a modR/M byte. The
/// instruction lists the corresponding hexadecimal value of the opcode byte
/// with low 3 bits as 000b. In non-64-bit mode, a register code, from 0
/// through 7, is added to the hexadecimal value of the opcode byte. In
/// 64-bit mode, indicates the four bit field of REX.b and `opcode[2:0]`
/// field encodes the register operand of the instruction. “+ro” is
/// applicable only in 64-bit mode."
pub opcode_mod: Option<OpcodeMod>,
}
impl Rex {
/// Set the `REX.W` bit.
#[must_use]
pub fn w(self) -> Self {
Self {
w: WBit::W1,
..self
}
}
/// Set the ModR/M byte to contain a register operand and an r/m operand;
/// equivalent to `/r` in the reference manual.
#[must_use]
pub fn r(self) -> Self {
Self {
modrm: Some(ModRmKind::Reg),
..self
}
}
/// Set the digit extending the opcode; equivalent to `/<digit>` in the
/// reference manual.
///
/// # Panics
///
/// Panics if `extension` is too large.
#[must_use]
pub fn digit(self, extension: u8) -> Self {
assert!(extension <= 0b111, "must fit in 3 bits");
Self {
modrm: Some(ModRmKind::Digit(extension)),
..self
}
}
/// Retrieve the digit extending the opcode, if available.
#[must_use]
pub fn unwrap_digit(&self) -> Option<u8> {
match self.modrm {
Some(ModRmKind::Digit(digit)) => Some(digit),
_ => None,
}
}
/// Append a byte-sized immediate operand (8-bit); equivalent to `ib` in the
/// reference manual.
///
/// # Panics
///
/// Panics if an immediate operand is already set.
#[must_use]
pub fn ib(self) -> Self {
assert_eq!(self.imm, Imm::None);
Self {
imm: Imm::ib,
..self
}
}
/// Append a word-sized immediate operand (16-bit); equivalent to `iw` in
/// the reference manual.
///
/// # Panics
///
/// Panics if an immediate operand is already set.
#[must_use]
pub fn iw(self) -> Self {
assert_eq!(self.imm, Imm::None);
Self {
imm: Imm::iw,
..self
}
}
/// Append a doubleword-sized immediate operand (32-bit); equivalent to `id`
/// in the reference manual.
///
/// # Panics
///
/// Panics if an immediate operand is already set.
#[must_use]
pub fn id(self) -> Self {
assert_eq!(self.imm, Imm::None);
Self {
imm: Imm::id,
..self
}
}
/// Append a quadword-sized immediate operand (64-bit); equivalent to `io`
/// in the reference manual.
///
/// # Panics
///
/// Panics if an immediate operand is already set.
#[must_use]
pub fn io(self) -> Self {
assert_eq!(self.imm, Imm::None);
Self {
imm: Imm::io,
..self
}
}
/// Modify the opcode byte with bits from an 8-bit `reg`; equivalent to
/// `+rb` in the reference manual.
#[must_use]
pub fn rb(self) -> Self {
Self {
opcode_mod: Some(OpcodeMod::rb),
..self
}
}
/// Modify the opcode byte with bits from a 16-bit `reg`; equivalent to
/// `+rw` in the reference manual.
#[must_use]
pub fn rw(self) -> Self {
Self {
opcode_mod: Some(OpcodeMod::rw),
..self
}
}
/// Modify the opcode byte with bits from a 32-bit `reg`; equivalent to
/// `+rd` in the reference manual.
#[must_use]
pub fn rd(self) -> Self {
Self {
opcode_mod: Some(OpcodeMod::rd),
..self
}
}
/// Modify the opcode byte with bits from a 64-bit `reg`; equivalent to
/// `+ro` in the reference manual.
#[must_use]
pub fn ro(self) -> Self {
Self {
opcode_mod: Some(OpcodeMod::ro),
..self
}
}
/// Check a subset of the rules for valid encodings outlined in chapter 2,
/// _Instruction Format_, of the Intel® 64 and IA-32 Architectures Software
/// Developer’s Manual, Volume 2A.
fn validate(&self, operands: &[Operand]) {
if let Some(OperandKind::Imm(op)) = operands
.iter()
.map(|o| o.location.kind())
.find(|k| matches!(k, OperandKind::Imm(_)))
{
assert_eq!(
op.bits(),
self.imm.bits(),
"for an immediate, the encoding width must match the declared operand width"
);
}
if let Some(opcode_mod) = &self.opcode_mod {
assert!(
self.opcodes.primary & 0b111 == 0,
"the lower three bits of the opcode byte should be 0"
);
assert!(
operands
.iter()
.all(|o| o.location.bits() == opcode_mod.bits().into()),
"the opcode modifier width must match the operand widths"
);
}
assert!(!matches!(self.w, WBit::WIG));
}
}
impl From<Rex> for Encoding {
fn from(rex: Rex) -> Encoding {
Encoding::Rex(rex)
}
}
impl fmt::Display for Rex {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
if let Some(group1) = &self.opcodes.prefixes.group1 {
write!(f, "{group1} + ")?;
}
if let Some(group2) = &self.opcodes.prefixes.group2 {
write!(f, "{group2} + ")?;
}
if let Some(group3) = &self.opcodes.prefixes.group3 {
write!(f, "{group3} + ")?;
}
if let Some(group4) = &self.opcodes.prefixes.group4 {
write!(f, "{group4} + ")?;
}
if self.w.as_bool() {
write!(f, "REX.W + ")?;
}
if self.opcodes.escape {
write!(f, "0x0F + ")?;
}
write!(f, "{:#04X}", self.opcodes.primary)?;
if let Some(secondary) = self.opcodes.secondary {
write!(f, " {secondary:#04X}")?;
}
if let Some(modrm) = self.modrm {
write!(f, " {modrm}")?;
}
if let Some(opcode_mod) = &self.opcode_mod {
write!(f, " {opcode_mod}")?;
}
if self.imm != Imm::None {
write!(f, " {}", self.imm)?;
}
Ok(())
}
}
/// Describe an instruction's opcodes. From section 2.1.2 "Opcodes" in the
/// reference manual:
///
/// > A primary opcode can be 1, 2, or 3 bytes in length. An additional 3-bit
/// > opcode field is sometimes encoded in the ModR/M byte. Smaller fields can
/// > be defined within the primary opcode. Such fields define the direction of
/// > operation, size of displacements, register encoding, condition codes, or
/// > sign extension. Encoding fields used by an opcode vary depending on the
/// > class of operation.
/// >
/// > Two-byte opcode formats for general-purpose and SIMD instructions consist
/// > of one of the following:
/// > - An escape opcode byte `0FH` as the primary opcode and a second opcode
/// > byte.
/// > - A mandatory prefix (`66H`, `F2H`, or `F3H`), an escape opcode byte, and
/// > a second opcode byte (same as previous bullet).
/// >
/// > For example, `CVTDQ2PD` consists of the following sequence: `F3 0F E6`.
/// > The first byte is a mandatory prefix (it is not considered as a repeat
/// > prefix).
/// >
/// > Three-byte opcode formats for general-purpose and SIMD instructions
/// > consist of one of the following:
/// > - An escape opcode byte `0FH` as the primary opcode, plus two additional
/// > opcode bytes.
/// > - A mandatory prefix (`66H`, `F2H`, or `F3H`), an escape opcode byte, plus
/// > two additional opcode bytes (same as previous bullet).
/// >
/// > For example, `PHADDW` for XMM registers consists of the following
/// > sequence: `66 0F 38 01`. The first byte is the mandatory prefix.
pub struct Opcodes {
/// The prefix bytes for this instruction.
pub prefixes: Prefixes,
/// Indicates the use of an escape opcode byte, `0x0f`.
pub escape: bool,
/// The primary opcode.
pub primary: u8,
/// Some instructions (e.g., SIMD) may have a secondary opcode.
pub secondary: Option<u8>,
}
impl Opcodes {
/// Return the main opcode for this instruction.
///
/// Note that [`Rex`]-encoded instructions have a complex opcode scheme (see
/// [`Opcodes`] documentation); the opcode one is usually looking for is the
/// last one. This returns the last opcode: the secondary opcode if one is
/// available and the primary otherwise.
fn opcode(&self) -> u8 {
if let Some(secondary) = self.secondary {
secondary
} else {
self.primary
}
}
}
impl From<u8> for Opcodes {
fn from(primary: u8) -> Opcodes {
Opcodes {
prefixes: Prefixes::default(),
escape: false,
primary,
secondary: None,
}
}
}
impl<const N: usize> From<[u8; N]> for Opcodes {
fn from(bytes: [u8; N]) -> Self {
let (prefixes, remaining) = Prefixes::parse(&bytes);
let (escape, primary, secondary) = match remaining {
[primary] => (false, *primary, None),
[0x0f, primary] => (true, *primary, None),
[0x0f, primary, secondary] => (true, *primary, Some(*secondary)),
_ => panic!(
"invalid opcodes after prefix; expected [opcode], [0x0f, opcode], or [0x0f, opcode, opcode], found {remaining:x?}"
),
};
Self {
prefixes,
escape,
primary,
secondary,
}
}
}
/// The allowed prefixes for an instruction. From the reference manual (section
/// 2.1.1):
///
/// > Instruction prefixes are divided into four groups, each with a set of
/// > allowable prefix codes. For each instruction, it is only useful to include
/// > up to one prefix code from each of the four groups (Groups 1, 2, 3, 4).
/// > Groups 1 through 4 may be placed in any order relative to each other.
#[derive(Default)]
pub struct Prefixes {
pub group1: Option<Group1Prefix>,
pub group2: Option<Group2Prefix>,
pub group3: Option<Group3Prefix>,
pub group4: Option<Group4Prefix>,
}
impl Prefixes {
/// Parse a slice of `bytes` into a set of prefixes, returning both the
/// configured [`Prefixes`] as well as any remaining bytes.
fn parse(mut bytes: &[u8]) -> (Self, &[u8]) {
let mut prefixes = Self::default();
while !bytes.is_empty() && prefixes.try_assign(bytes[0]).is_ok() {
bytes = &bytes[1..];
}
(prefixes, bytes)
}
/// Attempt to parse a `byte` as a prefix and, if successful, assigns it to
/// the correct prefix group.
///
/// # Panics
///
/// This function panics if the prefix for a group is already set; this
/// disallows specifying multiple prefixes per group.
fn try_assign(&mut self, byte: u8) -> Result<(), ()> {
if let Ok(p) = Group1Prefix::try_from(byte) {
assert!(self.group1.is_none());
self.group1 = Some(p);
Ok(())
} else if let Ok(p) = Group2Prefix::try_from(byte) {
assert!(self.group2.is_none());
self.group2 = Some(p);
Ok(())
} else if let Ok(p) = Group3Prefix::try_from(byte) {
assert!(self.group3.is_none());
self.group3 = Some(p);
Ok(())
} else if let Ok(p) = Group4Prefix::try_from(byte) {
assert!(self.group4.is_none());
self.group4 = Some(p);
Ok(())
} else {
Err(())
}
}
/// Check if any prefix is present.
pub fn is_empty(&self) -> bool {
self.group1.is_none()
&& self.group2.is_none()
&& self.group3.is_none()
&& self.group4.is_none()
}
}
pub enum Group1Prefix {
/// The LOCK prefix (`0xf0`). From the reference manual:
///
/// > The LOCK prefix (F0H) forces an operation that ensures exclusive use
/// > of shared memory in a multiprocessor environment. See "LOCK—Assert
/// > LOCK# Signal Prefix" in Chapter 3, Instruction Set Reference, A-L, for
/// > a description of this prefix.
Lock,
/// A REPNE/REPNZ prefix (`0xf2`) or a BND prefix under certain conditions.
/// `REP*` prefixes apply only to string and input/output instructions but
/// can be used as mandatory prefixes in other kinds of instructions (e.g.,
/// SIMD) From the reference manual:
///
/// > Repeat prefixes (F2H, F3H) cause an instruction to be repeated for
/// > each element of a string. Use these prefixes only with string and I/O
/// > instructions (MOVS, CMPS, SCAS, LODS, STOS, INS, and OUTS). Use of
/// > repeat prefixes and/or undefined opcodes with other Intel 64 or IA-32
/// > instructions is reserved; such use may cause unpredictable behavior.
/// >
/// > Some instructions may use F2H, F3H as a mandatory prefix to express
/// > distinct functionality.
REPNorBND,
/// A REPE/REPZ prefix (`0xf3`); `REP*` prefixes apply only to string and
/// input/output instructions but can be used as mandatory prefixes in other
/// kinds of instructions (e.g., SIMD). See `REPNorBND` for more details.
REP_,
}
impl TryFrom<u8> for Group1Prefix {
type Error = u8;
fn try_from(byte: u8) -> Result<Self, Self::Error> {
Ok(match byte {
0xF0 => Group1Prefix::Lock,
0xF2 => Group1Prefix::REPNorBND,
0xF3 => Group1Prefix::REP_,
byte => return Err(byte),
})
}
}
impl fmt::Display for Group1Prefix {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self {
Group1Prefix::Lock => write!(f, "0xF0"),
Group1Prefix::REPNorBND => write!(f, "0xF2"),
Group1Prefix::REP_ => write!(f, "0xF3"),
}
}
}
/// Contains the segment override prefixes or a (deprecated) branch hint when
/// used on a `Jcc` instruction. Note that using the segment override prefixes
/// on a branch instruction is reserved. See section 2.1.1, "Instruction
/// Prefixes," in the reference manual.
pub enum Group2Prefix {
/// The CS segment override prefix (`0x2e`); also the "branch not taken"
/// hint.
CSorBNT,
/// The SS segment override prefix (`0x36`).
SS,
/// The DS segment override prefix (`0x3e`); also the "branch taken" hint.
DSorBT,
/// The ES segment override prefix (`0x26`).
ES,
/// The FS segment override prefix (`0x64`).
FS,
/// The GS segment override prefix (`0x65`).
GS,
}
impl TryFrom<u8> for Group2Prefix {
type Error = u8;
fn try_from(byte: u8) -> Result<Self, Self::Error> {
Ok(match byte {
0x2E => Group2Prefix::CSorBNT,
0x36 => Group2Prefix::SS,
0x3E => Group2Prefix::DSorBT,
0x26 => Group2Prefix::ES,
0x64 => Group2Prefix::FS,
0x65 => Group2Prefix::GS,
byte => return Err(byte),
})
}
}
impl fmt::Display for Group2Prefix {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self {
Group2Prefix::CSorBNT => write!(f, "0x2E"),
Group2Prefix::SS => write!(f, "0x36"),
Group2Prefix::DSorBT => write!(f, "0x3E"),
Group2Prefix::ES => write!(f, "0x26"),
Group2Prefix::FS => write!(f, "0x64"),
Group2Prefix::GS => write!(f, "0x65"),
}
}
}
/// Contains the operand-size override prefix (`0x66`); also used as a SIMD
/// prefix. From the reference manual:
///
/// > The operand-size override prefix allows a program to switch between 16-
/// > and 32-bit operand sizes. Either size can be the default; use of the
/// > prefix selects the non-default size. Some SSE2/SSE3/SSSE3/SSE4
/// > instructions and instructions using a three-byte sequence of primary
/// > opcode bytes may use 66H as a mandatory prefix to express distinct
/// > functionality.
pub enum Group3Prefix {
OperandSizeOverride,
}
impl TryFrom<u8> for Group3Prefix {
type Error = u8;
fn try_from(byte: u8) -> Result<Self, Self::Error> {
Ok(match byte {
0x66 => Group3Prefix::OperandSizeOverride,
byte => return Err(byte),
})
}
}
impl fmt::Display for Group3Prefix {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self {
Group3Prefix::OperandSizeOverride => write!(f, "0x66"),
}
}
}
/// Contains the address-size override prefix (`0x67`). From the reference
/// manual:
///
/// > The address-size override prefix (67H) allows programs to switch between
/// > 16- and 32-bit addressing. Either size can be the default; the prefix
/// > selects the non-default size.
pub enum Group4Prefix {
AddressSizeOverride,
}
impl TryFrom<u8> for Group4Prefix {
type Error = u8;
fn try_from(byte: u8) -> Result<Self, Self::Error> {
Ok(match byte {
0x67 => Group4Prefix::AddressSizeOverride,
byte => return Err(byte),
})
}
}
impl fmt::Display for Group4Prefix {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self {
Group4Prefix::AddressSizeOverride => write!(f, "0x67"),
}
}
}
/// Indicate the size of an immediate operand. From the reference manual:
///
/// > A 1-byte (ib), 2-byte (iw), 4-byte (id) or 8-byte (io) immediate operand
/// > to the instruction that follows the opcode, ModR/M bytes or scale-indexing
/// > bytes. The opcode determines if the operand is a signed value. All words,
/// > doublewords, and quadwords are given with the low-order byte first.
#[derive(Debug, PartialEq)]
#[allow(non_camel_case_types, reason = "makes DSL definitions easier to read")]
pub enum Imm {
None,
ib,
iw,
id,
io,
}
impl Imm {
fn bits(&self) -> u16 {
match self {
Self::None => 0,
Self::ib => 8,
Self::iw => 16,
Self::id => 32,
Self::io => 64,
}
}
}
impl fmt::Display for Imm {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self {
Self::None => write!(f, ""),
Self::ib => write!(f, "ib"),
Self::iw => write!(f, "iw"),
Self::id => write!(f, "id"),
Self::io => write!(f, "io"),
}
}
}
/// Indicate the size of the `reg` used when modifying the lower three bits of
/// the opcode byte; this corresponds to the `+rb`, `+rw`, `+rd`, and `+ro`
/// modifiers in the reference manual.
///
/// ```
/// # use cranelift_assembler_x64_meta::dsl::{rex};
/// // The `bswap` instruction extends the opcode byte:
/// let enc = rex([0x0F, 0xC8]).rd();
/// assert_eq!(enc.to_string(), "0x0F + 0xC8 +rd");
/// ```
#[derive(Clone, Copy, Debug, PartialEq)]
#[allow(non_camel_case_types, reason = "makes DSL definitions easier to read")]
pub enum OpcodeMod {
rb,
rw,
rd,
ro,
}
impl OpcodeMod {
fn bits(&self) -> u8 {
match self {
Self::rb => 8,
Self::rw => 16,
Self::rd => 32,
Self::ro => 64,
}
}
}
impl fmt::Display for OpcodeMod {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self {
Self::rb => write!(f, "+rb"),
Self::rw => write!(f, "+rw"),
Self::rd => write!(f, "+rd"),
Self::ro => write!(f, "+ro"),
}
}
}
/// Contains the legacy prefixes allowed for VEX-encoded instructions.
///
/// VEX encodes a subset of [`Group1Prefix`] and `0x66` (see [`Group3Prefix`])
/// as part of the `pp` bit field.
#[derive(Clone, Copy, PartialEq)]
pub enum VexPrefix {
_66,
_F2,
_F3,
}
impl VexPrefix {
/// Encode the `pp` bits.
#[inline(always)]
pub(crate) fn bits(self) -> u8 {
match self {
Self::_66 => 0b01,
Self::_F3 => 0b10,
Self::_F2 => 0b11,
}
}
}
impl fmt::Display for VexPrefix {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self {
Self::_66 => write!(f, "66"),
Self::_F3 => write!(f, "F3"),
Self::_F2 => write!(f, "F2"),
}
}
}
/// Contains the escape sequences allowed for VEX-encoded instructions.
///
/// VEX encodes these in the `mmmmmm` bit field.
#[derive(Clone, Copy, PartialEq)]
pub enum VexEscape {
_0F,
_0F3A,
_0F38,
/// APX "opcode map 4"; only valid for APX legacy-GPR (Extended EVEX)
/// encodings, never for VEX. This is the map that enables promoting legacy
/// general-purpose-register instructions into the EVEX space.
_MAP4,
}
impl VexEscape {
/// Encode the `m-mmmm` bits.
#[inline(always)]
pub(crate) fn bits(&self) -> u8 {
match self {
Self::_0F => 0b01,
Self::_0F38 => 0b10,
Self::_0F3A => 0b11,
Self::_MAP4 => 0b100,
}
}
}
impl fmt::Display for VexEscape {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self {
Self::_0F => write!(f, "0F"),
Self::_0F3A => write!(f, "0F3A"),
Self::_0F38 => write!(f, "0F38"),
Self::_MAP4 => write!(f, "MAP4"),
}
}
}
/// Contains vector length definitions.
///
/// VEX encodes these in the `L` bit field, a single bit with `128-bit = 0` and
/// `256-bit = 1`. For convenience, we also include the `LIG` and `LZ` syntax,
/// used by the reference manual, and always set these to `0`.
///
/// EVEX encodes this in the `L'L` bits, two bits that typically indicate the
/// vector length for packed vector instructions but can also be used for
/// rounding control for floating-point instructions with rounding semantics
/// (see section 2.7.1 in the reference manual).
pub enum Length {
/// 128-bit vector length.
L128,
/// 256-bit vector length.
L256,
/// 512-bit vector length; invalid for VEX instructions.
L512,
/// Force the length bits to `0`, but not necessarily for 128-bit operation.
/// From the reference manual: "The VEX.L must be encoded to be 0B, an #UD
/// occurs if VEX.L is not zero."
LZ,
/// The length bits are ignored (e.g., for floating point scalar
/// instructions). This assembler will emit `0`.
LIG,
}
impl Length {
/// Encode the `VEX.L` bit.
pub fn vex_bits(&self) -> u8 {
match self {
Self::L128 | Self::LIG | Self::LZ => 0b0,
Self::L256 => 0b1,
Self::L512 => unreachable!("VEX does not support 512-bit vector length"),
}
}
/// Encode the `EVEX.L'L` bits.
///
/// See section 2.7.10, Vector Length Orthogonality, in the reference manual
pub fn evex_bits(&self) -> u8 {
match self {
Self::L128 | Self::LIG | Self::LZ => 0b00,
Self::L256 => 0b01,
Self::L512 => 0b10,
}
}
}
impl fmt::Display for Length {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self {
Self::L128 => write!(f, "128"),
Self::L256 => write!(f, "256"),
Self::L512 => write!(f, "512"),
Self::LIG => write!(f, "LIG"),
Self::LZ => write!(f, "LZ"),
}
}
}
/// Model the `W` bit.
pub enum WBit {
/// The `W` bit is ignored; equivalent to `.WIG` in the manual.
WIG,
/// The `W` bit is set to `0`; equivalent to `.W0` in the manual.
W0,
/// The `W` bit is set to `1`; equivalent to `.W1` in the manual.
W1,
}
impl WBit {
/// Return `true` if the `W` bit is ignored; this is useful to check in the
/// DSL for the default case.
fn is_ignored(&self) -> bool {
match self {
Self::WIG => true,
Self::W0 | Self::W1 => false,
}
}
/// Return `true` if the `W` bit is set (`W1`); otherwise, return `false`.
pub(crate) fn as_bool(&self) -> bool {
match self {
Self::W1 => true,
Self::W0 | Self::WIG => false,
}
}
}
impl fmt::Display for WBit {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self {
Self::WIG => write!(f, "WIG"),
Self::W0 => write!(f, "W0"),
Self::W1 => write!(f, "W1"),
}
}
}
/// The VEX encoding, introduced for AVX instructions.
///
/// ```
/// # use cranelift_assembler_x64_meta::dsl::{vex, Length::L128};
/// // To encode a BLENDPD instruction in the manual: VEX.128.66.0F3A.WIG 0D /r ib
/// let enc = vex(L128)._66()._0f3a().wig().op(0x0D).r().ib();
/// assert_eq!(enc.to_string(), "VEX.128.66.0F3A.WIG 0x0D /r ib");
/// ```
pub struct Vex {
/// The length of the operand (e.g., 128-bit or 256-bit).
pub length: Length,
/// Any SIMD prefixes, but encoded in the `VEX.pp` bit field.
pub pp: Option<VexPrefix>,
/// Any leading map bytes, but encoded in the `VEX.mmmmm` bit field.
pub mmmmm: Option<VexEscape>,
/// The `W` bit.
pub w: WBit,
/// VEX-encoded instructions have a single-byte opcode. Other prefix-related
/// bytes (see [`Opcodes`]) are encoded in the VEX prefixes (see `pp`,
/// `mmmmmm`). From the reference manual: "One (and only one) opcode byte
/// follows the 2 or 3 byte VEX."
pub opcode: u8,
/// See [`Rex.modrm`](Rex.modrm).
pub modrm: Option<ModRmKind>,
/// See [`Rex.imm`](Rex.imm).
pub imm: Imm,
/// See [`Vex::is4`]
pub is4: bool,
}
impl Vex {
/// Set the `pp` field to use [`VexPrefix::_66`]; equivalent to `.66` in the
/// manual.
pub fn _66(self) -> Self {
assert!(self.pp.is_none());
Self {
pp: Some(VexPrefix::_66),
..self
}
}
/// Set the `pp` field to use [`VexPrefix::_F2`]; equivalent to `.F2` in the
/// manual.
pub fn _f2(self) -> Self {
assert!(self.pp.is_none());
Self {
pp: Some(VexPrefix::_F2),
..self
}
}
/// Set the `pp` field to use [`VexPrefix::_F3`]; equivalent to `.F3` in the
/// manual.
pub fn _f3(self) -> Self {
assert!(self.pp.is_none());
Self {
pp: Some(VexPrefix::_F3),
..self
}
}
/// Set the `mmmmmm` field to use [`VexEscape::_0F`]; equivalent to `.0F` in
/// the manual.
pub fn _0f(self) -> Self {
assert!(self.mmmmm.is_none());
Self {
mmmmm: Some(VexEscape::_0F),
..self
}
}
/// Set the `mmmmmm` field to use [`VexEscape::_0F3A`]; equivalent to
/// `.0F3A` in the manual.
pub fn _0f3a(self) -> Self {
assert!(self.mmmmm.is_none());
Self {
mmmmm: Some(VexEscape::_0F3A),
..self
}
}
/// Set the `mmmmmm` field to use [`VexEscape::_0F38`]; equivalent to
/// `.0F38` in the manual.
pub fn _0f38(self) -> Self {
assert!(self.mmmmm.is_none());
Self {
mmmmm: Some(VexEscape::_0F38),
..self
}
}
/// Set the `W` bit to `0`; equivalent to `.W0` in the manual.
pub fn w0(self) -> Self {
assert!(self.w.is_ignored());
Self {
w: WBit::W0,
..self
}
}
/// Set the `W` bit to `1`; equivalent to `.W1` in the manual.
pub fn w1(self) -> Self {
assert!(self.w.is_ignored());
Self {
w: WBit::W1,
..self
}
}
/// Ignore the `W` bit; equivalent to `.WIG` in the manual.
pub fn wig(self) -> Self {
assert!(self.w.is_ignored());
Self {
w: WBit::WIG,
..self
}
}
/// Set the single opcode for this VEX-encoded instruction.
pub fn op(self, opcode: u8) -> Self {
assert_eq!(self.opcode, u8::MAX);
Self { opcode, ..self }
}
/// Set the ModR/M byte to contain a register operand; see [`Rex::r`].
pub fn r(self) -> Self {
assert!(self.modrm.is_none());
Self {
modrm: Some(ModRmKind::Reg),
..self
}
}
/// Append a byte-sized immediate operand (8-bit); equivalent to `ib` in the
/// reference manual.
///
/// # Panics
///
/// Panics if an immediate operand is already set.
#[must_use]
pub fn ib(self) -> Self {
assert_eq!(self.imm, Imm::None);
Self {
imm: Imm::ib,
..self
}
}
/// Append a word-sized immediate operand (16-bit); equivalent to `iw` in
/// the reference manual.
///
/// # Panics
///
/// Panics if an immediate operand is already set.
#[must_use]
pub fn iw(self) -> Self {
assert_eq!(self.imm, Imm::None);
Self {
imm: Imm::iw,
..self
}
}
/// Append a doubleword-sized immediate operand (32-bit); equivalent to `id`
/// in the reference manual.
///
/// # Panics
///
/// Panics if an immediate operand is already set.
#[must_use]
pub fn id(self) -> Self {
assert_eq!(self.imm, Imm::None);
Self {
imm: Imm::id,
..self
}
}
/// Append a quadword-sized immediate operand (64-bit); equivalent to `io`
/// in the reference manual.
///
/// # Panics
///
/// Panics if an immediate operand is already set.
#[must_use]
pub fn io(self) -> Self {
assert_eq!(self.imm, Imm::None);
Self {
imm: Imm::io,
..self
}
}
/// Set the digit extending the opcode; equivalent to `/<digit>` in the
/// reference manual.
///
/// # Panics
///
/// Panics if `extension` is too large.
#[must_use]
pub fn digit(self, extension: u8) -> Self {
assert!(extension <= 0b111, "must fit in 3 bits");
Self {
modrm: Some(ModRmKind::Digit(extension)),
..self
}
}
/// An 8-bit immediate byte is present containing a source register
/// specifier in either `imm8[7:4]` (for 64-bit
/// mode) or `imm8[6:4]` (for 32-bit mode), and instruction-specific payload
/// in `imm8[3:0]`.
pub fn is4(self) -> Self {
Self { is4: true, ..self }
}
fn validate(&self, _operands: &[Operand]) {
assert!(self.opcode != u8::MAX);
assert!(self.mmmmm.is_some());
assert!(!matches!(self.length, Length::L512));
}
/// Retrieve the digit extending the opcode, if available.
#[must_use]
pub fn unwrap_digit(&self) -> Option<u8> {
match self.modrm {
Some(ModRmKind::Digit(digit)) => Some(digit),
_ => None,
}
}
}
impl From<Vex> for Encoding {
fn from(vex: Vex) -> Encoding {
Encoding::Vex(vex)
}
}
impl fmt::Display for Vex {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
write!(f, "VEX.{}", self.length)?;
if let Some(pp) = self.pp {
write!(f, ".{pp}")?;
}
if let Some(mmmmm) = self.mmmmm {
write!(f, ".{mmmmm}")?;
}
write!(f, ".{} {:#04X}", self.w, self.opcode)?;
if let Some(modrm) = self.modrm {
write!(f, " {modrm}")?;
}
if self.imm != Imm::None {
write!(f, " {}", self.imm)?;
}
Ok(())
}
}
pub struct Evex {
/// The vector length of the operand (e.g., 128-bit, 256-bit, or 512-bit).
pub length: Length,
/// Any SIMD prefixes, but encoded in the `EVEX.pp` bit field (see similar:
/// [`Vex::pp`]).
pub pp: Option<VexPrefix>,
/// The `mmm` bits.
///
/// Bits `1:0` are identical to the lowest 2 bits of `VEX.mmmmm`; EVEX adds
/// one more bit here. From the reference manual: "provides access to up to
/// eight decoding maps. Currently, only the following decoding maps are
/// supported: 1, 2, 3, 5, and 6. Map ids 1, 2, and 3 are denoted by 0F,
/// 0F38, and 0F3A, respectively, in the instruction encoding descriptions."
pub mmm: Option<VexEscape>,
/// The `W` bit.
pub w: WBit,
/// EVEX-encoded instructions opcode byte"
pub opcode: u8,
/// See [`Rex.modrm`](Rex.modrm).
pub modrm: Option<ModRmKind>,
/// See [`Rex.imm`](Rex.imm).
pub imm: Imm,
/// The "Tuple Type" corresponding to scaling of the 8-bit displacement
/// parameter for memory operands. See [`TupleType`] for more information.
pub tuple_type: TupleType,
/// The APX "Extended EVEX" class, when this instruction is an APX
/// promotion.
///
/// Intel APX (Advanced Performance Extensions) reuses the `0x62` EVEX
/// identifier but does *not* define a single static payload layout.
/// Instead, the meaning of the payload bytes (`P0`, `P1`, `P2`) is
/// re-mapped depending on which class of instruction is being promoted (see
/// [`ApxClass`]). `None` denotes a standard (AVX-512) EVEX encoding;
/// `Some(_)` selects one of the APX layouts and enables addressing of the
/// extended general-purpose registers `R16`–`R31` ("EGPR").
pub apx: Option<ApxClass>,
/// The APX `ND` (New Data destination) bit.
///
/// When set, a legacy destructive two-operand instruction is promoted into
/// a non-destructive three-operand form (the extra destination is encoded
/// in the `EVEX.vvvv` field). `None` when the bit is not part of this
/// encoding; only valid for [`ApxClass::LegacyGpr`].
pub nd: Option<bool>,
/// The APX `NF` (No Flags) bit.
///
/// When set, the status-flag writes that a legacy integer instruction would
/// otherwise perform are suppressed. `None` when the bit is not part of
/// this encoding; only valid for [`ApxClass::LegacyGpr`].
pub nf: Option<bool>,
}
impl Evex {
/// Set the `pp` field to use [`VexPrefix::_66`]; equivalent to `.66` in the
/// manual.
pub fn _66(self) -> Self {
assert!(self.pp.is_none());
Self {
pp: Some(VexPrefix::_66),
..self
}
}
/// Set the `pp` field to use [`VexPrefix::_F2`]; equivalent to `.F2` in the
/// manual.
pub fn _f2(self) -> Self {
assert!(self.pp.is_none());
Self {
pp: Some(VexPrefix::_F2),
..self
}
}
/// Set the `pp` field to use [`VexPrefix::_F3`]; equivalent to `.F3` in the
/// manual.
pub fn _f3(self) -> Self {
assert!(self.pp.is_none());
Self {
pp: Some(VexPrefix::_F3),
..self
}
}
/// Set the `mmmmmm` field to use [`VexEscape::_0F`]; equivalent to `.0F` in
/// the manual.
pub fn _0f(self) -> Self {
assert!(self.mmm.is_none());
Self {
mmm: Some(VexEscape::_0F),
..self
}
}
/// Set the `mmmmmm` field to use [`VexEscape::_0F3A`]; equivalent to
/// `.0F3A` in the manual.
pub fn _0f3a(self) -> Self {
assert!(self.mmm.is_none());
Self {
mmm: Some(VexEscape::_0F3A),
..self
}
}
/// Set the `mmmmmm` field to use [`VexEscape::_0F38`]; equivalent to
/// `.0F38` in the manual.
pub fn _0f38(self) -> Self {
assert!(self.mmm.is_none());
Self {
mmm: Some(VexEscape::_0F38),
..self
}
}
/// Select the APX "opcode map 4", promoting a legacy general-purpose-register
/// instruction into the Extended EVEX space; equivalent to `.MAP4` in the
/// manual.
///
/// This both sets the `mmm` map bits and marks the encoding as
/// [`ApxClass::LegacyGpr`], which in turn enables addressing of the extended
/// GPRs `R16`–`R31` ("EGPR") and permits the `ND`/`NF` bits.
///
/// # Panics
///
/// Panics if the map (`mmm`) or APX class has already been set.
pub fn map4(self) -> Self {
assert!(self.mmm.is_none());
assert!(self.apx.is_none());
Self {
mmm: Some(VexEscape::_MAP4),
apx: Some(ApxClass::LegacyGpr),
..self
}
}
/// Set the `W` bit to `0`; equivalent to `.W0` in the manual.
pub fn w0(self) -> Self {
assert!(self.w.is_ignored());
Self {
w: WBit::W0,
..self
}
}
/// Set the `W` bit to `1`; equivalent to `.W1` in the manual.
pub fn w1(self) -> Self {
assert!(self.w.is_ignored());
Self {
w: WBit::W1,
..self
}
}
/// Ignore the `W` bit; equivalent to `.WIG` in the manual.
pub fn wig(self) -> Self {
assert!(self.w.is_ignored());
Self {
w: WBit::WIG,
..self
}
}
/// Set the single opcode for this VEX-encoded instruction.
pub fn op(self, opcode: u8) -> Self {
assert_eq!(self.opcode, u8::MAX);
Self { opcode, ..self }
}
/// Set the ModR/M byte to contain a register operand; see [`Rex::r`].
pub fn r(self) -> Self {
assert!(self.modrm.is_none());
Self {
modrm: Some(ModRmKind::Reg),
..self
}
}
/// Mark this as an APX "Extended EVEX" encoding of the given [`ApxClass`].
///
/// This selects the APX payload layout to emit and enables addressing of
/// the extended general-purpose registers `R16`–`R31` ("EGPR").
///
/// # Panics
///
/// Panics if an APX class has already been set.
pub fn apx(self, class: ApxClass) -> Self {
assert!(self.apx.is_none());
Self {
apx: Some(class),
..self
}
}
/// Set the APX `ND` (New Data destination) bit; equivalent to `.ND` in the
/// manual.
///
/// # Panics
///
/// Panics if this is not an [`ApxClass::LegacyGpr`] encoding, or if the bit
/// has already been set.
pub fn nd(self) -> Self {
assert_eq!(
self.apx,
Some(ApxClass::LegacyGpr),
"the ND bit is only valid for APX legacy-GPR promotions"
);
assert!(self.nd.is_none());
Self {
nd: Some(true),
..self
}
}
/// Set the APX `NF` (No Flags) bit; equivalent to `.NF` in the manual.
///
/// # Panics
///
/// Panics if this is not an [`ApxClass::LegacyGpr`] encoding, or if the bit
/// has already been set.
pub fn nf(self) -> Self {
assert_eq!(
self.apx,
Some(ApxClass::LegacyGpr),
"the NF bit is only valid for APX legacy-GPR promotions"
);
assert!(self.nf.is_none());
Self {
nf: Some(true),
..self
}
}
fn validate(&self, _operands: &[Operand]) {
assert!(self.opcode != u8::MAX);
assert!(self.mmm.is_some());
// The `ND`/`NF` bits are only defined for APX legacy-GPR promotions.
if self.nd.is_some() || self.nf.is_some() {
assert_eq!(
self.apx,
Some(ApxClass::LegacyGpr),
"the ND/NF bits require an APX legacy-GPR encoding"
);
}
}
/// Retrieve the digit extending the opcode, if available.
#[must_use]
pub fn unwrap_digit(&self) -> Option<u8> {
match self.modrm {
Some(ModRmKind::Digit(digit)) => Some(digit),
_ => None,
}
}
/// Set the digit extending the opcode; equivalent to `/<digit>` in the
/// reference manual.
///
/// # Panics
///
/// Panics if `extension` is too large.
#[must_use]
pub fn digit(self, extension: u8) -> Self {
assert!(extension <= 0b111, "must fit in 3 bits");
Self {
modrm: Some(ModRmKind::Digit(extension)),
..self
}
}
/// Append a byte-sized immediate operand (8-bit); equivalent to `ib` in the
/// reference manual.
///
/// # Panics
///
/// Panics if an immediate operand is already set.
#[must_use]
pub fn ib(self) -> Self {
assert_eq!(self.imm, Imm::None);
Self {
imm: Imm::ib,
..self
}
}
}
impl From<Evex> for Encoding {
fn from(evex: Evex) -> Encoding {
Encoding::Evex(evex)
}
}
impl fmt::Display for Evex {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
write!(f, "EVEX.{}", self.length)?;
if let Some(pp) = self.pp {
write!(f, ".{pp}")?;
}
if let Some(mmmmm) = self.mmm {
write!(f, ".{mmmmm}")?;
}
write!(f, ".{}", self.w)?;
if self.nd == Some(true) {
write!(f, ".ND")?;
}
if self.nf == Some(true) {
write!(f, ".NF")?;
}
write!(f, " {:#04X}", self.opcode)?;
if let Some(modrm) = self.modrm {
write!(f, " {modrm}")?;
}
if self.imm != Imm::None {
write!(f, " {}", self.imm)?;
}
Ok(())
}
}
/// The class of an APX "Extended EVEX" encoding.
///
/// Intel APX does not define a single static Extended-EVEX layout. Although
/// every APX instruction still begins with the `0x62` EVEX identifier, the
/// meaning of the payload bytes (`P0`, `P1`, `P2`) is re-mapped depending on
/// the class of instruction being promoted. This enum selects which layout the
/// assembler should emit; all classes gain access to the extended
/// general-purpose registers `R16`–`R31` ("EGPR").
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum ApxClass {
/// Promotion of a legacy general-purpose-register (GPR) instruction using
/// extended opcode map 4. Only this class may set the `ND` and `NF` bits.
LegacyGpr,
/// Promotion of a legacy SSE / VEX vector instruction into the EVEX space.
Vector,
/// An existing AVX-512 (EVEX) instruction extended with APX register bits.
Avx512,
}
impl fmt::Display for ApxClass {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self {
Self::LegacyGpr => write!(f, "LegacyGpr"),
Self::Vector => write!(f, "Vector"),
Self::Avx512 => write!(f, "Avx512"),
}
}
}
/// Tuple Type definitions used in EVEX encodings.
///
/// This enumeration corresponds to table 2-34 and 2-35 in the Intel manual.
/// This is a property of all instruction formats listed in the encoding table
/// for each instruction.
#[expect(missing_docs, reason = "matching manual names")]
pub enum TupleType {
Full,
Half,
FullMem,
Tuple1Scalar,
Tuple1Fixed,
Tuple2,
Tuple4,
Tuple8,
HalfMem,
QuarterMem,
EigthMem,
Mem128,
Movddup,
}