Data Model

Data Model for disassembled objects. More...

Data Structures
struct	opdis_reg_t
	CPU Register operand. More...
struct	opdis_abs_addr_t
	An absolute address operand. More...
struct	opdis_addr_expr_t
	An address expression operand. More...
struct	opdis_op_t
	Operand object. More...
struct	opdis_insn_t
	Instruction object. More...
Enumerations
enum	opdis_op_cat_t {   opdis_op_cat_unknown, opdis_op_cat_register, opdis_op_cat_immediate, opdis_op_cat_absolute,   opdis_op_cat_expr }
	The category of an operand. More...
enum	opdis_op_flag_t {   opdis_op_flag_none = 0, opdis_op_flag_r = 1, opdis_op_flag_w = 2, opdis_op_flag_x = 4,   opdis_op_flag_signed = 8, opdis_op_flag_address = 16, opdis_op_flag_indirect = 32 }
	Flags applied to an operand. More...
enum	opdis_insn_subset_t {   opdis_insn_subset_gen, opdis_insn_subset_fpu, opdis_insn_subset_gpu, opdis_insn_subset_simd,   opdis_insn_subset_vm }
	The subset of an ISA that the instruction belongs to. More...
enum	opdis_insn_cat_t {   opdis_insn_cat_unknown, opdis_insn_cat_cflow, opdis_insn_cat_stack, opdis_insn_cat_lost,   opdis_insn_cat_test, opdis_insn_cat_math, opdis_insn_cat_bit, opdis_insn_cat_io,   opdis_insn_cat_trap, opdis_insn_cat_priv, opdis_insn_cat_nop }
	The category of an instruction. More...
enum	opdis_cflow_flag_t {   opdis_cflow_flag_none = 0, opdis_cflow_flag_call = 1, opdis_cflow_flag_callcc = 2, opdis_cflow_flag_jmp = 4,   opdis_cflow_flag_jmpcc = 8, opdis_cflow_flag_ret = 16 }
	Details of the control flow instruction. More...
enum	opdis_stack_flag_t {   opdis_stack_flag_none = 0, opdis_stack_flag_push = 1, opdis_stack_flag_pop = 2, opdis_stack_flag_frame = 4,   opdis_stack_flag_unframe = 8 }
	Details of the instruction. More...
enum	opdis_bit_flag_t {   opdis_bit_flag_none = 0, opdis_bit_flag_and = 1, opdis_bit_flag_or = 2, opdis_bit_flag_xor = 4,   opdis_bit_flag_not = 8, opdis_bit_flag_lsl = 16, opdis_bit_flag_lsr = 32, opdis_bit_flag_asl = 64,   opdis_bit_flag_asr = 128, opdis_bit_flag_rol = 256, opdis_bit_flag_ror = 512, opdis_bit_flag_rcl = 1024,   opdis_bit_flag_rcr = 2048 }
	Details of the instruction. More...
enum	opdis_io_flag_t { opdis_io_flag_none = 0, opdis_io_flag_in = 1, opdis_io_flag_out = 2 }
	Details of the instruction. More...
enum	opdis_addr_expr_elem_t {   opdis_addr_expr_base = 1, opdis_addr_expr_index = 2, opdis_addr_expr_disp = 4, opdis_addr_expr_disp_u = 8,   opdis_addr_expr_disp_s = 16, opdis_addr_expr_disp_abs = 32 }
	Elements present in an address expression. More...
enum	opdis_addr_expr_shift_t {   opdis_addr_expr_lsl, opdis_addr_expr_lsr, opdis_addr_expr_asl, opdis_addr_expr_ror,   opdis_addr_expr_rrx }
	Type of shift operation used in address expression. More...
Functions
opdis_insn_t *LIBCALL	opdis_insn_alloc (opdis_off_t num_operands)
	Allocate an instruction object and initialize its contents to zero.
opdis_insn_t *LIBCALL	opdis_insn_alloc_fixed (size_t ascii_sz, size_t mnemonic_sz, size_t num_operands, size_t op_ascii_sz)
	Allocate a fixed-size instruction object for use as a buffer.
