IDA SDK
|
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 |
Debugger module features | |
const char ** | register_classes |
Array of register class names. | |
int | register_classes_default |
Mask of default printed register classes. | |
register_info_t * | _registers |
Array of registers. Use registers() to access it. | |
int | registers_size |
Number of registers. | |
int | memory_page_size |
Size of a memory page. | |
const uchar * | bpt_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 | |
bool(idaapi * | init_debugger )(const char *hostname, int portnum, const char *password) |
Initialize debugger. More... | |
bool(idaapi * | term_debugger )(void) |
Terminate debugger. More... | |
int(idaapi * | get_processes )(procinfo_vec_t *procs) |
Return information about the running processes. More... | |
int(idaapi * | start_process )(const char *path, const char *args, const char *startdir, int dbg_proc_flags, const char *input_path, uint32 input_file_crc32) |
Start an executable to debug. More... | |
int(idaapi * | attach_process )(pid_t pid, int event_id, int dbg_proc_flags) |
Attach to an existing running process. More... | |
int(idaapi * | detach_process )(void) |
Detach from the debugged process. More... | |
void(idaapi * | rebase_if_required_to )(ea_t new_base) |
Rebase database if the debugged program has been rebased by the system. More... | |
int(idaapi * | prepare_to_pause_process )(void) |
Prepare to pause the process. More... | |
int(idaapi * | exit_process )(void) |
Stop the process. More... | |
gdecode_t(idaapi * | get_debug_event )(debug_event_t *event, int timeout_ms) |
Get a pending debug event and suspend the process. More... | |
int(idaapi * | continue_after_event )(const debug_event_t *event) |
Continue after handling the event. More... | |
void(idaapi * | set_exception_info )(const exception_info_t *info, int qty) |
Set exception handling. More... | |
void(idaapi * | stopped_at_debug_event )(bool dlls_added) |
This function will be called by the kernel each time it has stopped the debugger process and refreshed the database. More... | |
int(idaapi * | read_registers )(thid_t tid, int clsmask, regval_t *values) |
Read thread registers. More... | |
int(idaapi * | write_register )(thid_t tid, int regidx, const regval_t *value) |
Write one thread register. More... | |
int(idaapi * | thread_get_sreg_base )(ea_t *answer, thid_t tid, int sreg_value) |
Get information about the base of a segment register. More... | |
int(idaapi * | is_ok_bpt )(bpttype_t type, ea_t ea, int len) |
Is it possible to set breakpoint?. More... | |
int(idaapi * | update_bpts )(update_bpt_info_t *bpts, int nadd, int ndel) |
Add/del breakpoints. More... | |
int(idaapi * | update_lowcnds )(const lowcnd_t *lowcnds, int nlowcnds) |
Update low-level (server side) breakpoint conditions. More... | |
ea_t(idaapi * | map_address )(ea_t off, const regval_t *regs, int regnum) |
Map process address. More... | |
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... | |
const void *(idaapi * | get_debmod_extensions )(void) |
Get pointer to debugger specific functions. More... | |
bool(idaapi * | update_call_stack )(thid_t tid, call_stack_t *trace) |
Calculate the call stack trace. More... | |
ea_t(idaapi * | 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) |
Call application function. More... | |
int(idaapi * | cleanup_appcall )(thid_t tid) |
Cleanup after appcall(). More... | |
int(idaapi * | eval_lowcnd )(thid_t tid, ea_t ea) |
Evaluate a low level breakpoint condition at 'ea'. More... | |
ssize_t(idaapi * | write_file )(int fn, qoff64_t off, const void *buf, size_t size) |
This function is called from main thread. | |
int(idaapi * | send_ioctl )(int fn, const void *buf, size_t size, void **poutbuf, ssize_t *poutsize) |
Perform a debugger-specific function. More... | |
bool(idaapi * | dbg_enable_trace )(thid_t tid, bool enable, int trace_flags) |
Enable/Disable tracing. More... | |
bool(idaapi * | is_tracing_enabled )(thid_t tid, int tracebit) |
Is tracing enabled? ONLY used for tracers. More... | |
int(idaapi * | rexec )(const char *cmdline) |
Execute a command on the remote computer. More... | |
void(idaapi * | get_debapp_attrs )(debapp_attrs_t *out_pattrs) |
Get (store to out_pattrs) process/debugger-specific runtime attributes. More... | |
bool(idaapi * | get_srcinfo_path )(qstring *path, ea_t base) |
Get the path to a file containing source debug info for the given module. More... | |
Memory manipulation | |
The following functions manipulate bytes in the memory. | |
int(idaapi * | get_memory_info )(meminfo_vec_t &ranges) |
Get information on the memory ranges. More... | |
ssize_t(idaapi * | read_memory )(ea_t ea, void *buffer, size_t size) |
Read process memory. More... | |
ssize_t(idaapi * | write_memory )(ea_t ea, const void *buffer, size_t size) |
Write process memory. More... | |
Remote file | |
Open/close/read a remote file. These functions are called from the main thread | |
int(idaapi * | open_file )(const char *file, uint64 *fsize, bool readonly) |
void(idaapi * | close_file )(int fn) |
ssize_t(idaapi * | read_file )(int fn, qoff64_t off, void *buf, size_t size) |
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 | is_resmod_avail (int resmod) const |
register_info_t & | registers (int idx) |
Threads | |||||||
The following functions manipulate threads. These functions are called from debthread.
| |||||||
int(idaapi * | thread_continue )(thid_t tid) | ||||||
Resume a suspended thread. | |||||||
int(idaapi * | set_resume_mode )(thid_t tid, resume_mode_t resmod) | ||||||
Specify resume action. | |||||||
int (idaapi *thread_suspend)(thid_t tid) | |||||||
Suspend a running thread. | |||||||
const char* debugger_t::processor |
Required processor name.
Used for instant debugging to load the correct processor module
Initialize debugger.
This function is called from the main thread.
bool(idaapi * debugger_t::term_debugger) (void) |
Terminate debugger.
This function is called from the main thread.
int(idaapi * debugger_t::get_processes) (procinfo_vec_t *procs) |
Return information about the running processes.
This function is called from the main thread.
1 | ok |
0 | failed |
-1 | network error |
int(idaapi * debugger_t::start_process) (const char *path, const char *args, const char *startdir, int dbg_proc_flags, const char *input_path, uint32 input_file_crc32) |
Start an executable to debug.
This function is called from debthread.
path | path to executable |
args | arguments to pass to executable |
startdir | current directory of new process |
dbg_proc_flags | Debug process flags |
input_path | path to database input file. (not always the same as 'path' - e.g. if you're analyzing a dll and want to launch an executable that loads it) |
input_file_crc32 | CRC value for 'input_path' |
1 | ok |
0 | failed |
-2 | file not found (ask for process options) |
1 | | CRC32_MISMATCH ok, but the input file crc does not match |
-1 | network error |
Attach to an existing running process.
event_id should be equal to -1 if not attaching to a crashed process. This function is called from debthread.
pid | process id to attach |
event_id | event to trigger upon attaching |
dbg_proc_flags | Debug process flags |
1 | ok |
0 | failed |
-1 | network error |
Detach from the debugged process.
May be called while the process is running or suspended. Must detach from the process in any case. The kernel will repeatedly call get_debug_event() and until PROCESS_DETACH. In this mode, all other events will be automatically handled and process will be resumed. This function is called from debthread.
1 | ok |
0 | failed |
-1 | network error |
Rebase database if the debugged program has been rebased by the system.
This function is called from the main thread.
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. The interface should take care of this situation. If this function is absent, then it won't be possible to pause the program. This function is called from debthread.
1 | ok |
0 | failed |
-1 | network error |
Stop the process.
May be called while the process is running or suspended. Must terminate the process in any case. The kernel will repeatedly call get_debug_event() and until PROCESS_EXIT. In this mode, all other events will be automatically handled and process will be resumed. This function is called from debthread.
1 | ok |
0 | failed |
-1 | network error |
gdecode_t(idaapi * debugger_t::get_debug_event) (debug_event_t *event, int timeout_ms) |
Get a pending debug event and suspend the process.
This function will be called regularly by IDA. This function is called from debthread. IMPORTANT: commdbg does not expect immediately after a BPT-related event any other event with the same thread/IP - this can cause erroneous restoring of a breakpoint before resume (the bug was encountered 24.02.2015 in pc_linux_upx.elf)
int(idaapi * debugger_t::continue_after_event) (const debug_event_t *event) |
Continue after handling the event.
This function is called from debthread.
1 | ok |
0 | failed |
-1 | network error |
void(idaapi * debugger_t::set_exception_info) (const exception_info_t *info, int qty) |
Set exception handling.
This function is called from debthread or the main thread.
void(idaapi * debugger_t::stopped_at_debug_event) (bool dlls_added) |
This function will be called by the kernel each time it has stopped the debugger process and refreshed the database.
The debugger module may add information to the database if it wants.
The reason for introducing this function 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() function. Only when the kernel has adjusted the database we can do it. Example: for imported PE DLLs we will add the exported function names to the database.
This function pointer may be absent, i.e. NULL. This function is called from the main thread.
Read thread registers.
This function is called from debthread.
tid | thread id |
clsmask | bitmask of register classes to read |
values | pointer to vector of regvals for all registers. regval is assumed to have debugger_t::registers_size elements |
1 | ok |
0 | failed |
-1 | network error |
Write one thread register.
This function is called from debthread.
tid | thread id |
regidx | register index |
value | new value of the register |
1 | ok |
0 | failed |
-1 | network error |
Get information about the base of a segment register.
Currently used by the IBM PC module to resolve references like fs:0. This function is called from debthread.
answer | pointer to the answer. can't be NULL. |
tid | thread id |
sreg_value | value of the segment register (returned by get_reg_val()) |
1 | ok |
0 | failed |
-1 | network error |
int(idaapi * debugger_t::get_memory_info) (meminfo_vec_t &ranges) |
Get information on the memory ranges.
The debugger module fills 'ranges'. The returned vector MUST be sorted. This function is called from debthread.
-3 | use idb segmentation |
-2 | no changes |
-1 | the process does not exist anymore |
0 | failed |
1 | new memory layout is returned |
Read process memory.
Returns number of read bytes. This function is called from debthread.
0 | read error |
-1 | process does not exist anymore |
Write process memory.
This function is called from debthread.
Is it possible to set breakpoint?.
This function is called from debthread or from the main thread if debthread is not running yet. It is called to verify hardware breakpoints.
int(idaapi * debugger_t::update_bpts) (update_bpt_info_t *bpts, int nadd, int ndel) |
Add/del breakpoints.
bpts array contains nadd bpts to add, followed by ndel bpts to del. This function is called from debthread.
Update low-level (server side) breakpoint conditions.
This function is called from debthread.
Map process address.
This function may be absent. This function is called from debthread.
off | offset to map |
regs | 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 | required mapping. maybe 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. |
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 call this function after reading the debugger specific config file (arguments are: keyword="", type=#IDPOPT_STR, value="") This function is optional. This function is called from the main thread
const void*(idaapi * debugger_t::get_debmod_extensions) (void) |
Get pointer to debugger specific functions.
This function returns a pointer to a structure that holds pointers to debugger module specific functions. 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 called from plugins. This function is called from the main thread.
bool(idaapi * debugger_t::update_call_stack) (thid_t tid, call_stack_t *trace) |
Calculate the call stack trace.
This function is called when the process is suspended and should fill the 'trace' object with the information about the current call stack. If this function is missing or returns false, IDA will use the standard mechanism (based on the frame pointer chain) to calculate the stack trace This function is called from the main thread.
ea_t(idaapi * debugger_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) |
Call application function.
This function calls a function from the debugged application. This function is called from debthread
func_ea | address to call | |
tid | thread to use | |
fti | type information for the called function | |
nargs | number of actual arguments | |
regargs | information about register arguments | |
stkargs | memory blob to pass as stack arguments (usually contains pointed data) it must be relocated by the callback but not changed otherwise | |
retregs | function return registers. | |
[out] | errbuf | 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 | the last debug event that occurred during appcall execution filled only if the appcall execution fails and APPCALL_DEBEV is set |
options | appcall options, usually taken from idainfo::appcall_options. possible values: combination of Appcall options or 0 |
Cleanup after appcall().
The debugger module must keep the stack blob in the memory until this function is called. It will be called 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 called. Otherwise, the debugger module should terminate the appcall when the called function returns. This function is called from debthread.
2 | ok, there are pending events |
1 | ok |
0 | failed |
-1 | network error |
Evaluate a low level breakpoint condition at 'ea'.
Other evaluation errors are displayed in a dialog box. This call is rarely used by IDA when the process has already been suspended for some reason and it has to decide whether the process should be resumed or definitely suspended because of a breakpoint with a low level condition. This function is called from debthread.
1 | condition is satisfied |
0 | not satisfied |
-1 | network error |
int(idaapi * debugger_t::send_ioctl) (int fn, const void *buf, size_t size, void **poutbuf, ssize_t *poutsize) |
Perform a debugger-specific function.
This function is called from debthread
Enable/Disable tracing.
"trace_flags" can be a set of STEP_TRACE, INSN_TRACE, BBLK_TRACE or FUNC_TRACE. See thread_t::trace_mode in debugger.h. This function is called from the main thread.
Is tracing enabled? ONLY used for tracers.
"trace_bit" can be one of the following: STEP_TRACE, INSN_TRACE, BBLK_TRACE or FUNC_TRACE
Execute a command on the remote computer.
void(idaapi * debugger_t::get_debapp_attrs) (debapp_attrs_t *out_pattrs) |
Get (store to out_pattrs) process/debugger-specific runtime attributes.
This function is called from main thread.
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.
path | output path (file might not exist) |
base | base address of a module in the target process |