IDA SDK
Classes | Functions | Macros | Typedefs | Enumerations | Variables
idd.hpp File Reference

Detailed Description

Contains definition of the interface to IDD modules.

The interface consists of structures describing the target debugged processor and a debugging API.

Classes

struct  process_info_t
 Process information. More...
 
struct  debapp_attrs_t
 Runtime attributes of the debugger/process. More...
 
struct  register_info_t
 Debuggee register information. More...
 
struct  memory_info_t
 Used by debugger modules to report memory are information to IDA kernel. More...
 
struct  scattered_segm_t
 Used by debugger modules to keep track of images that are not mapped uniformly into memory. More...
 
struct  modinfo_t
 Describes a module load event. More...
 
struct  bptaddr_t
 Describes a breakpoint event. More...
 
struct  excinfo_t
 Describes an exception. More...
 
struct  debug_event_t
 This structure is used only when detailed information about a debug event is needed. More...
 
struct  exception_info_t
 Exception information. More...
 
struct  regval_t
 Structure to hold a register value. More...
 
struct  idd_opinfo_t
 Instruction operand information. More...
 
struct  call_stack_info_t
 Call stack trace information. More...
 
struct  update_bpt_info_t
 Input argument for update_bpts() More...
 
struct  lowcnd_t
 Input argument for update_lowcnds(). More...
 
struct  thread_name_t
 Output argument for ev_suspended New thread names. More...
 
struct  debugger_t
 This structure describes a debugger API module. More...
 

Functions

idaman THREAD_SAFE void ida_export free_debug_event (debug_event_t *ev)
 
idaman THREAD_SAFE void ida_export copy_debug_event (debug_event_t *ev, const debug_event_t &r)
 
idaman THREAD_SAFE void ida_export set_debug_event_code (debug_event_t *ev, event_id_t id)
 
idaman error_t ida_export dbg_appcall (idc_value_t *retval, ea_t func_ea, thid_t tid, const tinfo_t *ptif, idc_value_t *argv, size_t argnum)
 Call a function from the debugged application. More...
 
idaman error_t ida_export cleanup_appcall (thid_t tid)
 Cleanup after manual appcall. More...
 
 CASSERT (sizeof(debugger_t)==60)
 

Macros

#define IDD_INTERFACE_VERSION   24
 The IDD interface version number.
 
#define NO_PROCESS   pid_t(-1)
 No process.
 
#define NO_THREAD   0
 No thread. More...
 
#define DEF_ADDRSIZE   4
 Default address size - see debapp_attrs_t::addrsize.
 
#define REGISTER_READONLY   0x0001
 the user can't modify the current value of this register
 
#define REGISTER_IP   0x0002
 instruction pointer
 
#define REGISTER_SP   0x0004
 stack pointer
 
#define REGISTER_FP   0x0008
 frame pointer
 
#define REGISTER_ADDRESS   0x0010
 may contain an address
 
#define REGISTER_CS   0x0020
 code segment
 
#define REGISTER_SS   0x0040
 stack segment
 
#define REGISTER_NOLF   0x0080
 displays this register without returning to the next line More...
 
#define REGISTER_CUSTFMT   0x0100
 register should be displayed using a custom data format. More...
 
#define EXC_BREAK   0x0001
 break on the exception
 
#define EXC_HANDLE   0x0002
 should be handled by the debugger?
 
#define EXC_MSG   0x0004
 instead of a warning, log the exception to the output window
 
#define EXC_SILENT   0x0008
 do not warn or log to the output window
 
#define RVT_INT   (-1)
 integer
 
#define RVT_FLOAT   (-2)
 floating point
 
#define RVT_UNAVAILABLE   (-3)
 unavailable More...
 
#define STEP_TRACE   0x01
 
#define INSN_TRACE   0x02
 
#define FUNC_TRACE   0x04
 
#define BBLK_TRACE   0x08
 
#define DEBUGGER_ID_X86_IA32_WIN32_USER   0
 Userland win32 processes (win32 debugging APIs)
 
#define DEBUGGER_ID_X86_IA32_LINUX_USER   1
 Userland linux processes (ptrace())
 
#define DEBUGGER_ID_X86_IA32_MACOSX_USER   3
 Userland MAC OS X processes.
 
