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)

Classes
class	regvar_t
	Proxy of C++ regvar_t class. More...

class	stkpnt_t
	Proxy of C++ stkpnt_t class. More...

class	stkpnts_t
	Proxy of C++ stkpnts_t class. More...

class	xreflist_entry_t
	Proxy of C++ xreflist_entry_t class. More...

class	xreflist_t
	Proxy of C++ qvector< xreflist_entry_t > class. More...

Functions
"PyObject *"	get_stkvar (*args)
	get_stkvar(insn, op, v) -> (member_t, int) or None Get pointer to stack variable

"bool"	is_funcarg_off (*args)
	is_funcarg_off(pfn, frameoff) -> bool

"sval_t"	lvar_off (*args)
	lvar_off(pfn, frameoff) -> sval_t

"bool"	add_frame (*args)
	add_frame(pfn, frsize, frregs, argsize) -> bool Add function frame.

"bool"	del_frame (*args)
	del_frame(pfn) -> bool Delete a function frame.

"bool"	set_frame_size (*args)
	set_frame_size(pfn, frsize, frregs, argsize) -> bool Set size of function frame.

"asize_t"	get_frame_size (*args)
	get_frame_size(pfn) -> asize_t Get full size of a function frame.

"int"	get_frame_retsize (*args)
	get_frame_retsize(pfn) -> int Get size of function return address.

"void"	get_frame_part (*args)
	get_frame_part(range, pfn, part) Get offsets of the frame part in the frame.

"ea_t"	frame_off_args (*args)
	frame_off_args(pfn) -> ea_t Get starting address of arguments section.

"ea_t"	frame_off_retaddr (*args)
	frame_off_retaddr(pfn) -> ea_t Get starting address of return address section.

"ea_t"	frame_off_savregs (*args)
	frame_off_savregs(pfn) -> ea_t Get starting address of saved registers section.

"ea_t"	frame_off_lvars (*args)
	frame_off_lvars(pfn) -> ea_t Get start address of local variables section.

"struc_t *"	get_frame (*args)
	get_frame(pfn) -> struc_t * Get pointer to function frame.

"sval_t"	soff_to_fpoff (*args)
	soff_to_fpoff(pfn, soff) -> sval_t Convert struct offsets into fp-relative offsets.

"bool"	update_fpd (*args)
	update_fpd(pfn, fpd) -> bool Update frame pointer delta.

"bool"	set_purged (*args)
	set_purged(ea, nbytes, override_old_value) -> bool Set the number of purged bytes for a function or data item (funcptr).

"ea_t"	get_func_by_frame (*args)
	get_func_by_frame(frame_id) -> ea_t Get function by its frame id.

"member_t *"	get_frame_member_by_id (*args)
	get_frame_member_by_id(out_mname, out_fptr, mid) -> member_t * Check if the specified member id points to a frame member.

"bool"	define_stkvar (*args)
	define_stkvar(pfn, name, off, flags, ti, nbytes) -> bool Define/redefine a stack variable.

"qstring *"	build_stkvar_name (*args)
	build_stkvar_name(pfn, v) -> str Build automatic stack variable name.

"ea_t"	calc_stkvar_struc_offset (*args)
	calc_stkvar_struc_offset(pfn, insn, n) -> ea_t Calculate offset of stack variable in the frame structure.

"void"	free_regvar (*args)
	free_regvar(v)

"int"	add_regvar (*args)
	add_regvar(pfn, ea1, ea2, canon, user, cmt) -> int Define a register variable.

"regvar_t *"	find_regvar (*args)
	find_regvar(pfn, ea1, ea2, canon, user) -> regvar_t Find a register variable definition.

"bool"	has_regvar (*args)
	has_regvar(pfn, ea) -> bool Is there a register variable definition?

"int"	rename_regvar (*args)
	rename_regvar(pfn, v, user) -> int Rename a register variable.

"int"	set_regvar_cmt (*args)
	set_regvar_cmt(pfn, v, cmt) -> int Set comment for a register variable.

"int"	del_regvar (*args)
	del_regvar(pfn, ea1, ea2, canon) -> int Delete a register variable definition.

"bool"	add_auto_stkpnt (*args)
	add_auto_stkpnt(pfn, ea, delta) -> bool Add automatic SP register change point.

"bool"	add_user_stkpnt (*args)
	add_user_stkpnt(ea, delta) -> bool Add user-defined SP register change point.

"bool"	del_stkpnt (*args)
	del_stkpnt(pfn, ea) -> bool Delete SP register change point.

"sval_t"	get_spd (*args)
	get_spd(pfn, ea) -> sval_t Get difference between the initial and current values of ESP.

"sval_t"	get_effective_spd (*args)
	get_effective_spd(pfn, ea) -> sval_t Get effective difference between the initial and current values of ESP.

"sval_t"	get_sp_delta (*args)
	get_sp_delta(pfn, ea) -> sval_t Get modification of SP made at the specified location

"bool"	set_auto_spd (*args)
	set_auto_spd(pfn, ea, new_spd) -> bool Add such an automatic SP register change point so that at EA the new cumulative SP delta (that is, the difference between the initial and current values of SP) would be equal to NEW_SPD.

"bool"	recalc_spd (*args)
	recalc_spd(cur_ea) -> bool Recalculate SP delta for an instruction that stops execution.

"bool"	recalc_spd_for_basic_block (*args)

"void"	build_stkvar_xrefs (*args)
	build_stkvar_xrefs(out, pfn, 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.

"ea_t"	get_min_spd_ea (*args)
	get_min_spd_ea(pfn) -> ea_t

"int"	delete_unreferenced_stkvars (*args)
	delete_unreferenced_stkvars(pfn) -> int

"int"	delete_wrong_stkvar_ops (*args)
	delete_wrong_stkvar_ops(pfn) -> int

Variables
	FPC_ARGS = _ida_frame.FPC_ARGS

	FPC_RETADDR = _ida_frame.FPC_RETADDR

	FPC_SAVREGS = _ida_frame.FPC_SAVREGS

	FPC_LVARS = _ida_frame.FPC_LVARS

	STKVAR_VALID_SIZE = _ida_frame.STKVAR_VALID_SIZE

	REGVAR_ERROR_OK = _ida_frame.REGVAR_ERROR_OK

	REGVAR_ERROR_ARG = _ida_frame.REGVAR_ERROR_ARG

	REGVAR_ERROR_RANGE = _ida_frame.REGVAR_ERROR_RANGE

	REGVAR_ERROR_NAME = _ida_frame.REGVAR_ERROR_NAME

Function Documentation

◆ add_auto_stkpnt()

"bool" add_auto_stkpnt ( * args )

Parameters

pfn	(C++: func_t *) pointer to the function. may be nullptr.
ea	(C++: ea_t) 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	(C++: sval_t) difference between old and new values of SP

Returns: : success

◆ add_frame()

"bool" add_frame ( * args )

Parameters

pfn	(C++: func_t *) pointer to function structure
frsize	(C++: sval_t) size of function local variables
frregs	(C++: ushort) size of saved registers
argsize	(C++: asize_t) 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)

◆ add_regvar()

"int" add_regvar ( * args )

Parameters

pfn	(C++: func_t *) function in which the definition will be created
ea1	(C++: ea_t) ,ea2: range of addresses within the function where the definition will be used
canon	(C++: const char *) name of a general register
canon	(C++: const char *) name of a general register
user	(C++: const char *) user-defined name for the register
cmt	(C++: const char *) comment for the definition

Returns: : Register variable error codes

◆ add_user_stkpnt()

"bool" add_user_stkpnt ( * args )

Parameters

ea	(C++: ea_t) linear address where SP changes
delta	(C++: sval_t) difference between old and new values of SP

Returns: : success

◆ build_stkvar_name()

"qstring *" build_stkvar_name ( * args )

Parameters

pfn	(C++: const func_t *) pointer to function (can't be nullptr!)
v	(C++: sval_t) value of variable offset

Returns: : length of stack variable name or -1

◆ build_stkvar_xrefs()

"void" build_stkvar_xrefs ( * args )

Parameters

out	(C++: xreflist_t *) the list of xrefs to fill.
pfn	(C++: func_t *) the function to scan.
mptr	(C++: const member_t *) the argument/variable in pfn's stack frame.

◆ calc_stkvar_struc_offset()

"ea_t" calc_stkvar_struc_offset ( * args )

Parameters

pfn	(C++: func_t *) pointer to function (can't be nullptr!)
insn	(C++: const insn_t &) the instruction
n	(C++: int) 0..UA_MAXOP-1 operand number -1 if error, return BADADDR

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

◆ define_stkvar()

"bool" define_stkvar ( * args )

Parameters

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

Returns: : success

◆ del_frame()

"bool" del_frame ( * args )

Parameters

pfn	(C++: func_t *) pointer to function structure

Returns: : success

◆ del_regvar()

"int" del_regvar ( * args )

Parameters

pfn	(C++: func_t *) function in question
ea1	(C++: ea_t) ,ea2: range of addresses within the function where the definition holds
canon	(C++: const char *) name of a general register
canon	(C++: const char *) name of a general register

Returns: : Register variable error codes

◆ del_stkpnt()

"bool" del_stkpnt ( * args )

Parameters

pfn	(C++: func_t *) pointer to the function. may be nullptr.
ea	(C++: ea_t) linear address

Returns: : success

◆ delete_unreferenced_stkvars()

"int" delete_unreferenced_stkvars ( * args )

Parameters

pfn func_t *

◆ delete_wrong_stkvar_ops()

"int" delete_wrong_stkvar_ops ( * args )

Parameters

pfn func_t *

◆ find_regvar()

"regvar_t *" find_regvar ( * args )

Parameters

pfn	(C++: func_t *) function in question
ea1	ea_t
canon	(C++: const char *) name of a general register
canon	(C++: const char *) name of a general register
user	char const *

Returns: : nullptr-not found, otherwise ptr to regvar_t find_regvar(pfn, ea, canon) -> regvar_t

Parameters

pfn	func_t *
ea	ea_t
canon	char const *

◆ frame_off_args()

"ea_t" frame_off_args ( * args )

Parameters

pfn	(C++: const func_t ) func_t const

◆ frame_off_lvars()

"ea_t" frame_off_lvars ( * args )

Parameters

pfn	(C++: const func_t ) func_t const

◆ frame_off_retaddr()

"ea_t" frame_off_retaddr ( * args )

Parameters

pfn	(C++: const func_t ) func_t const

◆ frame_off_savregs()

"ea_t" frame_off_savregs ( * args )

Parameters

pfn	(C++: const func_t ) func_t const

◆ free_regvar()

"void" free_regvar ( * args )

Parameters

v	regvar_t *

◆ get_effective_spd()

"sval_t" get_effective_spd ( * args )

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	(C++: func_t *) pointer to the function. may be nullptr.
ea	(C++: ea_t) linear address

Returns: : 0 or the difference, usually a negative number

◆ get_frame()

"struc_t *" get_frame ( * args )

Parameters

pfn	func_t const *

◆ get_frame_member_by_id()

"member_t *" get_frame_member_by_id ( * args )

Parameters

out_mname	(C++: qstring *)
out_fptr	(C++: struc_t **)
mid	(C++: tid_t)

◆ get_frame_part()

"void" get_frame_part ( * args )

Parameters

range	(C++: range_t *) pointer to the output buffer with the frame part start/end(exclusive) offsets, can't be nullptr
pfn	(C++: const func_t *) pointer to function structure, can't be nullptr
part	(C++: frame_part_t) frame part

◆ get_frame_retsize()

"int" get_frame_retsize ( * args )

Parameters

pfn	(C++: const func_t *) pointer to function structure, can't be nullptr

◆ get_frame_size()

"asize_t" get_frame_size ( * args )

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	(C++: const func_t *) pointer to function structure, may be nullptr

Returns: : size of frame in bytes or zero

◆ get_func_by_frame()

"ea_t" get_func_by_frame ( * args )

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

Parameters

frame_id (C++: tid_t) id of the function frame

Returns: : start address of the function or BADADDR

◆ get_min_spd_ea()

"ea_t" get_min_spd_ea ( * args )

Parameters

pfn func_t *

◆ get_sp_delta()

"sval_t" get_sp_delta ( * args )

Parameters

pfn	(C++: func_t *) pointer to the function. may be nullptr.
ea	(C++: ea_t) linear address

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

◆ get_spd()

"sval_t" get_spd ( * args )

Parameters

pfn	(C++: func_t *) pointer to the function. may be nullptr.
ea	(C++: ea_t) linear address of the instruction

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

◆ get_stkvar()

"PyObject *" get_stkvar ( * args )

Parameters

insn	an ida_ua.insn_t, or an address (C++: const insn_t &)
op	reference to instruction operand
v	immediate value in the operand (usually op.addr)

Returns

: - None on failure

tuple(member_t, actval) where actval: actual value used to fetch stack variable

◆ has_regvar()

"bool" has_regvar ( * args )

Parameters

pfn	(C++: func_t *) function in question
ea	(C++: ea_t) current address

◆ is_funcarg_off()

"bool" is_funcarg_off ( * args )

Parameters

pfn	func_t const *
frameoff	uval_t

◆ lvar_off()

"sval_t" lvar_off ( * args )

Parameters

pfn	func_t const *
frameoff	uval_t

◆ recalc_spd()

"bool" recalc_spd ( * args )

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 (C++: ea_t) linear address of the current instruction

Return values

1	new stkpnt is added
0	nothing is changed

◆ recalc_spd_for_basic_block()

"bool" recalc_spd_for_basic_block ( * args )

recalc_spd_for_basic_block(pfn, cur_ea) -> bool
Recalculate SP delta for the current instruction. The typical code snippet to
calculate SP delta in a proc module is:

if ( may_trace_sp() && pfn != nullptr )
  if ( !recalc_spd_for_basic_block(pfn, insn.ea) )

trace_sp(pfn, insn);

where trace_sp() is a typical name for a function that emulates the SP change of
an instruction.

@param pfn: (C++: func_t *) pointer to the function
@param cur_ea: (C++: ea_t) linear address of the current instruction
@retval true: the cumulative SP delta is set
@retval false: the instruction at CUR_EA passes flow to the next instruction. SP
       delta must be set as a result of emulating the current
       instruction.

◆ rename_regvar()

"int" rename_regvar ( * args )

Parameters

pfn	(C++: func_t *) function in question
v	(C++: regvar_t *) variable to rename
user	(C++: const char *) new user-defined name for the register

Returns: : Register variable error codes

◆ set_auto_spd()

"bool" set_auto_spd ( * args )

Parameters

pfn	(C++: func_t *) pointer to the function. may be nullptr.
ea	(C++: ea_t) linear address of the instruction
new_spd	(C++: sval_t) new value of the cumulative SP delta

Returns: : success

◆ set_frame_size()

"bool" set_frame_size ( * args )

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	(C++: func_t *) pointer to function structure
frsize	(C++: asize_t) size of function local variables
frregs	(C++: ushort) size of saved registers
argsize	(C++: asize_t) size of function arguments that will be purged from the stack upon return

Returns: : success

◆ set_purged()

"bool" set_purged ( * args )

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	(C++: ea_t) address of the function of item
nbytes	(C++: int) number of purged bytes
override_old_value	(C++: bool) may overwrite old information about purged bytes

Returns: : success

◆ set_regvar_cmt()

"int" set_regvar_cmt ( * args )

Parameters

pfn	(C++: func_t *) function in question
v	(C++: regvar_t *) variable to rename
cmt	(C++: const char *) new comment

Returns: : Register variable error codes

◆ soff_to_fpoff()

"sval_t" soff_to_fpoff ( * args )

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

Parameters

pfn	(C++: func_t *)
soff	(C++: uval_t)

◆ update_fpd()

"bool" update_fpd ( * args )

Parameters

pfn	(C++: func_t *) pointer to function structure
fpd	(C++: asize_t) new fpd value. cannot be bigger than the local variable range size.

Returns: : success

Variable Documentation

◆ FPC_ARGS

FPC_ARGS = _ida_frame.FPC_ARGS

◆ FPC_LVARS

FPC_LVARS = _ida_frame.FPC_LVARS

◆ FPC_RETADDR

FPC_RETADDR = _ida_frame.FPC_RETADDR

◆ FPC_SAVREGS

FPC_SAVREGS = _ida_frame.FPC_SAVREGS

◆ REGVAR_ERROR_ARG

REGVAR_ERROR_ARG = _ida_frame.REGVAR_ERROR_ARG

◆ REGVAR_ERROR_NAME

REGVAR_ERROR_NAME = _ida_frame.REGVAR_ERROR_NAME

◆ REGVAR_ERROR_OK

REGVAR_ERROR_OK = _ida_frame.REGVAR_ERROR_OK

◆ REGVAR_ERROR_RANGE

REGVAR_ERROR_RANGE = _ida_frame.REGVAR_ERROR_RANGE

◆ STKVAR_VALID_SIZE

STKVAR_VALID_SIZE = _ida_frame.STKVAR_VALID_SIZE

Detailed Description

Classes

Functions

Variables

Function Documentation

◆ add_auto_stkpnt()

◆ add_frame()

◆ add_regvar()

◆ add_user_stkpnt()

◆ build_stkvar_name()

◆ build_stkvar_xrefs()

◆ calc_stkvar_struc_offset()

◆ define_stkvar()

◆ del_frame()

◆ del_regvar()

◆ del_stkpnt()

◆ delete_unreferenced_stkvars()

◆ delete_wrong_stkvar_ops()

◆ find_regvar()

◆ frame_off_args()

◆ frame_off_lvars()

◆ frame_off_retaddr()

◆ frame_off_savregs()

◆ free_regvar()

◆ get_effective_spd()

◆ get_frame()

◆ get_frame_member_by_id()

◆ get_frame_part()

◆ get_frame_retsize()

◆ get_frame_size()

◆ get_func_by_frame()

◆ get_min_spd_ea()

◆ get_sp_delta()

◆ get_spd()

◆ get_stkvar()

◆ has_regvar()

◆ is_funcarg_off()

◆ lvar_off()

◆ recalc_spd()

◆ recalc_spd_for_basic_block()

◆ rename_regvar()

◆ set_auto_spd()

◆ set_frame_size()

◆ set_purged()

◆ set_regvar_cmt()

◆ soff_to_fpoff()

◆ update_fpd()

Variable Documentation

◆ FPC_ARGS

◆ FPC_LVARS

◆ FPC_RETADDR

◆ FPC_SAVREGS

◆ REGVAR_ERROR_ARG

◆ REGVAR_ERROR_NAME

◆ REGVAR_ERROR_OK

◆ REGVAR_ERROR_RANGE

◆ STKVAR_VALID_SIZE