IDA SDK

- Main Page
- Header Files
- Classes
- Modules

- File List
- File Members

Classes | Functions | Macros | Typedefs | Enumerations | Variables
ua.hpp File Reference

## Detailed Description

Functions that deal with the disassembling of program instructions.

There are 2 kinds of functions:

- functions that are called from the kernel to disassemble an instruction. These functions call IDP module for it.
- functions that are called from IDP module to disassemble an instruction. We will call them 'helper functions'.

Disassembly of an instruction is made in three steps:

1. analysis: ana.cpp
2. emulation: emu.cpp
3. conversion to text: out.cpp

The kernel calls the IDP module to perform these steps. At first, the kernel always calls analysis. The analyzer must decode the instruction and fill cmd. It has no rights to change anything in the database.

The second step, emulation, is called for each instruction. This step must make necessary changes to the database, plan analysis of subsequent instructions, track register values, memory contents, etc. However, the kernel may call the emulation step for any address in the program - there is no ordering of addresses. Usually, the emulation is called necessary for subsequent addresses but this is not guaranteed. The main goal of emulation step is to track down execution flow and to plan conversion of necessary bytes to instructions.

The last step, conversion to text, is called each time an instruction is displayed on the screen. The kernel will always call the analysis step first (the analysis should be very fast) and then will call conversion to text. The emulation and conversion steps should use information stored in cmd. They should not access the bytes of the instruction and decode it again - this should only be done in the analysis step.

## Classes
class | op_t
| Operand of an instruction. More...
class | insn_t
| Structure to hold information about an instruction. More...
union | value_u
| This structure is used to pass values of bytes to helper functions. More...
struct | value_u::dq_t
struct | value_u::dt_t
struct | value_u::d128_t