#define DEBUGGER_ID_ARM_IPHONE_USER   5
 iPhone 1.x
 
#define DEBUGGER_ID_X86_IA32_BOCHS   6
 BochsDbg.exe 32.
 
#define DEBUGGER_ID_6811_EMULATOR   7
 MC6812 emulator (beta)
 
#define DEBUGGER_ID_GDB_USER   8
 GDB remote.
 
#define DEBUGGER_ID_WINDBG   9
 WinDBG using Microsoft Debug engine.
 
#define DEBUGGER_ID_X86_DOSBOX_EMULATOR   10
 Dosbox MS-DOS emulator.
 
#define DEBUGGER_ID_ARM_LINUX_USER   11
 Userland arm linux.
 
#define DEBUGGER_ID_TRACE_REPLAYER   12
 Fake debugger to replay recorded traces.
 
#define DEBUGGER_ID_X86_PIN_TRACER   14
 PIN Tracer module.
 
#define DEBUGGER_ID_DALVIK_USER   15
 Dalvik.
 
#define DBG_FLAG_REMOTE   0x00000001
 Remote debugger (requires remote host name unless DBG_FLAG_NOHOST)
 
#define DBG_FLAG_NOHOST   0x00000002
 Remote debugger with does not require network params (host/port/pass). More...
 
#define DBG_FLAG_FAKE_ATTACH   0x00000004
 PROCESS_ATTACHED is a fake event More...
 
#define DBG_FLAG_HWDATBPT_ONE   0x00000008
 Hardware data breakpoints are. More...
 
#define DBG_FLAG_CAN_CONT_BPT   0x00000010
 Debugger knows to continue from a bpt. More...
 
#define DBG_FLAG_NEEDPORT   0x00000020
 Remote debugger requires port number (to be used with DBG_FLAG_NOHOST)
 
#define DBG_FLAG_DONT_DISTURB   0x00000040
 Debugger can handle only. More...
 
