Configuration

API for opdis configuration. More...

Data Structures
struct	opdis_info_t
	An opdis disassembler. More...
Typedefs
typedef int(*	OPDIS_HANDLER )(const opdis_insn_t i, void arg)
	Callback used to determine if disassembly should continue.
typedef void(*	OPDIS_DISPLAY )(const opdis_insn_t i, void arg)
	Callback used to display or store a disassembled instruction.
typedef int(*	OPDIS_DECODER )(const opdis_insn_buf_t in, opdis_insn_t out, const opdis_byte_t buf, opdis_off_t offset, opdis_vma_t vma, opdis_off_t length, void *arg)
	Callback used to fill an opdis_insn_t from an opdis_insn_buf_t.
typedef opdis_vma_t(*	OPDIS_RESOLVER )(const opdis_insn_t i, void arg)
	Callback used to convert a branch target to a buffer offset.
typedef void(*	OPDIS_ERROR )(enum opdis_error_t error, const char msg, void arg)
	Callback used to handle error messages.
typedef opdis_info_t *	opdis_t
	Disassembler handle (pointer to opdis_info_t).
Enumerations
enum	opdis_x86_syntax_t { opdis_x86_syntax_intel, opdis_x86_syntax_att }
	Syntax options for x86 disassembly. More...
Functions
int	opdis_default_handler (const opdis_insn_t insn, void arg)
	The built-in opdis handler callback. The default handler returns true unless the instruction is invalid or if the address has already been visited.
void	opdis_default_display (const opdis_insn_t i, void arg)
	The built-in opdis display callback This callback writes the instruction ascii field to STDOUT.
int	opdis_default_decoder (const opdis_insn_buf_t in, opdis_insn_t out, const opdis_byte_t buf, opdis_off_t offset, opdis_vma_t vma, opdis_off_t length, void *arg)
	The built-in opdis instruction decoder This callback fills the ascii, offset, vma, bytes, and size fields of the output instruction object. It is recommended that all other decoders invoke this callback directly to fill these fields.
opdis_vma_t	opdis_default_resolver (const opdis_insn_t insn, void arg)
	The built-in opdis resolver callback. This callback returns the immediate value of the taregt operand for the instruction (if set) or OPDIS_INVALID_ADDR.
void	opdis_default_error_reporter (enum opdis_error_t error, const char msg, void arg)
	The built-in error reporter.
void LIBCALL	opdis_set_defaults (opdis_t o)
	Initializes an opdis object to default, sane values.
void LIBCALL	opdis_set_x86_syntax (opdis_t o, enum opdis_x86_syntax_t syntax)
	Configure the disassembler to use Intel or AT&T syntax.
void LIBCALL	opdis_set_arch (opdis_t o, enum bfd_architecture arch, unsigned long mach, disassembler_ftype fn)
	Set the architecture and disassembler routine for libopcodes.
void LIBCALL	opdis_set_disassembler_options (opdis_t o, const char *options)
	Set libopcodes disassembler options.
void LIBCALL	opdis_set_display (opdis_t o, OPDIS_DISPLAY fn, void *arg)
	Set the callback used to display or store disassembled instructions.
void LIBCALL	opdis_set_handler (opdis_t o, OPDIS_HANDLER fn, void *arg)
	Set the callback used to determine whether to continue disassembly.
void LIBCALL	opdis_set_decoder (opdis_t o, OPDIS_DECODER fn, void *arg)
	Set the callback used to build an opdis_insn_t from libopcodes data.
void LIBCALL	opdis_set_resolver (opdis_t o, OPDIS_RESOLVER fn, void *arg)
	Set the callback used to obtain the buffer offset of a branch target.
void LIBCALL	opdis_set_error_reporter (opdis_t o, OPDIS_ERROR fn, void *arg)
	Set the callback used to report errors.

Detailed Description

API for opdis configuration.

The disassembly functions rely on an opdis_t object to store configuration information such as libopcodes options and callbacks for use during disassembly. It is possible to override much of the default behavior of libopdis by configuring the opdis_t appropriately.

There are two types of configuration possible: disassembler configuration, which determines the settings used by libopcodes, and callback configuration, which determines the behavior of libopdis.

