ida_frame

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

Tip

The IDA Domain API simplifies common tasks and provides better type hints, while remaining fully compatible with IDAPython for advanced use cases.

For function frame operations, see ida_domain.functions.

Attributes

`FRAME_UDM_NAME_R`
`FRAME_UDM_NAME_S`
`FPC_ARGS`
`FPC_RETADDR`
`FPC_SAVREGS`
`FPC_LVARS`
`STKVAR_VALID_SIZE`	x.dtype 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
`STKVAR_KEEP_EXISTING`	if a stack variable for this operand already exists then we do not create a new variable
`REGVAR_ERROR_OK`	all ok
`REGVAR_ERROR_ARG`	function arguments are bad
`REGVAR_ERROR_RANGE`	the definition range is bad
`REGVAR_ERROR_NAME`	the provided name(s) can't be accepted
`add_frame`
`del_frame`
`set_frame_size`
`get_frame_size`
`get_frame_retsize`
`get_frame_part`
`get_func_frame`
`soff_to_fpoff`
`update_fpd`
`define_stkvar`
`add_frame_member`
`set_frame_member_type`
`delete_frame_members`
`build_stkvar_name`
`calc_stkvar_struc_offset`
`calc_frame_offset`
`add_regvar`
`find_regvar`
`rename_regvar`
`set_regvar_cmt`
`del_regvar`
`has_regvar`
`add_auto_stkpnt`
`del_stkpnt`
`get_spd`
`get_effective_spd`
`get_sp_delta`
`set_auto_spd`
`recalc_spd_for_basic_block`
`build_stkvar_xrefs`
`frame_off_args`
`frame_off_retaddr`
`frame_off_savregs`
`frame_off_lvars`
`is_funcarg_off`
`lvar_off`

Classes

`stkpnts_template_t`
`xreflist_t`
`regvars_t`
`llabels_t`
`stkpnt_t`
`stkpnts_t`
`llabel_t`
`regvar_t`
`xreflist_entry_t`

Functions

