调试接口

#--------------------------------------------------------------------------
#                   D E B U G G E R  I N T E R F A C E
#--------------------------------------------------------------------------
def LoadDebugger(dbgname, use_remote):
    """
    Load the debugger

    @param dbgname: debugger module name Examples: win32, linux, mac.
    @param use_remote: 0/1: use remote debugger or not

    @note: This function is needed only when running idc scripts from the command line.
           In other cases IDA loads the debugger module automatically.
    """
    return idaapi.load_debugger(dbgname, use_remote)


def StartDebugger(path, args, sdir):
    """
    Launch the debugger

    @param path: path to the executable file.
    @param args: command line arguments
    @param sdir: initial directory for the process

    @return: -1-failed, 0-cancelled by the user, 1-ok

    @note: For all args: if empty, the default value from the database will be used
           See the important note to the StepInto() function
    """
    return idaapi.start_process(path, args, sdir)


def StopDebugger():
    """
    Stop the debugger
    Kills the currently debugger process and returns to the disassembly mode

    @return: success
    """
    return idaapi.exit_process()


def PauseProcess():
    """
    Suspend the running process
    Tries to suspend the process. If successful, the PROCESS_SUSPEND
    debug event will arrive (see GetDebuggerEvent)

    @return: success

    @note: To resume a suspended process use the GetDebuggerEvent function.
           See the important note to the StepInto() function
    """
    return idaapi.suspend_process()


def GetProcessQty():
    """
    Take a snapshot of running processes and return their number.
    """
    return idaapi.get_process_qty()


def GetProcessPid(idx):
    """
    Get the process ID of a running process

    @param idx: number of process, is in range 0..GetProcessQty()-1

    @return: 0 if failure
    """
    pinfo = idaapi.process_info_t()
    pid = idaapi.get_process_info(idx, pinfo)
    if pid != idaapi.NO_PROCESS:
        return pinfo.pid
    else:
        return 0


def GetProcessName(idx):
    """
    Get the name of a running process

    @param idx: number of process, is in range 0..GetProcessQty()-1

    @return: None if failure
    """
    pinfo = idaapi.process_info_t()
    pid = idaapi.get_process_info(idx, pinfo)
    return None if pid == idaapi.NO_PROCESS else pinfo.name


def AttachProcess(pid, event_id):
    """
    Attach the debugger to a running process

    @param pid: PID of the process to attach to. If NO_PROCESS, a dialog box
                will interactively ask the user for the process to attach to.
    @param event_id: reserved, must be -1

    @return:
             - -2: impossible to find a compatible process
             - -1: impossible to attach to the given process (process died, privilege
               needed, not supported by the debugger plugin, ...)
             - 0: the user cancelled the attaching to the process
             - 1: the debugger properly attached to the process
    @note: See the important note to the StepInto() function
    """
    return idaapi.attach_process(pid, event_id)


def DetachProcess():
    """
    Detach the debugger from the debugged process.

    @return: success
    """
    return idaapi.detach_process()


def GetThreadQty():
    """
    Get number of threads.

    @return: number of threads
    """
    return idaapi.get_thread_qty()


def GetThreadId(idx):
    """
    Get the ID of a thread

    @param idx: number of thread, is in range 0..GetThreadQty()-1

    @return: -1 if failure
    """
    return idaapi.getn_thread(idx)


def GetCurrentThreadId():
    """
    Get current thread ID

    @return: -1 if failure
    """
    return idaapi.get_current_thread()


def SelectThread(tid):
    """
    Select the given thread as the current debugged thread.

    @param tid: ID of the thread to select

    @return: success

    @note: The process must be suspended to select a new thread.
    """
    return idaapi.select_thread(tid)


def SuspendThread(tid):
    """
    Suspend thread

    @param tid: thread id

    @return: -1:network error, 0-failed, 1-ok

    @note: Suspending a thread may deadlock the whole application if the suspended
           was owning some synchronization objects.
    """
    return idaapi.suspend_thread(tid)


def ResumeThread(tid):
    """
    Resume thread

    @param tid: thread id

    @return: -1:network error, 0-failed, 1-ok
    """
    return idaapi.resume_thread(tid)


def _get_modules():
    """
    INTERNAL: Enumerate process modules
    """
    module = idaapi.module_info_t()
    result = idaapi.get_first_module(module)
    while result:
        yield module
        result = idaapi.get_next_module(module)


