Module ida_frame

IDA Plugin SDK API wrapper: frame

Classes
	llabel_t Proxy of C++ llabel_t class.
	regvar_t Proxy of C++ regvar_t class.
	stkpnt_t Proxy of C++ stkpnt_t class.
	stkpnts_t Proxy of C++ stkpnts_t class.
	xreflist_entry_t Proxy of C++ xreflist_entry_t class.
	xreflist_t Proxy of C++ qvector< xreflist_entry_t > class.

Functions

bool

add_auto_stkpnt(pfn, ea, delta)
Add automatic SP register change point.

bool

add_frame(pfn, frsize, frregs, argsize)
Add function frame.

int

add_regvar(pfn, ea1, ea2, canon, user, cmt)
Define a register variable.

bool

add_user_stkpnt(ea, delta)
Add user-defined SP register change point.

str

build_stkvar_name(pfn, v)
Build automatic stack variable name.

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

calc_stkvar_struc_offset(pfn, insn, n)
Calculate offset of stack variable in the frame structure.

bool

define_stkvar(pfn, name, off, flags, ti, nbytes)
Define/redefine a stack variable.

bool

del_frame(pfn)
Delete a function frame.

int

del_regvar(pfn, ea1, ea2, canon)
Delete a register variable definition.

bool

del_stkpnt(pfn, ea)
Delete SP register change point.

int

delete_unreferenced_stkvars(pfn)

int

delete_wrong_stkvar_ops(pfn)

regvar_t

find_regvar(pfn, ea1, ea2, canon, user)
find_regvar(pfn, ea, canon) -> regvar_t

ea_t

frame_off_args(pfn)
Get starting address of arguments section.

ea_t

frame_off_lvars(pfn)
Get start address of local variables section.

ea_t

frame_off_retaddr(pfn)
Get starting address of return address section.

ea_t

frame_off_savregs(pfn)
Get starting address of saved registers section.

sval_t

get_effective_spd(pfn, ea)
Get effective difference between the initial and current values of ESP.

struc_t

get_frame(pfn)
get_frame(ea) -> struc_t *

get_frame_part(range, pfn, part)
Get offsets of the frame part in the frame.

int

get_frame_retsize(pfn)
Get size of function return address.

asize_t

get_frame_size(pfn)
Get full size of a function frame.

ea_t

get_func_by_frame(frame_id)
Get function by its frame id.this function works only with databases created by IDA > 5.6

ea_t

get_min_spd_ea(pfn)

sval_t

get_sp_delta(pfn, ea)
Get modification of SP made at the specified location

sval_t

get_spd(pfn, ea)
Get difference between the initial and current values of ESP.

PyObject *

get_stkvar(insn, op, v)
Get pointer to stack variable

bool

has_regvar(pfn, ea)
Is there a register variable definition?

bool

is_funcarg_off(pfn, frameoff)
Does the given offset lie within the arguments section?

sval_t

lvar_off(pfn, frameoff)
Does the given offset lie within the local variables section?

bool

recalc_spd(cur_ea)
Recalculate SP delta for an instruction that stops execution.

int

rename_regvar(pfn, v, user)
Rename a register variable.

bool

set_frame_size(pfn, frsize, frregs, argsize)
Set size of function frame.

bool

set_purged(ea, nbytes, override_old_value)
Set the number of purged bytes for a function or data item (funcptr).

int

set_regvar_cmt(pfn, v, cmt)
Set comment for a register variable.

sval_t

soff_to_fpoff(pfn, soff)
Convert struct offsets into fp-relative offsets.

bool

update_fpd(pfn, fpd)
Update frame pointer delta.

Variables
	FPC_ARGS = `0`
	FPC_LVARS = `3`
	FPC_RETADDR = `1`
	FPC_SAVREGS = `2`
	REGVAR_ERROR_ARG = `-1`
	REGVAR_ERROR_NAME = `-3`
	REGVAR_ERROR_OK = `0`
	REGVAR_ERROR_RANGE = `-2`
	STKVAR_VALID_SIZE = `1`
	SWIG_PYTHON_LEGACY_BOOL = `1`
	__package__ = `None`

Function Details

add_auto_stkpnt(pfn, ea, delta)

Add automatic SP register change point.

Parameters:

pfn - pointer to function. may be NULL. (C++: func_t *)
ea - linear address where SP changes. usually this is the end of the instruction which modifies the stack pointer (\cmd{ea}+\cmd{size}) (C++: ea_t)
delta - difference between old and new values of SP (C++: sval_t)

Returns: bool

success

add_frame(pfn, frsize, frregs, argsize)

Add function frame.

Parameters:

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

Returns: bool

add_regvar(pfn, ea1, ea2, canon, user, cmt)

Define a register variable.

Parameters:

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