`is_funcarg_off`
`lvar_off`
`is_funcarg_off_ea`(→ bool)
`lvar_off_ea`(→ int)
`add_frame`
`del_frame`
`set_frame_size`
`get_frame_size`
`get_frame_retsize`
`get_frame_part`
`get_func_frame`
`soff_to_fpoff`
`update_fpd`
`set_purged`(→ bool)	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.
`define_stkvar`
`add_frame_member`
`is_anonymous_member_name`(→ bool)	Is member name prefixed with "anonymous"?
`is_dummy_member_name`(→ bool)	Is member name an auto-generated name?
`is_special_frame_member`(→ bool)	Is stkvar with TID the return address slot or the saved registers slot ?
`set_frame_member_type`
`delete_frame_members`
`build_stkvar_name`
`calc_stkvar_struc_offset`
`calc_frame_offset`
`regvar_t__compare`(→ int)
`free_regvar`(→ None)
`add_regvar`
`find_regvar`
`rename_regvar`
`set_regvar_cmt`
`del_regvar`
`add_auto_stkpnt`
`add_user_stkpnt`(→ bool)	Add user-defined SP register change point.
`del_stkpnt`
`get_spd`
`get_effective_spd`
`get_sp_delta`
`set_auto_spd`
`recalc_spd`(→ bool)	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.
`recalc_spd_for_basic_block`
`build_stkvar_xrefs`
`add_frame_ea`(→ bool)	Add function frame.
`del_frame_ea`(→ bool)	Delete a function frame.
`set_frame_size_ea`(→ bool)	Set size of function frame.
`get_frame_size_ea`(→ asize_t)	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.
`get_frame_retsize_ea`(→ int)	Get size of function return address.
`get_frame_part_ea`(→ bool)	Get offsets of the frame part in the frame.
`frame_off_args_ea`(→ ida_idaapi.ea_t)	Get starting address of arguments section
`frame_off_retaddr_ea`(→ ida_idaapi.ea_t)	Get starting address of return address section
`frame_off_savregs_ea`(→ ida_idaapi.ea_t)	Get starting address of saved registers section
`frame_off_lvars_ea`(→ ida_idaapi.ea_t)	Get start address of local variables section
`frame_off_args`
`frame_off_retaddr`
`frame_off_savregs`
`frame_off_lvars`
`get_func_frame_ea`(→ bool)	Get type of function frame
`soff_to_fpoff_ea`(→ int)	Convert struct offsets into fp-relative offsets.
`update_fpd_ea`(→ bool)	Update frame pointer delta.
`define_stkvar_ea`(→ bool)	Define/redefine a stack variable.
`add_frame_member_ea`(→ bool)	Add member to the frame type
`set_frame_member_type_ea`(→ bool)	Change type of the frame member
`delete_frame_members_ea`(→ bool)	Delete frame members
`build_stkvar_name_ea`(→ Union[str, None])	Build automatic stack variable name.
`calc_stkvar_struc_offset_ea`(→ ida_idaapi.ea_t)	Calculate offset of stack variable in the frame structure.
`calc_frame_offset_ea`(→ int)	Calculate the offset of stack variable in the frame.
`delete_wrong_frame_info_ea`() → int)	Find and delete wrong frame info. Namely, we delete:
`build_stkvar_xrefs_ea`(→ None)	Fill 'out' with a list of all the xrefs from a function to the specified range of the function's stack frame.
`add_func_regvar`(→ int)	Define a register variable.
`find_func_regvar`(→ ssize_t)	This function has the following signatures:
`has_func_regvar`(→ bool)	Is there a register variable definition?
`has_regvar`
`rename_func_regvar`(→ int)	Rename a register variable.
`set_func_regvar_cmt`(→ int)	Set comment for a register variable.
`set_func_regvar_range`(→ int)	Update the address range of a register variable by index. Only the range is changed; to rename a regvar or change its comment use rename_func_regvar()/set_func_regvar_cmt(). The new range must be well-formed (start_ea < end_ea) and must keep the function's register variables sorted by start_ea.
`del_func_regvar`(→ int)	Delete a register variable definition.
`get_func_regvar_qty`(→ int)	Get the number of register variables for a function.
`get_func_regvars`(→ bool)	Get all register variables for a function.
`get_func_regvar`(→ bool)	Get a copy of a register variable by index.
`add_func_auto_stkpnt`(→ bool)	Add automatic SP register change point.
`del_func_stkpnt`(→ bool)	Delete SP register change point.
`get_func_spd`(→ int)	Get difference between the initial and current values of ESP.
`get_func_effective_spd`(→ int)	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_func_spd() and get_func_effective_spd() is present only for instructions like "pop [esp+N]": they modify sp and use the modified value.
`get_func_sp_delta`(→ int)	Get modification of SP made at the specified location
`set_func_auto_spd`(→ bool)	Set the cumulative SP delta at the given address.
`recalc_func_spd_for_basic_block`(→ bool)	Recalculate SP delta for the current instruction. The typical code snippet to calculate SP delta in a proc module is:
`get_func_stkpnt_qty`(→ int)	Get the number of SP change points for a function.
`get_func_stkpnts`(→ bool)	Get all SP change points for a function.
`get_func_llabel_qty`(→ int)	Get the number of local labels for a function.
`get_func_llabels`(→ bool)	Get all local labels for a function.

Module Contents

class ida_frame.stkpnts_template_t(*args)

Bases: object

thisown

push_back(*args) → stkpnt_t &

pop_back() → None

size() → int

empty() → bool

at(_idx: int) → stkpnt_t const &

qclear() → None

clear() → None

resize(*args) → None

grow(*args) → None

capacity() → int

reserve(cnt: int) → None

truncate() → None

swap(r: stkpnts_template_t) → None

extract() → stkpnt_t *

inject(s: stkpnt_t, len: int) → None

begin(*args) → qvector< stkpnt_t >::const_iterator

end(*args) → qvector< stkpnt_t >::const_iterator

insert(it: stkpnt_t, x: stkpnt_t) → qvector< stkpnt_t >::iterator

erase(*args) → qvector< stkpnt_t >::iterator

find(*args) → qvector< stkpnt_t >::const_iterator

has(x: stkpnt_t) → bool

add_unique(x: stkpnt_t) → bool

append(x: stkpnt_t) → None

extend(x: stkpnts_template_t) → None

front

back

class ida_frame.xreflist_t(*args)

Bases: object

thisown

push_back(*args) → xreflist_entry_t &

pop_back() → None

size() → int

empty() → bool

at(_idx: int) → xreflist_entry_t const &

qclear() → None

clear() → None

resize(*args) → None

grow(*args) → None

capacity() → int

reserve(cnt: int) → None

truncate() → None

swap(r: xreflist_t) → None

extract() → xreflist_entry_t *

inject(s: xreflist_entry_t, len: int) → None

begin(*args) → qvector< xreflist_entry_t >::const_iterator

end(*args) → qvector< xreflist_entry_t >::const_iterator

insert(it: xreflist_entry_t, x: xreflist_entry_t) → qvector< xreflist_entry_t >::iterator

