Trait iced_x86::SpecializedFormatterTraitOptions

source ·

pub trait SpecializedFormatterTraitOptions {
    const ENABLE_SYMBOL_RESOLVER: bool = false;
    const ENABLE_DB_DW_DD_DQ: bool = false;

    // Provided methods
    unsafe fn verify_output_has_enough_bytes_left() -> bool { ... }
    fn space_after_operand_separator(_options: &FastFormatterOptions) -> bool { ... }
    fn rip_relative_addresses(_options: &FastFormatterOptions) -> bool { ... }
    fn use_pseudo_ops(_options: &FastFormatterOptions) -> bool { ... }
    fn show_symbol_address(_options: &FastFormatterOptions) -> bool { ... }
    fn always_show_segment_register(_options: &FastFormatterOptions) -> bool { ... }
    fn always_show_memory_size(_options: &FastFormatterOptions) -> bool { ... }
    fn uppercase_hex(_options: &FastFormatterOptions) -> bool { ... }
    fn use_hex_prefix(_options: &FastFormatterOptions) -> bool { ... }
}

Expand description

A trait that allows you to hard code some formatter options which can make the formatter faster and use less code.

The implementing struct can return hard coded values and/or return a value from the passed in options. If it returns the value from the passed in options, that option can be modified at runtime by calling formatter.options_mut().set_<option>(new_value), else it’s ignored and calling that method has no effect (except wasting CPU cycles).

Every fn must be a pure function and must return a value from the options input or a literal (true or false). Returning a literal is recommended since the compiler can remove unused formatter code.

Fastest possible disassembly

For fastest possible disassembly, you should not enable the db feature (or you should set ENABLE_DB_DW_DD_DQ to false) and you should also override the unsafe verify_output_has_enough_bytes_left() and return false.

use iced_x86::*;

struct MyTraitOptions;
impl SpecializedFormatterTraitOptions for MyTraitOptions {
    // If you never create a db/dw/dd/dq 'instruction', we don't need this feature.
    const ENABLE_DB_DW_DD_DQ: bool = false;
    // For a few percent faster code, you can also override `verify_output_has_enough_bytes_left()` and return `false`
    // unsafe fn verify_output_has_enough_bytes_left() -> bool {
    //     false
    // }
}
type MyFormatter = SpecializedFormatter<MyTraitOptions>;

// Assume this is a big slice and not just one instruction
let bytes = b"\x62\xF2\x4F\xDD\x72\x50\x01";
let mut decoder = Decoder::new(64, bytes, DecoderOptions::NONE);

let mut output = String::new();
let mut instruction = Instruction::default();
let mut formatter = MyFormatter::new();
while decoder.can_decode() {
    decoder.decode_out(&mut instruction);
    output.clear();
    formatter.format(&instruction, &mut output);
    // do something with 'output' here, eg.:
    //     println!("{}", output);
}

Also add this to your Cargo.toml file:

[profile.release]
codegen-units = 1
lto = true
opt-level = 3

See SpecializedFormatter<TraitOptions> for more examples

Provided Associated Constants§

source

const ENABLE_SYMBOL_RESOLVER: bool = false

Enables support for a symbol resolver. This is disabled by default. If this is disabled, you must not pass in a symbol resolver to the constructor.

For fastest code, this should be disabled, not enabled.

source

const ENABLE_DB_DW_DD_DQ: bool = false

Enables support for formatting db, dw, dd, dq.

For fastest code, this should be disabled, not enabled.

Provided Methods§

source

unsafe fn verify_output_has_enough_bytes_left() -> bool

The formatter makes sure that the output string has at least 300 bytes left at the start of format() and also after appending symbols to output. This is enough space for all formatted instructions.

No formatted instruction will ever get close to being 300 bytes long!

If this function returns false, the formatter won’t verify that it has enough bytes left when writing to the output string. Note that it will always reserve at least 300 bytes at the start of format() and after appending symbols.

For fastest code, this method should return false. Default is true.