IDA SDK

- Main Page
- Header Files
- Classes
- Modules

- File List
- File Members

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:

- get_struc() (use func_t::frame as structure ID)
- get_frame(const func_t *pfn)
- get_frame(ea_t ea)

## 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 (func_t *pfn)
| Get full size of a function frame. More...
idaman int ida_export | get_frame_retsize (func_t *pfn)
| Get size of function return address. More...
idaman void ida_export | get_frame_part (func_t *pfn, frame_part_t part, area_t *range)
| Get offsets of the frame part in the frame. More...
ea_t | frame_off_args (func_t *pfn)
| Get starting address of arguments section.
ea_t | frame_off_retaddr (func_t *pfn)
| Get starting address of return address section.
ea_t | frame_off_savregs (func_t *pfn)
| Get starting address of saved registers section.
ea_t | frame_off_lvars (func_t *pfn)
| Get start address of local variables section.
bool | is_funcarg_off (func_t *pfn, uval_t frameoff)
| Does the given offset lie within the arguments section?
sval_t | lvar_off (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_t * | get_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 (const op_t &x, sval_t v, sval_t *actval)
| Get pointer to stack variable. More...
idaman bool ida_export | add_stkvar3 (const op_t &x, sval_t v, int flags)
| Automatically add stack variable if doesn't exist. More...
idaman bool ida_export | add_stkvar2 (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 char *ida_export | build_stkvar_name (char *buf, size_t bufsize, func_t *pfn, sval_t v)
| Build automatic stack variable name. More...
idaman ea_t ida_export | calc_stkvar_struc_offset (func_t *pfn, ea_t ea, 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_t * | find_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_stkpnt2 (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_t > | xreflist_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

  pfn | pointer to function structure
  frsize | size of function local variables
  frregs | size of saved registers
  argsize | size of function arguments area which will be purged upon return. this parameter is used for __stdcall and __pascal calling conventions. for other calling conventions please pass 0.

Return values

  1 | ok
  0 | failed (no function, frame already exists)

idaman bool ida_export del_frame | ( | func_t * | pfn | ) |

Delete a function frame.

Parameters

  pfn | pointer 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

  pfn | pointer to function structure
  frsize | size of function local variables
  frregs | size of saved registers
  argsize | size of function arguments

Returns
  success

idaman asize_t ida_export get_frame_size | ( | 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

  pfn | pointer to function structure, may be NULL

Returns
  size of frame in bytes or zero

idaman int ida_export get_frame_retsize | ( | func_t * | pfn | ) |

Get size of function return address.

Parameters

  pfn | pointer to function structure, can't be NULL

idaman void ida_export get_frame_part | ( | func_t * | pfn,
|  | frame_part_t | part,
|  | area_t * | range
| ) |  |

Get offsets of the frame part in the frame.

Parameters

  pfn | pointer to function structure, can't be NULL
  part | frame part
  range | pointer to the output buffer with the frame part start/end(exclusive) offsets, can't be NULL

idaman struc_t* ida_export get_frame | ( | const func_t * | pfn | ) |

Get pointer to function frame.

Parameters

  pfn | pointer to function structure

struc_t* get_frame | ( | ea_t | ea | ) |
| inline

Get pointer to function frame.

Parameters

  ea | any address in the function

idaman bool ida_export update_fpd | ( | func_t * | pfn,
|  | asize_t | fpd
| ) |  |

Update frame pointer delta.

Parameters

  pfn | pointer to function structure
  fpd | new fpd value. can not be bigger than the local variable area 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

  ea | address of the function of item
  nbytes | number of purged bytes
  override_old_value | may 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_id | id of the function frame

Returns
  start address of the function or BADADDR

idaman member_t* ida_export get_stkvar | ( | const op_t & | x,
|  | sval_t | v,
|  | sval_t * | actval
| ) |  |

Get pointer to stack variable.

Parameters

  x | reference to instruction operand
  v | immediate value in the operand (usually x.addr)
  actval | actual value used to fetch stack variable this pointer may point to 'v'

Returns
  NULL or ptr to stack variable

idaman bool ida_export add_stkvar3 | ( | const op_t & | x,
|  | sval_t | v,
|  | int | flags
| ) |  |

Automatically add stack variable if doesn't exist.

Processor modules should use ua_stkvar().

Parameters

  x | reference to instruction operand
  v | immediate value in the operand (usually x.addr)
  flags | Add stkvar flags

Returns
  success

idaman bool ida_export add_stkvar2 | ( | 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

  pfn | pointer to function
  name | variable name, NULL means autogenerate a name
  off | offset of the stack variable in the frame. negative values denote local variables, positive - function arguments.
  flags | variable type flags (byteflag() for a byte variable, for example)
  ti | additional type information (like offsets, structs, etc)
  nbytes | number of bytes occupied by the variable

Returns
  success

idaman char* ida_export build_stkvar_name | ( | char * | buf,
|  | size_t | bufsize,
|  | func_t * | pfn,
|  | sval_t | v
| ) |  |

Build automatic stack variable name.

Parameters

  buf | pointer to buffer. must be at least MAXNAMELEN
  pfn | pointer to function (can't be NULL!)
  v | value of variable offset

Returns
  ptr to buf

idaman ea_t ida_export calc_stkvar_struc_offset | ( | func_t * | pfn,
|  | ea_t | ea,
|  | int | n
| ) |  |

Calculate offset of stack variable in the frame structure.

Parameters

  pfn | pointer to function (can't be NULL!)
  ea | linear address of the instruction
  n | number 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

  pfn | pointer 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

  pfn | pointer 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

  pfn | function in which the definition will be created
  ea | linear address of the label
  name | name 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

  pfn | function in question
  name | name 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

  pfn | function in question
  ea | linear address of the label

Returns
  NULL or ptr to the name

idaman bool ida_export add_auto_stkpnt2 | ( | func_t * | pfn,
|  | ea_t | ea,
|  | sval_t | delta
| ) |  |

Add automatic SP register change point.

Parameters

  pfn | pointer to function. may be NULL.
  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

idaman bool ida_export add_user_stkpnt | ( | ea_t | ea,
|  | sval_t | delta
| ) |  |

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

idaman bool ida_export del_stkpnt | ( | func_t * | pfn,
|  | ea_t | ea
| ) |  |

Delete SP register change point.

Parameters

  pfn | pointer to function. may be NULL.
  ea | linear 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

  pfn | pointer to function. may be NULL.
  ea | linear 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

  pfn | pointer to function. may be NULL.
  ea | linear 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

  pfn | pointer to function. may be NULL.
  ea | linear 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_ea | linear address of the current instruction

Return values

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

  out | the list of xrefs to fill.
  pfn | the function to scan.
  mptr | the argument/variable in pfn's stack frame.