opdis_insn_t *LIBCALL	opdis_insn_dupe (const opdis_insn_t *insn)
	Duplicate an instruction object.
void LIBCALL	opdis_insn_clear (opdis_insn_t *insn)
	Clear the contents of an instruction object.
void LIBCALL	opdis_insn_free (opdis_insn_t *insn)
	Free an allocated instruction object.
void LIBCALL	opdis_insn_set_ascii (opdis_insn_t *i, const char *ascii)
	Set the ascii field of an instruction.
void LIBCALL	opdis_insn_set_mnemonic (opdis_insn_t *i, const char *mnemonic)
	Set the mnemonic field of an instruction.
void LIBCALL	opdis_insn_add_prefix (opdis_insn_t *i, const char *prefix)
	Append a string to the prefix field.
void LIBCALL	opdis_insn_add_comment (opdis_insn_t *i, const char *cmt)
	Append a string to the comment field.
int LIBCALL	opdis_insn_add_operand (opdis_insn_t *i, opdis_op_t *op)
	Add an operand to an instruction.
opdis_op_t *LIBCALL	opdis_insn_next_avail_op (opdis_insn_t *i)
	Return next available allocated operand.
int LIBCALL	opdis_insn_is_branch (opdis_insn_t *i)
	Determine if the instruction has a branch target operand.
int LIBCALL	opdis_insn_fallthrough (opdis_insn_t *i)
	Determine if the execution falls through to the next instruction.
int LIBCALL	opdis_insn_isa_str (const opdis_insn_t *insn, char *buf, int buf_len)
	Generate a string representation of instruction isa field.
int LIBCALL	opdis_insn_cat_str (const opdis_insn_t *insn, char *buf, int buf_len)
	Generate a string representation of instruction category field.
int LIBCALL	opdis_insn_flags_str (const opdis_insn_t *insn, char *buf, int buf_len, const char *delim)
	Generate a string representation of instruction flags field.
opdis_op_t *LIBCALL	opdis_op_alloc (void)
	Allocate an operand object.
opdis_op_t *LIBCALL	opdis_op_alloc_fixed (size_t ascii_sz)
	Allocate a fixed-size operand object for use as a buffer.
opdis_op_t *LIBCALL	opdis_op_dupe (opdis_op_t *op)
	Duplicate an operand object.
void LIBCALL	opdis_op_clear (opdis_op_t *op)
	Clear the contents of an operand object.
void LIBCALL	opdis_op_free (opdis_op_t *op)
	Free an allocated operand object.
void LIBCALL	opdis_op_set_ascii (opdis_op_t *op, const char *ascii)
	Set the ascii field of an operand.
int LIBCALL	opdis_op_cat_str (const opdis_op_t *op, char *buf, int buf_len)
	Generate a string representation of operand category field.
int LIBCALL	opdis_op_flags_str (const opdis_op_t *op, char *buf, int buf_len, const char *delim)
	Generate a string representation of operand flags field.
int LIBCALL	opdis_reg_flags_str (const opdis_reg_t *reg, char *buf, int buf_len, const char *delim)
	Generate a string representation of register flags field.
int LIBCALL	opdis_addr_expr_shift_str (const opdis_addr_expr_t *exp, char *buf, int buf_len)
	Generate a string representation of addr expression shift field.

---

Detailed Description

Data Model for disassembled objects.

The libopdis data model consist of objects for instructions, operands, and operand values.

Each instruction consists of address details (vma, offset, size, bytes), zero or more prefixes, a
mnemonic for the machine opcode, and zero or more operands. Each operand consists of a value which may be a register , absolute address , address expression , or immediate value.

Instruction, operand, and register objects all have an ascii attribute that contains the raw output from libopcodes for this object. Note that libopcodes attempts to format its output for objdump, so there may be trailing whitespace in the ascii fields.

Instruction and operand objects have a category attribute that determines the broad type or category of the instruction (e.g. is it a control flow or stack operation) or operand (e.g. is it a register or immediate value).

Insructions, operands, and registers also have a flags attribute that contains additional information. For instructions, this will consist of a more detailed operation type (e.g. jump vs call). For operands, this will contain usage info (e.g. is the operand an address, is the operand read or written, etc). For registers, this will contain general usage info about the register (e.g. is it general-purpose, it is a stack pointer, etc).