erase(*args) → qvector< xreflist_entry_t >::iterator

find(*args) → qvector< xreflist_entry_t >::const_iterator

has(x: xreflist_entry_t) → bool

add_unique(x: xreflist_entry_t) → bool

append(x: xreflist_entry_t) → None

extend(x: xreflist_t) → None

front

back

class ida_frame.regvars_t(*args)

Bases: object

thisown

push_back(*args) → regvar_t &

pop_back() → None

size() → int

empty() → bool

at(_idx: int) → regvar_t const &

qclear() → None

clear() → None

resize(*args) → None

grow(*args) → None

capacity() → int

reserve(cnt: int) → None

truncate() → None

swap(r: regvars_t) → None

extract() → regvar_t *

inject(s: regvar_t, len: int) → None

begin(*args) → qvector< regvar_t >::const_iterator

end(*args) → qvector< regvar_t >::const_iterator

insert(it: regvar_t, x: regvar_t) → qvector< regvar_t >::iterator

erase(*args) → qvector< regvar_t >::iterator

find(*args) → qvector< regvar_t >::const_iterator

has(x: regvar_t) → bool

add_unique(x: regvar_t) → bool

append(x: regvar_t) → None

extend(x: regvars_t) → None

front

back

class ida_frame.llabels_t(*args)

Bases: object

thisown

push_back(*args) → llabel_t &

pop_back() → None

size() → int

empty() → bool

at(_idx: int) → llabel_t const &

qclear() → None

clear() → None

resize(*args) → None

grow(*args) → None

capacity() → int

reserve(cnt: int) → None

truncate() → None

swap(r: llabels_t) → None

extract() → llabel_t *

inject(s: llabel_t, len: int) → None

begin(*args) → qvector< llabel_t >::const_iterator

end(*args) → qvector< llabel_t >::const_iterator

insert(it: llabel_t, x: llabel_t) → qvector< llabel_t >::iterator

erase(*args) → qvector< llabel_t >::iterator

find(*args) → qvector< llabel_t >::const_iterator

has(x: llabel_t) → bool

add_unique(x: llabel_t) → bool

append(x: llabel_t) → None

extend(x: llabels_t) → None

front

back

ida_frame.is_funcarg_off(pfn: func_t const *, frameoff: int) → bool

ida_frame.lvar_off(pfn: func_t const *, frameoff: int) → int

ida_frame.is_funcarg_off_ea(ea: ida_idaapi.ea_t, frameoff: int) → bool

ida_frame.lvar_off_ea(ea: ida_idaapi.ea_t, frameoff: int) → int

ida_frame.FRAME_UDM_NAME_R

ida_frame.FRAME_UDM_NAME_S

class ida_frame.stkpnt_t

Bases: object

thisown

ea: ida_idaapi.ea_t

spd: int

compare(r: stkpnt_t) → int

class ida_frame.stkpnts_t

Bases: stkpnts_template_t

thisown

compare(r: stkpnts_t) → int

class ida_frame.llabel_t

Bases: object

thisown

ea: ida_idaapi.ea_t: linear address

name: str: label name

compare(r: llabel_t) → int

ida_frame.add_frame(pfn: func_t *, frsize: int, frregs: ushort, argsize: asize_t) → bool

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.

Returns:

1: ok

Returns:

0: failed (no function, frame already exists)

ida_frame.del_frame(pfn: func_t *) → bool

Delete a function frame.

Parameters:: pfn – pointer to function structure
Returns:: success

ida_frame.set_frame_size(pfn: func_t *, frsize: asize_t, frregs: ushort, argsize: asize_t) → bool

Set size of function frame.

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

ida_frame.get_frame_size(pfn: func_t const *) → asize_t

Get full size of a function frame.

Parameters:: pfn – pointer to function structure, may be nullptr
Returns:: size of frame in bytes or zero

ida_frame.get_frame_retsize(pfn: func_t const *) → int

Get size of function return address.

Parameters:: pfn – pointer to function structure, can’t be nullptr

ida_frame.FPC_ARGS

ida_frame.FPC_RETADDR

ida_frame.FPC_SAVREGS

ida_frame.FPC_LVARS

ida_frame.get_frame_part(range: range_t, pfn: func_t const *, part: frame_part_t) → None

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

ida_frame.get_func_frame(out: tinfo_t, pfn: func_t const *) → bool

Get type of function frame

Parameters:

out – type info
pfn – pointer to function structure

Returns:

success

ida_frame.soff_to_fpoff(pfn: func_t *, soff: int) → int: Convert struct offsets into fp-relative offsets.

