IDA SDK

- Main Page
- Header Files
- Classes
- Modules

- File List
- File Members

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 | module_info_t
| Describes a module load event. More...
struct | e_breakpoint_t
| Describes a breakpoint event. More...
struct | e_exception_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
| Describes a call stack. More...
struct | update_bpt_info_t
| Input argument for update_bpts() More...
struct | lowcnd_t
| Input argument for update_lowcnds(). More...
struct | debugger_t
| This structure describes a debugger API module. More...

## Functions
idaman error_t ida_export | dbg_appcall (ea_t func_ea, thid_t tid, const tinfo_t *tif, int argnum, idc_value_t *argv, idc_value_t *r)
| 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)%4)==0)

## Macros
#define | IDD_INTERFACE_VERSION 21
| The IDD interface version number.
#define | NO_PROCESS pid_t(0xFFFFFFFF)
| 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. More...
#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_ARM_WINCE_ASYNC 2
| Windows CE ARM (ActiveSync transport)
#define | DEBUGGER_ID_X86_IA32_MACOSX_USER 3
| Userland MAC OS X processes.
#define | DEBUGGER_ID_ARM_EPOC_USER 4
| Symbian OS.
#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_ARM_WINCE_TCPIP 13
| Windows CE ARM (TPC/IP transport)
#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_ATTACH 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_EXIT 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_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 | CRC32_MISMATCH 0x40000000
| crc32 mismatch bit (see return values for debugger_t::start_process)
#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 unsigned char | register_class_t
| Each register is associated to a register class. More...
typedef qvector< memory_info_t > | meminfo_vec_t
| vector of memory info objects
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

## Enumerations
enum | event_id_t { NO_EVENT = 0x00000000, PROCESS_START = 0x00000001, PROCESS_EXIT = 0x00000002, THREAD_START = 0x00000004, THREAD_EXIT = 0x00000008, BREAKPOINT = 0x00000010, STEP = 0x00000020, EXCEPTION = 0x00000040, LIBRARY_LOAD = 0x00000080, LIBRARY_UNLOAD = 0x00000100, INFORMATION = 0x00000200, SYSCALL = 0x00000400, WINMESSAGE = 0x00000800, PROCESS_ATTACH = 0x00001000, PROCESS_DETACH = 0x00002000, PROCESS_SUSPEND = 0x00004000, TRACE_FULL = 0x00008000 }
| 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...

## Variables
const bpttype_t | BPT_OLD_EXEC = 0
| obsolete: see BPT_EXEC
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_START this value can be used to specify that the main thread has not been created. It will be initialized later by a THREAD_START 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_START | New process has been started.
PROCESS_EXIT | Process has been stopped.
THREAD_START | New thread has been started.
THREAD_EXIT | 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.
LIBRARY_LOAD | New library has been loaded.
LIBRARY_UNLOAD | 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.
SYSCALL | Syscall (not used yet).
WINMESSAGE | Window message (not used yet).
PROCESS_ATTACH | Successfully attached to running process.
PROCESS_DETACH | Successfully detached from process.
PROCESS_SUSPEND | 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

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

## Function Documentation

idaman error_t ida_export dbg_appcall | ( | ea_t | func_ea,
|  | thid_t | tid,
|  | const tinfo_t * | tif,
|  | int | argnum,
|  | idc_value_t * | argv,
|  | idc_value_t * | r
| ) |  |

Call a function from the debugged application.

Parameters

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

Returns
  eOk if successful, otherwise an error code

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