Hex-Rays logo State-of-the-art binary code analysis tools
email icon
idd.hpp File Reference

Contains definition of the interface to IDD modules. More...


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  dynamic_register_set_t
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  call_stack_t
 defined as struct so it can be forward-declared 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...


 The IDD interface version number.
#define NO_PROCESS   pid_t(-1)
 No process.
#define NO_THREAD   0
 No thread. More...
#define DEF_ADDRSIZE   4
#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, allowing the next register to be displayed to its right (on the same line)
#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)
#define RVT_FLOAT   (-2)
 floating point
#define RVT_UNAVAILABLE   (-3)
 unavailable; other values mean custom data type
#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)
 Userland linux processes (ptrace())
 Userland MAC OS X processes.
 iPhone 1.x
#define DEBUGGER_ID_X86_IA32_BOCHS   6
 BochsDbg.exe 32.
#define DEBUGGER_ID_6811_EMULATOR   7
 MC6812 emulator (beta)
 GDB remote.
 WinDBG using Microsoft Debug engine.
 Dosbox MS-DOS emulator.
 Userland arm linux.
 Fake debugger to replay recorded traces.
 PIN Tracer module.
 XNU Kernel.
 Userland arm MAC OS.
#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 and does not suspend the execution
#define DBG_FLAG_HWDATBPT_ONE   0x00000008
 Hardware data breakpoints are one byte size by default.
#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 get_debug_event(), request_pause(), exit_process() when the debugged process is running. More...
#define DBG_FLAG_SAFE   0x00000080
 The debugger is safe (probably because it just emulates the application without really running it)
#define DBG_FLAG_CLEAN_EXIT   0x00000100
 IDA must suspend the application and remove all breakpoints before terminating the application. 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 will be available. 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 for the debugger (the debthread). 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_FLAG_LAZY_WATCHPTS   0x02000000
 Watchpoints are triggered before the offending instruction is executed. More...
#define DBG_FLAG_FAST_STEP   0x04000000
 Do not refresh memory layout info after single stepping.
#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_HAS_MAP_ADDRESS   0x00004000
 supports ev_map_address. More...
#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 DBG_SUSPENDED   0x40
 application should be suspended on startup (mac)
#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


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< register_info_tregister_info_vec_t
typedef qvector< memory_info_tmeminfo_vec_t
 vector of memory info objects
typedef qvector< scattered_segm_tscattered_image_t
 vector of scattered segments
typedef qvector< modinfo_tmodinfovec_t
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< 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


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...
 Return values for get_debug_event() More...
enum  resume_mode_t {
 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...


idaman THREAD_SAFE void ida_export serialize_dynamic_register_set (bytevec_t *buf, dynamic_register_set_t &idaregs)
idaman THREAD_SAFE void ida_export deserialize_dynamic_register_set (dynamic_register_set_t *idaregs, memory_deserializer_t &mmdsr)
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)
THREAD_SAFE void append_regval (bytevec_t &s, const regval_t &value)
template<class T >
THREAD_SAFE void extract_regval (regval_t *out, T &v)
template<class T >
THREAD_SAFE void extract_regvals (regval_t *values, int n, T &v, const uchar *regmap)
THREAD_SAFE void unpack_regvals (regval_t *values, int n, const uchar *regmap, memory_deserializer_t &mmdsr)
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)


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.

Detailed Description

Contains definition of the interface to IDD modules.

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

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.


#define REGISTER_CUSTFMT   0x0100

register should be displayed using a custom data format.

the format name is in bit_strings[0]; the corresponding regval_t will use bytevec_t


#define DBG_FLAG_NOHOST   0x00000002

Remote debugger with does not require network params (host/port/pass).

(a unique device connected to the machine)


#define DBG_FLAG_CAN_CONT_BPT   0x00000010

Debugger knows to continue from a bpt.

This flag also means that the debugger module hides breakpoints from ida upon read_memory


#define DBG_FLAG_DONT_DISTURB   0x00000040

Debugger can handle only get_debug_event(), request_pause(), exit_process() when the debugged process is running.

