IDA SDK
Classes | Functions | Macros | Typedefs | Enumerations
frame.hpp File 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 (func_t::argsize)           |
  +------------------------------------------------+
  | 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:

Classes

struct  regvar_t
 A register variable allows the user to rename a general processor register to a meaningful name. More...
 
struct  llabel_t
 Local label. More...
 
struct  xreflist_entry_t
 An xref to an argument or variable located in a function's stack frame. More...
 

Functions

idaman bool ida_export add_frame (func_t *pfn, sval_t frsize, ushort frregs, asize_t argsize)
 Add function frame. More...
 
idaman bool ida_export del_frame (func_t *pfn)
 Delete a function frame. More...
 
idaman bool ida_export set_frame_size (func_t *pfn, asize_t frsize, ushort frregs, asize_t argsize)
 Set size of function frame. More...
 
idaman asize_t ida_export get_frame_size (const func_t *pfn)
 Get full size of a function frame. More...
 
idaman int ida_export get_frame_retsize (const func_t *pfn)
 Get size of function return address. More...
 
idaman void ida_export get_frame_part (range_t *range, const func_t *pfn, frame_part_t part)
 Get offsets of the frame part in the frame. More...
 
ea_t frame_off_args (const func_t *pfn)
 Get starting address of arguments section.
 
ea_t frame_off_retaddr (const func_t *pfn)
 Get starting address of return address section.
 
ea_t frame_off_savregs (const func_t *pfn)
 Get starting address of saved registers section.
 
ea_t frame_off_lvars (const func_t *pfn)
 Get start address of local variables section.
 
bool is_funcarg_off (const func_t *pfn, uval_t frameoff)
 Does the given offset lie within the arguments section?
 
sval_t lvar_off (const func_t *pfn, uval_t frameoff)
 Does the given offset lie within the local variables section?
 
idaman struc_t *ida_export get_frame (const func_t *pfn)
 Get pointer to function frame. More...
 
struc_tget_frame (ea_t ea)
 Get pointer to function frame. More...
 
idaman bool ida_export update_fpd (func_t *pfn, asize_t fpd)
 Update frame pointer delta. More...
 
idaman bool ida_export set_purged (ea_t ea, int nbytes, bool override_old_value)
 Set the number of purged bytes for a function or data item (funcptr). More...
 
idaman ea_t ida_export get_func_by_frame (tid_t frame_id)
 Get function by its frame id. More...
 
idaman member_t *ida_export get_stkvar (sval_t *actval, const insn_t &insn, const op_t &x, sval_t v)
 Get pointer to stack variable. More...
 
idaman bool ida_export add_stkvar (const insn_t &insn, const op_t &x, sval_t v, int flags)
 Automatically add stack variable if doesn't exist. More...
 
idaman bool ida_export define_stkvar (func_t *pfn, const char *name, sval_t off, flags_t flags, const opinfo_t *ti, asize_t nbytes)
 Define/redefine a stack variable. More...
 
idaman ssize_t ida_export build_stkvar_name (qstring *buf, const func_t *pfn, sval_t v)
 Build automatic stack variable name. More...
 
idaman ea_t ida_export calc_stkvar_struc_offset (func_t *pfn, const insn_t &insn, int n)
 Calculate offset of stack variable in the frame structure. More...
 
idaman int ida_export delete_unreferenced_stkvars (func_t *pfn)
 Find and delete unreferenced stack variable definitions. More...
 
idaman int ida_export delete_wrong_stkvar_ops (func_t *pfn)
 Find and undefine references to dead stack variables. More...
 
idaman int ida_export add_regvar (func_t *pfn, ea_t ea1, ea_t ea2, const char *canon, const char *user, const char *cmt)
 Define a register variable. More...
 
idaman regvar_t *ida_export find_regvar (func_t *pfn, ea_t ea1, ea_t ea2, const char *canon, const char *user)
 Find a register variable definition (powerful version). More...
 
regvar_tfind_regvar (func_t *pfn, ea_t ea, const char *canon)
 Find a register variable definition. More...
 
idaman int ida_export rename_regvar (func_t *pfn, regvar_t *v, const char *user)
 Rename a register variable. More...
 
idaman int ida_export set_regvar_cmt (func_t *pfn, regvar_t *v, const char *cmt)
 Set comment for a register variable. More...
 
idaman int ida_export del_regvar (func_t *pfn, ea_t ea1, ea_t ea2, const char *canon)
 Delete a register variable definition. More...
 
idaman bool ida_export add_auto_stkpnt (func_t *pfn, ea_t ea, sval_t delta)
 Add automatic SP register change point. More...
 
idaman bool ida_export add_user_stkpnt (ea_t ea, sval_t delta)
 Add user-defined SP register change point. More...
 
idaman bool ida_export del_stkpnt (func_t *pfn, ea_t ea)
 Delete SP register change point. More...
 
idaman sval_t ida_export get_spd (func_t *pfn, ea_t ea)
 Get difference between the initial and current values of ESP. More...
 
idaman sval_t ida_export get_effective_spd (func_t *pfn, ea_t ea)
 Get effective difference between the initial and current values of ESP. More...
 
idaman sval_t ida_export get_sp_delta (func_t *pfn, ea_t ea)
 Get modification of SP made at the specified location. More...
 
idaman ea_t ida_export get_min_spd_ea (func_t *pfn)
 Get the address with the minimal spd (stack pointer delta). More...
 
idaman bool ida_export recalc_spd (ea_t cur_ea)
 Recalculate SP delta for an instruction that stops execution. More...
 
idaman void ida_export build_stkvar_xrefs (xreflist_t *out, func_t *pfn, const member_t *mptr)
 Fill 'out' with a list of all the xrefs made from function 'pfn', to the argument or variable 'mptr' in 'pfn's stack frame. More...
 
Local Labels

These are LOW LEVEL FUNCTIONS.

When possible, they should not be used. Use high level functions from <name.hpp>

bool set_llabel (func_t *pfn, ea_t ea, const char *name)
 Define/rename/delete a local label. More...
 
ea_t get_llabel_ea (func_t *pfn, const char *name)
 Get address of a local label. More...
 
const char * get_llabel (func_t *pfn, ea_t ea)
 Get local label at the specified address. More...
 

Macros

#define STKVAR_VALID_SIZE   0x0001
 x.dtyp contains correct variable type More...
 
#define REGVAR_ERROR_OK   0
 all ok
 
#define REGVAR_ERROR_ARG   (-1)
 function arguments are bad
 
#define REGVAR_ERROR_RANGE   (-2)
 the definition range is bad
 
#define REGVAR_ERROR_NAME   (-3)
 the provided name(s) can't be accepted
 

Typedefs

typedef qvector< xreflist_entry_txreflist_t
 vector of xrefs to variables in a function's stack frame
 

Enumerations

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

Function Documentation

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

Add function frame.

Parameters
pfnpointer to function structure
frsizesize of function local variables
frregssize of saved registers
argsizesize 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
1ok
0failed (no function, frame already exists)
idaman bool ida_export del_frame ( func_t pfn)

Delete a function frame.

Parameters
pfnpointer to function structure
Returns
success
idaman bool ida_export set_frame_size ( func_t pfn,
asize_t  frsize,
ushort  frregs,
asize_t  argsize 
)

Set size of function frame.

Parameters
pfnpointer to function structure
frsizesize of function local variables
frregssize of saved registers
argsizesize of function arguments
Returns
success
idaman asize_t ida_export get_frame_size ( const func_t pfn)

Get full size of a function frame.

This function takes into account size of local variables + size of saved registers + size of return address + size of function arguments.

Parameters
pfnpointer to function structure, may be NULL
Returns
size of frame in bytes or zero
idaman int ida_export get_frame_retsize ( const func_t pfn)

Get size of function return address.

Parameters
pfnpointer to function structure, can't be NULL
idaman void ida_export get_frame_part ( range_t *  range,
const func_t pfn,
frame_part_t  part 
)

Get offsets of the frame part in the frame.

Parameters
rangepointer to the output buffer with the frame part start/end(exclusive) offsets, can't be NULL
pfnpointer to function structure, can't be NULL
partframe part
idaman struc_t* ida_export get_frame ( const func_t pfn)

Get pointer to function frame.

Parameters
pfnpointer to function structure
struc_t* get_frame ( ea_t  ea)
inline

Get pointer to function frame.

Parameters
eaany address in the function
idaman bool ida_export update_fpd ( func_t pfn,
asize_t  fpd 
)

Update frame pointer delta.

Parameters
pfnpointer to function structure
fpdnew fpd value. can not be bigger than the local variable range size.
Returns
success
idaman bool ida_export set_purged ( ea_t  ea,
int  nbytes,
bool  override_old_value 
)

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

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

Parameters
eaaddress of the function of item
nbytesnumber of purged bytes
override_old_valuemay overwrite old information about purged bytes
Returns
success
idaman ea_t ida_export get_func_by_frame ( tid_t  frame_id)

Get function by its frame id.

Warning
this function works only with databases created by IDA > 5.6
Parameters
frame_idid of the function frame
Returns
start address of the function or BADADDR
idaman member_t* ida_export get_stkvar ( sval_t actval,
const insn_t insn,
const op_t x,
sval_t  v 
)

Get pointer to stack variable.

Parameters
actvalactual value used to fetch stack variable this pointer may point to 'v'
insnthe instruction
xreference to instruction operand
vimmediate value in the operand (usually x.addr)
Returns
NULL or ptr to stack variable
idaman bool ida_export add_stkvar ( const insn_t insn,
const op_t x,
sval_t  v,
int  flags 
)

Automatically add stack variable if doesn't exist.

Processor modules should use insn_t::create_stkvar().