Disassembler configuration consists of the following functions:

opdis_set_arch : Set the BFD machine type and print_insn function used by libopcodes.
opdis_set_disassembler_options : Set architecture-specific disassembler options for libopcodes.
opdis_set_x86_syntax : Set the print_insn function to one of the two x86 syntaxes supported by libopcodes. This is provided for convenience.

There are five callbacks used by libopdis :

display : Invoked to display a disassembled instruction. This can be considered the instruction emitter, though the callback is expected to duplicate the instruction if it is stored as the instruction pointer passed will be overwritten when the next instruction is disassembled.
handler : Determine whether disassembly should continue. This is used to halt disassembly if an invalid instruction is encountered or if an instruction has previously been disassembled.
resolver : Find the VMA for the target operand of a branch instruction so that control-flow disassembly can be performed on that target. Immediate operand will have their value returned; register and address expression operands will require a VM to determine their value.
decoder : Generate a libopdis instruction object from a list of strings emitted by libopcodes. This callback is responsible for generating all metadata for instructions.
error reporter : Print an error message generated by libopdis.
Note:
The opdis_t is not threadsafe: it has no mutexes guarding its fields. This is especially a concern with the opdis_insn_buf_t filled by libopcodes as it disassembles an instruction, and is directly the result of the libopcodes architecture (which emits instructions to a stream). To use libopdis across multiple threads, a separate opdis_t must be created for each thread.

Typedef Documentation

int(* OPDIS_DECODER)(const opdis_insn_buf_t, opdis_insn_t *, opdis_byte_t *, opdis_off_t, opdis_vma_t, opdis_off_t)

Callback used to fill an opdis_insn_t from an opdis_insn_buf_t.

Parameters:

	in	The opdis_insn_buf_t containing the libopcodes output.
	out	Pointer to the opdis_insn_t to fill.
	buf	Buffer containing the instruction
	offset	Offset of start of instruction in buf.
	vma	Address (vma) of start of instruction.
	length	Size of instruction in bytes.
	arg	Optional argument to pass to callback

Returns:: 0 on failure, nonzero on success.

This function is invoked after libopcodes has finished disassembling the instruction. The strings emitted from libopcodes are in the opdis_insn_buf_t; the decoder must use these to build a valid opdis_insn_t. The default decoder for unsupported architectures will only fill the ascii field of the opdis_insn_t. More sophisticated decoders, such as the decoder for the x86 platform, will fill the rest of the object.

See also:: Supported Architectures

Note:: The caller will only need to provide a decoder callback if they are disassembling an architecture not supported by Opdis.; The default decoder, opdis_default_decoder, should be used by all decoder callbacks to set the basic instruction info (ascii, offset, vma, bytes, size).

void(* OPDIS_DISPLAY)(const opdis_insn_t *i, void *arg)

Callback used to display or store a disassembled instruction.

Parameters:

	i	The most recently disassembled instruction.
	arg	Argument provided when the callback is set

This function is invoked every time an instruction is disassembled; it emits the instruction to the caller of the disassembler. The default display function writes to STDOUT.

Note:: The caller must copy the instruction if they are going to store it; the contents of i will be overwritten when the next instruction is disassembled.; The default display routine writes instructions to STDOUT without storing or sorting them. This will lead to unexpected behavior (i.e. out-of-order instruction listings) when using opdis_disasm_cflow().

void(* OPDIS_ERROR)(enum opdis_error_t error, const char *msg, void *arg)

Callback used to handle error messages.

Parameters:

	error	Type of error.
	msg	Detailed message describing error.
	arg	Argument provided when the callback is set.

This function is invoked whenever an error is encountered by the disassembler. The default error handler writes to STDERR.

int(* OPDIS_HANDLER)(const opdis_insn_t *i, void *arg)

Callback used to determine if disassembly should continue.

Parameters:

	i	The most recently disassembled instruction.
	arg	Argument provided when the callback is set

Returns:: 0 if disassembly should halt, nonzero (1) otherwise.

This function is invoked after the display callback. The default behavior is to halt disassembly only if an invalid instruction is encountered. The caller can override this function in order to specify more detailed halting conditions, e.g. to halt once a sequence of instructions has been encountered.