ida_frame.update_fpd(pfn: func_t *, fpd: asize_t) → bool

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

ida_frame.set_purged(ea: ida_idaapi.ea_t, nbytes: int, override_old_value: bool) → bool

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

ida_frame.STKVAR_VALID_SIZE: x.dtype 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

ida_frame.STKVAR_KEEP_EXISTING: if a stack variable for this operand already exists then we do not create a new variable

ida_frame.define_stkvar(pfn: func_t *, name: str, off: int, tif: tinfo_t, repr: value_repr_t = None) → bool

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.
tif – variable type
repr – variable representation

Returns:

success

ida_frame.add_frame_member(pfn: func_t const *, name: str, offset: int, tif: tinfo_t, repr: value_repr_t = None, etf_flags: uint = 0) → bool

Add member to the frame type

Parameters:

pfn – pointer to function
name – variable name, nullptr means autogenerate a name
offset – member offset in the frame structure, in bytes
tif – variable type
repr – variable representation

Returns:

success

ida_frame.is_anonymous_member_name(name: str) → bool: Is member name prefixed with “anonymous”?

ida_frame.is_dummy_member_name(name: str) → bool: Is member name an auto-generated name?

ida_frame.is_special_frame_member(tid: tid_t) → bool

Is stkvar with TID the return address slot or the saved registers slot ?

Parameters:: tid – frame member type id return address or saved registers member?

ida_frame.set_frame_member_type(pfn: func_t const *, offset: int, tif: tinfo_t, repr: value_repr_t = None, etf_flags: uint = 0) → bool

Change type of the frame member

Parameters:

pfn – pointer to function
offset – member offset in the frame structure, in bytes
tif – variable type
repr – variable representation

Returns:

success

ida_frame.delete_frame_members(pfn: func_t const *, start_offset: int, end_offset: int) → bool

Delete frame members

Parameters:

pfn – pointer to function
start_offset – member offset to start deletion from, in bytes
end_offset – member offset which not included in the deletion, in bytes

Returns:

success

ida_frame.build_stkvar_name(pfn: func_t const *, v: int) → str | None

Build automatic stack variable name.

Parameters:

pfn – pointer to function (can’t be nullptr!)
v – value of variable offset

Returns:

length of stack variable name or -1

ida_frame.calc_stkvar_struc_offset(pfn: func_t *, insn: insn_t const &, n: int) → ida_idaapi.ea_t

Calculate offset of stack variable in the frame structure.

Parameters:

pfn – pointer to function (cannot be nullptr)
insn – the instruction
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)

ida_frame.calc_frame_offset(pfn: func_t *, off: int, insn: insn_t const * = None, op: op_t const * = None) → int

Calculate the offset of stack variable in the frame.

Parameters:

pfn – pointer to function (cannot be nullptr)
off – the offset relative to stack pointer or frame pointer
insn – the instruction
op – the operand

Returns:

the offset in the frame

ida_frame.regvar_t__compare(l: regvar_t, r: regvar_t) → int

ida_frame.free_regvar(v: regvar_t) → None

class ida_frame.regvar_t(*args)

Bases: ida_range.range_t

thisown

canon: char *: canonical register name (case-insensitive)

user: char *: user-defined register name

cmt: char *: comment to appear near definition

swap(r: regvar_t) → None

compare(r: regvar_t) → int

ida_frame.add_regvar(pfn: func_t *, ea1: ida_idaapi.ea_t, ea2: ida_idaapi.ea_t, canon: str, user: str, cmt: str) → int

Define a register variable.

Parameters:

pfn – function in which the definition will be created
ea1 – range of addresses within the function where the definition will be used
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

ida_frame.find_regvar(*args) → regvar_t *

This function has the following signatures:

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

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

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

Find a register variable definition (powerful version).

Returns:: nullptr-not found, otherwise ptr to regvar_t

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

Find a register variable definition.

Returns:: nullptr-not found, otherwise ptr to regvar_t

ida_frame.rename_regvar(pfn: func_t *, v: regvar_t, user: str) → int

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

ida_frame.set_regvar_cmt(pfn: func_t *, v: regvar_t, cmt: str) → int

Set comment for a register variable.

Parameters:

pfn – function in question
v – variable to rename
cmt – new comment

Returns:

Register variable error codes

ida_frame.del_regvar(pfn: func_t *, ea1: ida_idaapi.ea_t, ea2: ida_idaapi.ea_t, canon: str) → int

Delete a register variable definition.

Parameters:

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

Returns:

