Functions that deal with the disassembling of program instructions. More...

Classes
class	op_t
	Operand of an instruction. More...
union	value_union_t
	This union is used to pass byte values to various helper functions. More...
struct	value_union_t::dq_t
struct	value_union_t::dt_t
struct	value_union_t::d128_t
struct	outctx_base_t
struct	outctx_t
struct	macro_constructor_t
	Helper class for processor modules to build macro instructions. More...

Typedefs
typedef uchar	optype_t
	see Operand types

Functions
	CASSERT (sizeof(insn_t)==360)
idaman size_t ida_export	get_immvals (uval_t out, ea_t ea, int n, flags64_t F, insn_t cache=nullptr)
	Get immediate values at the specified address.
size_t	get_printable_immvals (uval_t out, ea_t ea, int n, flags64_t F, insn_t cache=nullptr)
	Get immediate ready-to-print values at the specified address.
idaman int ida_export	get_lookback (void)
	Number of instructions to look back.
idaman outctx_base_t *ida_export	create_outctx (ea_t ea, flags64_t F=0, int suspop=0)
	Create a new output context.
idaman bool ida_export	print_insn_mnem (qstring *out, ea_t ea)
	Print instruction mnemonics.
idaman bool ida_export	format_charlit (qstring out, const uchar *ptr, size_t size, uint32 flags=0, int encidx=0)
	Format character literal.
idaman bool ida_export	print_fpval (char buf, size_t bufsize, const void v, int size)
	Print a floating point value.
idaman flags64_t ida_export	get_dtype_flag (op_dtype_t dtype)
	Get flags for op_t::dtype field.
idaman size_t ida_export	get_dtype_size (op_dtype_t dtype)
	Get size of opt_::dtype field.
idaman op_dtype_t ida_export	get_dtype_by_size (asize_t size)
	Get op_t::dtype from size.
bool	is_floating_dtype (op_dtype_t dtype)
	Is a floating type operand?
idaman int ida_export	create_insn (ea_t ea, insn_t *out=nullptr)
	Create an instruction at the specified address.
idaman int ida_export	decode_insn (insn_t *out, ea_t ea)
	Analyze the specified address and fill 'out'.
bool	can_decode (ea_t ea)
	Can the bytes at address 'ea' be decoded as instruction?
idaman bool ida_export	print_operand (qstring out, ea_t ea, int n, int getn_flags=0, struct printop_t newtype=nullptr)
	Generate text representation for operand n.
idaman ea_t ida_export	decode_prev_insn (insn_t *out, ea_t ea)
	Decode previous instruction if it exists, fill 'out'.
idaman ea_t ida_export	decode_preceding_insn (insn_t out, ea_t ea, bool p_farref=nullptr)
	Decode preceding instruction in the execution flow.
idaman bool ida_export	construct_macro (macro_constructor_t _this, insn_t insn, bool enable)
idaman int ida_export	get_spoiled_reg (const insn_t &insn, const uint32 *regs, size_t n)
	Does the instruction spoil any register from 'regs'?
Address translation
The following functions can be used by processor modules to map addresses from one region to another. They are especially useful for microprocessors that map the same memory region to multiple address ranges or use memory bank switching. The user can use the following techniques to desribe address translations: some processors support the segment transation feature. the user can specify the mapping in Edit, Segments, Change segment translation the user can specify mapping for an individual direct call instruction by specifying it as an offset (Edit, Operand types, Offset) specify the value of the data segment virtual register (ds). it will be used to calculate data addresses
idaman ea_t ida_export	calc_dataseg (const insn_t &insn, int n=-1, int rgnum=-1)
	Get data segment for the instruction operand.
ea_t	map_data_ea (const insn_t &insn, ea_t addr, int opnum=-1)
	Map a data address.
ea_t	map_data_ea (const insn_t &insn, const op_t &op)
idaman ea_t ida_export	map_code_ea (const insn_t &insn, ea_t addr, int opnum)
	Map a code address.
ea_t	map_code_ea (const insn_t &insn, const op_t &op)
ea_t	map_ea (const insn_t &insn, const op_t &op, bool iscode)
ea_t	map_ea (const insn_t &insn, ea_t addr, int opnum, bool iscode)

Variables
const optype_t	o_void = 0
	No Operand.
const optype_t	o_reg = 1
	General Register (al,ax,es,ds...).
const optype_t	o_mem = 2
	A direct memory reference to a data item.
const optype_t	o_phrase = 3
	An indirect memory reference that uses a register: [reg] There can be several registers but no displacement.
const optype_t	o_displ = 4
	An indirect memory reference that uses a register and has an immediate constant added to it: [reg+N] There can be several registers.
const optype_t	o_imm = 5
	An immediate Value (constant).
const optype_t	o_far = 6
	An immediate far code reference (inter-segment)
const optype_t	o_near = 7
	An immediate near code reference (intra-segment)
const optype_t	o_idpspec0 = 8
	processor specific type.
const optype_t	o_idpspec1 = 9
	processor specific type.
const optype_t	o_idpspec2 = 10
	processor specific type.
const optype_t	o_idpspec3 = 11
	processor specific type.
const optype_t	o_idpspec4 = 12
	processor specific type.
const optype_t	o_idpspec5 = 13
	processor specific type.

Detailed Description

Functions that deal with the disassembling of program instructions.

There are 2 kinds of functions:

functions that are called from the kernel to disassemble an instruction. These functions call IDP module for it.
functions that are called from IDP module to disassemble an instruction. We will call them 'helper functions'.

Disassembly of an instruction is made in three steps:

analysis: ana.cpp
emulation: emu.cpp
conversion to text: out.cpp

The kernel calls the IDP module to perform these steps. At first, the kernel always calls the analysis. The analyzer must decode the instruction and fill the insn_t instance that it receives through its callback. It must not change anything in the database.

The second step, the emulation, is called for each instruction. This step must make necessary changes to the database, plan analysis of subsequent instructions, track register values, memory contents, etc. Please keep in mind that the kernel may call the emulation step for any address in the program - there is no ordering of addresses. Usually, the emulation is called for consecutive addresses but this is not guaranteed.

The last step, conversion to text, is called each time an instruction is displayed on the screen. The kernel will always call the analysis step before calling the text conversion step. The emulation and the text conversion steps should use the information stored in the insn_t instance they receive. They should not access the bytes of the instruction and decode it again - this should only be done in the analysis step.

Typedef Documentation

◆ optype_t

typedef uchar optype_t

see Operand types

Function Documentation

◆ CASSERT()

CASSERT ( sizeof(insn_t) = =360 )

◆ get_immvals()

idaman size_t ida_export get_immvals	(	uval_t *	out,
		ea_t	ea,
		int	n,
		flags64_t	F,
		insn_t *	cache = nullptr )

Get immediate values at the specified address.

This function decodes instruction at the specified address or inspects the data item. It finds immediate values and copies them to 'out'. This function will store the original value of the operands in 'out', unless the last bits of 'F' are "...0 11111111", in which case the transformed values (as needed for printing) will be stored instead.

Parameters

