Struct bddisasm::decoded_instruction::DecodedInstruction

pub struct DecodedInstruction { /* private fields */ }

A decoded instruction.

Implementations

impl DecodedInstruction

pub fn decode_with_ip(code: &[u8], mode: DecodeMode, ip: u64) -> DecodeResult

Decodes an array of bytes.

Arguments

• code - An u8 slice that holds the code to be decoded. Note that decoding is attempted only from offset 0 inside this code chunk.
• mode - The mode in which to decode the instruction.
• ip - The instruction pointer value to use when formatting the decoded instruction. Does not affect the decoding process in any way. If not needed, use decode instead.

Errors

Wil return Err if the given bytes do not encode a valid instruction in the given mode.

Examples

use bddisasm::{DecodedInstruction, DecodeMode, Mnemonic};

let code = vec![0x48, 0x8b, 0x05, 0xf9, 0xff, 0xff, 0xff];

let instruction = DecodedInstruction::decode_with_ip(&code, DecodeMode::Bits64, 0)?;
assert_eq!(format!("{}", instruction), "MOV       rax, qword ptr [rel 0x0]");

let instruction = DecodedInstruction::decode_with_ip(&code, DecodeMode::Bits64, 0x100)?;
assert_eq!(format!("{}", instruction), "MOV       rax, qword ptr [rel 0x100]");

Panics

This function will panic if the result of the C library is unrecognized. This can not happen under normal circumstances.

pub fn decode(code: &[u8], mode: DecodeMode) -> DecodeResult

Decodes an array of bytes.

This function is a thin wrapper over decode_with_ip and behaves exactly the same. It sets ip to 0.

Errors

Wil return Err if the given bytes do not encode a valid instruction in the given mode.

Panics

This function will panic if the result of the C library is unrecognized. This can not happen under normal circumstances.

pub fn mnemonic(&self) -> Mnemonic

Get the mnemonic of the instruction.

pub fn length(&self) -> usize

Get the instruction length, in bytes.

It is guaranteed that no instruction will exceed a length of 15 bytes.

pub fn operands(&self) -> Operands

Get the instruction operands.

For working with specific operands (like the source or destination), operand_lookup() might be a better choice.

The number of elements in the returned vector will always be equal to operands_count.

Examples

See operand for more in-depth examples on how to work with instruction operands.

use bddisasm::{DecodedInstruction, DecodeMode, Mnemonic};

// `MOV       ebx, dword ptr [ecx+edi]`
let instruction = DecodedInstruction::decode(b"\x8b\x1c\x39", DecodeMode::Bits32)?;    ///
let operands = instruction.operands();
// The first operand is the destination
let dst = operands[0];
// The second operand is the source
let src = operands[1];

// Print information about the operands
println!("{:#?} {:#?}", dst.info, src.info);

Panics

This function will panic if the operand returned by the C library is invalid. This can not happen under normal circumstances.

pub fn cpuid(&self) -> Option<Cpuid>

Returns the CPUID support flag.

If None, the instruction is supported on any CPU, and no CPUID flag exists.

Examples

See cpuid for more in-depth examples on how to use the CPUID information.

use bddisasm::{DecodedInstruction, DecodeMode, Mnemonic};

// `RDMSR`
let instruction = DecodedInstruction::decode(b"\x0f\x32", DecodeMode::Bits64)?;
let cpuid = instruction.cpuid();
assert!(cpuid.is_some());

let cpuid = cpuid.unwrap();
assert_eq!(cpuid.leaf, 1);
assert_eq!(cpuid.sub_leaf, None);
assert_eq!(cpuid.register, 2);
assert_eq!(cpuid.bit, 5);

pub fn encoding_mode(&self) -> EncodingMode

Get the encoding mode used.

Panics

This function will panic if the encoding mode is unrecognized. This can not happen under normal circumstances.

pub fn vex_mode(&self) -> Option<VexMode>

Get the VEX mode, if any.

Panics

This function will panic if the VEX mode is unrecognized. This can not happen under normal circumstances.