def GetFirstModule():
    """
    Enumerate process modules

    @return: first module's base address or None on failure
    """
    for module in _get_modules():
        return module.base
    else:
        return None


def GetNextModule(base):
    """
    Enumerate process modules

    @param base: previous module's base address

    @return: next module's base address or None on failure
    """
    foundit = False
    for module in _get_modules():
        if foundit:
            return module.base
        if module.base == base:
            foundit = True
    else:
        return None


def GetModuleName(base):
    """
    Get process module name

    @param base: the base address of the module

    @return: required info or None
    """
    for module in _get_modules():
        if module.base == base:
            return module.name
    else:
        return 0


def GetModuleSize(base):
    """
    Get process module size

    @param base: the base address of the module

    @return: required info or -1
    """
    for module in _get_modules():
        if module.base == base:
            return module.size
    else:
        return -1


def StepInto():
    """
    Execute one instruction in the current thread.
    Other threads are kept suspended.

    @return: success

    @note: You must call GetDebuggerEvent() after this call
           in order to find out what happened. Normally you will
           get the STEP event but other events are possible (for example,
           an exception might occur or the process might exit).
           This remark applies to all execution control functions.
           The event codes depend on the issued command.
    """
    return idaapi.step_into()


def StepOver():
    """
    Execute one instruction in the current thread,
    but without entering into functions
    Others threads keep suspended.
    See the important note to the StepInto() function

    @return: success
    """
    return idaapi.step_over()


def RunTo(ea):
    """
    Execute the process until the given address is reached.
    If no process is active, a new process is started.
    See the important note to the StepInto() function

    @return: success
    """
    return idaapi.run_to(ea)


def StepUntilRet():
    """
    Execute instructions in the current thread until
    a function return instruction is reached.
    Other threads are kept suspended.
    See the important note to the StepInto() function

    @return: success
    """
    return idaapi.step_until_ret()


def GetDebuggerEvent(wfne, timeout):
    """
    Wait for the next event
    This function (optionally) resumes the process
    execution and wait for a debugger event until timeout

    @param wfne: combination of WFNE_... constants
    @param timeout: number of seconds to wait, -1-infinity

    @return: debugger event codes, see below
    """
    return idaapi.wait_for_next_event(wfne, timeout)


def ResumeProcess():
    return GetDebuggerEvent(WFNE_CONT|WFNE_NOWAIT, 0)

def SendDbgCommand(cmd):
    """Sends a command to the debugger module and returns the output string.
    An exception will be raised if the debugger is not running or the current debugger does not export
    the 'SendDbgCommand' IDC command.
    """
    s = Eval('SendDbgCommand("%s");' % idaapi.str2user(cmd))
    if s.startswith("IDC_FAILURE"):
        raise Exception, "Debugger command is available only when the debugger is active!"
    return s

# wfne flag is combination of the following:
WFNE_ANY    = 0x0001 # return the first event (even if it doesn't suspend the process)
                        # if the process is still running, the database
                        # does not reflect the memory state. you might want
                        # to call RefreshDebuggerMemory() in this case
WFNE_SUSP   = 0x0002 # wait until the process gets suspended
WFNE_SILENT = 0x0004 # 1: be slient, 0:display modal boxes if necessary
WFNE_CONT   = 0x0008 # continue from the suspended state
WFNE_NOWAIT = 0x0010 # do not wait for any event, immediately return DEC_TIMEOUT
                        # (to be used with WFNE_CONT)

# debugger event codes
NOTASK         = -2         # process does not exist
DBG_ERROR      = -1         # error (e.g. network problems)
DBG_TIMEOUT    = 0          # timeout
PROCESS_START  = 0x00000001 # New process started
PROCESS_EXIT   = 0x00000002 # Process stopped
THREAD_START   = 0x00000004 # New thread started
THREAD_EXIT    = 0x00000008 # Thread stopped
BREAKPOINT     = 0x00000010 # Breakpoint reached
STEP           = 0x00000020 # One instruction executed
EXCEPTION      = 0x00000040 # Exception
LIBRARY_LOAD   = 0x00000080 # New library loaded
LIBRARY_UNLOAD = 0x00000100 # Library unloaded
INFORMATION    = 0x00000200 # User-defined information
SYSCALL        = 0x00000400 # Syscall (not used yet)
WINMESSAGE     = 0x00000800 # Window message (not used yet)
PROCESS_ATTACH = 0x00001000 # Attached to running process
PROCESS_DETACH = 0x00002000 # Detached from process
PROCESS_SUSPEND = 0x00004000 # Process has been suspended