out	array of immediate values (at least 2*#UA_MAXOP elements)
ea	address to analyze
n	0..#UA_MAXOP-1 operand number, OPND_ALL all the operands
F	flags for the specified address
cache	optional already decoded instruction or buffer for it. if the cache does not contain the decoded instruction, it will be updated (useful if we call get_immvals for the same address multiple times)

Returns: number of immediate values (0..2*#UA_MAXOP)

◆ get_printable_immvals()

size_t get_printable_immvals	(	uval_t *	out,
		ea_t	ea,
		int	n,
		flags64_t	F,
		insn_t *	cache = nullptr )

inline

Get immediate ready-to-print values at the specified address.

Parameters

out	array of immediate values (at least 2*#UA_MAXOP elements)
ea	address to analyze
n	0..#UA_MAXOP-1 operand number, OPND_ALL all the operands
F	flags for the specified address
cache	optional already decoded instruction or buffer for it. if the cache does not contain the decoded instruction, it will be updated (useful if we call get_immvals for the same address multiple times)

Returns: number of immediate values (0..2*#UA_MAXOP)

◆ get_lookback()

idaman int ida_export get_lookback ( void )

Number of instructions to look back.

This variable is not used by the kernel. Its value may be specified in ida.cfg: LOOKBACK = <number>. IDP may use it as you like it. (TMS module uses it)

◆ calc_dataseg()

idaman ea_t ida_export calc_dataseg	(	const insn_t &	insn,
		int	n = -1,
		int	rgnum = -1 )

Get data segment for the instruction operand.

'opnum' and 'rgnum' are meaningful only if the processor has segment registers.

◆ map_data_ea() [1/2]

ea_t map_data_ea	(	const insn_t &	insn,
		ea_t	addr,
		int	opnum = -1 )

inline

Map a data address.

Parameters

insn	the current instruction
addr	the referenced address to map
opnum	operand number

◆ map_data_ea() [2/2]

ea_t map_data_ea	(	const insn_t &	insn,
		const op_t &	op )

inline

◆ map_code_ea() [1/2]

idaman ea_t ida_export map_code_ea	(	const insn_t &	insn,
		ea_t	addr,
		int	opnum )

Map a code address.

This function takes into account the segment translations.

Parameters

insn	the current instruction
addr	the referenced address to map
opnum	operand number

◆ map_code_ea() [2/2]

ea_t map_code_ea	(	const insn_t &	insn,
		const op_t &	op )

inline

◆ map_ea() [1/2]

ea_t map_ea	(	const insn_t &	insn,
		const op_t &	op,
		bool	iscode )

inline

◆ map_ea() [2/2]

ea_t map_ea	(	const insn_t &	insn,
		ea_t	addr,
		int	opnum,
		bool	iscode )

inline

◆ create_outctx()

idaman outctx_base_t *ida_export create_outctx	(	ea_t	ea,
		flags64_t	F = 0,
		int	suspop = 0 )

Create a new output context.

To delete it, just use "delete pctx"

◆ print_insn_mnem()

idaman bool ida_export print_insn_mnem	(	qstring *	out,
		ea_t	ea )

Print instruction mnemonics.

Parameters

out	output buffer
ea	linear address of the instruction

Returns: success

◆ format_charlit()

idaman bool ida_export format_charlit	(	qstring *	out,
		const uchar **	ptr,
		size_t	size,
		uint32	flags = 0,
		int	encidx = 0 )

Format character literal.

Try and format 'size' bytes pointed to by '*ptr', as literal characters, using the 'encidx' encoding, and with the specified 'flags' directives.

By default, format_charlit() will fail and return an error, in any of the following cases:

a byte cannot be decoded using the specified (or default) encoding
a codepoint is < 0x20 (i.e., ' ')
a codepoint is present in 'ash.esccodes'
a codepoint is 0xFF
a codepoint is >= 0x80, and AS_NHIAS was specified in ash.flag The function can be told to keep going instead of bailing out, for any of these situations, by using one of the FCBF_*_OK flags.

If the function is told to proceed on a specific error, by default it will format the byte as a C-encoded byte value (i.e., '\xNN'), unless the corresponding FCBF_*_REPL flag is passed, in which case the problematic byte/codepoint will be replaced by the Unicode replacement character in the output.

Parameters

out	output buffer (can be nullptr)
ptr	pointer to pointer to bytes to print (will be advanced by the number of bytes that were successfully printed)
size	size of input value in bytes
flags	format flags
encidx	the 1 byte-per-unit encoding to use (or 0 to use the default 1 BPU encoding)

Returns: success

◆ print_fpval()

idaman bool ida_export print_fpval	(	char *	buf,
		size_t	bufsize,
		const void *	v,
		int	size )

Print a floating point value.

Parameters

buf	output buffer. may be nullptr
bufsize	size of the output buffer
v	floating point value in processor native format
size	size of the value in bytes

Returns: success

Return values

true	ok
false	can't represent as floating point number

◆ get_dtype_flag()

idaman flags64_t ida_export get_dtype_flag ( op_dtype_t dtype )

Get flags for op_t::dtype field.

◆ get_dtype_size()

idaman size_t ida_export get_dtype_size ( op_dtype_t dtype )

Get size of opt_::dtype field.

◆ get_dtype_by_size()

idaman op_dtype_t ida_export get_dtype_by_size ( asize_t size )

Get op_t::dtype from size.

◆ is_floating_dtype()

bool is_floating_dtype ( op_dtype_t dtype )

inline

Is a floating type operand?

◆ create_insn()

idaman int ida_export create_insn	(	ea_t	ea,
		insn_t *	out = nullptr )

Create an instruction at the specified address.

This function checks if an instruction is present at the specified address and will try to create one if there is none. It will fail if there is a data item or other items hindering the creation of the new instruction. This function will also fill the 'out' structure.

Parameters

ea	linear address
out	the resulting instruction

Returns: the length of the instruction or 0

◆ decode_insn()

idaman int ida_export decode_insn	(	insn_t *	out,
		ea_t	ea )

Analyze the specified address and fill 'out'.

This function does not modify the database. It just tries to interpret the specified address as an instruction and fills the 'out' structure.

Parameters

out	the resulting instruction
ea	linear address

Returns: the length of the (possible) instruction or 0

◆ can_decode()

bool can_decode ( ea_t ea )

inline

Can the bytes at address 'ea' be decoded as instruction?

Parameters

ea	linear address

Returns: whether or not the contents at that address could be a valid instruction

◆ print_operand()

idaman bool ida_export print_operand	(	qstring *	out,
		ea_t	ea,
		int	n,
		int	getn_flags = 0,
		struct printop_t *	newtype = nullptr )

Generate text representation for operand n.

This function will generate the text representation of the specified operand (includes color codes.)

Parameters

out	output buffer
ea	the item address (instruction or data)
n	0..#UA_MAXOP-1 operand number, meaningful only for instructions
getn_flags	Name expression flags Currently only #GETN_NODUMMY is accepted.
newtype	if specified, print the operand using the specified type

Returns: success

◆ decode_prev_insn()

idaman ea_t ida_export decode_prev_insn	(	insn_t *	out,
		ea_t	ea )

Decode previous instruction if it exists, fill 'out'.

Parameters

out	the resulting instruction
ea	the address to decode the previous instruction from

Returns: the previous instruction address (#BADADDR-no such insn)

◆ decode_preceding_insn()

idaman ea_t ida_export decode_preceding_insn	(	insn_t *	out,
		ea_t	ea,
		bool *	p_farref = nullptr )

Decode preceding instruction in the execution flow.

Prefer far xrefs from addresses < the current to ordinary flows.

Parameters

out	the resulting instruction
ea	the address to decode the preceding instruction from
p_farref	will contain 'true' if followed an xref, false otherwise.

Returns: the preceding instruction address (#BADADDR-no such insn) and 'out'.

◆ construct_macro()

idaman bool ida_export construct_macro	(	macro_constructor_t *	_this,
		insn_t *	insn,
		bool	enable )

◆ get_spoiled_reg()

idaman int ida_export get_spoiled_reg	(	const insn_t &	insn,
		const uint32 *	regs,
		size_t	n )

Does the instruction spoil any register from 'regs'?

This function checks the Instruction feature bits flags from the instructions array. Only o_reg operand types are consulted.

Parameters

insn	the instruction
regs	array with register indexes
n	size of 'regs'

Returns: index in the 'regs' array or -1

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ optype_t

Function Documentation

◆ CASSERT()

◆ get_immvals()

◆ get_printable_immvals()

◆ get_lookback()

◆ calc_dataseg()

◆ map_data_ea() [1/2]

◆ map_data_ea() [2/2]

◆ map_code_ea() [1/2]

◆ map_code_ea() [2/2]

◆ map_ea() [1/2]

◆ map_ea() [2/2]

◆ create_outctx()

◆ print_insn_mnem()

◆ format_charlit()

◆ print_fpval()

◆ get_dtype_flag()

◆ get_dtype_size()

◆ get_dtype_by_size()

◆ is_floating_dtype()

◆ create_insn()

◆ decode_insn()

◆ can_decode()

◆ print_operand()

◆ decode_prev_insn()

◆ decode_preceding_insn()

◆ construct_macro()

◆ get_spoiled_reg()