Register variable error codes

ida_frame.add_auto_stkpnt(pfn: func_t *, ea: ida_idaapi.ea_t, delta: int) → bool

Add automatic SP register change point.

Parameters:

pfn – pointer to the 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

ida_frame.add_user_stkpnt(ea: ida_idaapi.ea_t, delta: int) → bool

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

ida_frame.del_stkpnt(pfn: func_t *, ea: ida_idaapi.ea_t) → bool

Delete SP register change point.

Parameters:

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

Returns:

success

ida_frame.get_spd(pfn: func_t *, ea: ida_idaapi.ea_t) → int

Get difference between the initial and current values of ESP.

Parameters:

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

Returns:

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

ida_frame.get_effective_spd(pfn: func_t *, ea: ida_idaapi.ea_t) → int

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

Parameters:

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

Returns:

0 or the difference, usually a negative number

ida_frame.get_sp_delta(pfn: func_t *, ea: ida_idaapi.ea_t) → int

Get modification of SP made at the specified location

Parameters:

pfn – pointer to the 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.

ida_frame.set_auto_spd(pfn: func_t *, ea: ida_idaapi.ea_t, new_spd: int) → 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.

Parameters:

pfn – pointer to the function. may be nullptr.
ea – linear address of the instruction
new_spd – new value of the cumulative SP delta

Returns:

success

ida_frame.recalc_spd(cur_ea: ida_idaapi.ea_t) → bool

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
Returns:: 1: new stkpnt is added
Returns:: 0: nothing is changed

ida_frame.recalc_spd_for_basic_block(pfn: func_t *, cur_ea: ida_idaapi.ea_t) → bool

Recalculate SP delta for the current instruction.

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.

Parameters:

pfn – pointer to the function
cur_ea – linear address of the current instruction

Returns:

true: the cumulative SP delta is set

Returns:

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.

class ida_frame.xreflist_entry_t

Bases: object

thisown

ea: ida_idaapi.ea_t: Location of the insn referencing the stack frame member.

opnum: uchar: Number of the operand of that instruction.

type: uchar: The type of xref (cref_t & dref_t).

compare(r: xreflist_entry_t) → int

ida_frame.build_stkvar_xrefs(out: xreflist_t, pfn: func_t *, start_offset: int, end_offset: int) → None

Fill ‘out’ with a list of all the xrefs made from function ‘pfn’ to specified range of the pfn’s stack frame.

Parameters:

out – the list of xrefs to fill.
pfn – the function to scan.
start_offset – start frame structure offset, in bytes
end_offset – end frame structure offset, in bytes

ida_frame.add_frame_ea(func_ea: ida_idaapi.ea_t, frsize: int, frregs: ushort, argsize: asize_t) → bool

Add function frame.

Parameters:

func_ea – any address of the function
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.

Returns:

1: ok

Returns:

0: failed (no function at func_ea, frame already exists)

ida_frame.del_frame_ea(func_ea: ida_idaapi.ea_t) → bool

Delete a function frame.

Parameters:: func_ea – any address of the function
Returns:: success

ida_frame.set_frame_size_ea(func_ea: ida_idaapi.ea_t, frsize: asize_t, frregs: ushort, argsize: asize_t) → bool

Set size of function frame.

Parameters:

func_ea – any address of the function
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

ida_frame.get_frame_size_ea(func_ea: ida_idaapi.ea_t) → asize_t

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.

Parameters:: func_ea – any address of the function
Returns:: size of frame in bytes or zero

ida_frame.get_frame_retsize_ea(func_ea: ida_idaapi.ea_t) → int

Get size of function return address.

Parameters:: func_ea – any address of the function
Returns:: return address size or 0

ida_frame.get_frame_part_ea(range: range_t, func_ea: ida_idaapi.ea_t, part: frame_part_t) → bool

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
func_ea – any address of the function
part – frame part

Returns:

false if no function at func_ea

ida_frame.frame_off_args_ea(func_ea: ida_idaapi.ea_t) → ida_idaapi.ea_t

Get starting address of arguments section

Parameters:: func_ea – any address of the function
Returns:: offset in frame or BADADDR on failure

ida_frame.frame_off_retaddr_ea(func_ea: ida_idaapi.ea_t) → ida_idaapi.ea_t

Get starting address of return address section

Parameters:: func_ea – any address of the function
Returns:: offset in frame or BADADDR on failure

ida_frame.frame_off_savregs_ea(func_ea: ida_idaapi.ea_t) → ida_idaapi.ea_t

Get starting address of saved registers section

