IDA SDK
Public Attributes | Public Member Functions | Public Types | List of all members
debugger_t Struct Reference

Detailed Description

This structure describes a debugger API module.

(functions needed to debug a process on a specific operating system).

The address of this structure must be put into the dbg variable by the plugin_t::init() function of the debugger plugin.

Public Attributes

int version
 Expected kernel version, should be IDD_INTERFACE_VERSION.
 
const char * name
 Short debugger name like win32 or linux.
 
int id
 one of Debugger API module id
 
const char * processor
 Required processor name. More...
 
uint32 flags
 
uint32 flags2
 Debugger module features
 
const char ** regclasses
 Array of register class names.
 
int default_regclasses
 Mask of default printed register classes.
 
register_info_tregisters
 Array of registers. Use regs() to access it.
 
int nregs
 Number of registers.
 
int memory_page_size
 Size of a memory page.
 
const ucharbpt_bytes
 Array of bytes for a breakpoint instruction.
 
uchar bpt_size
 Size of this array.
 
uchar filetype
 for miniidbs: use this value for the file type after attaching to a new process
 
ushort resume_modes
 Resume modes
 
const char *(idaapiset_dbg_options )(const char *keyword, int pri, int value_type, const void *value)
 Set debugger options (parameters that are specific to the debugger module). More...
 
hook_cb_tcallback
 Event notification callback. More...
 

Public Member Functions

bool is_remote (void) const
 
bool must_have_hostname (void) const
 
bool can_continue_from_bpt (void) const
 
bool may_disturb (void) const
 
bool is_safe (void) const
 
bool use_sregs (void) const
 
size_t cache_block_size (void) const
 
bool use_memregs (void) const
 
bool may_take_exit_snapshot (void) const
 
bool virtual_threads (void) const
 
bool supports_lowcnds (void) const
 
bool supports_debthread (void) const
 
bool can_debug_standalone_dlls (void) const
 
bool fake_memory (void) const
 
bool has_get_processes (void) const
 
bool has_attach_process (void) const
 
bool has_detach_process (void) const
 
bool has_request_pause (void) const
 
bool has_set_exception_info (void) const
 
bool has_thread_suspend (void) const
 
bool has_thread_continue (void) const
 
bool has_set_resume_mode (void) const
 
bool has_thread_get_sreg_base (void) const
 
bool has_check_bpt (void) const
 
bool has_open_file (void) const
 
bool has_update_call_stack (void) const
 
bool has_appcall (void) const
 
bool has_rexec (void) const
 
register_info_tregs (int idx)
 
bool is_resmod_avail (int resmod) const
 
ssize_t notify (event_t event_code,...)
 Event notification handler.
 
drc_t notify_drc (event_t event_code,...)
 
bool init_debugger (const char *hostname, int portnum, const char *password, qstring *errbuf=NULL)
 
bool term_debugger (void)
 
drc_t get_processes (procinfo_vec_t *procs, qstring *errbuf=NULL)
 
drc_t start_process (const char *path, const char *args, const char *startdir, uint32 dbg_proc_flags, const char *input_path, uint32 input_file_crc32, qstring *errbuf=NULL)
 
drc_t attach_process (pid_t pid, int event_id, uint32 dbg_proc_flags, qstring *errbuf=NULL)
 
drc_t detach_process (qstring *errbuf=NULL)
 
bool get_debapp_attrs (debapp_attrs_t *out_pattrs)
 
void rebase_if_required_to (ea_t new_base)
 
drc_t request_pause (qstring *errbuf=NULL)
 
drc_t exit_process (qstring *errbuf=NULL)
 
gdecode_t get_debug_event (debug_event_t *event, int timeout_ms)
 
drc_t resume (const debug_event_t *event, qstring *errbuf=NULL)
 
void set_exception_info (const exception_info_t *info, int qty)
 
void suspended (bool dlls_added, thread_name_vec_t *thr_names=NULL)
 
drc_t thread_suspend (thid_t tid, qstring *errbuf=NULL)
 
drc_t thread_continue (thid_t tid, qstring *errbuf=NULL)
 
drc_t set_resume_mode (thid_t tid, resume_mode_t resmod, qstring *errbuf=NULL)
 