def RefreshDebuggerMemory():
    """
    Refresh debugger memory
    Upon this call IDA will forget all cached information
    about the debugged process. This includes the segmentation
    information and memory contents (register cache is managed
    automatically). Also, this function refreshes exported name
    from loaded DLLs.
    You must call this function before using the segmentation
    information, memory contents, or names of a non-suspended process.
    This is an expensive call.
    """
    return idaapi.refresh_debugger_memory()


def TakeMemorySnapshot(only_loader_segs):
    """
    Take memory snapshot of the debugged process

    @param only_loader_segs: 0-copy all segments to idb
                             1-copy only SFL_LOADER segments
    """
    return idaapi.take_memory_snapshot(only_loader_segs)


def GetProcessState():
    """
    Get debugged process state

    @return: one of the DBG_... constants (see below)
    """
    return idaapi.get_process_state()

DSTATE_SUSP            = -1 # process is suspended
DSTATE_NOTASK          =  0 # no process is currently debugged
DSTATE_RUN             =  1 # process is running
DSTATE_RUN_WAIT_ATTACH =  2 # process is running, waiting for process properly attached
DSTATE_RUN_WAIT_END    =  3 # process is running, but the user asked to kill/detach the process
                            # remark: in this case, most events are ignored

"""
 Get various information about the current debug event
 These functions are valid only when the current event exists
 (the process is in the suspended state)
"""

# For all events:

def GetEventId():
    """
    Get ID of debug event

    @return: event ID
    """
    ev = idaapi.get_debug_event()
    assert ev, "Could not retrieve debug event"
    return ev.eid


def GetEventPid():
    """
    Get process ID for debug event

    @return: process ID
    """
    ev = idaapi.get_debug_event()
    assert ev, "Could not retrieve debug event"
    return ev.pid


def GetEventTid():
    """
    Get type ID for debug event

    @return: type ID
    """
    ev = idaapi.get_debug_event()
    assert ev, "Could not retrieve debug event"
    return ev.tid


def GetEventEa():
    """
    Get ea for debug event

    @return: ea
    """
    ev = idaapi.get_debug_event()
    assert ev, "Could not retrieve debug event"
    return ev.ea


def IsEventHandled():
    """
    Is the debug event handled?

    @return: boolean
    """
    ev = idaapi.get_debug_event()
    assert ev, "Could not retrieve debug event"
    return ev.handled


# For PROCESS_START, PROCESS_ATTACH, LIBRARY_LOAD events:

def GetEventModuleName():
    """
    Get module name for debug event

    @return: module name
    """
    ev = idaapi.get_debug_event()
    assert ev, "Could not retrieve debug event"
    return idaapi.get_event_module_name(ev)


def GetEventModuleBase():
    """
    Get module base for debug event

    @return: module base
    """
    ev = idaapi.get_debug_event()
    assert ev, "Could not retrieve debug event"
    return idaapi.get_event_module_base(ev)


def GetEventModuleSize():
    """
    Get module size for debug event

    @return: module size
    """
    ev = idaapi.get_debug_event()
    assert ev, "Could not retrieve debug event"
    return idaapi.get_event_module_size(ev)


def GetEventExitCode():
    """
    Get exit code for debug event

    @return: exit code for PROCESS_EXIT, THREAD_EXIT events
    """
    ev = idaapi.get_debug_event()
    assert ev, "Could not retrieve debug event"
    return ev.exit_code


def GetEventInfo():
    """
    Get debug event info

    @return: event info: for LIBRARY_UNLOAD (unloaded library name)
                         for INFORMATION (message to display)
    """
    ev = idaapi.get_debug_event()
    assert ev, "Could not retrieve debug event"
    return idaapi.get_event_info(ev)


def GetEventBptHardwareEa():
    """
    Get hardware address for BREAKPOINT event

    @return: hardware address
    """
    ev = idaapi.get_debug_event()
    assert ev, "Could not retrieve debug event"
    return idaapi.get_event_bpt_hea(ev)