Parameters:: func_ea – any address of the function
Returns:: offset in frame or BADADDR on failure

ida_frame.frame_off_lvars_ea(func_ea: ida_idaapi.ea_t) → ida_idaapi.ea_t

Get start address of local variables section

Parameters:: func_ea – any address of the function
Returns:: offset in frame or BADADDR on failure

ida_frame.frame_off_args(pfn: func_t const *) → ida_idaapi.ea_t: Get starting address of arguments section

ida_frame.frame_off_retaddr(pfn: func_t const *) → ida_idaapi.ea_t: Get starting address of return address section

ida_frame.frame_off_savregs(pfn: func_t const *) → ida_idaapi.ea_t: Get starting address of saved registers section

ida_frame.frame_off_lvars(pfn: func_t const *) → ida_idaapi.ea_t: Get start address of local variables section

ida_frame.get_func_frame_ea(out: tinfo_t, func_ea: ida_idaapi.ea_t) → bool

Get type of function frame

Parameters:

out – type info
func_ea – any address of the function

Returns:

success

ida_frame.soff_to_fpoff_ea(func_ea: ida_idaapi.ea_t, soff: int) → int

Convert struct offsets into fp-relative offsets.

Parameters:

func_ea – any address of the function
soff – struct offset

Returns:

fp-relative offset, or soff if no function at func_ea

ida_frame.update_fpd_ea(func_ea: ida_idaapi.ea_t, fpd: asize_t) → bool

Update frame pointer delta.

Parameters:

func_ea – any address of the function
fpd – new fpd value. cannot be bigger than the local variable range size.

Returns:

success

ida_frame.define_stkvar_ea(func_ea: ida_idaapi.ea_t, name: str, off: int, tif: tinfo_t, repr: value_repr_t = None) → bool

Define/redefine a stack variable.

Parameters:

func_ea – any address of the 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.
tif – variable type
repr – variable representation

Returns:

success

ida_frame.add_frame_member_ea(func_ea: ida_idaapi.ea_t, name: str, offset: int, tif: tinfo_t, repr: value_repr_t = None, etf_flags: uint = 0) → bool

Add member to the frame type

Parameters:

func_ea – any address of the function
name – variable name, nullptr means autogenerate a name
offset – member offset in the frame structure, in bytes
tif – variable type
repr – variable representation

Returns:

success

ida_frame.set_frame_member_type_ea(func_ea: ida_idaapi.ea_t, offset: int, tif: tinfo_t, repr: value_repr_t = None, etf_flags: uint = 0) → bool

Change type of the frame member

Parameters:

func_ea – any address of the function
offset – member offset in the frame structure, in bytes
tif – variable type
repr – variable representation

Returns:

success

ida_frame.delete_frame_members_ea(func_ea: ida_idaapi.ea_t, start_offset: int, end_offset: int) → bool

Delete frame members

Parameters:

func_ea – any address of the function
start_offset – member offset to start deletion from, in bytes
end_offset – member offset which not included in the deletion, in bytes

Returns:

success

ida_frame.build_stkvar_name_ea(func_ea: ida_idaapi.ea_t, v: int) → str | None

Build automatic stack variable name.

Parameters:

func_ea – any address of the function
v – value of variable offset

Returns:

length of stack variable name or -1

ida_frame.calc_stkvar_struc_offset_ea(func_ea: ida_idaapi.ea_t, insn: insn_t const &, n: int) → ida_idaapi.ea_t

Calculate offset of stack variable in the frame structure.

Parameters:

func_ea – any address of the function
insn – the instruction
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)

ida_frame.calc_frame_offset_ea(func_ea: ida_idaapi.ea_t, off: int, insn: insn_t const * = None, op: op_t const * = None) → int

Calculate the offset of stack variable in the frame.

Parameters:

func_ea – any address of the function
off – the offset relative to stack pointer or frame pointer
insn – the instruction
op – the operand

Returns:

the offset in the frame

ida_frame.delete_wrong_frame_info_ea(func_ea: ida_idaapi.ea_t, should_reanalyze: bool (*)(insn_t const &)) → int

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:

func_ea – any address of the function
should_reanalyze – callback to determine which instructions to reanalyze

Returns:

number of deleted definitions or -1 if no function

ida_frame.build_stkvar_xrefs_ea(out: xreflist_t, func_ea: ida_idaapi.ea_t, start_offset: int, end_offset: int) → None

Fill ‘out’ with a list of all the xrefs from a function to the specified range of the function’s stack frame.

Parameters:

out – the list of xrefs to fill
func_ea – any address of the function
start_offset – start frame structure offset, in bytes
end_offset – end frame structure offset, in bytes