Returns: int

add_user_stkpnt(ea, delta)

Add user-defined SP register change point.

Parameters:

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

Returns: bool

success

build_stkvar_name(pfn, v)

Build automatic stack variable name.

Parameters:

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

Returns: str

length of stack variable name or -1

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.

Parameters:

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

calc_stkvar_struc_offset(pfn, insn, n)

Calculate offset of stack variable in the frame structure.

Parameters:

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

Returns: ea_t

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

define_stkvar(pfn, name, off, flags, ti, nbytes)

Define/redefine a stack variable.

Parameters:

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

Returns: bool

success

del_frame(pfn)

Delete a function frame.

Parameters:

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

Returns: bool

success

del_regvar(pfn, ea1, ea2, canon)

Delete a register variable definition.

Parameters:

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

Returns: int

del_stkpnt(pfn, ea)

Delete SP register change point.

Parameters:

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

Returns: bool

success

find_regvar(pfn, ea1, ea2, canon, user)

find_regvar(pfn, ea, canon) -> regvar_t

Find a register variable definition (powerful version). One of 'canon' and 'user' should be NULL. If both 'canon' and 'user' are NULL it returns the first regvar definition in the range.

Parameters:

pfn - function in question (C++: func_t *)
ea1 - range of addresses to search. ea1==BADADDR means the entire function (C++: ea_t)
ea2 - range of addresses to search. ea1==BADADDR means the entire function (C++: ea_t)
canon - name of a general register (C++: const char *)
user - user-defined name for the register (C++: const char *)

Returns: regvar_t

NULL-not found, otherwise ptr to regvar_t

frame_off_args(pfn)

Get starting address of arguments section.

Parameters:

pfn, (C++ - const func_t *)

Returns: ea_t

frame_off_lvars(pfn)

Get start address of local variables section.

Parameters:

pfn, (C++ - const func_t *)

Returns: ea_t

frame_off_retaddr(pfn)

Get starting address of return address section.

Parameters:

pfn, (C++ - const func_t *)

Returns: ea_t

frame_off_savregs(pfn)

Get starting address of saved registers section.

Parameters:

pfn, (C++ - const func_t *)

Returns: ea_t

get_effective_spd(pfn, 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 NULL. (C++: func_t *)
ea - linear address (C++: ea_t)

Returns: sval_t

0 or the difference, usually a negative number

get_frame(pfn)

get_frame(ea) -> struc_t *

Get pointer to function frame.

Parameters:

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

Returns: struc_t

get_frame_part(range, pfn, 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 NULL (C++: range_t *)
pfn - pointer to function structure, can't be NULL (C++: const func_t *)
part - frame part (C++: frame_part_t)

get_frame_retsize(pfn)

Get size of function return address.

Parameters:

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

Returns: int

get_frame_size(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 NULL (C++: const func_t *)

Returns: asize_t

size of frame in bytes or zero

get_func_by_frame(frame_id)

Get function by its frame id.this function works only with databases created by IDA > 5.6

Parameters:

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

Returns: ea_t

start address of the function or BADADDR

get_sp_delta(pfn, ea)

Get modification of SP made at the specified location

Parameters:

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

Returns: sval_t

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

get_spd(pfn, ea)

Get difference between the initial and current values of ESP.

Parameters:

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

Returns: sval_t

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

get_stkvar(insn, op, v)

Get pointer to stack variable

Parameters:

op - reference to instruction operand
v - immediate value in the operand (usually op.addr)

Returns: PyObject *

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

has_regvar(pfn, ea)

Is there a register variable definition?

Parameters:

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

Returns: bool

is_funcarg_off(pfn, frameoff)

Does the given offset lie within the arguments section?

Parameters:

pfn, (C++ - const func_t *)
frameoff, (C++ - uval_t)

Returns: bool

lvar_off(pfn, frameoff)

Does the given offset lie within the local variables section?

Parameters:

pfn, (C++ - const func_t *)
frameoff, (C++ - uval_t)

Returns: sval_t

recalc_spd(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 (C++: ea_t)

Returns: bool

rename_regvar(pfn, v, user)

Rename a register variable.

Parameters:

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

Returns: int

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

Returns: bool

success

set_purged(ea, nbytes, 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 (C++: ea_t)
nbytes - number of purged bytes (C++: int)
override_old_value - may overwrite old information about purged bytes (C++: bool)

Returns: bool

success

set_regvar_cmt(pfn, v, cmt)

Set comment for a register variable.

Parameters:

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

Returns: int

soff_to_fpoff(pfn, soff)

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).

Parameters:

pfn, (C++ - func_t *)
soff, (C++ - uval_t)

Returns: sval_t

update_fpd(pfn, fpd)

Update frame pointer delta.

Parameters:

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

Returns: bool

success