## Functions
idaman size_t ida_export | get_operand_immvals (ea_t ea, int n, uval_t *v)
| Get immediate values used in the operand if it fits into uval_t. More...
idaman void ida_export | init_output_buffer (char *buf, size_t bufsize)
| Initialize output buffer. More...
idaman char *ida_export | term_output_buffer (void)
| Terminate output buffer. More...
idaman int ida_export | out_snprintf (const char *format,...)
| Append a formatted string to the output string. More...
idaman char *ida_export | set_output_ptr (char *ptr)
| Set the pointer to the output buffer. More...
char *idaapi | get_output_ptr (void)
| Get pointer to the output buffer.
idaman void ida_export | out_insert (char *ptr, const char *string)
| Insert a string into the output string. More...
idaman int ida_export | OutMnem (int width=8, const char *postfix=NULL)
| Output instruction mnemonics using information in cmd. More...
idaman void ida_export | OutBadInstruction (void)
| Output instruction as a sequence of bytes, followed by a comment character and instruction mnemonics. More...
idaman bool ida_export | out_one_operand (int n)
| Use this function to output an operand of an instruction. More...
idaman flags_t ida_export | OutValue (const op_t &x, int outflags=0)
| Output immediate value. More...
uval_t | get_immval (const op_t &x, int outf=0, bool extend_sign=false, char *dtyp_ptr=NULL, size_t *nbytes_ptr=NULL)
| Extract immediate value from the operand according to the specified flags. More...
idaman void ida_export | out_symbol (char c)
| Output a character with COLOR_SYMBOL color.
idaman void ida_export | out_line (const char *str, color_t color)
| Output a string with the specified color.
void | out_keyword (const char *str)
| Output a string with COLOR_KEYWORD color.
void | out_register (const char *str)
| Output a character with COLOR_REG color.
idaman void ida_export | out_tagon (color_t tag)
| Output "turn color on" escape sequence.
idaman void ida_export | out_tagoff (color_t tag)
| Output "turn color off" escape sequence.
idaman void ida_export | out_addr_tag (ea_t ea)
| Output "address" escape sequence.
idaman void ida_export | out_colored_register_line (const char *str)
| Output a colored line with register names in it. More...
idaman void ida_export | OutLine (const char *s)
| Output plain text without color codes. More...
idaman void ida_export | OutChar (char c)
| Output one character. More...
idaman void ida_export | OutLong (uval_t Word, char radix)
| Output a number with the specified base (binary, octal, decimal, hex) The number is output without color codes. More...
idaman void ida_export | OutImmChar (const op_t &x)
| Output operand value as a commented character constant. More...
idaman bool ida_export | showAsChar (const void *ptr, char *buf, int size)
| Try to display value as a character constant. More...
idaman bool ida_export | out_real (const void *v, int size, char *buf, size_t bufsize)
| Output a floating point value. More...
idaman void ida_export | out_long (sval_t v, char radix)
| Output a number with appropriate color. More...
idaman bool ida_export | out_name_expr (const op_t &x, ea_t ea, adiff_t off=BADADDR)
| Output a name expression. More...
idaman bool ida_export | ua_dodata2 (int opoff, ea_t ea, int dtype)
| Convert to data using information about operand value type (op_t::dtyp). More...
idaman bool ida_export | ua_stkvar2 (const op_t &x, adiff_t v, int flags)
| Create or modify a stack variable in the function frame. More...
idaman void ida_export | ua_add_cref (int opoff, ea_t to, cref_t type)
| Add a code cross-reference from the current instruction ( insn_t::ea). More...
idaman void ida_export | ua_add_dref (int opoff, ea_t to, dref_t type)
| Add a data cross-reference from the current instruction ( insn_t::ea). More...
idaman ea_t ida_export | ua_add_off_drefs (const op_t &x, dref_t type)
| Add xrefs for an operand of the current instruction ( insn_t::ea). More...
idaman ea_t ida_export | ua_add_off_drefs2 (const op_t &x, dref_t type, int outf)
| See ua_add_off_drefs()
idaman flags_t ida_export | get_dtyp_flag (char dtype)
| Get flags for op_t::dtyp field.
idaman size_t ida_export | get_dtyp_size (char dtype)
| Get size of opt_::dtyp field.
idaman char ida_export | get_dtyp_by_size (asize_t size)
| Get op_t::dtyp from size.
idaman int ida_export | create_insn (ea_t ea)
| Create an instruction at the specified address. More...
idaman int ida_export | decode_insn (ea_t ea)
| Analyze the specified address and fill cmd. More...
idaman bool ida_export | ua_outop2 (ea_t ea, char *buf, size_t bufsize, int n, int flags=0)
| Generate text representation for operand #n. More...
idaman const char *ida_export | ua_mnem (ea_t ea, char *buf, size_t bufsize)
| Generate text representation of the instruction mnemonics. More...
idaman ea_t ida_export | decode_prev_insn (ea_t ea)
| Decode previous instruction if it exists, fill cmd. More...
idaman ea_t ida_export | decode_preceding_insn (ea_t ea, bool *p_farref)
| Decode preceding instruction in the execution flow. More...
idaman bool ida_export | construct_macro (bool enable, bool(idaapi *build_macro)(insn_t &s, bool may_go_forward))
| Construct a macro instruction. More...
idaman ea_t ida_export | guess_table_address (void)
| Guess the jump table address (ibm pc specific)
idaman asize_t ida_export | guess_table_size (ea_t jump_table)
| Guess the jump table size.
idaman int ida_export | get_spoiled_reg (const uint32 *regs, size_t n)
| Does the instruction in cmd spoil any register from 'regs'?. More...
Segment bases
The following functions return segment base linear addresses of the data or code segment for the current instruction. They use values of segment registers, operand types, etc.
idaman ea_t ida_export | dataSeg_opreg (int opnum, int rgnum)
| Get data segment by operand. More...
idaman ea_t ida_export | dataSeg_op (int opnum)
| Get data segment by operand number.
idaman ea_t ida_export | dataSeg (void)
| Get data segment regardless of operand number.
idaman ea_t ida_export | codeSeg (ea_t addr, int opnum)
| Get code segment. More...
Analysis helpers
The following functions return the next byte, 2 bytes, 4 bytes, and 8 bytes of cmd. They use and modify the size field ( insn_t::size). Normally they are used in the analyzer to get bytes of the instruction. Warning These functions work only for normal (8bit) byte processors!
idaman uint8 ida_export | ua_next_byte (void)
idaman uint16 ida_export | ua_next_word (void)
idaman uint32 ida_export | ua_next_long (void)
idaman uint64 ida_export | ua_next_qword (void)