ida_frame.add_func_regvar(func_ea: ida_idaapi.ea_t, ea1: ida_idaapi.ea_t, ea2: ida_idaapi.ea_t, canon: str, user: str, cmt: str) → int

Define a register variable.

Parameters:

func_ea – any address of the function
ea1 – range of addresses within the function where the definition will be used
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

ida_frame.REGVAR_ERROR_OK: all ok

ida_frame.REGVAR_ERROR_ARG: function arguments are bad

ida_frame.REGVAR_ERROR_RANGE: the definition range is bad

ida_frame.REGVAR_ERROR_NAME: the provided name(s) can’t be accepted

ida_frame.find_func_regvar(*args) → ssize_t

This function has the following signatures:

find_func_regvar(rv: regvar_t *, func_ea: ida_idaapi.ea_t, ea1: ida_idaapi.ea_t, ea2: ida_idaapi.ea_t, canon: str, user: str) -> ssize_t

find_func_regvar(rv: regvar_t *, func_ea: ida_idaapi.ea_t, ea: ida_idaapi.ea_t, canon: str) -> ssize_t

# 0: find_func_regvar(rv: regvar_t *, func_ea: ida_idaapi.ea_t, ea1: ida_idaapi.ea_t, ea2: ida_idaapi.ea_t, canon: str, user: str) -> ssize_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:: index of the register variable, or -1 if not found

# 1: find_func_regvar(rv: regvar_t *, func_ea: ida_idaapi.ea_t, ea: ida_idaapi.ea_t, canon: str) -> ssize_t

Find a register variable definition.

Returns:: index of the register variable, or -1 if not found

ida_frame.has_func_regvar(func_ea: ida_idaapi.ea_t, ea: ida_idaapi.ea_t) → bool

Is there a register variable definition?

Parameters:

func_ea – any address of the function
ea – current address

ida_frame.has_regvar(pfn: func_t *, ea: ida_idaapi.ea_t) → bool

Is there a register variable definition?

Parameters:

pfn – function in question
ea – current address

ida_frame.rename_func_regvar(func_ea: ida_idaapi.ea_t, index: ssize_t, user: str) → int

Rename a register variable.

Parameters:

func_ea – any address of the function
index – index of the register variable (see find_func_regvar())
user – new user-defined name for the register

Returns:

Register variable error codes

ida_frame.set_func_regvar_cmt(func_ea: ida_idaapi.ea_t, index: ssize_t, cmt: str) → int

Set comment for a register variable.

Parameters:

func_ea – any address of the function
index – index of the register variable (see find_func_regvar())
cmt – new comment

Returns:

Register variable error codes

ida_frame.set_func_regvar_range(func_ea: ida_idaapi.ea_t, index: ssize_t, range: range_t) → int

Update the address range of a register variable by index. Only the range is changed; to rename a regvar or change its comment use rename_func_regvar()/set_func_regvar_cmt(). The new range must be well-formed (start_ea < end_ea) and must keep the function’s register variables sorted by start_ea.

Parameters:

func_ea – any address of the function
index – index of the register variable (see find_func_regvar())
range – new address range for the register variable

Returns:

Register variable error codes

ida_frame.del_func_regvar(func_ea: ida_idaapi.ea_t, ea1: ida_idaapi.ea_t, ea2: ida_idaapi.ea_t, canon: str) → int

Delete a register variable definition.

Parameters:

func_ea – any address of the function
ea1 – range of addresses within the function where the definition holds
ea2 – range of addresses within the function where the definition holds
canon – name of a general register

Returns:

Register variable error codes

ida_frame.get_func_regvar_qty(func_ea: ida_idaapi.ea_t) → int

Get the number of register variables for a function.

Parameters:: func_ea – function start address
Returns:: number of register variables, or 0

ida_frame.get_func_regvars(out: regvars_t, func_ea: ida_idaapi.ea_t) → bool

Get all register variables for a function.

Parameters:

out – output vector of regvar_t
func_ea – function start address

Returns:

success

ida_frame.get_func_regvar(out: regvar_t, func_ea: ida_idaapi.ea_t, index: ssize_t) → bool

Get a copy of a register variable by index.

Parameters:

out – output regvar_t (deep copy)
func_ea – any address of the function
index – index of the register variable (see find_func_regvar())

Returns:

false if the index is out of range

ida_frame.add_func_auto_stkpnt(func_ea: ida_idaapi.ea_t, ea: ida_idaapi.ea_t, delta: int) → bool

