ida_frame Namespace Reference

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 and stack variables, use:
* tinfo_t::get_func_frame(const func_t *pfn) (the preferred way)
* get_func_frame(tinfo_t *out, const func_t *pfn)
* tinfo_t::get_udt_details() gives info about stack variables: their type, names, offset, etc 

Classes
class	regvar_t
class	stkpnt_t
class	stkpnts_t
class	xreflist_entry_t
class	xreflist_t

Functions
bool	is_funcarg_off ('func_t const *' pfn, int frameoff)
int	lvar_off ('func_t const *' pfn, int frameoff)
bool	add_frame ('func_t *' pfn, int frsize, 'ushort' frregs, 'asize_t' argsize)
bool	del_frame ('func_t *' pfn)
bool	set_frame_size ('func_t *' pfn, 'asize_t' frsize, 'ushort' frregs, 'asize_t' argsize)
'asize_t'	get_frame_size ('func_t const *' pfn)
int	get_frame_retsize ('func_t const *' pfn)
None	get_frame_part ('range_t' range, 'func_t const *' pfn, 'frame_part_t' part)
ida_idaapi.ea_t	frame_off_args ('func_t const *' pfn)
ida_idaapi.ea_t	frame_off_retaddr ('func_t const *' pfn)
ida_idaapi.ea_t	frame_off_savregs ('func_t const *' pfn)
ida_idaapi.ea_t	frame_off_lvars ('func_t const *' pfn)
bool	get_func_frame ('tinfo_t' out, 'func_t const *' pfn)
int	soff_to_fpoff ('func_t *' pfn, int soff)
bool	update_fpd ('func_t *' pfn, 'asize_t' fpd)
bool	set_purged (ida_idaapi.ea_t ea, int nbytes, bool override_old_value)
bool	define_stkvar ('func_t *' pfn, str name, int off, 'tinfo_t' tif, 'value_repr_t' repr=None)
bool	add_frame_member ('func_t const *' pfn, str name, int offset, 'tinfo_t' tif, 'value_repr_t' repr=None, 'uint' etf_flags=0)
bool	is_anonymous_member_name (str name)
bool	is_dummy_member_name (str name)
bool	is_special_frame_member ('tid_t' tid)
bool	set_frame_member_type ('func_t const *' pfn, int offset, 'tinfo_t' tif, 'value_repr_t' repr=None, 'uint' etf_flags=0)
bool	delete_frame_members ('func_t const *' pfn, int start_offset, int end_offset)
str	build_stkvar_name ('func_t const *' pfn, int v)
ida_idaapi.ea_t	calc_stkvar_struc_offset ('func_t *' pfn, 'insn_t const &' insn, int n)
int	calc_frame_offset ('func_t *' pfn, int off, 'insn_t const *' insn=None, 'op_t const *' op=None)
None	free_regvar ('regvar_t' v)
int	add_regvar ('func_t *' pfn, ida_idaapi.ea_t ea1, ida_idaapi.ea_t ea2, str canon, str user, str cmt)
'regvar_t *'	find_regvar (*args)
bool	has_regvar ('func_t *' pfn, ida_idaapi.ea_t ea)
int	rename_regvar ('func_t *' pfn, 'regvar_t' v, str user)
int	set_regvar_cmt ('func_t *' pfn, 'regvar_t' v, str cmt)
int	del_regvar ('func_t *' pfn, ida_idaapi.ea_t ea1, ida_idaapi.ea_t ea2, str canon)
bool	add_auto_stkpnt ('func_t *' pfn, ida_idaapi.ea_t ea, int delta)
bool	add_user_stkpnt (ida_idaapi.ea_t ea, int delta)
bool	del_stkpnt ('func_t *' pfn, ida_idaapi.ea_t ea)
int	get_spd ('func_t *' pfn, ida_idaapi.ea_t ea)
int	get_effective_spd ('func_t *' pfn, ida_idaapi.ea_t ea)
int	get_sp_delta ('func_t *' pfn, ida_idaapi.ea_t ea)
bool	set_auto_spd ('func_t *' pfn, ida_idaapi.ea_t ea, int new_spd)
bool	recalc_spd (ida_idaapi.ea_t cur_ea)
bool	recalc_spd_for_basic_block ('func_t *' pfn, ida_idaapi.ea_t cur_ea)
None	build_stkvar_xrefs ('xreflist_t' out, 'func_t *' pfn, int start_offset, int end_offset)