Parameters
insnthe instruction
xreference to instruction operand
vimmediate value in the operand (usually x.addr)
flagsAdd stkvar flags
Returns
success
idaman bool ida_export define_stkvar ( func_t pfn,
const char *  name,
sval_t  off,
flags_t  flags,
const opinfo_t ti,
asize_t  nbytes 
)

Define/redefine a stack variable.

Parameters
pfnpointer to function
namevariable name, NULL means autogenerate a name
offoffset of the stack variable in the frame. negative values denote local variables, positive - function arguments.
flagsvariable type flags (byte_flag() for a byte variable, for example)
tiadditional type information (like offsets, structs, etc)
nbytesnumber of bytes occupied by the variable
Returns
success
idaman ssize_t ida_export build_stkvar_name ( qstring buf,
const func_t pfn,
sval_t  v 
)

Build automatic stack variable name.

Parameters
bufpointer to buffer
pfnpointer to function (can't be NULL!)
vvalue of variable offset
Returns
length of stack variable name or -1
idaman ea_t ida_export calc_stkvar_struc_offset ( func_t pfn,
const insn_t insn,
int  n 
)

Calculate offset of stack variable in the frame structure.

Parameters
pfnpointer to function (can't be NULL!)
insnthe instruction
nnumber of operand: (0..UA_MAXOP-1) -1 if error, return BADADDR
Returns
BADADDR if some error (issue a warning if stack frame is bad)
idaman int ida_export delete_unreferenced_stkvars ( func_t pfn)

Find and delete unreferenced stack variable definitions.

Parameters
pfnpointer to the function
Returns
number of deleted definitions
idaman int ida_export delete_wrong_stkvar_ops ( func_t pfn)

Find and undefine references to dead stack variables.

(i.e. operands displayed in red) These operands will be untyped and most likely displayed in hex.

Parameters
pfnpointer to the function
Returns
number of reset operands
bool set_llabel ( func_t pfn,
ea_t  ea,
const char *  name 
)

Define/rename/delete a local label.

THIS IS A LOW LEVEL FUNCTION - use set_name() instead of it!

Parameters
pfnfunction in which the definition will be created
ealinear address of the label
namename of the label. If NULL or empty string, name will be removed
Returns
success
ea_t get_llabel_ea ( func_t pfn,
const char *  name 
)

Get address of a local label.

THIS IS A LOW LEVEL FUNCTION - use get_name_ea() instead of it!

Parameters
pfnfunction in question
namename of the label
Returns
BADADDR if not found
const char* get_llabel ( func_t pfn,
ea_t  ea 
)

Get local label at the specified address.

THIS IS A LOW LEVEL FUNCTION - use get_name() instead of it!

Parameters
pfnfunction in question
ealinear address of the label
Returns
NULL or ptr to the name
idaman bool ida_export add_auto_stkpnt ( func_t pfn,
ea_t  ea,
sval_t  delta 
)

Add automatic SP register change point.

Parameters
pfnpointer to function. may be NULL.
ealinear address where SP changes. usually this is the end of the instruction which modifies the stack pointer ( insn_t::ea+ insn_t::size)
deltadifference between old and new values of SP
Returns
success
idaman bool ida_export add_user_stkpnt ( ea_t  ea,
sval_t  delta 
)

Add user-defined SP register change point.

Parameters
ealinear address where SP changes
deltadifference between old and new values of SP
Returns
success
idaman bool ida_export del_stkpnt ( func_t pfn,
ea_t  ea 
)

Delete SP register change point.

Parameters
pfnpointer to function. may be NULL.
ealinear address
Returns
success
idaman sval_t ida_export get_spd ( func_t pfn,
ea_t  ea 
)

Get difference between the initial and current values of ESP.

Parameters
pfnpointer to function. may be NULL.
ealinear address of an instruction
Returns
0 or the difference, usually a negative number. returns the sp-diff before executing the instruction.
idaman sval_t ida_export get_effective_spd ( func_t pfn,
ea_t  ea 
)

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

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

Parameters
pfnpointer to function. may be NULL.
ealinear address
Returns
0 or the difference, usually a negative number
idaman sval_t ida_export get_sp_delta ( func_t pfn,
ea_t  ea 
)

Get modification of SP made at the specified location.

Parameters
pfnpointer to function. may be NULL.
ealinear address
Returns
0 if the specified location doesn't contain a SP change point. otherwise return delta of SP modification.
idaman ea_t ida_export get_min_spd_ea ( func_t pfn)

Get the address with the minimal spd (stack pointer delta).

If there are no SP change points, then return BADADDR.

idaman bool ida_export recalc_spd ( ea_t  cur_ea)

Recalculate SP delta for an instruction that stops execution.

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

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

Parameters
cur_ealinear address of the current instruction
Return values
1new stkpnt is added
0nothing is changed
idaman void ida_export build_stkvar_xrefs ( xreflist_t out,
func_t pfn,
const member_t mptr 
)

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

Parameters
outthe list of xrefs to fill.
pfnthe function to scan.
mptrthe argument/variable in pfn's stack frame.