## Macros
#define | OF_NO_BASE_DISP 0x80
| base displacement doesn't exist. More...
#define | OF_OUTER_DISP 0x40
| outer displacement exists. More...
#define | PACK_FORM_DEF 0x20
| packed factor defined. More...
#define | OF_NUMBER 0x10
| the operand can be converted to a number only
#define | OF_SHOW 0x08
| should the operand be displayed?
#define | dt_byte 0
| 8 bit
#define | dt_word 1
| 16 bit
#define | dt_dword 2
| 32 bit
#define | dt_float 3
| 4 byte
#define | dt_double 4
| 8 byte
#define | dt_tbyte 5
| variable size ( processor_t::tbyte_size)
#define | dt_packreal 6
| packed real format for mc68040
#define | dt_qword 7
| 64 bit
#define | dt_byte16 8
| 128 bit
#define | dt_code 9
| ptr to code (not used?)
#define | dt_void 10
| none
#define | dt_fword 11
| 48 bit
#define | dt_bitfild 12
| bit field (mc680x0)
#define | dt_string 13
| pointer to asciiz string
#define | dt_unicode 14
| pointer to unicode string
#define | dt_3byte 15
| 3-byte data
#define | dt_ldbl 16
| long double (which may be different from tbyte)
#define | dt_byte32 17
| 256 bit
#define | dt_byte64 18
| 512 bit
#define | UA_MAXOP 6
| max number of operands allowed for an instruction
#define | Op1 Operands[0]
| first operand
#define | Op2 Operands[1]
| second operand
#define | Op3 Operands[2]
| third operand
#define | Op4 Operands[3]
| fourth operand
#define | Op5 Operands[4]
| fifth operand
#define | Op6 Operands[5]
| sixth operand
#define | INSN_MACRO 0x01
| macro instruction
#define | INSN_MODMAC 0x02
| may modify the database to make room for the macro insn
#define | OOF_SIGNMASK 0x0003
| sign symbol (+/-) output
#define | OOFS_IFSIGN 0x0000
| output sign if needed
#define | OOFS_NOSIGN 0x0001
| don't output sign, forbid the user to change the sign
#define | OOFS_NEEDSIGN 0x0002
| always out sign (+-)
#define | OOF_SIGNED 0x0004
| output as signed if < 0
#define | OOF_NUMBER 0x0008
| always as a number
#define | OOF_WIDTHMASK 0x0070
| width of value in bits
#define | OOFW_IMM 0x0000
| take from x.dtyp
#define | OOFW_8 0x0010
| 8 bit width
#define | OOFW_16 0x0020
| 16 bit width
#define | OOFW_24 0x0030
| 24 bit width
#define | OOFW_32 0x0040
| 32 bit width
#define | OOFW_64 0x0050
| 64 bit width
#define | OOF_ADDR 0x0080
| output x.addr, otherwise x.value
#define | OOF_OUTER 0x0100
| output outer operand
#define | OOF_ZSTROFF 0x0200
| meaningful only if isStroff(uFlag) More...
#define | OOF_NOBNOT 0x0400
| prohibit use of binary not
#define | OOF_SPACES 0x0800
| do not suppress leading spaces More...
#define | STKVAR_VALID_SIZE 0x0001
| x.dtyp contains correct variable type More...

## Typedefs
typedef uchar | optype_t
| see Operand types

## Enumerations
enum | tribyte_order_t { tbo_123, tbo_132, tbo_213, tbo_231, tbo_312, tbo_321 }
| 3-byte (tribyte) data item order More...

