Routines to manipulate function stack frames, stack variables, register variables and local labels. More...

Classes
struct	stkpnt_t

struct	stkpnts_t

struct	regvar_t
	A register variable allows the user to rename a general processor register to a meaningful name. More...

struct	xreflist_entry_t
	An xref to an argument or variable located in a function's stack frame. More...

Macros
#define	STKVAR_VALID_SIZE 0x0001
	x.dtyp contains correct variable type (for insns like 'lea' this bit must be off). More...

#define	REGVAR_ERROR_OK 0
	all ok

#define	REGVAR_ERROR_ARG (-1)
	function arguments are bad

#define	REGVAR_ERROR_RANGE (-2)
	the definition range is bad

#define	REGVAR_ERROR_NAME (-3)
	the provided name(s) can't be accepted

Typedefs
typedef qvector< xreflist_entry_t >	xreflist_t
	vector of xrefs to variables in a function's stack frame

Enumerations
enum	frame_part_t { FPC_ARGS , FPC_RETADDR , FPC_SAVREGS , FPC_LVARS }
	Parts of a frame.

Functions
idaman bool ida_export	add_frame (func_t *pfn, sval_t frsize, ushort frregs, asize_t argsize)
	Add function frame. More...

idaman bool ida_export	del_frame (func_t *pfn)
	Delete a function frame. More...

idaman bool ida_export	set_frame_size (func_t *pfn, asize_t frsize, ushort frregs, asize_t argsize)
	Set size of function frame. More...

idaman asize_t ida_export	get_frame_size (const func_t *pfn)
	Get full size of a function frame. More...

idaman int ida_export	get_frame_retsize (const func_t *pfn)
	Get size of function return address. More...

idaman void ida_export	get_frame_part (range_t range, const func_t pfn, frame_part_t part)
	Get offsets of the frame part in the frame. More...

ea_t	frame_off_args (const func_t *pfn)
	Get starting address of arguments section.

ea_t	frame_off_retaddr (const func_t *pfn)
	Get starting address of return address section.

ea_t	frame_off_savregs (const func_t *pfn)
	Get starting address of saved registers section.

ea_t	frame_off_lvars (const func_t *pfn)
	Get start address of local variables section.

idaman struc_t *ida_export	get_frame (const func_t *pfn)
	Get pointer to function frame. More...

struc_t *	get_frame (ea_t ea)
	Get pointer to function frame. More...

sval_t	soff_to_fpoff (func_t *pfn, uval_t soff)
	Convert struct offsets into fp-relative offsets. More...

idaman bool ida_export	update_fpd (func_t *pfn, asize_t fpd)
	Update frame pointer delta. More...

idaman bool ida_export	set_purged (ea_t ea, int nbytes, bool override_old_value)
	Set the number of purged bytes for a function or data item (funcptr). More...

idaman ea_t ida_export	get_func_by_frame (tid_t frame_id)
	Get function by its frame id. More...

idaman member_t *ida_export	get_stkvar (sval_t *actval, const insn_t &insn, const op_t &x, sval_t v)
	Get pointer to stack variable. More...

idaman bool ida_export	add_stkvar (const insn_t &insn, const op_t &x, sval_t v, int flags)
	Automatically add stack variable if doesn't exist. More...

idaman bool ida_export	define_stkvar (func_t pfn, const char name, sval_t off, flags64_t flags, const opinfo_t *ti, asize_t nbytes)
	Define/redefine a stack variable. More...

idaman ssize_t ida_export	build_stkvar_name (qstring buf, const func_t pfn, sval_t v)
	Build automatic stack variable name. More...

idaman ea_t ida_export	calc_stkvar_struc_offset (func_t *pfn, const insn_t &insn, int n)
	Calculate offset of stack variable in the frame structure. More...

idaman int ida_export	delete_wrong_frame_info (func_t *pfn, bool idaapi should_reanalyze(const insn_t &insn))
	Find and delete wrong frame info. More...

idaman void ida_export	free_regvar (struct regvar_t *v)

idaman int ida_export	add_regvar (func_t pfn, ea_t ea1, ea_t ea2, const char canon, const char user, const char cmt)
	Define a register variable. More...

idaman regvar_t *ida_export	find_regvar (func_t pfn, ea_t ea1, ea_t ea2, const char canon, const char *user)
	Find a register variable definition (powerful version). More...

regvar_t *	find_regvar (func_t pfn, ea_t ea, const char canon)
	Find a register variable definition. More...

bool	has_regvar (func_t *pfn, ea_t ea)
	Is there a register variable definition? More...

idaman int ida_export	rename_regvar (func_t pfn, regvar_t v, const char *user)
	Rename a register variable. More...

idaman int ida_export	set_regvar_cmt (func_t pfn, regvar_t v, const char *cmt)
	Set comment for a register variable. More...

idaman int ida_export	del_regvar (func_t pfn, ea_t ea1, ea_t ea2, const char canon)
	Delete a register variable definition. More...

idaman bool ida_export	add_auto_stkpnt (func_t *pfn, ea_t ea, sval_t delta)
	Add automatic SP register change point. More...

idaman bool ida_export	add_user_stkpnt (ea_t ea, sval_t delta)
	Add user-defined SP register change point. More...

idaman bool ida_export	del_stkpnt (func_t *pfn, ea_t ea)
	Delete SP register change point. More...

idaman sval_t ida_export	get_spd (func_t *pfn, ea_t ea)
	Get difference between the initial and current values of ESP. More...

idaman sval_t ida_export	get_effective_spd (func_t *pfn, ea_t ea)
	Get effective difference between the initial and current values of ESP. More...

idaman sval_t ida_export	get_sp_delta (func_t *pfn, ea_t ea)
	Get modification of SP made at the specified location. More...

idaman bool ida_export	recalc_spd (ea_t cur_ea)
	Recalculate SP delta for an instruction that stops execution. More...

idaman void ida_export	build_stkvar_xrefs (xreflist_t out, func_t pfn, const member_t *mptr)
	Fill 'out' with a list of all the xrefs made from function 'pfn', to the argument or variable 'mptr' in 'pfn's stack frame. More...

Detailed Description

Routines to manipulate function stack frames, stack variables, register variables and local labels.