Add automatic SP register change point.

Parameters:

func_ea – any address of the function, may be BADADDR to auto-resolve
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

ida_frame.del_func_stkpnt(func_ea: ida_idaapi.ea_t, ea: ida_idaapi.ea_t) → bool

Delete SP register change point.

Parameters:

func_ea – any address of the function, may be BADADDR to auto-resolve
ea – linear address

Returns:

success

ida_frame.get_func_spd(func_ea: ida_idaapi.ea_t, ea: ida_idaapi.ea_t) → int

Get difference between the initial and current values of ESP.

Parameters:

func_ea – any address of the function, may be BADADDR to auto-resolve
ea – linear address of the instruction

Returns:

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

ida_frame.get_func_effective_spd(func_ea: ida_idaapi.ea_t, ea: ida_idaapi.ea_t) → int

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_func_spd() and get_func_effective_spd() is present only for instructions like “pop [esp+N]”: they modify sp and use the modified value.

Parameters:

func_ea – any address of the function, may be BADADDR to auto-resolve
ea – linear address

Returns:

0 or the difference, usually a negative number

ida_frame.get_func_sp_delta(func_ea: ida_idaapi.ea_t, ea: ida_idaapi.ea_t) → int

Get modification of SP made at the specified location

Parameters:

func_ea – any address of the function, may be BADADDR to auto-resolve
ea – linear address

Returns:

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

ida_frame.set_func_auto_spd(func_ea: ida_idaapi.ea_t, ea: ida_idaapi.ea_t, new_spd: int) → bool

Set the cumulative SP delta at the given address.

Parameters:

func_ea – any address of the function, may be BADADDR to auto-resolve
ea – linear address of the instruction
new_spd – new value of the cumulative SP delta

Returns:

success

ida_frame.recalc_func_spd_for_basic_block(func_ea: ida_idaapi.ea_t, cur_ea: ida_idaapi.ea_t) → bool

Recalculate SP delta for the current instruction. The typical code snippet to calculate SP delta in a proc module is:

ea_t func_ea = get_func_start(insn.ea); if ( may_trace_sp() && func_ea != BADADDR )

if ( !recalc_func_spd_for_basic_block(func_ea, insn.ea) )
trace_sp(func_ea, insn);

Parameters:

func_ea – any address of the function
cur_ea – linear address of the current instruction

Returns:

true: the cumulative SP delta is set

Returns:

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.

ida_frame.get_func_stkpnt_qty(func_ea: ida_idaapi.ea_t) → int

Get the number of SP change points for a function.

Parameters:: func_ea – function start address
Returns:: number of SP change points, or 0 if no function / no points

ida_frame.get_func_stkpnts(out: stkpnts_t, func_ea: ida_idaapi.ea_t) → bool

Get all SP change points for a function.

Parameters:

out – output vector of stkpnt_t
func_ea – function start address

Returns:

success

ida_frame.get_func_llabel_qty(func_ea: ida_idaapi.ea_t) → int

Get the number of local labels for a function.

Parameters:: func_ea – function start address
Returns:: number of local labels, or 0

ida_frame.get_func_llabels(out: llabels_t, func_ea: ida_idaapi.ea_t) → bool

Get all local labels for a function.

Parameters:

out – output vector of llabel_t
func_ea – function start address

Returns:

success

ida_frame.add_frame

ida_frame.del_frame

ida_frame.set_frame_size

ida_frame.get_frame_size

ida_frame.get_frame_retsize

ida_frame.get_frame_part

ida_frame.get_func_frame

ida_frame.soff_to_fpoff

ida_frame.update_fpd

ida_frame.define_stkvar

ida_frame.add_frame_member

ida_frame.set_frame_member_type

ida_frame.delete_frame_members

ida_frame.build_stkvar_name

ida_frame.calc_stkvar_struc_offset

ida_frame.calc_frame_offset

ida_frame.add_regvar

ida_frame.find_regvar

ida_frame.rename_regvar

ida_frame.set_regvar_cmt

ida_frame.del_regvar

ida_frame.has_regvar

ida_frame.add_auto_stkpnt

ida_frame.del_stkpnt

ida_frame.get_spd

ida_frame.get_effective_spd

ida_frame.get_sp_delta

ida_frame.set_auto_spd

ida_frame.recalc_spd_for_basic_block

ida_frame.build_stkvar_xrefs

ida_frame.frame_off_args

ida_frame.frame_off_retaddr

ida_frame.frame_off_savregs

ida_frame.frame_off_lvars

ida_frame.is_funcarg_off

ida_frame.lvar_off