## Variables
const optype_t | o_void = 0
| No Operand.
const optype_t | o_reg = 1
| General Register (al,ax,es,ds...). More...
const optype_t | o_mem = 2
| Direct Memory Reference (DATA). More...
const optype_t | o_phrase = 3
| Memory Ref [Base Reg + Index Reg]. More...
const optype_t | o_displ = 4
| Memory Reg [Base Reg + Index Reg + Displacement]. More...
const optype_t | o_imm = 5
| Immediate Value. More...
const optype_t | o_far = 6
| Immediate Far Address (CODE). More...
const optype_t | o_near = 7
| Immediate Near Address (CODE). More...
const optype_t | o_idpspec0 = 8
| processor specific type.
const optype_t | o_idpspec1 = 9
| processor specific type.
const optype_t | o_idpspec2 = 10
| processor specific type.
const optype_t | o_idpspec3 = 11
| processor specific type.
const optype_t | o_idpspec4 = 12
| processor specific type.
const optype_t | o_idpspec5 = 13
| processor specific type. More...
idaman insn_t ida_export_data | cmd
| Structure holding information about the current instruction. More...
idaman int ida_export_data | lookback
| Number of instructions to look back. More...
idaman flags_t ida_export_data | uFlag
| Flags value for the byte at the start of the current instruction. More...
idaman int ida_export_data | voidop
| see out_long()

## Enumeration Type Documentation

enum tribyte_order_t

3-byte (tribyte) data item order

Enumerator
tbo_123 | regular most significant byte first (big endian) - default
tbo_321 | regular least significant byte first (little endian)

## Function Documentation

idaman size_t ida_export get_operand_immvals | ( | ea_t | ea,
|  | int | n,
|  | uval_t * | v
| ) |  |

Get immediate values used in the operand if it fits into uval_t.

Parameters

  ea | linear address
  n | number of operand (0..UA_MAXOP-1), -1 means all operands
  v | array of immediate values (at least 2*UA_MAXOP elements)

Returns
  number of immediate values (0..2*UA_MAXOP)

idaman ea_t ida_export dataSeg_opreg | ( | int | opnum,
|  | int | rgnum
| ) |  |

Get data segment by operand.

'opnum' and 'rgnum' are meaningful only if the processor has segment registers.

idaman ea_t ida_export codeSeg | ( | ea_t | addr,
|  | int | opnum
| ) |  |

Get code segment.

This function takes into account the segment translations.

Parameters

  addr | the referenced address used by translations
  opnum | operand number

idaman bool ida_export ua_dodata2 | ( | int | opoff,
|  | ea_t | ea,
|  | int | dtype
| ) |  |

Convert to data using information about operand value type (op_t::dtyp).

Emulator could use this function to convert unexplored bytes to data when an instruction references them. This function creates data only if the address was unexplored.

Parameters

  opoff | offset of the operand from the start of instruction if the offset is unknown, then 0
  ea | linear address to be converted to data
  dtype | operand value type (from op_t::dtyp)

Return values

  1 | ok
  0 | failed to create data item

idaman bool ida_export ua_stkvar2 | ( | const op_t & | x,
|  | adiff_t | v,
|  | int | flags
| ) |  |

Create or modify a stack variable in the function frame.

The emulator could use this function to create stack variables in the function frame before converting the operand to a stack variable. Please check with may_create_stkvars() before calling this function.

Parameters

  x | operand (used to determine the addressing type)
  v | a displacement in the operand
  flags | Stack variable flags

Return values

  1 | ok, a stack variable exists now
  0 | no, couldn't create stack variable

idaman void ida_export ua_add_cref | ( | int | opoff,
|  | ea_t | to,
|  | cref_t | type
| ) |  |

Add a code cross-reference from the current instruction ( insn_t::ea).

Parameters

  opoff | offset of the operand from the start of instruction. if the offset is unknown, then 0.
  to | target linear address
  type | type of xref

idaman void ida_export ua_add_dref | ( | int | opoff,
|  | ea_t | to,
|  | dref_t | type
| ) |  |

Add a data cross-reference from the current instruction ( insn_t::ea).

See ua_add_off_drefs() - usually it can be used in most cases.

Parameters

  opoff | offset of the operand from the start of instruction if the offset is unknown, then 0
  to | target linear address
  type | type of xref

idaman ea_t ida_export ua_add_off_drefs | ( | const op_t & | x,
|  | dref_t | type
| ) |  |

Add xrefs for an operand of the current instruction ( insn_t::ea).

This function creates all cross references for 'offset' and 'structure offset' operands. Use ua_add_off_drefs2() in the presence of negative offsets.