def GetEventExceptionCode():
    """
    Get exception code for EXCEPTION event

    @return: exception code
    """
    ev = idaapi.get_debug_event()
    assert ev, "Could not retrieve debug event"
    return idaapi.get_event_exc_code(ev)


def GetEventExceptionEa():
    """
    Get address for EXCEPTION event

    @return: adress of exception
    """
    ev = idaapi.get_debug_event()
    assert ev, "Could not retrieve debug event"
    return idaapi.get_event_exc_ea(ev)


def CanExceptionContinue():
    """
    Can it continue after EXCEPTION event?

    @return: boolean
    """
    ev = idaapi.get_debug_event()
    assert ev, "Could not retrieve debug event"
    return idaapi.can_exc_continue(ev)


def GetEventExceptionInfo():
    """
    Get info for EXCEPTION event

    @return: info string
    """
    ev = idaapi.get_debug_event()
    assert ev, "Could not retrieve debug event"
    return idaapi.get_event_exc_info(ev)


def SetDebuggerOptions(opt):
    """
    Get/set debugger options

    @param opt: combination of DOPT_... constants

    @return: old options
    """
    return idaapi.set_debugger_options(opt)


DOPT_SEGM_MSGS    = 0x00000001 # print messages on debugger segments modifications
DOPT_START_BPT    = 0x00000002 # break on process start
DOPT_THREAD_MSGS  = 0x00000004 # print messages on thread start/exit
DOPT_THREAD_BPT   = 0x00000008 # break on thread start/exit
DOPT_BPT_MSGS     = 0x00000010 # print message on breakpoint
DOPT_LIB_MSGS     = 0x00000040 # print message on library load/unlad
DOPT_LIB_BPT      = 0x00000080 # break on library load/unlad
DOPT_INFO_MSGS    = 0x00000100 # print message on debugging information
DOPT_INFO_BPT     = 0x00000200 # break on debugging information
DOPT_REAL_MEMORY  = 0x00000400 # don't hide breakpoint instructions
DOPT_REDO_STACK   = 0x00000800 # reconstruct the stack
DOPT_ENTRY_BPT    = 0x00001000 # break on program entry point
DOPT_EXCDLG       = 0x00006000 # exception dialogs:

EXCDLG_NEVER      = 0x00000000 # never display exception dialogs
EXCDLG_UNKNOWN    = 0x00002000 # display for unknown exceptions
EXCDLG_ALWAYS     = 0x00006000 # always display

DOPT_LOAD_DINFO   = 0x00008000 # automatically load debug files (pdb)


def GetDebuggerEventCondition():
    """
    Return the debugger event condition
    """
    return idaapi.get_debugger_event_cond()


def SetDebuggerEventCondition(cond):
    """
    Set the debugger event condition
    """
    return idaapi.set_debugger_event_cond(cond)


def SetRemoteDebugger(hostname, password, portnum):
    """
    Set remote debugging options

    @param hostname: remote host name or address if empty, revert to local debugger
    @param password: password for the debugger server
    @param portnum: port number to connect (-1: don't change)

    @return: nothing
    """
    return idaapi.set_remote_debugger(hostname, password, portnum)


def GetExceptionQty():
    """
    Get number of defined exception codes
    """
    return idaapi.get_exception_qty()


def GetExceptionCode(idx):
    """
    Get exception code

    @param idx: number of exception in the vector (0..GetExceptionQty()-1)

    @return: exception code (0 - error)
    """
    return idaapi.get_exception_code(idx)


def GetExceptionName(code):
    """
    Get exception information

    @param code: exception code

    @return: "" on error
    """
    return idaapi.get_exception_name(code)


def GetExceptionFlags(code):
    """
    Get exception information

    @param code: exception code

    @return: -1 on error
    """
    return idaapi.get_exception_flags(code)

def DefineException(code, name, desc, flags):
    """
    Add exception handling information

    @param code: exception code
    @param name: exception name
    @param desc: exception description
    @param flags: exception flags (combination of EXC_...)

    @return: failure description or ""
    """
    return idaapi.define_exception(code, name, desc, flags)

EXC_BREAK  = 0x0001 # break on the exception
EXC_HANDLE = 0x0002 # should be handled by the debugger?