pub fn addr_mode(&self) -> AddressingMode

Get the addressing mode.

Panics

This function will panic if the addressing mode is unrecognized. This can not happen under normal circumstances.

pub fn op_mode(&self) -> OperandSize

Get the operand mode/size.

This is computed based on the passed-in DecodeMode and instruction prefixes.

Remarks

The effective mode can be different (see effective_op_mode).

Examples

Using DecodeMode::Bits64, 0x50 encodes a PUSH rax instruction with an operand size of 32 because it has no prefix that promotes it, but the effective size is 64 because the instruction always operates on 64 bits.

use bddisasm::{DecodedInstruction, DecodeMode, Mnemonic, OperandSize};

let ins =
    DecodedInstruction::decode(&[0x50], DecodeMode::Bits64)?;
assert_eq!(ins.mnemonic(), Mnemonic::PUSH);
assert_eq!(ins.op_mode(), OperandSize::OpSize32);
assert_eq!(ins.effective_op_mode(), OperandSize::OpSize64);

let ins =
    DecodedInstruction::decode(&[0x48, 0x50], DecodeMode::Bits64)?;
assert_eq!(ins.mnemonic(), Mnemonic::PUSH);
assert_eq!(ins.op_mode(), OperandSize::OpSize64);
assert_eq!(ins.effective_op_mode(), OperandSize::OpSize64);

Panics

This function will panic if the operand size is unrecognized. This can not happen under normal circumstances.

pub fn effective_op_mode(&self) -> OperandSize

Get the effective operand mode/size.

Unlike op_mode, this takes into account the actual instruction.

Panics

This function will panic if the operand size is unrecognized. This can not happen under normal circumstances.

pub fn vec_mode(&self) -> Option<VectorSize>

Get the Vector mode/size, if any.

This is computed based on the passed-in DecodeMode and instruction prefixes.

Remarks

The effective mode can be different (see effective_vec_mode).

Panics

This function will panic if the vector mode is unrecognized. This can not happen under normal circumstances.

pub fn effective_vec_mode(&self) -> Option<VectorSize>

Get the Vector mode/size, if any.

Unlike vec_mode, this takes into account the actual instruction.

Panics

This function will panic if the vector mode is unrecognized. This can not happen under normal circumstances.

pub fn has_rex(&self) -> bool

true if REX is present.

pub fn has_vex(&self) -> bool

true if VEX is present.

pub fn has_xop(&self) -> bool

true if XOP is present.

pub fn has_evex(&self) -> bool

true if EVEX is present.

pub fn has_op_size(&self) -> bool

true if 0x66 is present.

pub fn has_addr_size(&self) -> bool

true if 0x67 is present.

pub fn has_lock(&self) -> bool

true if 0xF0 is present.

pub fn has_repnz_xacquire_bnd(&self) -> bool

true if 0xF2 is present.

pub fn has_rep_repz_xrelease(&self) -> bool

true if 0xF3 is present.

pub fn has_seg(&self) -> bool

true if segment override is present.

pub fn is_repeated(&self) -> bool

true if the instruction is repeated up to RCX times.

pub fn is_xacquire_enabled(&self) -> bool

true if the instruction is XACQUIRE enabled.

pub fn is_xrelease_enabled(&self) -> bool

true if the instruction is XRELEASE enabled.

pub fn is_rip_relative(&self) -> bool

true if the instruction uses RIP relative addressing.

pub fn is_cet_tracked(&self) -> bool

true if this is an indirect CALL/JMP that is CET tracked.

pub fn has_mod_rm(&self) -> bool

true if we have valid MODRM.

pub fn has_sib(&self) -> bool

true if we have valid SIB.

pub fn has_disp(&self) -> bool

true if the instruction has displacement.

pub fn has_addr(&self) -> bool

true if the instruction contains a direct address (ie, CALL far 0x9A).

pub fn has_moffset(&self) -> bool

true if the instruction contains a moffset (ie, MOV al, [mem], 0xA0).

pub fn has_imm1(&self) -> bool

true if immediate is present.

pub fn has_imm2(&self) -> bool

true if second immediate is present.

pub fn has_rel_offs(&self) -> bool

true if the instruction contains a relative offset (ie, Jcc 0x7x).

pub fn has_sse_imm(&self) -> bool

true if SSE immediate that encodes additional registers is present.

pub fn has_comp_disp(&self) -> bool

true if the instruction uses compressed displacement.

pub fn has_broadcast(&self) -> bool

true if the instruction uses broadcast addressing.

pub fn has_mask(&self) -> bool

true if the instruction has mask.

pub fn has_zero(&self) -> bool

true if the instruction uses zeroing.

pub fn has_er(&self) -> bool

true if the instruction has embedded rounding.

pub fn has_sae(&self) -> bool

true if the instruction has SAE.

pub fn has_ign_er(&self) -> bool

true if the instruction ignores embedded rounding.

pub fn has_mandatory_66(&self) -> bool

true if changing prefix.

pub fn has_mandatory_f2(&self) -> bool

0x66 is mandatory prefix. Does not behave as REP prefix.

pub fn has_mandatory_f3(&self) -> bool

0x66 is mandatory prefix. Does not behave as REP prefix.

pub fn word_length(&self) -> usize

The length of the instruction word. 2, 4 or 8.

pub fn pref_length(&self) -> usize

The total number of bytes consumed by prefixes.

This will also be the offset to the first opcode. The primary opcode will always be the last one.

pub fn op_length(&self) -> usize

Number of opcode bytes. Max 3.

pub fn disp_length(&self) -> usize

Displacement length, in bytes. Maximum 4.

pub fn addr_length(&self) -> usize

Absolute address length, in bytes. Maximum 8 bytes.

pub fn moffset_length(&self) -> usize

Memory offset length, in bytes. Maximum 8 bytes.

pub fn imm1_length(&self) -> usize

First immediate length, in bytes. Maximum 8 bytes.

pub fn imm2_length(&self) -> usize

Second immediate length, in bytes. Maximum 8 bytes.

pub fn rel_offs_length(&self) -> usize

Relative offset length, in bytes. Maximum 4 bytes.

pub fn op_offset(&self) -> usize

The offset of the first opcode, inside the instruction.

pub fn main_op_offset(&self) -> usize

The offset of the nominal opcode, inside the instruction.

pub fn disp_offset(&self) -> Option<usize>

The offset of the displacement, inside the instruction.

pub fn addr_offset(&self) -> Option<usize>

The offset of the hard-coded address.

pub fn moffset_offset(&self) -> Option<usize>

The offset of the absolute address, inside the instruction.

pub fn imm1_offset(&self) -> Option<usize>

The offset of the immediate, inside the instruction.

pub fn imm2_offset(&self) -> Option<usize>

The offset of the second immediate, if any, inside the instruction.

pub fn rel_offs_offset(&self) -> Option<usize>

The offset of the relative offset used in instruction.

pub fn sse_imm_offset(&self) -> Option<usize>

The offset of the SSE immediate, if any, inside the instruction.

pub fn mod_rm_offset(&self) -> Option<usize>

The offset of the mod rm byte inside the instruction, if any.

pub fn stack_words(&self) -> usize

Number of words accessed on/from the stack.

pub fn rep(&self) -> Option<u8>

The last rep/repz/repnz prefix. if any.

pub fn seg(&self) -> Option<u8>

The last segment override prefix. if none. FS/GS if 64 bit.

pub fn mod_rm(&self) -> Option<u8>

Get the ModRM byte.

pub fn sib(&self) -> Option<u8>

Get the SIB byte.

pub fn vex2(&self) -> Option<(u8, u8)>

Get the 2-bytes VEX prefix.

pub fn vex3(&self) -> Option<(u8, u8, u8)>

Get the 3-bytes VEX prefix.

pub fn xop(&self) -> Option<(u8, u8, u8)>

Get the XOP bytes.

pub fn evex(&self) -> Option<(u8, u8, u8, u8)>

Get the EVEX bytes.

pub fn moffset(&self) -> Option<u64>

Get the absolute offset, if any.

pub fn disp(&self) -> Option<u32>

Get the displacement. Max 4 bytes. Used in ModRM instructions.

pub fn rel_offset(&self) -> Option<u32>

Get the relative offset, used for branches. Max 4 bytes.

pub fn immediate1(&self) -> Option<u64>

Get the first immediate.

pub fn immediate2(&self) -> Option<u8>

Get the second immediate. Used mainly for Mnemonic::ENTER.

pub fn sse_immediate(&self) -> Option<u8>

Get the SSE immediate. It is used to select a register.

pub fn cond(&self) -> Option<u8>

Get the condition byte.

pub fn is_3d_now(&self) -> bool

true if the instruction is 3DNow!.

The opcode is the last byte.

pub fn operands_count(&self) -> usize

Get the number of operands.

pub fn exp_operands_count(&self) -> usize

Number of explicit operands.

Use this if you want to ignore implicit operands such as stack, flags, etc.

pub fn cs_access(&self) -> OpAccess

Get the CS access mode.

pub fn rip_access(&self) -> OpAccess

Get the RIP access mode.

pub fn stack_access(&self) -> OpAccess

Get the stack access mode.

pub fn memory_access(&self) -> OpAccess

Get the memory access mode.

This includes the stack or shadow stack access.

pub fn is_branch(&self) -> bool

true if the instruction is a branch.

pub fn is_conditional_branch(&self) -> bool

true if the instruction is a conditional branch.

pub fn is_indirect_branch(&self) -> bool

true if the instruction is a indirect branch.

pub fn is_far_branch(&self) -> bool

true if the instruction is a far branch.

pub fn flags_access(&self) -> FlagsAccess

Get the rflags access.

pub fn fpu_flags_access(&self) -> FpuFlags

FPU status word C0-C3 bits access.

Panics

This function will panic if the access mode is unrecognized. This can not happen under normal circumstances.

pub fn evex_tuple(&self) -> Option<Tuple>

EVEX tuple type.

Panics

This function will panic if the EVEX tuple type is unrecognized. This can not happen under normal circumstances.

pub fn evex_rounding(&self) -> Option<EvexRounding>

EVEX rounding mode.

Panics

This function will panic if the EVEX rounding mode is unrecognized. This can not happen under normal circumstances.

pub fn category(&self) -> Category

Get the instruction category.

Panics

This function will panic if the cateogory not recognized. This can not happen under normal circumstances.

pub fn isa_set(&self) -> IsaSet

Get the ISA set.

Panics

This function will panic if the ISA set not recognized. This can not happen under normal circumstances.

pub fn valid_cpu_modes(&self) -> CpuModes

Get the CPU modes in which the instruction is valid.

Examples

See cpu_modes for examples.

pub fn valid_prefixes(&self) -> ValidPrefixes

Get the valid prefixes for this instruction.

pub fn valid_decorators(&self) -> ValidDecorators

Get the decorators accepted by the instruction.

pub fn primary_op_code(&self) -> u8

Get the main/nominal opcode.

pub fn has_vector(&self) -> bool

true if the instruction is a SIMD instruction that operates on vector regs.

impl<'a> DecodedInstruction

pub fn bytes(&'a self) -> &'a [u8]

Get the instruction bytes.

pub fn op_code_bytes(&'a self) -> &'a [u8]

Get the opcode bytes (escape codes and main op code).

pub fn operand_lookup(&'a self) -> OperandsLookup<'_>

Get an operand lookup table.

This can be useful when needing to work with a specific operand without needing to iterate over the operands returned by operands(), and without needing to rely on the order of the operands.

Examples

See OperandsLookup for examples.

Panics

This function will panic if the result of the C library is unrecognized. This can not happen under normal circumstances.

Trait Implementations

impl Clone for DecodedInstruction

fn clone(&self) -> DecodedInstruction

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DecodedInstruction

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for DecodedInstruction

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Copy for DecodedInstruction