The frame is represented as a structure:

  +------------------------------------------------+
  | function arguments                             |
  +------------------------------------------------+
  | return address (isn't stored in func_t)        |
  +------------------------------------------------+
  | saved registers (SI, DI, etc - func_t::frregs) |
  +------------------------------------------------+ <- typical BP
  |                                                |  |
  |                                                |  | func_t::fpd
  |                                                |  |
  |                                                | <- real BP
  | local variables (func_t::frsize)               |
  |                                                |
  |                                                |
  +------------------------------------------------+ <- SP

To access the structure of a function frame, use:

get_struc() (use func_t::frame as structure ID)
get_frame(const func_t *pfn)
get_frame(ea_t ea)

Macro Definition Documentation

◆ STKVAR_VALID_SIZE

#define STKVAR_VALID_SIZE 0x0001

x.dtyp contains correct variable type (for insns like 'lea' this bit must be off).

In general, dr_O references do not allow to determine the variable size

Function Documentation

◆ add_frame()

idaman bool ida_export add_frame	(	func_t *	pfn,
		sval_t	frsize,
		ushort	frregs,
		asize_t	argsize
	)

Add function frame.

Parameters

pfn	pointer to function structure
frsize	size of function local variables
frregs	size of saved registers
argsize	size of function arguments range which will be purged upon return. this parameter is used for __stdcall and __pascal calling conventions. for other calling conventions please pass 0.

Return values

1	ok
0	failed (no function, frame already exists)

◆ del_frame()

idaman bool ida_export del_frame ( func_t * pfn )

Delete a function frame.

Parameters

pfn	pointer to function structure

Returns: success

◆ set_frame_size()

idaman bool ida_export set_frame_size	(	func_t *	pfn,
		asize_t	frsize,
		ushort	frregs,
		asize_t	argsize
	)

Set size of function frame.

Note: The returned size may not include all stack arguments. It does so only for __stdcall and __fastcall calling conventions. To get the entire frame size for all cases use get_struc_size(get_frame(pfn)).

Parameters

pfn	pointer to function structure
frsize	size of function local variables
frregs	size of saved registers
argsize	size of function arguments that will be purged from the stack upon return

Returns: success

◆ get_frame_size()

idaman asize_t ida_export get_frame_size ( const func_t * pfn )

Get full size of a function frame.

This function takes into account size of local variables + size of saved registers + size of return address + number of purged bytes. The purged bytes correspond to the arguments of the functions with __stdcall and __fastcall calling conventions.

Parameters

pfn	pointer to function structure, may be nullptr

Returns: size of frame in bytes or zero

◆ get_frame_retsize()

idaman int ida_export get_frame_retsize ( const func_t * pfn )

Get size of function return address.

Parameters

pfn	pointer to function structure, can't be nullptr

◆ get_frame_part()

idaman void ida_export get_frame_part	(	range_t *	range,
		const func_t *	pfn,
		frame_part_t	part
	)

Get offsets of the frame part in the frame.

Parameters

range	pointer to the output buffer with the frame part start/end(exclusive) offsets, can't be nullptr
pfn	pointer to function structure, can't be nullptr
part	frame part

◆ get_frame() [1/2]

idaman struc_t *ida_export get_frame ( const func_t * pfn )

Get pointer to function frame.

Parameters

pfn	pointer to function structure

◆ get_frame() [2/2]

struc_t * get_frame ( ea_t ea )

inline

Get pointer to function frame.

Parameters

ea	any address in the function

◆ soff_to_fpoff()

sval_t soff_to_fpoff	(	func_t *	pfn,
		uval_t	soff
	)

inline

Convert struct offsets into fp-relative offsets.

This function converts the offsets inside the struc_t object into the frame pointer offsets (for example, EBP-relative).

◆ update_fpd()

idaman bool ida_export update_fpd	(	func_t *	pfn,
		asize_t	fpd
	)

Update frame pointer delta.

Parameters

pfn	pointer to function structure
fpd	new fpd value. cannot be bigger than the local variable range size.

Returns: success

◆ set_purged()

idaman bool ida_export set_purged	(	ea_t	ea,
		int	nbytes,
		bool	override_old_value
	)

Set the number of purged bytes for a function or data item (funcptr).

This function will update the database and plan to reanalyze items referencing the specified address. It works only for processors with PR_PURGING bit in 16 and 32 bit modes.

Parameters

ea	address of the function of item
nbytes	number of purged bytes
override_old_value	may overwrite old information about purged bytes

Returns: success

◆ get_func_by_frame()

idaman ea_t ida_export get_func_by_frame ( tid_t frame_id )

Get function by its frame id.

Warning: this function works only with databases created by IDA > 5.6

Parameters

frame_id id of the function frame

Returns: start address of the function or BADADDR

◆ get_stkvar()

idaman member_t *ida_export get_stkvar	(	sval_t *	actval,
		const insn_t &	insn,
		const op_t &	x,
		sval_t	v
	)

Get pointer to stack variable.

Parameters

actval	actual value used to fetch stack variable this pointer may point to 'v'
insn	the instruction
x	reference to instruction operand
v	immediate value in the operand (usually x.addr)

Returns: nullptr or ptr to stack variable

◆ add_stkvar()

idaman bool ida_export add_stkvar	(	const insn_t &	insn,
		const op_t &	x,
		sval_t	v,
		int	flags
	)

Automatically add stack variable if doesn't exist.

Processor modules should use insn_t::create_stkvar().

Parameters

insn	the instruction
x	reference to instruction operand
v	immediate value in the operand (usually x.addr)
flags	Add stkvar flags

Returns: success

◆ define_stkvar()

idaman bool ida_export define_stkvar	(	func_t *	pfn,
		const char *	name,
		sval_t	off,
		flags64_t	flags,
		const opinfo_t *	ti,
		asize_t	nbytes
	)

Define/redefine a stack variable.

Parameters

pfn	pointer to function
name	variable name, nullptr means autogenerate a name
off	offset of the stack variable in the frame. negative values denote local variables, positive - function arguments.
flags	variable type flags (byte_flag() for a byte variable, for example)
ti	additional type information (like offsets, structs, etc)
nbytes	number of bytes occupied by the variable

Returns: success

◆ build_stkvar_name()

idaman ssize_t ida_export build_stkvar_name	(	qstring *	buf,
		const func_t *	pfn,
		sval_t	v
	)

Build automatic stack variable name.

Parameters

buf	pointer to buffer
pfn	pointer to function (can't be nullptr!)
v	value of variable offset

Returns: length of stack variable name or -1

◆ calc_stkvar_struc_offset()

idaman ea_t ida_export calc_stkvar_struc_offset	(	func_t *	pfn,
		const insn_t &	insn,
		int	n
	)

Calculate offset of stack variable in the frame structure.

Parameters

pfn	pointer to function (can't be nullptr!)
insn	the instruction
n	number of operand: (0..UA_MAXOP-1) -1 if error, return BADADDR

Returns: BADADDR if some error (issue a warning if stack frame is bad)

◆ delete_wrong_frame_info()

idaman int ida_export delete_wrong_frame_info	(	func_t *	pfn,
		bool idaapi	should_reanalyzeconst insn_t &insn
	)

Find and delete wrong frame info.

Namely, we delete:

unreferenced stack variable definitions
references to dead stack variables (i.e. operands displayed in red) these operands will be untyped and most likely displayed in hex. We also plan to reanalyze instruction with the stack frame references
Parameters

pfn pointer to the function

should_reanalyze callback to determine which instructions to reanalyze

Returns
number of deleted definitions

◆ add_regvar()

idaman int ida_export add_regvar	(	func_t *	pfn,
		ea_t	ea1,
		ea_t	ea2,
		const char *	canon,
		const char *	user,
		const char *	cmt
	)

Define a register variable.

Parameters

pfn	function in which the definition will be created
ea1,ea2	range of addresses within the function where the definition will be used
canon	name of a general register
user	user-defined name for the register
cmt	comment for the definition

Returns: Register variable error codes

◆ find_regvar() [1/2]

idaman regvar_t *ida_export find_regvar	(	func_t *	pfn,
		ea_t	ea1,
		ea_t	ea2,
		const char *	canon,
		const char *	user
	)

Find a register variable definition (powerful version).

One of 'canon' and 'user' should be nullptr. If both 'canon' and 'user' are nullptr it returns the first regvar definition in the range.

Parameters

pfn	function in question
ea1,ea2	range of addresses to search. ea1==BADADDR means the entire function
canon	name of a general register
user	user-defined name for the register

Returns: nullptr-not found, otherwise ptr to regvar_t

◆ find_regvar() [2/2]

regvar_t * find_regvar	(	func_t *	pfn,
		ea_t	ea,
		const char *	canon
	)

inline

Find a register variable definition.

Parameters

pfn	function in question
ea	current address
canon	name of a general register

Returns: nullptr-not found, otherwise ptr to regvar_t

◆ has_regvar()

bool has_regvar	(	func_t *	pfn,
		ea_t	ea
	)

inline

Is there a register variable definition?

Parameters

pfn	function in question
ea	current address

◆ rename_regvar()

idaman int ida_export rename_regvar	(	func_t *	pfn,
		regvar_t *	v,
		const char *	user
	)

Rename a register variable.

Parameters

pfn	function in question
v	variable to rename
user	new user-defined name for the register

Returns: Register variable error codes

◆ set_regvar_cmt()

idaman int ida_export set_regvar_cmt	(	func_t *	pfn,
		regvar_t *	v,
		const char *	cmt
	)

Set comment for a register variable.

Parameters

pfn	function in question
v	variable to rename
cmt	new comment

Returns: Register variable error codes

◆ del_regvar()

idaman int ida_export del_regvar	(	func_t *	pfn,
		ea_t	ea1,
		ea_t	ea2,
		const char *	canon
	)

Delete a register variable definition.

Parameters

pfn	function in question
ea1,ea2	range of addresses within the function where the definition holds
canon	name of a general register

Returns: Register variable error codes

◆ add_auto_stkpnt()

idaman bool ida_export add_auto_stkpnt	(	func_t *	pfn,
		ea_t	ea,
		sval_t	delta
	)

Add automatic SP register change point.

Parameters

pfn	pointer to function. may be nullptr.
ea	linear address where SP changes. usually this is the end of the instruction which modifies the stack pointer ( insn_t::ea+ insn_t::size)
delta	difference between old and new values of SP

Returns: success

◆ add_user_stkpnt()

idaman bool ida_export add_user_stkpnt	(	ea_t	ea,
		sval_t	delta
	)

Add user-defined SP register change point.

Parameters

ea	linear address where SP changes
delta	difference between old and new values of SP

Returns: success

◆ del_stkpnt()

idaman bool ida_export del_stkpnt	(	func_t *	pfn,
		ea_t	ea
	)

Delete SP register change point.

Parameters

pfn	pointer to function. may be nullptr.
ea	linear address

Returns: success

◆ get_spd()

idaman sval_t ida_export get_spd	(	func_t *	pfn,
		ea_t	ea
	)

Get difference between the initial and current values of ESP.

Parameters

pfn	pointer to function. may be nullptr.
ea	linear address of an instruction

Returns: 0 or the difference, usually a negative number. returns the sp-diff before executing the instruction.

◆ get_effective_spd()

idaman sval_t ida_export get_effective_spd	(	func_t *	pfn,
		ea_t	ea
	)

Get effective difference between the initial and current values of ESP.

This function returns the sp-diff used by the instruction. The difference between get_spd() and get_effective_spd() is present only for instructions like "pop [esp+N]": they modify sp and use the modified value.

Parameters

pfn	pointer to function. may be nullptr.
ea	linear address

Returns: 0 or the difference, usually a negative number

◆ get_sp_delta()

idaman sval_t ida_export get_sp_delta	(	func_t *	pfn,
		ea_t	ea
	)

Get modification of SP made at the specified location.

Parameters

pfn	pointer to function. may be nullptr.
ea	linear address

Returns: 0 if the specified location doesn't contain a SP change point. otherwise return delta of SP modification.

◆ recalc_spd()

idaman bool ida_export recalc_spd ( ea_t cur_ea )

Recalculate SP delta for an instruction that stops execution.

The next instruction is not reached from the current instruction. We need to recalculate SP for the next instruction.

This function will create a new automatic SP register change point if necessary. It should be called from the emulator (emu.cpp) when auto_state == AU_USED if the current instruction doesn't pass the execution flow to the next instruction.

Parameters

cur_ea linear address of the current instruction

Return values

1	new stkpnt is added
0	nothing is changed

◆ build_stkvar_xrefs()

idaman void ida_export build_stkvar_xrefs	(	xreflist_t *	out,
		func_t *	pfn,
		const member_t *	mptr
	)

Fill 'out' with a list of all the xrefs made from function 'pfn', to the argument or variable 'mptr' in 'pfn's stack frame.

Parameters

out	the list of xrefs to fill.
pfn	the function to scan.
mptr	the argument/variable in pfn's stack frame.

pfn	pointer to the function
should_reanalyze	callback to determine which instructions to reanalyze

IDA SDK: frame.hpp File Reference

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ STKVAR_VALID_SIZE

Function Documentation

◆ add_frame()

◆ del_frame()

◆ set_frame_size()

◆ get_frame_size()

◆ get_frame_retsize()

◆ get_frame_part()

◆ get_frame() [1/2]

◆ get_frame() [2/2]

◆ soff_to_fpoff()

◆ update_fpd()

◆ set_purged()

◆ get_func_by_frame()

◆ get_stkvar()

◆ add_stkvar()

◆ define_stkvar()

◆ build_stkvar_name()

◆ calc_stkvar_struc_offset()

◆ delete_wrong_frame_info()

◆ add_regvar()

◆ find_regvar() [1/2]

◆ find_regvar() [2/2]

◆ has_regvar()

◆ rename_regvar()

◆ set_regvar_cmt()

◆ del_regvar()

◆ add_auto_stkpnt()

◆ add_user_stkpnt()

◆ del_stkpnt()

◆ get_spd()

◆ get_effective_spd()

◆ get_sp_delta()

◆ recalc_spd()

◆ build_stkvar_xrefs()