opdis_vma_t(* OPDIS_RESOLVER)(const opdis_insn_t *i, void *arg)

Callback used to convert a branch target to a buffer offset.

Parameters:

	i	The instruction to resolve.
	arg	Argument provided when the callback is set.

Returns:: A valid offset in the buffer, or OPDIS_INVALID_ADDR.

This function is invoked when a branch instruction (call or jmp) is encountered; it determines the buffer offset of the branch target. This is used to convert relative addresses, virtual memory addresses, and registers into buffer offsets. If the branch target cannot be converted to a memory address (e.g. register contents are not being tracked, the load address of the buffer is not known, or the address lies outside the buffer) then this function must return OPDIS_INVALID_ADDR. The default resolver only handled relative addresses.

Enumeration Type Documentation

enum opdis_x86_syntax_t

Syntax options for x86 disassembly.

Note:: This wraps the libopcodes syntax options, which only include Intel and AT&T (i.e. no Nasm support).

Enumerator:

opdis_x86_syntax_intel	Intel syntax (dest, src)
opdis_x86_syntax_att	AT&T syntax (src, dest)

Function Documentation

int opdis_default_decoder	(	const opdis_insn_buf_t	in,
		opdis_insn_t *	out,
		const opdis_byte_t *	buf,
		opdis_off_t	offset,
		opdis_vma_t	vma,
		opdis_off_t	length,
		void *	arg
	)

The built-in opdis instruction decoder This callback fills the ascii, offset, vma, bytes, and size fields of the output instruction object. It is recommended that all other decoders invoke this callback directly to fill these fields.

Note:: The default decoder callback takes a NULL arg parameter.

void opdis_default_display	(	const opdis_insn_t *	i,
		void *	arg
	)

The built-in opdis display callback This callback writes the instruction ascii field to STDOUT.

Note:: The default display callback takes a NULL arg parameter.

void opdis_default_error_reporter	(	enum opdis_error_t	error,
		const char *	msg,
		void *	arg
	)

The built-in error reporter.

Note:: The default error reporter takes a NULL arg parameter.

int opdis_default_handler	(	const opdis_insn_t *	insn,
		void *	arg
	)

The built-in opdis handler callback. The default handler returns true unless the instruction is invalid or if the address has already been visited.

Note:: The default handler callback takes an opdis_t as the arg parameter. If this parameter is NULL, or if the visited_addr field of the opdis_t is NULL, the handler will not check check if an address has already been visited.

opdis_vma_t opdis_default_resolver	(	const opdis_insn_t *	insn,
		void *	arg
	)

The built-in opdis resolver callback. This callback returns the immediate value of the taregt operand for the instruction (if set) or OPDIS_INVALID_ADDR.

Note:: The default resolver callback takes a NULL arg parameter.

opdis_set_arch	(	opdis_t	o,
		enum bfd_architecture	arch,
		unsigned long	mach,
		disassembler_ftype	fn
	)

Set the architecture and disassembler routine for libopcodes.

This will set architecture of the libopcodes target to a BFD architecture, and specify the libopcodes print_insn routine that will be used for disassembly.

Parameters:

	o	opdis disassembler to configure.
	arch	A valid BFD architecture from /usr/include/bfd.h.
	mach	A valid bfd_mach definition from /usr/include/bfd.h.
	fn	A valid libopcodes print_insn routine from /usr/include/dis-asm.h .

Note:

If the disassembler_ftype parameter is NULL, the default disassembler for the architecture will be selected. On x86 targets, this is print_insn_i386_att.

This sets the decoder to the appropriate built-in decoder for the architecture. To override the decoder, call opdis_set_decoder after calling this routine.

The arch parameter is only used when calling disassemble_init_for_target to initialize the libopcodes disassemble_info structure. The mach parameter is used by the disassembler to determine how to decode the instructions. For x86 and x86-64 platforms, arch is always bfd_arch_i386, and mach is one of the following:

bfd_mach_i386_i386
bfd_mach_i386_i8086
bfd_mach_i386_i386_intel_syntax
bfd_mach_x86_64
bfd_mach_x86_64_intel_syntax It is not necessary to specify the Intel syntax in mach; this can be done with opdis_set_x86_syntax.