#define DBG_FLAG_SAFE   0x00000080
 The debugger is safe (probably because it just emulates the application. More...
 
#define DBG_FLAG_CLEAN_EXIT   0x00000100
 IDA must suspend the application and remove. More...
 
#define DBG_FLAG_USE_SREGS   0x00000200
 Take segment register values into account (non flat memory)
 
#define DBG_FLAG_NOSTARTDIR   0x00000400
 Debugger module doesn't use startup directory.
 
#define DBG_FLAG_NOPARAMETERS   0x00000800
 Debugger module doesn't use commandline parameters.
 
#define DBG_FLAG_NOPASSWORD   0x00001000
 Remote debugger doesn't use password.
 
#define DBG_FLAG_CONNSTRING   0x00002000
 Display "Connection string" instead of "Hostname" and hide the "Port" field.
 
#define DBG_FLAG_SMALLBLKS   0x00004000
 If set, IDA uses 256-byte blocks for caching memory contents. More...
 
#define DBG_FLAG_MANMEMINFO   0x00008000
 If set, manual memory region manipulation commands. More...
 
#define DBG_FLAG_EXITSHOTOK   0x00010000
 IDA may take a memory snapshot at PROCESS_EXITED event.
 
#define DBG_FLAG_VIRTHREADS   0x00020000
 Thread IDs may be shuffled after each debug event. More...
 
#define DBG_FLAG_LOWCNDS   0x00040000
 Low level breakpoint conditions are supported.
 
#define DBG_FLAG_DEBTHREAD   0x00080000
 Supports creation of a separate thread in ida. More...
 
#define DBG_FLAG_DEBUG_DLL   0x00100000
 Can debug standalone DLLs. More...
 
#define DBG_FLAG_FAKE_MEMORY   0x00200000
 get_memory_info()/read_memory()/write_memory() work with the idb. More...
 
#define DBG_FLAG_ANYSIZE_HWBPT   0x00400000
 The debugger supports arbitrary size hardware breakpoints.
 
#define DBG_FLAG_TRACER_MODULE   0x00800000
 The module is a tracer, not a full featured debugger module.
 
#define DBG_FLAG_PREFER_SWBPTS   0x01000000
 Prefer to use software breakpoints.
 
#define DBG_HAS_GET_PROCESSES   0x00000001
 supports ev_get_processes
 
#define DBG_HAS_ATTACH_PROCESS   0x00000002
 supports ev_attach_process
 
#define DBG_HAS_DETACH_PROCESS   0x00000004
 supports ev_detach_process
 
#define DBG_HAS_REQUEST_PAUSE   0x00000008
 supports ev_request_pause
 
#define DBG_HAS_SET_EXCEPTION_INFO   0x00000010
 supports ev_set_exception_info
 
#define DBG_HAS_THREAD_SUSPEND   0x00000020
 supports ev_thread_suspend
 
#define DBG_HAS_THREAD_CONTINUE   0x00000040
 supports ev_thread_continue
 
#define DBG_HAS_SET_RESUME_MODE   0x00000080
 supports ev_set_resume_mode More...
 
#define DBG_HAS_THREAD_GET_SREG_BASE   0x00000100
 supports ev_thread_get_sreg_base
 
#define DBG_HAS_CHECK_BPT   0x00000200
 supports ev_check_bpt
 
#define DBG_HAS_OPEN_FILE   0x00000400
 supports ev_open_file, ev_close_file, ev_read_file, ev_write_file
 
#define DBG_HAS_UPDATE_CALL_STACK   0x00000800
 supports ev_update_call_stack
 
#define DBG_HAS_APPCALL   0x00001000
 supports ev_appcall, ev_cleanup_appcall
 
#define DBG_HAS_REXEC   0x00002000
 supports ev_rexec
 
#define DBG_RESMOD_STEP_INTO   0x0001
 RESMOD_INTO is available
 
#define DBG_RESMOD_STEP_OVER   0x0002
 RESMOD_OVER is available
 
#define DBG_RESMOD_STEP_OUT   0x0004
 RESMOD_OUT is available
 
#define DBG_RESMOD_STEP_SRCINTO   0x0008
 RESMOD_SRCINTO is available
 
#define DBG_RESMOD_STEP_SRCOVER   0x0010
 RESMOD_SRCOVER is available
 
#define DBG_RESMOD_STEP_SRCOUT   0x0020
 RESMOD_SRCOUT is available
 
#define DBG_RESMOD_STEP_USER   0x0040
 RESMOD_USER is available
 
#define DBG_RESMOD_STEP_HANDLE   0x0080
 RESMOD_HANDLE is available
 
#define DEBUGGER_PORT_NUMBER   23946
 
#define DBG_PROC_IS_DLL   0x01
 database contains a dll (not exe)
 
#define DBG_PROC_IS_GUI   0x02
 using gui version of ida
 
#define DBG_PROC_32BIT   0x04
 application is 32-bit
 
#define DBG_PROC_64BIT   0x08
 application is 64-bit
 
#define DBG_NO_TRACE   0x10
 do not trace the application (mac/linux)
 
#define DBG_HIDE_WINDOW   0x20
 application should be hidden on startup (windows)
 
#define BPT_OK   0
 breakpoint can be set
 
#define BPT_INTERNAL_ERR   1
 interr occurred when verifying breakpoint
 
#define BPT_BAD_TYPE   2
 bpt type is not supported
 
#define BPT_BAD_ALIGN   3
 alignment is invalid
 
#define BPT_BAD_ADDR   4
 ea is invalid
 
#define BPT_BAD_LEN   5
 bpt len is invalid
 
#define BPT_TOO_MANY   6
 reached max number of supported breakpoints
 
#define BPT_READ_ERROR   7
 failed to read memory at bpt ea
 
#define BPT_WRITE_ERROR   8
 failed to write memory at bpt ea
 
#define BPT_SKIP   9
 update_bpts(): do not process bpt
 
#define BPT_PAGE_OK   10
 update_bpts(): ok, added a page bpt
 
#define APPCALL_MANUAL   0x0001
 Only set up the appcall, do not run. More...
 
#define APPCALL_DEBEV   0x0002
 Return debug event information.
 
#define APPCALL_TIMEOUT   0x0004
 Appcall with timeout. More...
 
#define SET_APPCALL_TIMEOUT(msecs)    ((uint(msecs) << 16)|APPCALL_TIMEOUT)
 Set appcall timeout in milliseconds.
 
#define GET_APPCALL_TIMEOUT(options)   (uint(options) >> 16)
 Timeout value is contained in high 2 bytes of 'options' parameter.
 
#define RQ_MASKING   0x0001
 
#define RQ_SUSPEND   0x0002
 
#define RQ_NOSUSP   0x0000
 
#define RQ_IGNWERR   0x0004
 
#define RQ_SILENT   0x0008
 
#define RQ_VERBOSE   0x0000
 
#define RQ_SWSCREEN   0x0010
 
#define RQ__NOTHRRF   0x0020
 
#define RQ_PROCEXIT   0x0040
 
#define RQ_IDAIDLE   0x0080
 
#define RQ_SUSPRUN   0x0100
 
#define RQ_RESUME   0x0200
 
#define RQ_RESMOD   0xF000
 
#define RQ_RESMOD_SHIFT   12
 
#define RQ_INTO   (RESMOD_INTO << RQ_RESMOD_SHIFT)
 

Typedefs

typedef int pid_t
 process id
 
typedef int thid_t
 thread id
 
typedef qvector< process_info_tprocinfo_vec_t
 
typedef unsigned char register_class_t
 Each register is associated to a register class. More...
 
typedef qvector< memory_info_tmeminfo_vec_t
 vector of memory info objects
 
typedef qvector< scattered_segm_tscattered_image_t
 vector of scattered segments
 
typedef int bpttype_t
 hardware breakpoint type (see Hardware breakpoint ids)
 
typedef qvector< exception_info_texcvec_t
 vector of exception info objects
 
typedef qvector< regval_tregvals_t
 vector register value objects
 
typedef qvector< call_stack_info_tcall_stack_t
 
typedef qvector< update_bpt_info_tupdate_bpt_vec_t
 vector of update breakpoint info objects
 
typedef qvector< lowcnd_tlowcnd_vec_t
 vector of low-level breakpoint conditions
 
typedef qvector< thread_name_tthread_name_vec_t
 vector of thread names
 

Enumerations

enum  event_id_t {
  NO_EVENT = 0x00000000, PROCESS_STARTED = 0x00000001, PROCESS_EXITED = 0x00000002, THREAD_STARTED = 0x00000004,
  THREAD_EXITED = 0x00000008, BREAKPOINT = 0x00000010, STEP = 0x00000020, EXCEPTION = 0x00000040,
  LIB_LOADED = 0x00000080, LIB_UNLOADED = 0x00000100, INFORMATION = 0x00000200, PROCESS_ATTACHED = 0x00000400,
  PROCESS_DETACHED = 0x00000800, PROCESS_SUSPENDED = 0x00001000, TRACE_FULL = 0x00002000
}
 Debug event codes. More...
 
enum  gdecode_t { GDE_ERROR = -1, GDE_NO_EVENT, GDE_ONE_EVENT, GDE_MANY_EVENTS }
 Return values for get_debug_event() More...
 
enum  resume_mode_t {
  RESMOD_NONE, RESMOD_INTO, RESMOD_OVER, RESMOD_OUT,
  RESMOD_SRCINTO, RESMOD_SRCOVER, RESMOD_SRCOUT, RESMOD_USER,
  RESMOD_HANDLE, RESMOD_MAX
}
 How to resume the application. More...
 
enum  drc_t {
  DRC_EVENTS = 3, DRC_CRC = 2, DRC_OK = 1, DRC_NONE = 0,
  DRC_FAILED = -1, DRC_NETERR = -2, DRC_NOFILE = -3, DRC_IDBSEG = -4,
  DRC_NOPROC = -5, DRC_NOCHG = -6, DRC_ERROR = -7
}
 Debugger return codes. More...
 

Variables

const bpttype_t BPT_WRITE = 1
 Write access.
 
const bpttype_t BPT_READ = 2
 Read access.
 
const bpttype_t BPT_RDWR = 3
 Read/write access.
 
const bpttype_t BPT_SOFT = 4
 Software breakpoint.
 
const bpttype_t BPT_EXEC = 8
 Execute instruction.
 
const bpttype_t BPT_DEFAULT = (BPT_SOFT|BPT_EXEC)
 Choose bpt type automatically.
 

Macro Definition Documentation

#define NO_THREAD   0

No thread.

in PROCESS_STARTED this value can be used to specify that the main thread has not been created. It will be initialized later by a THREAD_STARTED event.

Typedef Documentation

typedef unsigned char register_class_t

Each register is associated to a register class.

example: "segment", "mmx", ...

Enumeration Type Documentation

enum event_id_t

Debug event codes.

Enumerator
NO_EVENT 

Not an interesting event.

This event can be used if the debugger module needs to return an event but there are no valid events.

PROCESS_STARTED 

New process has been started.

PROCESS_EXITED 

Process has been stopped.

THREAD_STARTED 

New thread has been started.

THREAD_EXITED 

Thread has been stopped.

BREAKPOINT 

Breakpoint has been reached.

IDA will complain about unknown breakpoints, they should be reported as exceptions.

STEP 

One instruction has been executed.

Spurious events of this kind are silently ignored by IDA.

EXCEPTION 

Exception.

LIB_LOADED 

New library has been loaded.

LIB_UNLOADED 

Library has been unloaded.

INFORMATION 

User-defined information.

This event can be used to return empty information This will cause IDA to call get_debug_event() immediately once more.

PROCESS_ATTACHED 

Successfully attached to running process.

PROCESS_DETACHED 

Successfully detached from process.

PROCESS_SUSPENDED 

Process has been suspended.

This event can be used by the debugger module to signal if the process spontaneously gets suspended (not because of an exception, breakpoint, or single step). IDA will silently switch to the 'suspended process' mode without displaying any messages.

TRACE_FULL 

The trace buffer of the tracer module is full and IDA needs to read it before continuing.

enum gdecode_t

Return values for get_debug_event()

Enumerator
GDE_ERROR 

error

GDE_NO_EVENT 

no debug events are available

GDE_ONE_EVENT 

got one event, no more available yet

GDE_MANY_EVENTS 

got one event, more events available

How to resume the application.

The corresponding bit for Debugger module features must be set in order to use a resume mode.

Enumerator
RESMOD_NONE 

no stepping, run freely

RESMOD_INTO 

step into call (the most typical single stepping)

RESMOD_OVER 

step over call

RESMOD_OUT 

step out of the current function (run until return)

RESMOD_SRCINTO 

until control reaches a different source line

RESMOD_SRCOVER 

next source line in the current stack frame

RESMOD_SRCOUT 

next source line in the previous stack frame

RESMOD_USER 

step out to the user code

RESMOD_HANDLE 

step into the exception handler

enum drc_t

Debugger return codes.

Success if positive (> DRC_NONE).

Enumerator
DRC_EVENTS 

success, there are pending events

DRC_CRC 

success, but the input file crc does not match

DRC_OK 

success

DRC_NONE 

reaction to the event not implemented

DRC_FAILED 

failed or false

DRC_NETERR 

network error

DRC_NOFILE 

file not found

DRC_IDBSEG 

use idb segmentation

DRC_NOPROC 

the process does not exist anymore

DRC_NOCHG 

no changes

DRC_ERROR 

unclassified error, may be complemented by errbuf

Function Documentation

idaman error_t ida_export dbg_appcall ( idc_value_t retval,
ea_t  func_ea,
thid_t  tid,
const tinfo_t ptif,
idc_value_t argv,
size_t  argnum 
)

Call a function from the debugged application.

Parameters
[out]rfunction return value
  • for APPCALL_MANUAL, r will hold the new stack point value
  • for APPCALL_DEBEV, r will hold the exception information upon failure and the return code will be eExecThrow
func_eaaddress to call
tidthread to use. NO_THREAD means to use the current thread
ptifpointer to type of the function to call
argvarray of arguments
argnumnumber of actual arguments
Returns
eOk if successful, otherwise an error code
idaman error_t ida_export cleanup_appcall ( thid_t  tid)

Cleanup after manual appcall.

Parameters
tidthread to use. NO_THREAD means to use the current thread The application state is restored as it was before calling the last appcall(). Nested appcalls are supported.
Returns
eOk if successful, otherwise an error code