Parameters

  x | reference to operand
  type | type of xref
  outf | OutValue() flags. These flags should match the flags used to output the operand

Returns
  if isOff(), the reference target address (the same as calc_reference_target). else, BADADDR, because for stroffs the target address is unknown

idaman int ida_export create_insn | ( | ea_t | ea | ) |

Create an instruction at the specified address.

This function checks if an instruction is present at the specified address and will try to create one if there is none. It will fail if there is a data item or other items hindering the creation of the new instruction. This function will also fill the cmd structure.

Parameters

  ea | linear address

Returns
  the length of the instruction or 0

idaman int ida_export decode_insn | ( | ea_t | ea | ) |

Analyze the specified address and fill cmd.

This function does not modify the database. It just tries to interpret the specified address as an instruction and fills the cmd structure with the results.

Parameters

  ea | linear address

Returns
  the length of the (possible) instruction or 0

idaman bool ida_export ua_outop2 | ( | ea_t | ea,
|  | char * | buf,
|  | size_t | bufsize,
|  | int | n,
|  | int | flags = `0`
| ) |  |

Generate text representation for operand #n.

This function will generate the text representation of the specified operand. If the instruction is not present in the database, it will be created. This function will also fill the cmd structure.

Parameters

  ea | linear address
  buf | output buffer
  bufsize | size of output buffer
  n | operand number (0,1,2...)
  flags | Name expression flags - Currently only GETN_NODUMMY is allowed.

Returns
  success

idaman const char* ida_export ua_mnem | ( | ea_t | ea,
|  | char * | buf,
|  | size_t | bufsize
| ) |  |

Generate text representation of the instruction mnemonics.

This function will generate the text representation of the instruction mnemonics, like 'mov', 'add', etc. If the instruction is not present in the database, it will be created. This function will also fill the cmd structure.

Parameters

  ea | linear address
  buf | output buffer
  bufsize | size of output buffer

Returns
  pointer to buf or NULL if failure

idaman ea_t ida_export decode_prev_insn | ( | ea_t | ea | ) |

Decode previous instruction if it exists, fill cmd.

Returns
  the previous instruction address (BADADDR-no such insn)

idaman ea_t ida_export decode_preceding_insn | ( | ea_t | ea,
|  | bool * | p_farref
| ) |  |

Decode preceding instruction in the execution flow.

Prefer far xrefs from addresses < the current to ordinary flows.

Returns
  the preceding instruction address (BADADDR-no such insn) and fill cmd. *p_farref will contain 'true' if followed an xref, false otherwise.

idaman bool ida_export construct_macro | ( | bool | enable,
|  | bool(idaapi *)(insn_t &s, bool may_go_forward) | build_macro
| ) |  |

Construct a macro instruction.

This function may be called from ana() to generate a macro instruction.

The real work is done by the 'build_macro()' parameter. This callback should be provided by the module writer.

Here we just create the instruction in the database when the macro generation is turned on/off.

Parameters

  enable | enable macro generation
  build_macro | try to grow the instruction in 'cmd' to a macro

Return values

  true | the macro instruction is generated in 's'
  false | no macro

idaman int ida_export get_spoiled_reg | ( | const uint32 * | regs,
|  | size_t | n
| ) |  |

Does the instruction in cmd spoil any register from 'regs'?.

This function checks the Instruction feature bits flags from the instructions array. Only o_reg operand types are consulted.

Returns
  index in the 'regs' array or -1

## Variable Documentation

idaman insn_t ida_export_data cmd

Structure holding information about the current instruction.

Analyzer should fill this structure.

idaman int ida_export_data lookback

Number of instructions to look back.

This variable is not used by the kernel. Its value may be specified in ida.cfg: LOOKBACK = <number>. IDP may use it as you like it. (TMS module uses it)

idaman flags_t ida_export_data uFlag

Flags value for the byte at the start of the current instruction.

(see bytes.hpp for explanation of flags). The kernel retrieves flags value and stores it in this variable for your convenience. Anytime you change the database by calling functions that change flags value you should refresh it using get_flags_novalue() uFlag does not contain MS_VAL and FF_IVL fields of flags, so please don't call hasValue() on it.