drc_t read_registers (thid_t tid, int clsmask, regval_t *values, qstring *errbuf=NULL)
 
drc_t write_register (thid_t tid, int regidx, const regval_t *value, qstring *errbuf=NULL)
 
drc_t thread_get_sreg_base (ea_t *answer, thid_t tid, int sreg_value, qstring *errbuf=NULL)
 
drc_t get_memory_info (meminfo_vec_t &ranges, qstring *errbuf=NULL)
 
drc_t read_memory (size_t *nbytes, ea_t ea, void *buffer, size_t size, qstring *errbuf=NULL)
 
drc_t write_memory (size_t *nbytes, ea_t ea, const void *buffer, size_t size, qstring *errbuf=NULL)
 
drc_t check_bpt (int *bptvc, bpttype_t type, ea_t ea, int len)
 
drc_t update_bpts (int *nbpts, update_bpt_info_t *bpts, int nadd, int ndel, qstring *errbuf=NULL)
 
drc_t update_lowcnds (int *nupdated, const lowcnd_t *lowcnds, int nlowcnds, qstring *errbuf=NULL)
 
int open_file (const char *file, uint64 *fsize, bool readonly, qstring *errbuf=NULL)
 
void close_file (int fn)
 
ssize_t read_file (int fn, qoff64_t off, void *buf, size_t size, qstring *errbuf=NULL)
 
ssize_t write_file (int fn, qoff64_t off, const void *buf, size_t size, qstring *errbuf=NULL)
 
ea_t map_address (ea_t off, const regval_t *regs, int regnum)
 
const void * get_debmod_extensions (void)
 
bool update_call_stack (thid_t tid, call_stack_t *trace)
 
ea_t appcall (ea_t func_ea, thid_t tid, const struct func_type_data_t *fti, int nargs, const struct regobjs_t *regargs, struct relobj_t *stkargs, struct regobjs_t *retregs, qstring *errbuf, debug_event_t *event, int options)
 
drc_t cleanup_appcall (thid_t tid)
 
drc_t eval_lowcnd (thid_t tid, ea_t ea, qstring *errbuf=NULL)
 
drc_t send_ioctl (int fn, const void *buf, size_t size, void **poutbuf, ssize_t *poutsize, qstring *errbuf=NULL)
 
bool dbg_enable_trace (thid_t tid, bool enable, int trace_flags)
 
bool is_tracing_enabled (thid_t tid, int tracebit)
 
int rexec (const char *cmdline)
 
bool get_srcinfo_path (qstring *path, ea_t base)
 
drc_t bin_search (ea_t *out, ea_t start_ea, ea_t end_ea, const compiled_binpat_vec_t &data, int srch_flags, qstring *errbuf=NULL)
 

Public Types

enum  event_t {
  ev_init_debugger, ev_term_debugger, ev_get_processes, ev_start_process,
  ev_attach_process, ev_detach_process, ev_get_debapp_attrs, ev_rebase_if_required_to,
  ev_request_pause, ev_exit_process, ev_get_debug_event, ev_resume,
  ev_set_exception_info, ev_suspended, ev_thread_suspend, ev_thread_continue,
  ev_set_resume_mode, ev_read_registers, ev_write_register, ev_thread_get_sreg_base,
  ev_get_memory_info, ev_read_memory, ev_write_memory, ev_check_bpt,
  ev_update_bpts, ev_update_lowcnds, ev_open_file, ev_close_file,
  ev_read_file, ev_write_file, ev_map_address, ev_get_debmod_extensions,
  ev_update_call_stack, ev_appcall, ev_cleanup_appcall, ev_eval_lowcnd,
  ev_send_ioctl, ev_dbg_enable_trace, ev_is_tracing_enabled, ev_rexec,
  ev_get_srcinfo_path, ev_bin_search
}
 Callback notification codes. More...
 
Threads

The following events manipulate threads.

These events are generated in debthread.

Returns
DRC_OK, DRC_FAILED, DRC_NETERR
Memory manipulation

The following events manipulate bytes in the memory.

Remote file

Open/close/read/write a remote file.

These events are generated in the main thread Available if DBG_HAS_OPEN_FILE is set