Variables
	FRAME_UDM_NAME_R = _ida_frame.FRAME_UDM_NAME_R
	FRAME_UDM_NAME_S = _ida_frame.FRAME_UDM_NAME_S
	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	(	'func_t *'	pfn,
		ida_idaapi.ea_t	ea,
		int	delta )

Add automatic SP register change point. 
    
@param pfn: pointer to the function. may be nullptr.
@param 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)
@param delta: difference between old and new values of SP
@returns success

add_frame()

bool add_frame	(	'func_t *'	pfn,
		int	frsize,
		'ushort'	frregs,
		'asize_t'	argsize )

Add function frame. 
    
@param pfn: pointer to function structure
@param frsize: size of function local variables
@param frregs: size of saved registers
@param 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.
@retval 1: ok
@retval 0: failed (no function, frame already exists)

add_frame_member()

bool add_frame_member	(	'func_t const *'	pfn,
		str	name,
		int	offset,
		'tinfo_t'	tif,
		'value_repr_t'	repr = None,
		'uint'	etf_flags = 0 )

Add member to the frame type 
    
@param pfn: pointer to function
@param name: variable name, nullptr means autogenerate a name
@param offset: member offset in the frame structure, in bytes
@param tif: variable type
@param repr: variable representation
@returns success

add_regvar()

int add_regvar	(	'func_t *'	pfn,
		ida_idaapi.ea_t	ea1,
		ida_idaapi.ea_t	ea2,
		str	canon,
		str	user,
		str	cmt )

Define a register variable. 
    
@param pfn: function in which the definition will be created
@param ea1: range of addresses within the function where the definition will be used
@param ea2: range of addresses within the function where the definition will be used
@param canon: name of a general register
@param user: user-defined name for the register
@param cmt: comment for the definition
@returns Register variable error codes

add_user_stkpnt()

bool add_user_stkpnt	(	ida_idaapi.ea_t	ea,
		int	delta )

Add user-defined SP register change point. 
    
@param ea: linear address where SP changes
@param delta: difference between old and new values of SP
@returns success

build_stkvar_name()

str build_stkvar_name	(	'func_t const *'	pfn,
		int	v )

Build automatic stack variable name. 
    