def SetExceptionFlags(code, flags):
    """
    Set exception flags

    @param code: exception code
    @param flags: exception flags (combination of EXC_...)
    """
    return idaapi.set_exception_flags(code, flags)


def ForgetException(code):
    """
    Delete exception handling information

    @param code: exception code
    """
    return idaapi.forget_exception(code)


def GetRegValue(name):
    """
    Get register value

    @param name: the register name

    @note: The debugger should be running. otherwise the function fails
           the register name should be valid.
           It is not necessary to use this function to get register values
           because a register name in the script will do too.

    @return: register value (integer or floating point)
    """
    rv = idaapi.regval_t()
    res = idaapi.get_reg_val(name, rv)
    assert res, "get_reg_val() failed, bogus register name ('%s') perhaps?" % name
    return rv.ival


def SetRegValue(value, name):
    """
    Set register value

    @param name: the register name
    @param value: new register value

    @note: The debugger should be running
           It is not necessary to use this function to set register values.
           A register name in the left side of an assignment will do too.
    """
    rv = idaapi.regval_t()
    if type(value) == types.StringType:
        value = int(value, 16)
    elif type(value) != types.IntType and type(value) != types.LongType:
        print "SetRegValue: value must be integer!"
        return BADADDR

    if value < 0:
        #ival_set cannot handle negative numbers
        value &= 0xFFFFFFFF

    rv.ival = value
    return idaapi.set_reg_val(name, rv)


def GetBptQty():
    """
    Get number of breakpoints.

    @return: number of breakpoints
    """
    return idaapi.get_bpt_qty()


def GetBptEA(n):
    """
    Get breakpoint address

    @param n: number of breakpoint, is in range 0..GetBptQty()-1

    @return: addresss of the breakpoint or BADADDR
    """
    bpt = idaapi.bpt_t()

    if idaapi.getn_bpt(n, bpt):
        return bpt.ea
    else:
        return BADADDR


def GetBptAttr(ea, bptattr):
    """
    Get the characteristics of a breakpoint

    @param ea: any address in the breakpoint range
    @param bptattr: the desired attribute code, one of BPTATTR_... constants

    @return: the desired attribute value or -1
    """
    bpt = idaapi.bpt_t()

    if not idaapi.get_bpt(ea, bpt):
        return -1
    else:
        if bptattr == BPTATTR_EA:
            return bpt.ea
        if bptattr == BPTATTR_SIZE:
            return bpt.size
        if bptattr == BPTATTR_TYPE:
            return bpt.type
        if bptattr == BPTATTR_COUNT:
            return bpt.pass_count
        if bptattr == BPTATTR_FLAGS:
            return bpt.flags
        if bptattr == BPTATTR_COND:
            return bpt.condition
        return -1


BPTATTR_EA    =  1   # starting address of the breakpoint
BPTATTR_SIZE  =  2   # size of the breakpoint (undefined for software breakpoint)

# type of the breakpoint
BPTATTR_TYPE  =  3

# Breakpoint types:
BPT_WRITE    = 1                     # Hardware: Write access
BPT_RDWR     = 3                     # Hardware: Read/write access
BPT_SOFT     = 4                     # Software breakpoint
BPT_EXEC     = 8                     # Hardware: Execute instruction
BPT_DEFAULT  = (BPT_SOFT|BPT_EXEC);  # Choose bpt type automaticaly

BPTATTR_COUNT  =  4
BPTATTR_FLAGS  =  5
BPT_BRK        = 0x001 # the debugger stops on this breakpoint
BPT_TRACE      = 0x002 # the debugger adds trace information when this breakpoint is reached
BPT_UPDMEM     = 0x004 # refresh the memory layout and contents before evaluating bpt condition
BPT_ENABLED    = 0x008 # enabled?
BPT_LOWCND     = 0x010 # condition is calculated at low level (on the server side)
BPT_TRACEON    = 0x020 # enable tracing when the breakpoint is reached
BPT_TRACE_INSN = 0x040 #   instruction tracing
BPT_TRACE_FUNC = 0x080 #   function tracing
BPT_TRACE_BBLK = 0x100 #   basic block tracing

BPTATTR_COND  =  6   # Breakpoint condition. NOTE: the return value is a string in this case

# Breakpoint location type:
BPLT_ABS  =  0   # Absolute address. Attributes:
                    # - locinfo: absolute address

BPLT_REL  =  1   # Module relative address. Attributes:
                    # - locpath: the module path
                    # - locinfo: offset from the module base address

BPLT_SYM  =  2   # Symbolic name. The name will be resolved on DLL load/unload
                    # events and on naming an address. Attributes:
                    # - locpath: symbol name
                    # - locinfo: offset from the symbol base address


def SetBptAttr(address, bptattr, value):
    """
        modifiable characteristics of a breakpoint

    @param address: any address in the breakpoint range
    @param bptattr: the attribute code, one of BPTATTR_* constants
                    BPTATTR_CND is not allowed, see SetBptCnd()
    @param value: the attibute value

    @return: success
    """
    bpt = idaapi.bpt_t()

    if not idaapi.get_bpt(address, bpt):
        return False
    else:
        if bptattr not in [ BPTATTR_SIZE, BPTATTR_TYPE, BPTATTR_FLAGS, BPTATTR_COUNT ]:
            return False
        if bptattr == BPTATTR_SIZE:
            bpt.size = value
        if bptattr == BPTATTR_TYPE:
            bpt.type = value
        if bptattr == BPTATTR_COUNT:
            bpt.pass_count = value
        if bptattr == BPTATTR_FLAGS:
            bpt.flags = value

        idaapi.update_bpt(bpt)
        return True

def SetBptCndEx(ea, cnd, is_lowcnd):
    """
    Set breakpoint condition

    @param ea: any address in the breakpoint range
    @param cnd: breakpoint condition
    @param is_lowcnd: 0 - regular condition, 1 - low level condition

    @return: success
    """
    bpt = idaapi.bpt_t()

    if not idaapi.get_bpt(ea, bpt):
        return False

    bpt.condition = cnd
    if is_lowcnd:
        bpt.flags |= BPT_LOWCND
    else:
        bpt.flags &= ~BPT_LOWCND

    return idaapi.update_bpt(bpt)


def SetBptCnd(ea, cnd):
    """
    Set breakpoint condition

    @param ea: any address in the breakpoint range
    @param cnd: breakpoint condition

    @return: success
    """
    return SetBptCndEx(ea, cnd, 0)


def AddBptEx(ea, size, bpttype):
    """
    Add a new breakpoint

    @param ea: any address in the process memory space:
    @param size: size of the breakpoint (irrelevant for software breakpoints):
    @param bpttype: type of the breakpoint (one of BPT_... constants)

    @return: success

    @note: Only one breakpoint can exist at a given address.
    """
    return idaapi.add_bpt(ea, size, bpttype)


def AddBpt(ea):
    return AddBptEx(ea, 0, BPT_DEFAULT)


def DelBpt(ea):
    """
    Delete breakpoint

    @param ea: any address in the process memory space:

    @return: success
    """
    return idaapi.del_bpt(ea)


def EnableBpt(ea, enable):
    """
    Enable/disable breakpoint

    @param ea: any address in the process memory space

    @return: success

    @note: Disabled breakpoints are not written to the process memory
    """
    return idaapi.enable_bpt(ea, enable)


def CheckBpt(ea):
    """
    Check a breakpoint

    @param ea: address in the process memory space

    @return: one of BPTCK_... constants
    """
    return idaapi.check_bpt(ea)

BPTCK_NONE = -1  # breakpoint does not exist
BPTCK_NO   =  0  # breakpoint is disabled
BPTCK_YES  =  1  # breakpoint is enabled
BPTCK_ACT  =  2  # breakpoint is active (written to the process)


def EnableTracing(trace_level, enable):
    """
    Enable step tracing

    @param trace_level:  what kind of trace to modify
    @param enable: 0: turn off, 1: turn on

    @return: success
    """
    assert trace_level in [ TRACE_STEP, TRACE_INSN, TRACE_FUNC ], 
           "trace_level must be one of TRACE_* constants"

    if trace_level == TRACE_STEP:
        return idaapi.enable_step_trace(enable)

    if trace_level == TRACE_INSN:
        return idaapi.enable_insn_trace(enable)

    if trace_level == TRACE_FUNC:
        return idaapi.enable_func_trace(enable)

    return False

TRACE_STEP = 0x0  # lowest level trace. trace buffers are not maintained
TRACE_INSN = 0x1  # instruction level trace
TRACE_FUNC = 0x2  # function level trace (calls & rets)


def GetStepTraceOptions():
    """
    Get step current tracing options

    @return: a combination of ST_... constants
    """
    return idaapi.get_step_trace_options()


def SetStepTraceOptions(options):
    """
    Set step current tracing options.
    @param options: combination of ST_... constants
    """
    return idaapi.set_step_trace_options(options)


ST_OVER_DEBUG_SEG = 0x01 # step tracing will be disabled when IP is in a debugger segment
ST_OVER_LIB_FUNC  = 0x02 # step tracing will be disabled when IP is in a library function
ST_ALREADY_LOGGED = 0x04 # step tracing will be disabled when IP is already logged
ST_SKIP_LOOPS     = 0x08 # step tracing will try to skip loops already recorded

def LoadTraceFile(filename):
    """
    Load a previously recorded binary trace file
    @param filename: trace file
    """
    return idaapi.load_trace_file(filename)

def SaveTraceFile(filename, description):
    """
    Save current trace to a binary trace file
    @param filename: trace file
    @param description: trace description
    """
    return idaapi.save_trace_file(filename, description)

def CheckTraceFile(filename):
    """
    Check the given binary trace file
    @param filename: trace file
    """
    return idaapi.is_valid_trace_file(filename)

def DiffTraceFile(filename):
    """
    Diff current trace buffer against given trace
    @param filename: trace file
    """
    return idaapi.diff_trace_file(filename)

def ClearTraceFile(filename):
    """
    Clear the current trace buffer
    """
    return idaapi.clear_trace()

def GetTraceDesc(filename):
    """
    Get the trace description of the given binary trace file
    @param filename: trace file
    """
    return idaapi.get_trace_file_desc(filename)

def SetTraceDesc(filename, description):
    """
    Update the trace description of the given binary trace file
    @param filename: trace file
    @description: trace description
    """
    return idaapi.set_trace_file_desc(filename, description)

def GetMaxTev():
    """
    Return the total number of recorded events
    """
    return idaapi.get_tev_qty()

def GetTevEa(tev):
    """
    Return the address of the specified event
    @param tev: event number
    """
    return idaapi.get_tev_ea(tev)

TEV_NONE  = 0 # no event
TEV_INSN  = 1 # an instruction trace
TEV_CALL  = 2 # a function call trace
TEV_RET   = 3 # a function return trace
TEV_BPT   = 4 # write, read/write, execution trace
TEV_MEM   = 5 # memory layout changed
TEV_EVENT = 6 # debug event

def GetTevType(tev):
    """
    Return the type of the specified event (TEV_... constants)
    @param tev: event number
    """
    return idaapi.get_tev_type(tev)

def GetTevTid(tev):
    """
    Return the thread id of the specified event
    @param tev: event number
    """
    return idaapi.get_tev_tid(tev)

def GetTevRegVal(tev, reg):
    """
    Return the register value for the specified event
    @param tev: event number
    @param reg: register name (like EAX, RBX, ...)
    """
    return idaapi.get_tev_reg_val(tev, reg)

def GetTevRegMemQty(tev):
    """
    Return the number of memory addresses recorded for the specified event
    @param tev: event number
    """
    return idaapi.get_tev_reg_mem_qty(tev)

def GetTevRegMem(tev, idx):
    """
    Return the memory pointed by 'index' for the specified event
    @param tev: event number
    @param idx: memory address index
    """
    return idaapi.get_tev_reg_mem(tev, idx)

def GetTevRegMemEa(tev, idx):
    """
    Return the address pointed by 'index' for the specified event
    @param tev: event number
    @param idx: memory address index
    """
    return idaapi.get_tev_reg_mem_ea(tev, idx)

def GetTevCallee(tev):
    """
    Return the address of the callee for the specified event
    @param tev: event number
    """
    return idaapi.get_call_tev_callee(tev)

def GetTevReturn(tev):
    """
    Return the return address for the specified event
    @param tev: event number
    """
    return idaapi.get_ret_tev_return(tev)

def GetBptTevEa(tev):
    """
    Return the address of the specified TEV_BPT event
    @param tev: event number
    """
    return idaapi.get_bpt_tev_ea(tev)