---

Enumeration Type Documentation

enum opdis_addr_expr_elem_t

Elements present in an address expression.

See also:

opdis_addr_expr_t

Note:

Scale factor is always present; it defaults to 1.

Enumerator:

opdis_addr_expr_base	Base register
opdis_addr_expr_index	Index register
opdis_addr_expr_disp	Displacement
opdis_addr_expr_disp_u	Unsigned disp
opdis_addr_expr_disp_s	Signed disp
opdis_addr_expr_disp_abs	Absolute addr disp

enum opdis_addr_expr_shift_t

Type of shift operation used in address expression.

See also:

opdis_addr_expr_t

Note:

These only apply to ARM; x86 is always ASL.

Enumerator:

opdis_addr_expr_lsl	Logical shift left
opdis_addr_expr_lsr	Logical shift right
opdis_addr_expr_asl	Arithmetic shift left
opdis_addr_expr_ror	Rotate right
opdis_addr_expr_rrx	Rotate right with carry

enum opdis_bit_flag_t

Details of the instruction.

These flags encode specific information about the instructions: is it a shift or rotate (and is the carry flag significant), is it an AND/OR/XOR/NOT operation, etc.

Note:

It is the responsibility of the architecture-specific decoder to enure that the correct flags set. A missing flag does not necessarily mean that the flag does not apply, but may indicate that the decoder does not fully support the instruction.

Enumerator:

opdis_bit_flag_none	No flags
opdis_bit_flag_and	bitwise AND
opdis_bit_flag_or	bitwise OR
opdis_bit_flag_xor	bitwise XOR
opdis_bit_flag_not	bitwise NOT
opdis_bit_flag_lsl	Logical shift left
opdis_bit_flag_lsr	Logical shift right
opdis_bit_flag_asl	Arithmetic shift left
opdis_bit_flag_asr	Arithmetic shift right
opdis_bit_flag_rol	Rotate left
opdis_bit_flag_ror	Rotate right
opdis_bit_flag_rcl	Rotate left with carry
opdis_bit_flag_rcr	Rotate right with carry

enum opdis_cflow_flag_t

Details of the control flow instruction.

These flags encode specific information about the control flow instructions: is it a call, does it branch, is it a return, etc.

Note:

It is the responsibility of the architecture-specific decoder to enure that the correct flags set. A missing flag does not necessarily mean that the flag does not apply, but may indicate that the decoder does not fully support the instruction.

Enumerator:

opdis_cflow_flag_none	No flags
opdis_cflow_flag_call	Call
opdis_cflow_flag_callcc	Conditional call
opdis_cflow_flag_jmp	Jump
opdis_cflow_flag_jmpcc	Conditional jump
opdis_cflow_flag_ret	Return from call

enum opdis_insn_cat_t

The category of an instruction.

The type or category of an instruction. This is used to distinguish between instructions at a high level : control flow instructions (jmp, call, ret), stack instructions (push, pop), floating point instructions, etc.

Note:

It is the responsibility of the architecture-specific decoder to enure that the correct category is set. A value of 'unknown' does not ensure that one of the other values is not suitable, but may indicate that the decoder does not fully support the instruction.

Enumerator:

opdis_insn_cat_unknown	Unknown instruction type
opdis_insn_cat_cflow	Control flow instruction
opdis_insn_cat_stack	Stack manipulation instruction
opdis_insn_cat_lost	Load/store instruction
opdis_insn_cat_test	Test/compare instruction
opdis_insn_cat_math	Arithmetic instruction
opdis_insn_cat_bit	Bitwise (shift/and/or/etc) instruction
opdis_insn_cat_io	I/O port instruction
opdis_insn_cat_trap	Interrupt/trap instruction
opdis_insn_cat_priv	Privileged (ring0) instruction
opdis_insn_cat_nop	No-operation instruction

enum opdis_insn_subset_t

The subset of an ISA that the instruction belongs to.

Note:

