Instruction¶

class iced_x86.Instruction¶

A 16/32/64-bit x86 instruction. Created by Decoder or by Instruction.create*() methods.

Examples:

A decoder is usually used to create instructions:

from iced_x86 import *

# xchg ah,[rdx+rsi+16h]
data = b"\x86\x64\x32\x16"
decoder = Decoder(64, data, ip=0x1234_5678)

instr = decoder.decode()

# Instruction supports __bool__() and returns True if it's
# a valid instruction:
if not instr:
    print("Invalid instruction (garbage, data, etc)")
# The above code is the same as:
if instr.code == Code.INVALID:
    print("Not an instruction")

But there are also static Instruction.create*() methods that can be used to create instructions:

nop = Instruction.create(Code.NOPD)
xor = Instruction.create_reg_i32(Code.XOR_RM64_IMM8, Register.R14, -1)
rep_stosd = Instruction.create_rep_stosd(64)
add = Instruction.create_mem_i32(Code.ADD_RM64_IMM8, MemoryOperand(Register.RCX, Register.RDX, 8, 0x1234_5678), 2)
print(f"{nop}")
print(f"{xor}")
print(f"{rep_stosd}")
print(f"{add}")

Output:

nop
xor r14,0FFFFFFFFFFFFFFFFh
rep stosd
add qword ptr [rcx+rdx*8+12345678h],2

Once you have an instruction you can format it either by using a Formatter or by calling the instruction’s __repr__(), __str__() or __format__() methods.

# Continued from the above example

formatter = Formatter(FormatterSyntax.INTEL)

# Change some options
formatter.uppercase_mnemonics = True
formatter.space_after_operand_separator = True
formatter.first_operand_char_index = 8

print(f"disasm  : {formatter.format(instr)}")
# `instr.mnemonic` also returns a `Mnemonic` enum
print(f"mnemonic: {formatter.format_mnemonic(instr, FormatMnemonicOptions.NO_PREFIXES)}")
print(f"operands: {formatter.format_all_operands(instr)}")
# `instr.op0_kind`/etc return operand kind, see also `instr.op0_register`, etc to get reg/mem info
print(f"op #0   : {formatter.format_operand(instr, 0)}")
print(f"op #1   : {formatter.format_operand(instr, 1)}")
print(f"reg RCX : {formatter.format_register(Register.RCX)}")

Output:

disasm  : XCHG    [rdx+rsi+16h], ah
mnemonic: XCHG
operands: [rdx+rsi+16h], ah
op #0   : [rdx+rsi+16h]
op #1   : ah
reg RCX : rcx

# A formatter isn't needed if you like most of the default options.
# repr() == str() == format() all return the same thing.
print(f"disasm  : {repr(instr)}")
print(f"disasm  : {str(instr)}")
print(f"disasm  : {instr}")

Output:

disasm  : xchg ah,[rdx+rsi+16h]
disasm  : xchg ah,[rdx+rsi+16h]
disasm  : xchg ah,[rdx+rsi+16h]

# __format__() supports a format spec argument, see the table below
print(f"disasm  : {instr:f}")
print(f"disasm  : {instr:g}")
print(f"disasm  : {instr:i}")
print(f"disasm  : {instr:m}")
print(f"disasm  : {instr:n}")
print(f"disasm  : {instr:gxsSG}")

Output:

disasm  : xchg [rdx+rsi+16h],ah
disasm  : xchg %ah,0x16(%rdx,%rsi)
disasm  : xchg [rdx+rsi+16h],ah
disasm  : xchg ah,[rdx+rsi+16h]
disasm  : xchg ah,[rdx+rsi+16h]
disasm  : xchgb %ah, %ds:0x16(%rdx,%rsi)

The following format specifiers are supported in any order. If you omit the formatter kind, the default formatter is used (eg. masm):

F-Spec	Description
f	Fast formatter (masm-like syntax)
g	GNU Assembler formatter
i	Intel (XED) formatter
m	masm formatter
n	nasm formatter
X	Uppercase hex numbers with `0x` prefix
x	Lowercase hex numbers with `0x` prefix
H	Uppercase hex numbers with `h` suffix
h	Lowercase hex numbers with `h` suffix
r	RIP-relative memory operands use RIP register instead of abs addr (`[rip+123h]` vs `[123456789ABCDEF0h]`)
U	Uppercase everything except numbers and hex prefixes/suffixes (ignored by fast fmt)
s	Add a space after the operand separator
S	Always show the segment register (memory operands)
B	Don’t show the branch size (`SHORT` or `NEAR PTR`) (ignored by fast fmt)
G	(GNU Assembler): Add mnemonic size suffix (eg. `movl` vs `mov`)
M	Always show the memory size (eg. `BYTE PTR`) even when not needed
_	Use digit separators (eg. `0x12345678` vs `0x1234_5678`) (ignored by fast fmt)

as_near_branch()¶

Converts Jcc/JMP SHORT to Jcc/JMP NEAR and does nothing if it’s not a Jcc/JMP SHORT instruction

Examples:

from iced_x86 import *

# jbe short label
data = b"\x76\x5A"
decoder = Decoder(64, data)

instr = decoder.decode()
assert instr.code == Code.JBE_REL8_64
instr.as_near_branch()
assert instr.code == Code.JBE_REL32_64
instr.as_near_branch()
assert instr.code == Code.JBE_REL32_64

as_short_branch()¶

Converts Jcc/JMP NEAR to Jcc/JMP SHORT and does nothing if it’s not a Jcc/JMP NEAR instruction

Examples:

from iced_x86 import *

# jbe near ptr label
data = b"\x0F\x86\x5A\xA5\x12\x34"
decoder = Decoder(64, data)

instr = decoder.decode()
assert instr.code == Code.JBE_REL32_64
instr.as_short_branch()
assert instr.code == Code.JBE_REL8_64
instr.as_short_branch()
assert instr.code == Code.JBE_REL8_64

code¶

Gets the instruction code (a Code enum value), see also Instruction.mnemonic

Type:: Code

code_size¶

Gets the code size (a CodeSize enum value) when the instruction was decoded.

Note

This value is informational and can be used by a formatter.

Type:: CodeSize

condition_code¶

Gets the condition code (a ConditionCode enum value) if it’s Jcc, SETcc, CMOVcc, CMPccXADD, LOOPcc else ConditionCode.NONE is returned

Examples:

from iced_x86 import *

# setbe al
# jl short label
# cmovne ecx,esi
# nop
data = b"\x0F\x96\xC0\x7C\x5A\x0F\x45\xCE\x90"
decoder = Decoder(64, data)

# setbe al
instr = decoder.decode()
assert instr.condition_code == ConditionCode.BE

# jl short label
instr = decoder.decode()
assert instr.condition_code == ConditionCode.L

# cmovne ecx,esi
instr = decoder.decode()
assert instr.condition_code == ConditionCode.NE

# nop
instr = decoder.decode()
assert instr.condition_code == ConditionCode.NONE

Type:: ConditionCode

copy()¶

Returns a copy of this instance.

Returns:: A copy of this instance
Return type:: Instruction

cpuid_features()¶

Gets the CPU or CPUID feature flags (a list of CpuidFeature enum values)

Returns:: CPU or CPUID feature flags
Return type:: List[CpuidFeature]

Examples:

from iced_x86 import *

# vmovaps xmm1,xmm5
# vmovaps xmm10{k3}{z},xmm19
data = b"\xC5\xF8\x28\xCD\x62\x31\x7C\x8B\x28\xD3"
decoder = Decoder(64, data)

# vmovaps xmm1,xmm5
instr = decoder.decode()
cpuid = instr.cpuid_features()
assert len(cpuid) == 1
assert cpuid[0] == CpuidFeature.AVX

# vmovaps xmm10{k3}{z},xmm19
instr = decoder.decode()
cpuid = instr.cpuid_features()
assert len(cpuid) == 2
assert cpuid[0] == CpuidFeature.AVX512VL
assert cpuid[1] == CpuidFeature.AVX512F

static create(code)¶

Creates an instruction with no operands

Parameters:: code (Code) – Code value
Returns:: Created instruction
Return type:: Instruction

static create_branch(code, target)¶

Creates a new near/short branch instruction

Parameters:

code (Code) – Code value
target (int) – (u64) Target address

Returns:

Created instruction

Return type: