Formatter¶

class iced_x86.Formatter(syntax)¶

x86 formatter that supports GNU Assembler, Intel XED, masm and nasm syntax

Parameters:: syntax (FormatterSyntax) – Formatter syntax

Examples:

from iced_x86 import *

data = b"\x62\xF2\x4F\xDD\x72\x50\x01"
decoder = Decoder(64, data)
instr = decoder.decode()

formatter = Formatter(FormatterSyntax.MASM)
formatter.uppercase_mnemonics = True
disasm = formatter.format(instr)
assert disasm == "VCVTNE2PS2BF16 zmm2{k5}{z},zmm6,dword bcst [rax+4]"

add_leading_zero_to_hex_numbers¶

Add a leading zero to hex numbers if there’s no prefix and the number starts with hex digits A-F

Default	Value	Example
👍	`True`	`0FFh`
	`False`	`FFh`

Type:: bool

always_show_scale¶

Always show the scale value even if it’s *1

Default	Value	Example
	`True`	`mov eax,[rbx+rcx*1]`
👍	`False`	`mov eax,[rbx+rcx]`

Type:: bool

always_show_segment_register¶

Always show the effective segment register.

If the option is False, only show the segment register if there’s a segment override prefix.

Default	Value	Example
	`True`	`mov eax,ds:[ecx]`
👍	`False`	`mov eax,[ecx]`

Type:: bool

binary_digit_group_size¶

(u8) Size of a digit group, see also Formatter.digit_separator

Default	Value	Example
	`0`	`11010111`
👍	`4`	`1101_0111`

Type:: int

binary_prefix¶

Binary number prefix or an empty string

Default: "" (masm/nasm/intel), "0b" (gas)

Type:: str

binary_suffix¶

Binary number suffix or an empty string

Default: "b" (masm/nasm/intel), "" (gas)

Type:: str

branch_leading_zeros¶

Add leading zeros to branch offsets. Used by CALL NEAR, CALL FAR, JMP NEAR, JMP FAR, Jcc, LOOP, LOOPcc, XBEGIN

Default	Value	Example
👍	`True`	`je 00000123h`
	`False`	`je 123h`

Type:: bool

cc_a¶

Mnemonic condition code selector (eg. JA / JNBE)

Default: JA, CMOVA, SETA

Type:: CC_a

cc_ae¶

Mnemonic condition code selector (eg. JAE / JNB / JNC)

Default: JAE, CMOVAE, SETAE

Type:: CC_ae

cc_b¶

Mnemonic condition code selector (eg. JB / JC / JNAE)

Default: JB, CMOVB, SETB

Type:: CC_b

cc_be¶

Mnemonic condition code selector (eg. JBE / JNA)

Default: JBE, CMOVBE, SETBE

Type:: CC_be

cc_e¶

Mnemonic condition code selector (eg. JE / JZ)

Default: JE, CMOVE, SETE, LOOPE, REPE

Type:: CC_e

cc_g¶

Mnemonic condition code selector (eg. JG / JNLE)

Default: JG, CMOVG, SETG

Type:: CC_g

cc_ge¶

Mnemonic condition code selector (eg. JGE / JNL)

Default: JGE, CMOVGE, SETGE

Type:: CC_ge

cc_l¶

Mnemonic condition code selector (eg. JL / JNGE)

Default: JL, CMOVL, SETL

Type:: CC_l

cc_le¶

Mnemonic condition code selector (eg. JLE / JNG)

Default: JLE, CMOVLE, SETLE

Type:: CC_le

cc_ne¶

Mnemonic condition code selector (eg. JNE / JNZ)

Default: JNE, CMOVNE, SETNE, LOOPNE, REPNE

Type:: CC_ne

cc_np¶

Mnemonic condition code selector (eg. JNP / JPO)

Default: JNP, CMOVNP, SETNP

Type:: CC_np

cc_p¶

Mnemonic condition code selector (eg. JP / JPE)

Default: JP, CMOVP, SETP

Type:: CC_p

decimal_digit_group_size¶

(u8) Size of a digit group, see also Formatter.digit_separator

Default	Value	Example
	`0`	`12345678`
👍	`3`	`12_345_678`

Type:: int

decimal_prefix¶

Decimal number prefix or an empty string

Default: ""

Type:: str

decimal_suffix¶

Decimal number suffix or an empty string

Default: ""

Type:: str

digit_separator¶

Digit separator or an empty string. See also eg. Formatter.hex_digit_group_size

Default	Value	Example
👍	`""`	`0x12345678`
	`"_"`	`0x1234_5678`

Type:: str

displacement_leading_zeros¶

Add leading zeros to displacements

Default	Value	Example
	`True`	`mov al,[eax+00000012h]`
👍	`False`	`mov al,[eax+12h]`

Type:: bool

first_operand_char_index¶

(u32) Character index (0-based) where the first operand is formatted. Can be set to 0 to format it immediately after the mnemonic. At least one space or tab is always added between the mnemonic and the first operand.

Default	Value	Example
👍	`0`	`mov•rcx,rbp`
	`8`	`mov•••••rcx,rbp`

Type:: int

format(instruction)¶

Formats the whole instruction: prefixes, mnemonic, operands

Parameters:: instruction (Instruction) – Instruction to format
Returns:: The formatted string
Return type:: str

format_all_operands(instruction)¶

Formats all operands

Parameters:: instruction (Instruction) – Instruction to format
Returns:: The formatted string
Return type:: str

format_i16(value)¶

Formats a i16

Parameters:: value (int) – (i16) Value
Returns:: The formatted string
Return type:: str

format_i32(value)¶

Formats a i32

Parameters:: value (int) – (i32) Value
Returns:: The formatted string
Return type:: str

format_i64(value)¶

Formats a i64

Parameters:: value (int) – (i64) Value
Returns:: The formatted string
Return type:: str

format_i8(value)¶

Formats a i8

Parameters:: value (int) – (i8) Value
Returns:: The formatted string
Return type:: str

format_mnemonic(instruction, options=0)¶

Formats the mnemonic and any prefixes

Parameters:

instruction (Instruction) – Instruction to format
options (FormatMnemonicOptions) – (default = FormatMnemonicOptions.NONE) Options

Returns:

The formatted string

Return type:

str

format_operand(instruction, operand)¶

Formats an operand.

Parameters:

instruction (Instruction) – Instruction
operand (int) – Operand number, 0-based. This is a formatter operand and isn’t necessarily the same as an instruction operand. See Formatter.operand_count

Returns:

The formatted string

Return type:

str

Raises:

ValueError – If operand is invalid

format_operand_separator(instruction)¶

Formats an operand separator

Parameters:: instruction (Instruction) – Instruction
Returns:: The formatted string
Return type:: str

format_register(register)¶

Formats a register

Parameters:: register (Register) – Register
Returns:: The formatted string
Return type:: str

format_u16(value)¶

Formats a u16

Parameters:: value (int) – (u16) Value
Returns:: The formatted string
Return type:: str

format_u32(value)¶

Formats a u32

Parameters:: value (int) – (u32) Value
Returns:: The formatted string
Return type:: str

format_u64(value)¶

Formats a u64

Parameters:: value (int) – (u64) Value
Returns:: The formatted string
Return type:: str

format_u8(value)¶

Formats a u8

Parameters:: value (int) – (u8) Value
Returns:: The formatted string
Return type:: str

gas_naked_registers¶

(gas only): If True, the formatter doesn’t add % to registers

Default	Value	Example
	`True`	`mov eax,ecx`
👍	`False`	`mov %eax,%ecx`

Type:: bool

gas_show_mnemonic_size_suffix¶

(gas only): Shows the mnemonic size suffix even when not needed

Default	Value	Example
	`True`	`movl %eax,%ecx`
👍	`False`	`mov %eax,%ecx`

Type:: bool

gas_space_after_memory_operand_comma¶

(gas only): Add a space after the comma if it’s a memory operand

Default	Value	Example
	`True`	`(%eax, %ecx, 2)`
👍	`False`	`(%eax,%ecx,2)`

Type:: bool

get_formatter_operand(instruction, instruction_operand)¶

Converts an instruction operand index to a formatter operand index.

Returns None if the instruction operand isn’t used by the formatter

Parameters:

instruction (Instruction) – Instruction
instruction_operand (int) – Instruction operand

Returns:

Instruction operand or None if the instruction operand isn’t used by the formatter

Return type:

int, None

Raises:

ValueError – If instruction_operand is invalid

get_instruction_operand(instruction, operand)¶

Converts a formatter operand index to an instruction operand index.

Returns None if it’s an operand added by the formatter

Parameters:

instruction (Instruction) – Instruction
operand (int) – Operand number, 0-based. This is a formatter operand and isn’t necessarily the same as an instruction operand. See Formatter.operand_count

Returns:

Instruction operand or None if it’s an operand added by the formatter

Return type:

int, None

Raises:

ValueError – If operand is invalid

hex_digit_group_size¶

(u8) Size of a digit group, see also Formatter.digit_separator

Default	Value	Example
	`0`	`0x12345678`
👍	`4`	`0x1234_5678`

Type:: int

hex_prefix¶

Hex number prefix or an empty string, eg. "0x"

Default: "" (masm/nasm/intel), "0x" (gas)

Type:: str

hex_suffix¶

Hex number suffix or an empty string, eg. "h"

Default: "h" (masm/nasm/intel), "" (gas)

Type:: str

leading_zeros¶

Add leading zeros to hexadecimal/octal/binary numbers.

This option has no effect on branch targets and displacements, use Formatter.branch_leading_zeros and Formatter.displacement_leading_zeros.

Default	Value	Example
	`True`	`0x0000000A`/`0000000Ah`
👍	`False`	`0xA`/`0Ah`

Type:: bool

masm_add_ds_prefix32¶

(masm only): Add a DS segment override even if it’s not present. Used if it’s 16/32-bit code and mem op is a displ

Default	Value	Example
👍	`True`	`mov eax,ds:[12345678]`
	`False`	`mov eax,[12345678]`

Type:: bool

masm_displ_in_brackets¶

(masm only): Show displacements in brackets

Default	Value	Example
👍	`True`	`[ecx+1234h]`
	`False`	`1234h[ecx]`

Type:: bool

masm_symbol_displ_in_brackets¶

(masm only): Show symbols in brackets

Default	Value	Example
👍	`True`	`[ecx+symbol]` / `[symbol]`
	`False`	`symbol[ecx]` / `symbol`

Type:: bool

memory_size_options¶

Options that control if the memory size (eg. DWORD PTR) is shown or not.

This is ignored by the gas (AT&T) formatter.

Default: MemorySizeOptions.DEFAULT

Type:: MemorySizeOptions

nasm_show_sign_extended_immediate_size¶

(nasm only): Shows BYTE, WORD, DWORD or QWORD if it’s a sign extended immediate operand value

Default	Value	Example
	`True`	`or rcx,byte -1`
👍	`False`	`or rcx,-1`

Type:: bool

number_base¶

Number base (2, 8, 10, 16)

Raises:: ValueError – If it’s an invalid number base

Default: 16

Type:: int

octal_digit_group_size¶

(u8) Size of a digit group, see also Formatter.digit_separator

Default	Value	Example
	`0`	`12345670`
👍	`4`	`1234_5670`

Type:: int

octal_prefix¶

Octal number prefix or an empty string

Default: "" (masm/nasm/intel), "0" (gas)

Type:: str

octal_suffix¶

Octal number suffix or an empty string

Default: "o" (masm/nasm/intel), "" (gas)

Type:: str

op_access(instruction, operand)¶

Returns the operand access but only if it’s an operand added by the formatter.

If it’s an operand that is part of Instruction, you should call eg. InstructionInfoFactory.info.

Parameters:

instruction (Instruction) – Instruction
operand (int) – Operand number, 0-based. This is a formatter operand and isn’t necessarily the same as an instruction operand. See Formatter.operand_count

Returns:

Operand access or None

Return type:

OpAccess, None

Raises:

ValueError – If operand is invalid

operand_count(instruction)¶

Gets the number of operands that will be formatted. A formatter can add and remove operands

Parameters:: instruction (Instruction) – Instruction
Returns:: Operand count
Return type:: int

prefer_st0¶

Use st(0) instead of st if st can be used. Ignored by the nasm formatter.

Default	Value	Example
	`True`	`fadd st(0),st(3)`
👍	`False`	`fadd st,st(3)`

Type:: bool

rip_relative_addresses¶

Show RIP+displ or the virtual address

Default	Value	Example
	`True`	`mov eax,[rip+12345678h]`
👍	`False`	`mov eax,[1029384756AFBECDh]`

Type:: bool

scale_before_index¶

Show memory operand scale value before the index register

Default	Value	Example
	`True`	`mov eax,[8*rdx]`
👍	`False`	`mov eax,[rdx*8]`

Type:: bool

show_branch_size¶

Show NEAR, SHORT, etc if it’s a branch instruction

Default	Value	Example
👍	`True`	`je short 1234h`
	`False`	`je 1234h`

Type:: bool

show_symbol_address¶

Show the original value after the symbol name

Default	Value	Example
	`True`	`mov eax,[myfield (12345678)]`
👍	`False`	`mov eax,[myfield]`

Type:: bool

show_useless_prefixes¶

Show useless prefixes. If it has useless prefixes, it could be data and not code.

Default	Value	Example
	`True`	`es rep add eax,ecx`
👍	`False`	`add eax,ecx`

Type:: bool

show_zero_displacements¶

Show zero displacements

Default	Value	Example
	`True`	`mov eax,[rcx*2+0]`
👍	`False`	`mov eax,[rcx*2]`

Type:: bool

signed_immediate_operands¶

Show immediate operands as signed numbers

Default	Value	Example
	`True`	`mov eax,-1`
👍	`False`	`mov eax,FFFFFFFF`

Type:: bool

signed_memory_displacements¶

Displacements are signed numbers

Default	Value	Example
👍	`True`	`mov al,[eax-2000h]`
	`False`	`mov al,[eax+0FFFFE000h]`

Type:: bool

small_hex_numbers_in_decimal¶

Small hex numbers (-9 .. 9) are shown in decimal

Default	Value	Example
👍	`True`	`9`
	`False`	`0x9`

Type:: bool

space_after_memory_bracket¶

Add a space between the memory expression and the brackets

Default	Value	Example
	`True`	`mov eax,[ rcx+rdx ]`
👍	`False`	`mov eax,[rcx+rdx]`

Type:: bool

space_after_operand_separator¶

Add a space after the operand separator

Default	Value	Example
	`True`	`mov rax, rcx`
👍	`False`	`mov rax,rcx`

Type:: bool

space_between_memory_add_operators¶

Add spaces between memory operand + and - operators

Default	Value	Example
	`True`	`mov eax,[rcx + rdx*8 - 80h]`
👍	`False`	`mov eax,[rcx+rdx*8-80h]`

Type:: bool

space_between_memory_mul_operators¶

Add spaces between memory operand * operator

Default	Value	Example
	`True`	`mov eax,[rcx+rdx * 8-80h]`
👍	`False`	`mov eax,[rcx+rdx*8-80h]`

Type:: bool

tab_size¶

(u32) Size of a tab character or 0 to use spaces

Default: 0

Type:: int

uppercase_all¶

Everything is uppercased, except numbers and their prefixes/suffixes

Default	Value	Example
	`True`	`MOV EAX,GS:[RCX*4+0ffh]`
👍	`False`	`mov eax,gs:[rcx*4+0ffh]`

Type:: bool

uppercase_decorators¶

Uppercase decorators, eg. {z}, {sae}, {rd-sae} (but not opmask registers: {k1})

Default	Value	Example
	`True`	`vunpcklps xmm2{k5}{Z},xmm6,dword bcst [rax+4]`
👍	`False`	`vunpcklps xmm2{k5}{z},xmm6,dword bcst [rax+4]`

Type:: bool

uppercase_hex¶

Use uppercase hex digits

Default	Value	Example
👍	`True`	`0xFF`
	`False`	`0xff`

Type:: bool

uppercase_keywords¶

Keywords are uppercased (eg. BYTE PTR, SHORT)

Default	Value	Example
	`True`	`mov BYTE PTR [rcx],12h`
👍	`False`	`mov byte ptr [rcx],12h`

Type:: bool

uppercase_mnemonics¶

Mnemonics are uppercased

Default	Value	Example
	`True`	`MOV rcx,rax`
👍	`False`	`mov rcx,rax`

Type:: bool

uppercase_prefixes¶

Prefixes are uppercased

Default	Value	Example
	`True`	`REP stosd`
👍	`False`	`rep stosd`

Type:: bool

uppercase_registers¶

Registers are uppercased

Default	Value	Example
	`True`	`mov RCX,[RAX+RDX*8]`
👍	`False`	`mov rcx,[rax+rdx*8]`

Type:: bool

use_pseudo_ops¶

Use pseudo instructions

Default	Value	Example
👍	`True`	`vcmpnltsd xmm2,xmm6,xmm3`
	`False`	`vcmpsd xmm2,xmm6,xmm3,5`

Type:: bool

Formatter¶

iced-x86

Navigation

Related Topics