It is the responsibility of the architecture-specific decoder to enure that the correct ISA is set. A value of 'general' does not ensure that one of the other values is not suitable, but may indicate that the decoder does not fully support the ISA.

Enumerator:

opdis_insn_subset_gen	General-purpose instruction
opdis_insn_subset_fpu	Floating-Point instruction
opdis_insn_subset_gpu	GPU instruction
opdis_insn_subset_simd	SIMD extension instruction
opdis_insn_subset_vm	Virtual Machine extension

enum opdis_io_flag_t

Details of the instruction.

These flags encode specific information about the instructions: does it read input from a port, does it write output to a port, etc.

Note:

It is the responsibility of the architecture-specific decoder to enure that the correct flags set. A missing flag does not necessarily mean that the flag does not apply, but may indicate that the decoder does not fully support the instruction.

Enumerator:

opdis_io_flag_none	No flags
opdis_io_flag_in	Input from port
opdis_io_flag_out	Output from port

enum opdis_op_cat_t

The category of an operand.

The type or category of an instruction operand. This is used to distinguish between operands that are registers, memory locations, immediate values, or relative offsets.

Note:

It is the responsibility of the architecture-specific decoder to enure that the correct category is set. A value of 'unknown' does not ensure that one of the other values is not suitable, but may indicate that the decoder does not fully support the operand.

Enumerator:

opdis_op_cat_unknown	Unknown operand type
opdis_op_cat_register	CPU register
opdis_op_cat_immediate	Immediate value
opdis_op_cat_absolute	Absolute address (seg:offset)
opdis_op_cat_expr	Address expression

enum opdis_op_flag_t

Flags applied to an operand.

Operand flags are used to encode additional information about the operand.

Note:

It is the responsibility of the architecture-specific decoder to enure that the correct flags set. A missing flag does not necessarily mean that the flag does not apply, but may indicate that the decoder does not fully support the operand.

Enumerator:

opdis_op_flag_none	No flags
opdis_op_flag_r	Operand is read by insn
opdis_op_flag_w	Operand is written by insn
opdis_op_flag_x	Operand is executed by insn
opdis_op_flag_signed	Immediate data is signed
opdis_op_flag_address	Operand value is an address
opdis_op_flag_indirect	Operand value points to address

enum opdis_stack_flag_t

Details of the instruction.

These flags encode specific information about the instructions: is it a push or a pop, does it enter or leave a stack frame, etc.

Note:

It is the responsibility of the architecture-specific decoder to enure that the correct flags set. A missing flag does not necessarily mean that the flag does not apply, but may indicate that the decoder does not fully support the instruction.

Enumerator:

opdis_stack_flag_none	No flags
opdis_stack_flag_push	Push to stack
opdis_stack_flag_pop	Pop from stack
opdis_stack_flag_frame	Enter stack frame
opdis_stack_flag_unframe	Exit stack frame

---

Function Documentation

int opdis_addr_expr_shift_str	(	const opdis_addr_expr_t *	exp,
		char *	buf,
		int	buf_len
	)

Generate a string representation of addr expression shift field.

Parameters:

	exp	The address expression.
	buf	The buffer to append the string to.
	buf_len	The length of the buffer.

Note:

If buf is not an empty string, it will be appended (not replaced).

See also:

opdis_op_cat_str

opdis_op_flags_str

void opdis_insn_add_comment	(	opdis_insn_t *	i,
		const char *	cmt
	)

Append a string to the comment field.

Parameters:

	i	The instruction to modify.
	cmt	The value to append to the comment field.

int opdis_insn_add_operand	(	opdis_insn_t *	i,
		opdis_op_t *	op
	)

Add an operand to an instruction.

Append an operand to the list of operands in the instruction. This does not duplicate the operand; it performs a realloc on the operands array, appends the pointer op to it, and increases the instruction count.

Parameters:

	i	The instruction to modify.
	op	The operand to append to the instruction.

Returns:

1 on success, 0 on failure.

Note:

If the number of operands in i is less than the number of allocated operands in i, no realloc is performed.

void opdis_insn_add_prefix	(	opdis_insn_t *	i,
		const char *	prefix
	)

Append a string to the prefix field.

a a