The kernel may also call service functions (file I/O, map_address, etc)


#define DBG_FLAG_CLEAN_EXIT   0x00000100

IDA must suspend the application and remove all breakpoints before terminating the application.

Usually this is not required because the application memory disappears upon termination.


#define DBG_FLAG_SMALLBLKS   0x00004000

If set, IDA uses 256-byte blocks for caching memory contents.

Otherwise, 1024-byte blocks are used


#define DBG_FLAG_MANMEMINFO   0x00008000

If set, manual memory region manipulation commands will be available.

Use this bit for debugger modules that cannot return memory layout information


#define DBG_FLAG_VIRTHREADS   0x00020000

Thread IDs may be shuffled after each debug event.

(to be used for virtual threads that represent cpus for windbg kmode)


#define DBG_FLAG_DEBTHREAD   0x00080000

Supports creation of a separate thread in ida for the debugger (the debthread).

Most debugger functions will be called from debthread (exceptions are marked below) The debugger module may directly call only THREAD_SAFE functions. To call other functions please use execute_sync(). The debthread significantly increases debugging speed, especially if debug events occur frequently.


#define DBG_FLAG_DEBUG_DLL   0x00100000

Can debug standalone DLLs.

For example, Bochs debugger can debug any snippet of code


#define DBG_FLAG_FAKE_MEMORY   0x00200000

get_memory_info()/read_memory()/write_memory() work with the idb.

(there is no real process to read from, as for the replayer module) the kernel will not call these functions if this flag is set. however, third party plugins may call them, they must be implemented.


#define DBG_FLAG_LAZY_WATCHPTS   0x02000000

Watchpoints are triggered before the offending instruction is executed.

The debugger must temporarily disable the watchpoint and single-step before resuming.


#define DBG_HAS_SET_RESUME_MODE   0x00000080

supports ev_set_resume_mode.

Cannot be set inside the debugger_t::init_debugger()


#define DBG_HAS_MAP_ADDRESS   0x00004000

supports ev_map_address.

Avoid using this bit, especially together with DBG_FLAG_DEBTHREAD because it may cause big slow downs


#define APPCALL_MANUAL   0x0001

Only set up the appcall, do not run.

debugger_t::cleanup_appcall will not be generated by ida!


#define APPCALL_TIMEOUT   0x0004

Appcall with timeout.

If timed out, errbuf will contain "timeout". See SET_APPCALL_TIMEOUT and GET_APPCALL_TIMEOUT

Typedef Documentation

◆ register_class_t

typedef unsigned char register_class_t

Each register is associated to a register class.

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

Enumeration Type Documentation

◆ event_id_t

enum event_id_t

Debug event codes.


Not an interesting event.

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


New process has been started.


Process has been stopped.


New thread has been started.


Thread has been stopped.


Breakpoint has been reached.

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


One instruction has been executed.

Spurious events of this kind are silently ignored by IDA.




New library has been loaded.


Library has been unloaded.


User-defined information.

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


Successfully attached to running process.


Successfully detached from process.


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.


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

◆ gdecode_t

enum gdecode_t

Return values for get_debug_event()




no debug events are available


got one event, no more available yet


got one event, more events available

◆ resume_mode_t

How to resume the application.

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


no stepping, run freely


step into call (the most typical single stepping)


step over call


step out of the current function (run until return)


until control reaches a different source line


next source line in the current stack frame


next source line in the previous stack frame


step out to the user code


step into the exception handler

◆ drc_t

enum drc_t

Debugger return codes.

Success if positive (> DRC_NONE).


success, there are pending events


success, but the input file crc does not match




reaction to the event not implemented


failed or false


network error


file not found


use idb segmentation


the process does not exist anymore


no changes


unclassified error, may be complemented by errbuf

Function Documentation

◆ dbg_appcall()

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.

[out]retvalfunction 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
eOk if successful, otherwise an error code

◆ cleanup_appcall()

idaman error_t ida_export cleanup_appcall ( thid_t  tid)

Cleanup after manual appcall.

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.
eOk if successful, otherwise an error code