@param pfn: pointer to function (can't be nullptr!)
@param v: value of variable offset
@returns length of stack variable name or -1

build_stkvar_xrefs()

None build_stkvar_xrefs	(	'xreflist_t'	out,
		'func_t *'	pfn,
		int	start_offset,
		int	end_offset )

Fill 'out' with a list of all the xrefs made from function 'pfn' to specified range of the pfn's stack frame. 
    
@param out: the list of xrefs to fill.
@param pfn: the function to scan.
@param start_offset: start frame structure offset, in bytes
@param end_offset: end frame structure offset, in bytes

calc_frame_offset()

int calc_frame_offset	(	'func_t *'	pfn,
		int	off,
		'insn_t const *'	insn = None,
		'op_t const *'	op = None )

Calculate the offset of stack variable in the frame. 
    
@param pfn: pointer to function (cannot be nullptr)
@param off: the offset relative to stack pointer or frame pointer
@param insn: the instruction
@param op: the operand
@returns the offset in the frame

calc_stkvar_struc_offset()

ida_idaapi.ea_t calc_stkvar_struc_offset	(	'func_t *'	pfn,
		'insn_t const &'	insn,
		int	n )

Calculate offset of stack variable in the frame structure. 
    
@param pfn: pointer to function (cannot be nullptr)
@param insn: the instruction
@param n: 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	(	'func_t *'	pfn,
		str	name,
		int	off,
		'tinfo_t'	tif,
		'value_repr_t'	repr = None )

Define/redefine a stack variable. 
    
@param pfn: pointer to function
@param name: variable name, nullptr means autogenerate a name
@param off: offset of the stack variable in the frame. negative values denote local variables, positive - function arguments.
@param tif: variable type
@param repr: variable representation
@returns success

del_frame()

bool del_frame

(

'func_t *'

pfn

)

Delete a function frame. 
    
@param pfn: pointer to function structure
@returns success

del_regvar()

int del_regvar	(	'func_t *'	pfn,
		ida_idaapi.ea_t	ea1,
		ida_idaapi.ea_t	ea2,
		str	canon )

Delete a register variable definition. 
    
@param pfn: function in question
@param ea1: range of addresses within the function where the definition holds
@param ea2: range of addresses within the function where the definition holds
@param canon: name of a general register
@returns Register variable error codes

del_stkpnt()

bool del_stkpnt	(	'func_t *'	pfn,
		ida_idaapi.ea_t	ea )

Delete SP register change point. 
    
@param pfn: pointer to the function. may be nullptr.
@param ea: linear address
@returns success

delete_frame_members()

bool delete_frame_members	(	'func_t const *'	pfn,
		int	start_offset,
		int	end_offset )

Delete frame members 
    
@param pfn: pointer to function
@param start_offset: member offset to start deletion from, in bytes
@param end_offset: member offset which not included in the deletion, in bytes
@returns success

find_regvar()

'regvar_t *' find_regvar

(

*

args

)

This function has the following signatures:

0. find_regvar(pfn: func_t *, ea1: ida_idaapi.ea_t, ea2: ida_idaapi.ea_t, canon: str, user: str) -> regvar_t *
1. find_regvar(pfn: func_t *, ea: ida_idaapi.ea_t, canon: str) -> regvar_t *

# 0: find_regvar(pfn: func_t *, ea1: ida_idaapi.ea_t, ea2: ida_idaapi.ea_t, canon: str, user: str) -> regvar_t *

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. 
    
@returns nullptr-not found, otherwise ptr to regvar_t

# 1: find_regvar(pfn: func_t *, ea: ida_idaapi.ea_t, canon: str) -> regvar_t *

Find a register variable definition. 
    
@returns nullptr-not found, otherwise ptr to regvar_t

frame_off_args()

ida_idaapi.ea_t frame_off_args

(

'func_t const *'

pfn

)

Get starting address of arguments section.

frame_off_lvars()

ida_idaapi.ea_t frame_off_lvars

(

'func_t const *'

pfn

)

Get start address of local variables section.

frame_off_retaddr()

ida_idaapi.ea_t frame_off_retaddr

(

'func_t const *'

pfn

)

Get starting address of return address section.

frame_off_savregs()

ida_idaapi.ea_t frame_off_savregs

(

'func_t const *'

pfn

)

Get starting address of saved registers section.

free_regvar()

None free_regvar

(

'regvar_t'

v

)

get_effective_spd()

int get_effective_spd	(	'func_t *'	pfn,
		ida_idaapi.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. 
    
@param pfn: pointer to the function. may be nullptr.
@param ea: linear address
@returns 0 or the difference, usually a negative number

get_frame_part()

None get_frame_part	(	'range_t'	range,
		'func_t const *'	pfn,
		'frame_part_t'	part )

Get offsets of the frame part in the frame. 
    
@param range: pointer to the output buffer with the frame part start/end(exclusive) offsets, can't be nullptr
@param pfn: pointer to function structure, can't be nullptr
@param part: frame part

get_frame_retsize()

int get_frame_retsize

(

'func_t const *'

pfn

)

Get size of function return address. 
    
@param pfn: pointer to function structure, can't be nullptr

get_frame_size()

'asize_t' get_frame_size

(

'func_t const *'

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. 
    
@param pfn: pointer to function structure, may be nullptr
@returns size of frame in bytes or zero

get_func_frame()

bool get_func_frame	(	'tinfo_t'	out,
		'func_t const *'	pfn )

Get type of function frame 
    
@param out: type info
@param pfn: pointer to function structure
@returns success

get_sp_delta()

int get_sp_delta	(	'func_t *'	pfn,
		ida_idaapi.ea_t	ea )

Get modification of SP made at the specified location 
    
@param pfn: pointer to the function. may be nullptr.
@param ea: linear address
@returns 0 if the specified location doesn't contain a SP change point. otherwise return delta of SP modification.

get_spd()

int get_spd	(	'func_t *'	pfn,
		ida_idaapi.ea_t	ea )

Get difference between the initial and current values of ESP. 
    
@param pfn: pointer to the function. may be nullptr.
@param ea: linear address of the instruction
@returns 0 or the difference, usually a negative number. returns the sp-diff before executing the instruction.

has_regvar()

bool has_regvar	(	'func_t *'	pfn,
		ida_idaapi.ea_t	ea )

Is there a register variable definition? 
    
@param pfn: function in question
@param ea: current address

is_anonymous_member_name()

bool is_anonymous_member_name

(

str

name

)

Is member name prefixed with "anonymous"?

is_dummy_member_name()

bool is_dummy_member_name

(

str

name

)

Is member name an auto-generated name?

is_funcarg_off()

bool is_funcarg_off	(	'func_t const *'	pfn,
		int	frameoff )

is_special_frame_member()

bool is_special_frame_member

(

'tid_t'

tid

)

Is stkvar with TID the return address slot or the saved registers slot ? 
    
@param tid: frame member type id return address or saved registers member?

lvar_off()

int lvar_off	(	'func_t const *'	pfn,
		int	frameoff )

recalc_spd()

bool recalc_spd

(

ida_idaapi.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. 
    
@param cur_ea: linear address of the current instruction
@retval 1: new stkpnt is added
@retval 0: nothing is changed

recalc_spd_for_basic_block()

bool recalc_spd_for_basic_block	(	'func_t *'	pfn,
		ida_idaapi.ea_t	cur_ea )

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: pointer to the function
@param cur_ea: 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	(	'func_t *'	pfn,
		'regvar_t'	v,
		str	user )

Rename a register variable. 
    
@param pfn: function in question
@param v: variable to rename
@param user: new user-defined name for the register
@returns Register variable error codes

set_auto_spd()

bool set_auto_spd	(	'func_t *'	pfn,
		ida_idaapi.ea_t	ea,
		int	new_spd )

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. 
    
@param pfn: pointer to the function. may be nullptr.
@param ea: linear address of the instruction
@param new_spd: new value of the cumulative SP delta
@returns success

set_frame_member_type()

bool set_frame_member_type	(	'func_t const *'	pfn,
		int	offset,
		'tinfo_t'	tif,
		'value_repr_t'	repr = None,
		'uint'	etf_flags = 0 )

Change type of the frame member 
    
@param pfn: pointer to function
@param offset: member offset in the frame structure, in bytes
@param tif: variable type
@param repr: variable representation
@returns success

set_frame_size()

bool 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 frame.get_func_frame(pfn).get_size() 
    
@param pfn: pointer to function structure
@param frsize: size of function local variables
@param frregs: size of saved registers
@param argsize: size of function arguments that will be purged from the stack upon return
@returns success

set_purged()

bool set_purged	(	ida_idaapi.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. 
    
@param ea: address of the function of item
@param nbytes: number of purged bytes
@param override_old_value: may overwrite old information about purged bytes
@returns success

set_regvar_cmt()

int set_regvar_cmt	(	'func_t *'	pfn,
		'regvar_t'	v,
		str	cmt )

Set comment for a register variable. 
    
@param pfn: function in question
@param v: variable to rename
@param cmt: new comment
@returns Register variable error codes

soff_to_fpoff()

int soff_to_fpoff	(	'func_t *'	pfn,
		int	soff )

Convert struct offsets into fp-relative offsets. This function converts the offsets inside the udt_type_data_t object into the frame pointer offsets (for example, EBP-relative). 

update_fpd()

bool update_fpd	(	'func_t *'	pfn,
		'asize_t'	fpd )

Update frame pointer delta. 
    
@param pfn: pointer to function structure
@param fpd: 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

FRAME_UDM_NAME_R

FRAME_UDM_NAME_R = _ida_frame.FRAME_UDM_NAME_R

FRAME_UDM_NAME_S

FRAME_UDM_NAME_S = _ida_frame.FRAME_UDM_NAME_S

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