Parameters:

	i	The instruction to modify.
	prefix	The value to append to the prefix field.

opdis_insn_t * opdis_insn_alloc

(

opdis_off_t

num_operands

)

Allocate an instruction object and initialize its contents to zero.

Parameters:

num_operands

The number of operands to allocate, or 0.

Returns:

The allocated instruction.

See also:

opdis_insn_free

Note:

The ascii and mnemonic fields are not allocated.

The operands array is allocated as an empty array of pointers; the operands themselves are not allocated.

opdis_insn_t * opdis_insn_alloc_fixed	(	size_t	ascii_sz,
		size_t	mnemonic_sz,
		size_t	num_operands,
		size_t	op_ascii_sz
	)

Allocate a fixed-size instruction object for use as a buffer.

This allocates an instruction object with the specified number of operands, and with ascii and mnemonic allocated to the specified sizes. Each operand is allocated by opdis_op_alloc_fixed.

Parameters:

	ascii_sz
	mnemonic_sz
	num_operands
	op_ascii_sz

Returns:

The allocated instruction.

See also:

opdis_insn_alloc

opdis_insn_free

Note:

The instruction object returned by this function is intended for use as a buffer.

int opdis_insn_cat_str	(	const opdis_insn_t *	insn,
		char *	buf,
		int	buf_len
	)

Generate a string representation of instruction category field.

Parameters:

	i	The instruction.
	buf	The buffer to append the string to.
	buf_len	The length of the buffer.

Note:

'/' should not be used as a delimiter, as some flags (e.g. load/store, i/o) use it in their string representation.

See also:

opdis_insn_isa_str

opdis_insn_flags_str

Note:

If buf is not an empty string, it will be appended (not replaced).

void opdis_insn_clear

(

opdis_insn_t *

insn

)

Clear the contents of an instruction object.

Parameters:

i

The instruction to clear.

opdis_insn_t * opdis_insn_dupe

(

const opdis_insn_t *

insn

)

Duplicate an instruction object.

Allocate an instruction object and initialize it with the contents of i. This is primarily used to create an instruction object from a fixed-size opdis_insn_t. The ascii, mnemonic, and operands fields are only as large as they need to be (i.e. the length of the string and the number of valid operands).

Parameters:

i

The instruction to duplicate.

Returns:

The duplicate instruction.

See also:

opdis_insn_alloc

int opdis_insn_fallthrough

(

opdis_insn_t *

i

)

Determine if the execution falls through to the next instruction.

Returns true (1) if execution falls through to the subsequent instruction in memory. This is true for all instructions except unconditional jumps (JMP) and procedure returns (RET).

Parameters:

i

The instruction to examine.

Returns:

1 if execution continues, 0 otherwise.

Note:

This will only work if of the decoder supports it. Check that status contains opdis_decode_mnem_flags before relying on the return value.

int opdis_insn_flags_str	(	const opdis_insn_t *	insn,
		char *	buf,
		int	buf_len,
		const char *	delim
	)

Generate a string representation of instruction flags field.

Parameters:

	i	The instruction.
	buf	The buffer to append the string to.
	buf_len	The length of the buffer.
	delim	The delimiter to use between flags.

See also:

opdis_insn_cat_str

opdis_insn_isa_str

Note:

If buf is not an empty string, it will be appended (not replaced).

void opdis_insn_free

(

opdis_insn_t *

insn

)

Free an allocated instruction object.

Parameters:

i

The instruction to free.

See also:

opdis_insn_alloc

Note:

This frees ascii, mnemonic, and all allocated operands.

int opdis_insn_is_branch

(

opdis_insn_t *

i

)

Determine if the instruction has a branch target operand.

Returns true (1) if the instruction has a branch target operand. The branch target operand is accessible via i->target.

Parameters:

i

The instruction to examine.

Returns:

1 if the instruction has a branch target, 0 otherwise.

Note:

This will only work if of the decoder supports it. Check that status contains both opdis_decode_mnem_flags and opdis_decode_ops before relying on the return value.

int opdis_insn_isa_str	(	const opdis_insn_t *	insn,
		char *	buf,
		int	buf_len
	)

Generate a string representation of instruction isa field.