Member Enumeration Documentation

Callback notification codes.

They are passed to notify() when certain events occur in the kernel, allowing the debugger plugin to take appropriate actions.

Debugger plugins must implement the desired reaction to these events in the notify() function.

The notify() function should not be called directly. See inline functions below.

Enumerator
ev_init_debugger 

Initialize debugger.

This event is generated in the main thread.

Parameters
hostname(const char *)
portnum(int)
password(const char *)
errbuf(qstring *) may be NULL
Returns
DRC_OK, DRC_FAILED
ev_term_debugger 

Terminate debugger.

This event is generated in the main thread.

Returns
DRC_OK, DRC_FAILED
ev_get_processes 

Return information about the running processes.

This event is generated in the main thread. Available if DBG_HAS_GET_PROCESSES is set

Parameters
procs(::procinfo_vec_t *)
errbuf(qstring *) may be NULL
Returns
DRC_NONE, DRC_OK, DRC_FAILED, DRC_NETERR
ev_start_process 

Start an executable to debug.

This event is generated in debthread. Must be implemented.

Parameters
path(const char *) path to executable
args(const char *) arguments to pass to executable
startdir(const char *) initial working directory of new process
dbg_proc_flags(uint32) Debug process flags
input_path(const char *) path to the file that was used to create the idb file It is not always the same as 'path' - e.g. if we are analyzing a dll and want to launch an executable that loads it.
input_file_crc32(uint32) CRC value for 'input_path'
errbuf(qstring *) may be NULL
Returns
DRC_OK, DRC_CRC, DRC_FAILED, DRC_NETERR, DRC_NOFILE
ev_attach_process 

Attach to an existing running process.

event_id should be equal to -1 if not attaching to a crashed process. This event is generated in debthread. Available if DBG_HAS_ATTACH_PROCESS is set

Parameters
pid(pid_t) process id to attach
event_id(int) event to trigger upon attaching
dbg_proc_flags(uint32) Debug process flags
errbuf(qstring *) may be NULL
Returns
DRC_NONE, DRC_OK, DRC_FAILED, DRC_NETERR
ev_detach_process 

Detach from the debugged process.

May be generated while the process is running or suspended. Must detach from the process in any case. The kernel will repeatedly call get_debug_event() until PROCESS_DETACHED is received. In this mode, all other events will be automatically handled and process will be resumed. This event is generated from debthread. Available if DBG_HAS_DETACH_PROCESS is set

Returns
DRC_NONE, DRC_OK, DRC_FAILED, DRC_NETERR
ev_get_debapp_attrs 

Retrieve process- and debugger-specific runtime attributes.

This event is generated in the main thread.

Parameters
out_pattrs(debapp_attrs_t *)
Returns
DRC_NONE, DRC_OK
ev_rebase_if_required_to 

Rebase database if the debugged program has been rebased by the system.

This event is generated in the main thread.

Parameters
new_base(ea_t)
Returns
DRC_NONE, DRC_OK
ev_request_pause 

Prepare to pause the process.

Normally the next get_debug_event() will pause the process If the process is sleeping, then the pause will not occur until the process wakes up. If the debugger module does not react to this event, then it will be impossible to pause the program. This event is generated in debthread. Available if DBG_HAS_REQUEST_PAUSE is set

Parameters
errbuf(qstring *) may be NULL
Returns
DRC_NONE, DRC_OK, DRC_FAILED, DRC_NETERR
ev_exit_process 

Stop the process.

May be generated while the process is running or suspended. Must terminate the process in any case. The kernel will repeatedly call get_debug_event() until PROCESS_EXITED is received. In this mode, all other events will be automatically handled and process will be resumed. This event is generated in debthread. Must be implemented.

Parameters
errbuf(qstring *) may be NULL
Returns
DRC_NONE, DRC_OK, DRC_FAILED, DRC_NETERR
ev_get_debug_event 

Get a pending debug event and suspend the process.

This event will be generated regularly by IDA. This event is generated in debthread. IMPORTANT: the BREAKPOINT/EXCEPTION/STEP events must be reported only after reporting other pending events for a thread. Must be implemented.

Parameters
code(gdecode_t *)
event(debug_event_t *)
timeout_ms(int)
Return values
ignored
ev_resume 

Continue after handling the event.

This event is generated in debthread. Must be implemented.

Parameters
event(debug_event_t *)
Returns
DRC_OK, DRC_FAILED, DRC_NETERR
ev_set_exception_info 

Set exception handling.

This event is generated in debthread or the main thread. Available if DBG_HAS_SET_EXCEPTION_INFO is set

Parameters
info(exception_info_t *)
qty(int)
Returns
DRC_NONE, DRC_OK
ev_suspended 

This event will be generated by the kernel each time it has suspended the debugger process and refreshed the database.

The debugger module may add information to the database if it wants.

The reason for introducing this event is that when an event line LOAD_DLL happens, the database does not reflect the memory state yet and therefore we can't add information about the dll into the database in the get_debug_event() event. Only when the kernel has adjusted the database we can do it. Example: for imported PE DLLs we will add the exported event names to the database.

This event is generated in the main thread.

Parameters
dlls_added(bool)
thr_names(thread_name_vec_t *) (for the kernel only, must be NULL)
Returns
DRC_NONE, DRC_OK
ev_thread_suspend 

Suspend a running thread Available if DBG_HAS_THREAD_SUSPEND is set.

Parameters
tid(thid_t)
ev_thread_continue 

Resume a suspended thread Available if DBG_HAS_THREAD_CONTINUE is set.

Parameters
tid(thid_t)
ev_set_resume_mode 

Specify resume action Available if DBG_HAS_SET_RESUME_MODE is set.

Parameters
tid(thid_t)
resmod(resume_mode_t)
ev_read_registers 

Read thread registers.

This event is generated in debthread. Must be implemented.

Parameters
tid(thid_t) thread id
clsmask(int) bitmask of register classes to read
values(regval_t *) pointer to vector of regvals for all registers. regval must have debugger_t::nregs elements
errbuf(qstring *) may be NULL
Returns
DRC_OK, DRC_FAILED, DRC_NETERR
ev_write_register 

Write one thread register.

This event is generated in debthread. Must be implemented.

Parameters
tid(thid_t) thread id
regidx(int) register index
value(const regval_t *) new value of the register
errbuf(qstring *) may be NULL
Returns
DRC_OK, DRC_FAILED, DRC_NETERR
ev_thread_get_sreg_base 

Get information about the base of a segment register.

Currently used by the IBM PC module to resolve references like fs:0. This event is generated in debthread. Available if DBG_HAS_THREAD_GET_SREG_BASE is set

Parameters
answer(ea_t *) pointer to the answer. can't be NULL.
tid(thid_t) thread id
sreg_value(int) value of the segment register (returned by get_reg_val())
errbuf(qstring *) may be NULL
Returns
DRC_NONE, DRC_OK, DRC_FAILED, DRC_NETERR
ev_get_memory_info 

Get information on the memory ranges.

The debugger module fills 'ranges'. The returned vector must be sorted. This event is generated in debthread. Must be implemented.

Parameters
ranges(meminfo_vec_t *)
errbuf(qstring *) may be NULL
Return values
DRC_OKnew memory layout is returned
DRC_FAILED,DRC_NETERR,DRC_NOPROC,DRC_NOCHG,DRC_IDBSEG
ev_read_memory 

Read process memory.

This event is generated in debthread.

Parameters
nbytes(size_t *) number of read bytes
ea(ea_t)
buffer(void *)
size(::size_t)
errbuf(qstring *) may be NULL
Returns
DRC_OK, DRC_FAILED, DRC_NOPROC
ev_write_memory 

Write process memory.

This event is generated in debthread.

Parameters
nbytes(size_t *) number of written bytes
ea(ea_t)
buffer(const void *)
size(::size_t)
errbuf(qstring *) may be NULL
Return values
DRC_OK,DRC_FAILED,DRC_NOPROC
ev_check_bpt 

Is it possible to set breakpoint? This event is generated in debthread or in the main thread if debthread is not running yet.

It is generated to verify hardware breakpoints. Available if DBG_HAS_CHECK_BPT is set

Parameters
bptvc(int *) breakpoint verification codes Breakpoint verification codes
type(bpttype_t) Hardware breakpoint ids
ea(ea_t)
len(int)
Returns
DRC_OK, DRC_NONE
ev_update_bpts 

Add/del breakpoints.

bpts array contains nadd bpts to add, followed by ndel bpts to del. This event is generated in debthread.

Parameters
nbpts(int *) number of updated breakpoints
bpts(update_bpt_info_t *)
nadd(int)
ndel(int)
errbuf(qstring *) may be NULL
Returns
DRC_OK, DRC_FAILED, DRC_NETERR
ev_update_lowcnds 

Update low-level (server side) breakpoint conditions.

This event is generated in debthread.

Parameters
nupdated(int *) number of updated conditions
lowcnds(const lowcnd_t *)
nlowcnds(int)
errbuf(qstring *) may be NULL
Returns
DRC_OK, DRC_NETERR
ev_open_file 
Parameters
file(const char *)
fsize(uint64 *)
readonly(bool)
errbuf(qstring *) may be NULL
Return values
(int)handle
-1error
ev_close_file 
Parameters
fn(int) handle
Returns
ignored
ev_read_file 
Parameters
fn(int) handle
off(qoff64_t)
buf(void *)
size(size_t)
errbuf(qstring *) may be NULL
Return values
numberof read bytes
ev_write_file 
Parameters
fn(int) handle
off(qoff64_t)
buf(const void *)
size(size_t)
errbuf(qstring *) may be NULL
Return values
numberof written bytes
ev_map_address 

Map process address.

The debugger module may ignore this event. This event is generated in debthread.

Parameters
mapped(ea_t *) mapped address or BADADDR
off(ea_t) offset to map
regs(const regval_t *) current register values. if regs == NULL, then perform global mapping, which is independent on used registers usually such a mapping is a trivial identity mapping
regnum(int) required mapping. May be specified as a segment register number or a regular register number if the required mapping can be deduced from it. For example, esp implies that ss should be used.
Returns
DRC_NONE, DRC_OK see MAPPED
ev_get_debmod_extensions 

Get pointer to debugger specific events.

This event returns a pointer to a structure that holds pointers to debugger module specific events. For information on the structure layout, please check the corresponding debugger module. Most debugger modules return NULL because they do not have any extensions. Available extensions may be generated from plugins. This event is generated in the main thread.

Parameters
ext(void **)
Returns
DRC_NONE, DRC_OK see EXT
ev_update_call_stack 

Calculate the call stack trace.

This event is generated when the process is suspended and should fill the 'trace' object with the information about the current call stack. If this event returns DRC_NONE, IDA will use the standard mechanism (based on the frame pointer chain) to calculate the stack trace This event is generated in the main thread. Available if DBG_HAS_UPDATE_CALL_STACK is set

Parameters
tid(thid_t)
trace(::call_stack_t *)
Return values
DRC_NONEfalse or not implemented
Returns
DRC_OK success
ev_appcall 

Call application function.

This event calls a function from the debugged application. This event is generated in debthread Available if HAS_APPCALL is set

Parameters
[out]blob_ea(ea_t *) ea of stkargs blob, BADADDR if failed and errbuf is filled
func_ea(ea_t) address to call
tid(thid_t) thread to use
fti(const func_type_data_t *) type information for the generated event
nargs(int) number of actual arguments
regargs(const regobjs_t *) information about register arguments
stkargs(relobj_t *) memory blob to pass as stack arguments (usually contains pointed data) it must be relocated by the callback but not changed otherwise
retregs(regobjs_t *) event return registers.
[out]errbuf(qstring *) the error message. if empty on failure, see EVENT. should not be filled if an appcall exception happened but APPCALL_DEBEV is set
[out]event(debug_event_t *) the last debug event that occurred during appcall execution filled only if the appcall execution fails and APPCALL_DEBEV is set
options(int) appcall options, usually taken from idainfo::appcall_options. possible values: combination of Appcall options or 0
Return values
DRC_NONE
DRC_OK,seeBLOB_EA
ev_cleanup_appcall 

Cleanup after appcall().

The debugger module must keep the stack blob in the memory until this event is generated. It will be generated by the kernel for each successful appcall(). There is an exception: if APPCALL_MANUAL, IDA may not call cleanup_appcall. If the user selects to terminate a manual appcall, then cleanup_appcall will be generated. Otherwise, the debugger module should terminate the appcall when the generated event returns. This event is generated in debthread. Available if HAS_APPCALL is set

Parameters
tid(thid_t)
Return values
DRC_EVENTSsuccess, there are pending events
DRC_OKsuccess
DRC_FAILEDfailed
DRC_NETERRnetwork error
ev_eval_lowcnd 

Evaluate a low level breakpoint condition at 'ea'.

Other evaluation errors are displayed in a dialog box. This call is used by IDA when the process has already been temporarily suspended for some reason and IDA has to decide whether the process should be resumed or definitely suspended because of a breakpoint with a low level condition. This event is generated in debthread.

Parameters
tid(thid_t)
ea(ea_t)
errbuf(qstring *) may be NULL
Return values
DRC_OKcondition is satisfied
DRC_FAILEDnot satisfied
DRC_NETERRnetwork error
ev_send_ioctl 

Perform a debugger-specific event.

This event is generated in debthread

Parameters
fn(int)
buf(const void *)
size(size_t)
poutbuf(void **)
poutsize(ssize_t *)
errbuf(qstring *) may be NULL \retval DRC_...
ev_dbg_enable_trace 

Enable/Disable tracing.

The kernel will generated this event if the debugger plugin set DBG_FLAG_TRACER_MODULE. TRACE_FLAGS can be a set of #STEP_TRACE, #INSN_TRACE, #BBLK_TRACE or #FUNC_TRACE. This event is generated in the main thread.

Parameters
tid(thid_t)
enable(bool)
trace_flags(int)
Returns
DRC_OK, DRC_FAILED, DRC_NONE
ev_is_tracing_enabled 

Is tracing enabled? The kernel will generated this event if the debugger plugin set DBG_FLAG_TRACER_MODULE.

TRACE_BIT can be one of the following: #STEP_TRACE, #INSN_TRACE, #BBLK_TRACE or #FUNC_TRACE

Parameters
tid(thid_t)
tracebit(int)
Return values
DRC_OKbit is set
DRC_NONEbit is not set or not implemented
ev_rexec 

Execute a command on the remote computer.

Available if DBG_HAS_REXEC is set

Parameters
cmdline(const char *)
Returns
(int) exit code
ev_get_srcinfo_path 

Get the path to a file containing source debug info for the given module.

This allows srcinfo providers to call into the debugger when looking for debug info. It is useful in certain cases like the iOS debugger, which is a remote debugger but the remote debugserver does not provide dwarf info. So, we allow the debugger client to decide where to look for debug info locally.

Parameters
path(qstring *) output path (file might not exist)
base(ea_t) base address of a module in the target process
Returns
DRC_NONE, DRC_OK result stored in PATH
ev_bin_search 

Search for a binary pattern in the program.

Parameters
out(ea_t *) binary pattern address
start_ea(ea_t) linear address, start of range to search
end_ea(ea_t) linear address, end of range to search (exclusive)
data(const ::compiled_binpat_vec_t *) the prepared data to search for (see parse_binpat_str())
srch_flags(int) combination of Search flags
errbuf(qstring *) may be NULL
Returns
DRC_OK EA contains the binary pattern address
Return values
DRC_FAILEDnot found
DRC_NONEnot implemented
DRC_NETERR,DRC_ERROR

Member Data Documentation

const char* debugger_t::processor

Required processor name.

Used for instant debugging to load the correct processor module

const char*(idaapi * debugger_t::set_dbg_options) (const char *keyword, int pri, int value_type, const void *value)

Set debugger options (parameters that are specific to the debugger module).

See the definition of ::set_options_t for arguments. See the convenience function in dbg.hpp if you need to call it. The kernel will generate this event after reading the debugger specific config file (arguments are: keyword="", type=#IDPOPT_STR, value="") This event is optional. This event is generated in the main thread

hook_cb_t* debugger_t::callback

Event notification callback.

It will be hooked to the HT_IDD notification point when the debugger is loaded and unhooked during the debugger unloading. The debugger plugin will be the last one who will receive the notification.


The documentation for this struct was generated from the following file: