| 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 | dynamic_register_set_t
struct | memory_info_t
| Used by debugger modules to report memory are information to IDA kernel. More...
struct | meminfo_vec_t
| vector of memory info objects More...
struct | scattered_segm_t
| Used by debugger modules to keep track of images that are not mapped uniformly into memory. More...
struct | launch_env_t
| Used by debugger modules to launching processes with environment variables. 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...

## Functions
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 | serialize_insn (bytevec_t *s, const insn_t &insn)
idaman THREAD_SAFE void ida_export | deserialize_insn (insn_t *insn, 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)
idaman int ida_export | cpu2ieee (fpvalue_t *ieee_out, const void *cpu_fpval, int size)
| Convert a floating point number in CPU native format to IDA's internal format. More...
idaman int ida_export | ieee2cpu (void *cpu_fpval_out, const fpvalue_t &ieee, int size)
| Convert a floating point number in IDA's internal format to CPU native format. More...

## Macros
#define | IDD_INTERFACE_VERSION 30
| 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_FLOAT (-1)
| floating point
#define | RVT_INT (-2)
| integer
#define | RVT_UNAVAILABLE (-3)
| unavailable; other values mean custom data type
#define | STEP_TRACE 0x01
| lowest level trace. trace buffers are not maintained
#define | INSN_TRACE 0x02
| instruction tracing
#define | FUNC_TRACE 0x04
| function tracing
#define | BBLK_TRACE 0x08
| basic block tracing
#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 | DEBUGGER_ID_XNU_USER 16
| XNU Kernel.
#define | DEBUGGER_ID_ARM_MACOS_USER 17
| 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_FLAG_ADD_ENVS 0x08000000
| The debugger supports launching processes with environment variables.
#define | DBG_FLAG_MERGE_ENVS 0x10000000
| The debugger supports merge or replace setting for environment variables (only makes sense if DBG_FLAG_ADD_ENVS is set)
#define | DBG_FLAG_DISABLE_ASLR 0x20000000
| The debugger support ASLR disabling (Address space layout randomization)
#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 | DBG_NO_ASLR 0x80
| disable ASLR (linux)
#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
| masking step handler: unless errors, tmpbpt handlers won't be generated should be used only with request_internal_step()
#define | RQ_SUSPEND 0x0002
| suspending step handler: suspends the app handle_debug_event: suspends the app
#define | RQ_NOSUSP 0x0000
| running step handler: continues the app
#define | RQ_IGNWERR 0x0004
| ignore breakpoint write failures
#define | RQ_SILENT 0x0008
| all: no dialog boxes
#define | RQ_VERBOSE 0x0000
| all: display dialog boxes
#define | RQ_SWSCREEN 0x0010
| handle_debug_event: switch screens
#define | RQ__NOTHRRF 0x0020
| handle_debug_event: do not refresh threads
#define | RQ_PROCEXIT 0x0040
| snapshots: the process is exiting
#define | RQ_IDAIDLE 0x0080
| handle_debug_event: ida is idle
#define | RQ_SUSPRUN 0x0100
| handle_debug_event: suspend at PROCESS_STARTED
#define | RQ_RESUME 0x0200
| handle_debug_event: resume application
#define | RQ_RESMOD 0xF000
| resume_mode_t
#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_t > | procinfo_vec_t
typedef unsigned char | register_class_t
| Each register is associated to a register class. More...
typedef qvector< register_info_t > | register_info_vec_t
typedef qvector< scattered_segm_t > | scattered_image_t
| vector of scattered segments
typedef qvector< modinfo_t > | modinfovec_t
typedef int | bpttype_t
| hardware breakpoint type (see Hardware breakpoint ids)
typedef qvector< exception_info_t > | excvec_t
| vector of exception info objects
typedef qvector< regval_t > | regvals_t
| vector register value objects
typedef qvector< update_bpt_info_t > | update_bpt_vec_t
| vector of update breakpoint info objects
typedef qvector< lowcnd_t > | lowcnd_vec_t
| vector of low-level breakpoint conditions
typedef qvector< thread_name_t > | thread_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

## ◆ NO_THREAD

#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

## ◆ 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.

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.

## ◆ gdecode_t

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

## ◆ resume_mode_t

enum 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.

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

## ◆ drc_t

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

## ◆ 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.

Parameters

  [out] | retval | function 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_ea | address to call
  | tid | thread to use. NO_THREAD means to use the current thread
  | ptif | pointer to type of the function to call
  | argv | array of arguments
  | argnum | number of actual arguments

Returns
  eOk if successful, otherwise an error code

## ◆ cleanup_appcall()

idaman error_t ida_export cleanup_appcall | ( | thid_t | tid | ) |

Cleanup after manual appcall.

Parameters

  tid | thread 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

## ◆ cpu2ieee()

idaman int ida_export cpu2ieee | ( | fpvalue_t * | ieee_out,
|  | const void * | cpu_fpval,
|  | int | size
| ) |  |

Convert a floating point number in CPU native format to IDA's internal format.

Parameters

  ieee_out | output buffer
  cpu_fpval | floating point number in CPU native format
  size | size of cpu_fpval in bytes (size of the input buffer)

Returns
  Floating point/IEEE Conversion codes

## ◆ ieee2cpu()

idaman int ida_export ieee2cpu | ( | void * | cpu_fpval_out,
|  | const fpvalue_t & | ieee,
|  | int | size
| ) |  |

Convert a floating point number in IDA's internal format to CPU native format.

Parameters

  cpu_fpval_out | output buffer
  ieee | floating point number of IDA's internal format
  size | size of cpu_fpval in bytes (size of the output buffer)

Returns
  Floating point/IEEE Conversion codes