Parameters:

	i	The instruction.
	buf	The buffer to append the string to.
	buf_len	The length of the buffer.

See also:

opdis_insn_cat_str

opdis_insn_flags_str

Note:

If buf is not an empty string, it will be appended (not replaced).

opdis_op_t * opdis_insn_next_avail_op

(

opdis_insn_t *

i

)

Return next available allocated operand.

Parameters:

i

The instruction to containing the operand.

Returns:

The next unused operand, or NULL if all allocated operands are used.

void opdis_insn_set_ascii	(	opdis_insn_t *	i,
		const char *	ascii
	)

Set the ascii field of an instruction.

This duplicates the string ascii and sets the ascii field of i to the new string. If the ascii field is non-NULL, it is freed before the assignment.

Parameters:

	i	The instruction to modify.
	ascii	The new value for the ascii field.

See also:

opdis_insn_set_mnemonic

void opdis_insn_set_mnemonic	(	opdis_insn_t *	i,
		const char *	mnemonic
	)

Set the mnemonic field of an instruction.

This duplicates the string mnemonic and sets the mnemonic field of i to the new string. If the mnemonic field is non-NULL, it is freed before the assignment.

Parameters:

	i	The instruction to modify.
	mnemonic	The new value for the mnemonic field.

See also:

opdis_insn_set_ascii

opdis_op_t * opdis_op_alloc

(

void

)

Allocate an operand object.

Returns:

The allocated operand.

See also:

opdis_op_free

opdis_op_t * opdis_op_alloc_fixed

(

size_t

ascii_sz

)

Allocate a fixed-size operand object for use as a buffer.

This allocates an operand object with ascii allocated to the specified size.

Parameters:

ascii_sz

Returns:

The allocated operand.

See also:

opdis_op_alloc

opdis_op_free

int opdis_op_cat_str	(	const opdis_op_t *	op,
		char *	buf,
		int	buf_len
	)

Generate a string representation of operand category field.

Parameters:

	op	The operand.
	buf	The buffer to append the string to.
	buf_len	The length of the buffer.

Note:

If buf is not an empty string, it will be appended (not replaced).

See also:

opdis_op_flags_str

opdis_reg_flags_str

void opdis_op_clear

(

opdis_op_t *

op

)

Clear the contents of an operand object.

Parameters:

o

The operand to clear.

opdis_op_t * opdis_op_dupe

(

opdis_op_t *

op

)

Duplicate an operand object.

Allocate an operand object and initialize it with the contents of op. This is primarily used to create an operand object from a fixed-size opdis_op_t.

Parameters:

op

The operand to duplicate.

Returns:

The duplicate operand.

See also:

opdis_op_alloc

opdis_insn_dupe

int opdis_op_flags_str	(	const opdis_op_t *	op,
		char *	buf,
		int	buf_len,
		const char *	delim
	)

Generate a string representation of operand flags field.

Parameters:

	op	The operand.
	buf	The buffer to append the string to.
	buf_len	The length of the buffer.
	delim	The delimiter to use between flags.

Note:

If buf is not an empty string, it will be appended (not replaced).

See also:

opdis_op_cat_str

opdis_reg_flags_str

void opdis_op_free

(

opdis_op_t *

op

)

Free an allocated operand object.

Parameters:

op

The operand to free.

See also:

opdis_op_alloc

void opdis_op_set_ascii	(	opdis_op_t *	op,
		const char *	ascii
	)

Set the ascii field of an operand.

This duplicates the string ascii and sets the ascii field of op to the new string. If the ascii field is non-NULL, it is freed before the assignment.

Parameters:

	op	The operand to modify
	ascii	The new value for the ascii field.

int opdis_reg_flags_str	(	const opdis_reg_t *	reg,
		char *	buf,
		int	buf_len,
		const char *	delim
	)

Generate a string representation of register flags field.

Parameters:

	reg	The register.
	buf	The buffer to append the string to.
	buf_len	The length of the buffer.
	delim	The delimiter to use between flags.

Note:

If buf is not an empty string, it will be appended (not replaced).

See also:

opdis_op_cat_str

opdis_op_flags_str