opdis_set_decoder	(	opdis_t	o,
		OPDIS_DECODER	fn,
		void *	arg
	)

Set the callback used to build an opdis_insn_t from libopcodes data.

This sets the function used to fill an opdis_insn_t based on the array of strings (stored in an opdis_insn_buf_t) emitted by libopcodes. If the default handler does not support the ISA being disassembled (i.e. an architecture other than x86 is being used), then this must be overridden in order to get more than the ASCII version of the instruction in the opdis_insn_t.

Parameters:

	o	opdis disassembler to configure.
	fn	The callback function.
	arg	An optional argument to pass to the callback function.

opdis_set_defaults ( opdis_t o )

Initializes an opdis object to default, sane values.

Parameters:

o

opdis disassembler to configure.

See also:: opdis_init opdis_set_arch opdis_set_x86_syntax opdis_set_error; opdis_set_display opdis_set_handler opdis_set_resolver opdis_set_decoder; opdis_set_disassembler_options

Note:: The default architecture is i386, and the default syntax is Intel. All callbacks will be set to the default internal routines.

opdis_set_disassembler_options	(	opdis_t	o,
		const char *	options
	)

Set libopcodes disassembler options.

Sets the libopcodes disassembler_options config field. Opdis passes this string blindly to libopcodes. To view the valid options for a disassembler, invoke the appropriate print_*_disassembler_options routine listed in /usr/include/dis-asm.h .

Parameters:

	o	opdis disassembler to configure.
	options	The options string for the disassembler.

Note:: The libopcodes disassembler options override the settings applied by opdis_set_syntax.

opdis_set_display	(	opdis_t	o,
		OPDIS_DISPLAY	fn,
		void *	arg
	)

Set the callback used to display or store disassembled instructions.

This sets the function invoked to manage disassembled instructions. The callback is invoked every time an instruction is disassembled. It is expected to display or store the instruction, which will be discarded when the next address is disassembled. The default handler writes to STDOUT.

Parameters:

	o	opdis disassembler to configure.
	fn	The callback function.
	arg	An optional argument to pass to the callback function.

Note:: If the callback stores the instruction, it must make a copy using opdis_insn_dupe().

opdis_set_error_reporter	(	opdis_t	o,
		OPDIS_ERROR	fn,
		void *	arg
	)

Set the callback used to report errors.

This sets the function used to report errors encountered during disassembly. The default error reporter simply writes to STDERR.

Parameters:

	o	opdis disassembler to configure.
	fn	The callback function.
	arg	An optional argument to pass to the callback function.

opdis_set_handler	(	opdis_t	o,
		OPDIS_HANDLER	fn,
		void *	arg
	)

Set the callback used to determine whether to continue disassembly.

This sets the function invoked to determine whether to continue linear or control-flow disassembly after each instruction has been disassembled and displayed. The default handler will halt disassembly if an invalid instruction has been encountered, or (for control-flow) if the end of a control-flow branch (i.e. a return statement) has been reached.

Parameters:

	o	opdis disassembler to configure.
	fn	The callback function.
	arg	An optional argument to pass to the callback function.

opdis_set_resolver	(	opdis_t	o,
		OPDIS_RESOLVER	fn,
		void *	arg
	)

Set the callback used to obtain the buffer offset of a branch target.

This sets the function used to convert the target of a branch to an offset into the buffer. The control flow disassembler will require a resolver in order to disassemble all non-relative branch targets.

Parameters:

	o	opdis disassembler to configure.
	fn	The callback function.
	arg	An optional argument to pass to the callback function.

Note:: The resolver receives an instruction and is expected to return a valid offset or -1 if no address can be determined. The resolver can be a subsystem that manages the stack and registers in order to provide more complete branch resolution.

opdis_set_x86_syntax	(	opdis_t	o,
		enum opdis_x86_syntax_t	syntax
	)

Configure the disassembler to use Intel or AT&T syntax.

Sets the libopcodes print instruction to either print_insn_i386_intel or print_insn_i386_att.

Parameters:

	o	opdis disassembler to configure.
	syntax	The syntax option to use.

Note:: This only applies to x86 disassemblers.

Configuration

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation