debugger_t Struct Reference

This structure describes a debugger API module. More...

#include <idd.hpp>

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

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
bool	has_map_address (void) const
bool	has_soft_bpt (void) const
register_info_t &	regs (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=nullptr)
bool	term_debugger (void)
drc_t	get_processes (procinfo_vec_t *procs, qstring *errbuf=nullptr)
drc_t	start_process (const char *path, const char *args, launch_env_t *envs, const char *startdir, uint32 dbg_proc_flags, const char *input_path, uint32 input_file_crc32, qstring *errbuf=nullptr)
drc_t	attach_process (pid_t pid, int event_id, uint32 dbg_proc_flags, qstring *errbuf=nullptr)
drc_t	detach_process (qstring *errbuf=nullptr)
bool	get_debapp_attrs (debapp_attrs_t *out_pattrs)
void	rebase_if_required_to (ea_t new_base)
drc_t	request_pause (qstring *errbuf=nullptr)
drc_t	exit_process (qstring *errbuf=nullptr)
gdecode_t	get_debug_event (debug_event_t *event, int timeout_ms)
drc_t	resume (const debug_event_t *event, qstring *errbuf=nullptr)
void	set_exception_info (const exception_info_t *info, int qty)
void	suspended (bool dlls_added, thread_name_vec_t *thr_names=nullptr)
drc_t	thread_suspend (thid_t tid, qstring *errbuf=nullptr)
drc_t	thread_continue (thid_t tid, qstring *errbuf=nullptr)
drc_t	set_resume_mode (thid_t tid, resume_mode_t resmod, qstring *errbuf=nullptr)
drc_t	read_registers (thid_t tid, int clsmask, regval_t *values, qstring *errbuf=nullptr)
drc_t	write_register (thid_t tid, int regidx, const regval_t *value, qstring *errbuf=nullptr)
drc_t	thread_get_sreg_base (ea_t *answer, thid_t tid, int sreg_value, qstring *errbuf=nullptr)
drc_t	get_memory_info (meminfo_vec_t &ranges, qstring *errbuf=nullptr)
drc_t	read_memory (size_t *nbytes, ea_t ea, void *buffer, size_t size, qstring *errbuf=nullptr)
drc_t	write_memory (size_t *nbytes, ea_t ea, const void *buffer, size_t size, qstring *errbuf=nullptr)
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=nullptr)
drc_t	update_lowcnds (int *nupdated, const lowcnd_t *lowcnds, int nlowcnds, qstring *errbuf=nullptr)
int	open_file (const char *file, uint64 *fsize, bool readonly, qstring *errbuf=nullptr)
void	close_file (int fn)
ssize_t	read_file (int fn, qoff64_t off, void *buf, size_t size, qstring *errbuf=nullptr)
ssize_t	write_file (int fn, qoff64_t off, const void *buf, size_t size, qstring *errbuf=nullptr)
ea_t	map_address (ea_t off, const regval_t *regs, int regnum)
const void *	get_debmod_extensions (void)
drc_t	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=nullptr)
drc_t	send_ioctl (int fn, const void *buf, size_t size, void **poutbuf, ssize_t *poutsize, qstring *errbuf=nullptr)
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=nullptr)

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_t *	registers
	Array of registers. Use regs() to access it.
int	nregs
	Number of registers.
int	memory_page_size
	Size of a memory page. Usually 4K.
const uchar *	bpt_bytes
	A software breakpoint instruction.
uchar	bpt_size
	Size of the software breakpoint instruction in bytes.
uchar	filetype
	Input file type for the instant debugger. More...
ushort	resume_modes
	Resume modes
const char *(idaapi *	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). More...
hook_cb_t *	callback
	Event notification callback. More...

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.

Member Enumeration Documentation

event_t

enum debugger_t::event_t

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 nullptr 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 nullptr 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 nullptr envs (launch_env_t *) environment variables for debugged process 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 nullptr 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 nullptr 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 nullptr 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 debuggee process and refreshed the database. The debugger module may add information to the database if necessary. The reason for introducing this event is that when an event like 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() function. Only when the kernel has adjusted the database we can do it. Example: for loaded PE DLLs we can add the exported function names to the list of debug names (see set_debug_names()). This event is generated in the main thread. Parameters dlls_added (bool) thr_names (thread_name_vec_t *) (for the kernel only, must be nullptr) 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 nullptr 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 nullptr 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 nullptr. tid (thid_t) thread id sreg_value (int) value of the segment register (returned by get_reg_val()) errbuf (qstring *) may be nullptr 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 nullptr Return values DRC_OK new 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 nullptr 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 nullptr 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 nullptr 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 nullptr Returns DRC_OK, DRC_NETERR
ev_open_file	Parameters file (const char *) fsize (::uint64 *) readonly (bool) errbuf (qstring *) may be nullptr Return values (int) handle -1 error
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 nullptr Return values number of read bytes
ev_write_file	Parameters fn (int) handle off (qoff64_t) buf (const void *) size (size_t) errbuf (qstring *) may be nullptr Return values number of written bytes
ev_map_address	Map process address. The debugger module may ignore this event. This event is generated in debthread. IDA will generate this event only if DBG_HAS_MAP_ADDRESS is set. Parameters mapped (::ea_t *) mapped address or BADADDR off (::ea_t) offset to map regs (const regval_t *) current register values. if regs == nullptr, 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 nullptr 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 for the given thread. 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 try to invoke a processor-specific mechanism (see processor_t::ev_update_call_stack). If the current processor module does not implement stack tracing, then IDA will fall back to a generic algorithm (based on the frame pointer chain) to calculate the trace. This event is ideal if the debugging targets manage stack frames in a peculiar way, requiring special analysis. 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_NONE false 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,see BLOB_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_EVENTS success, there are pending events DRC_OK success DRC_FAILED failed DRC_NETERR network 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 nullptr Return values DRC_OK condition is satisfied DRC_FAILED not satisfied DRC_NETERR network 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 nullptr Return values 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_OK bit is set DRC_NONE bit 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 nullptr Returns DRC_OK EA contains the binary pattern address Return values DRC_FAILED not found DRC_NONE not implemented DRC_NETERR,DRC_ERROR

Member Data Documentation

processor

const char* debugger_t::processor

Required processor name.

Used for instant debugging to load the correct processor module

filetype

uchar debugger_t::filetype

Input file type for the instant debugger.

This value will be used after attaching to a new process.

set_dbg_options

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

Parameters

keyword	keyword encountered in IDA.CFG/user config file. if nullptr, then an interactive dialog form should be displayed
pri	option priority, one of IDAOPT_PRIO values
value_type	type of value of the keyword - one of IDPOPT_T
value	pointer to value

Returns

one of IDPOPT_RET, otherwise a pointer to an error message 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

callback

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:

• idd.hpp