platforms Package

platforms Package

Platform Support Modules

The vtrace platforms package is where the modules live that implement platform specific functionality that is used behind the scenes of the top level Trace object. If you’re not porting vtrace to a new platform, or chasing a bug, you probably don’t need anything from here...

android Module

class vtrace.platforms.android.AndroidArmTrace(avd=None)

Bases: vtrace.Trace, vtrace.platforms.gdbstub.GdbStubMixin, vtrace.archs.arm.ArmMixin, vtrace.platforms.posix.ElfMixin, vtrace.platforms.base.TracerBase

platformAttach(pid)

platformDetach()

platformGetMaps()

platformOpenFile(filename)

platformPs()

vtrace.platforms.android.adbCommand(*argv)

vtrace.platforms.android.checkGdbServer()

vtrace.platforms.android.getTrace(avd=None)

vtrace.platforms.android.openAndroidFile(fname)

base Module

Tracer Platform Base

class vtrace.platforms.base.TracerBase

Bases: vtrace.notifiers.Notifier

The basis for a tracer’s internals. All platformFoo/archFoo functions are defaulted, and internal state is initialized. Additionally, a number of internal utilities are housed here.

addLibraryBase(libname, address, always=False)

This should be used at load time to setup the library event metadata.

This must be called from a context where it’s safe to fire notifiers, because it will fire a notifier to alert about a LOAD_LIBRARY. (This means not from inside another notifer)

archAddWatchpoint(address, size=4, perms='rw')

Add a watchpoint for the given address. Raise if the platform doesn’t support, or too many are active...

archCheckWatchpoints()

If the current register state indicates that a watchpoint was hit, return the address of the watchpoint and clear the event. Otherwise return None

archGetRegCtx()

Return a new empty envi.registers.RegisterContext object for this trace.

archGetStackTrace()

archRemWatchpoint(address)

checkBreakpoints()

This is mostly for systems (like linux) where you can’t tell the difference between some SIGSTOP/SIGBREAK conditions and an actual breakpoint instruction.

This method will return true if either the breakpoint subsystem or the sendBreak (via ShouldBreak meta) is true (and it will have handled firing events for the bp)

checkPageWatchpoints()

Check if the given memory fault was part of a valid MapWatchpoint.

checkWatchpoints()

delLibraryBase(baseaddr)

doStepLoop()

fireNotifiers(event)

Fire the registered notifiers for the NOTIFY_* event.

fireTracerThread()

getExe()

Get the full path to the main executable for this attached Trace

getResolverForFile(filename)

getStackTrace()

Return a list of the stack frames for this process (currently Intel/ebp based only). Each element of the “frames list” consists of another list which is (eip,ebp)

initMode(name, value, descr)

Initialize a mode, this should ONLY be called during setup routines for the trace! It determines the available mode setings.

nextBpId()

normFileName(libname)

notify(event, trace)

We are frequently a notifier for ourselves, so we can do things like handle events on attach and on break in a unified fashion.

platformAllocateMemory(size, perms=7, suggestaddr=0)

platformAttach(pid)

Actually carry out attaching to a target process. Like platformStepi this is expected to be ATOMIC and not return until a complete attach.

platformCall(address, args, convention=None)

Platform call takes an address, and an array of args (string types will be mapped and located for you)

platformCall is expected to return a dicionary of the current register values at the point where the call has returned...

platformContinue()

platformDetach()

Actually perform the detach for this type

platformExec(cmdline)

Platform exec will execute the process specified in cmdline and return the PID

platformGetFds()

Return what getFds() wants for this particular platform

platformGetMaps()

Return a list of the memory maps where each element has the following structure: (address, length, perms, file=””) NOTE: By Default this list is available as Trace.maps because the default implementation attempts to populate them on every break/stop/etc...

platformGetMemFault()

Return the addr of the current memory fault or None

platformGetRegCtx(threadid)

platformGetSignal()

Return the currently posted exception/signal....

platformGetThreads()

Return a dictionary of <threadid>:<tinfo> pairs where tinfo is either the stack top, or the teb for win32

platformInjectSo(filename)

platformInjectThread(pc, arg=0)

platformKill()

platformOpenFile(filename)

platformParseBinary(filename, baseaddr, normname)

Platforms must parse the given binary file and load any symbols into the internal SymbolResolver using self.addSymbol()

platformProcessEvent(event)

This method processes the event data provided by platformWait()

This method is responsible for firing ALL notifiers except:

vtrace.NOTIFY_CONTINUE - This is handled by the run api (and isn’t the result of an event)

platformProtectMemory(va, size, perms)

platformPs()

Actually return a list of tuples in the format (pid, name) for this platform

platformReadMemory(address, size)

platformRelease()

Called back on release.

platformResumeThread(thrid)

platformSelectThread(thrid)

Platform implementers are encouraged to use the metadata field “ThreadId” as the identifier (int) for which thread has “focus”. Additionally, the field “StoppedThreadId” should be used in instances (like win32) where you must specify the ORIGINALLY STOPPED thread-id in the continue.

platformSetRegCtx(threadid, ctx)

platformSetSignal(sig=None)

Set the current signal to deliver to the process on cont. (Use None for no signal delivery.

platformStepi()

PlatformStepi should be ATOMIC, meaning it gets called, and by the time it returns, you’re one step further. This is completely regardless of blocking/nonblocking/whatever.

platformSuspendThread(thrid)

platformWait()

Wait for something interesting to occur and return a platform specific representation of what happened.

This will then be passed to the platformProcessEvent() method which will be responsible for doing things like firing notifiers. Because the platformWait() method needs to be commonly @threadwrap and you can’t fire notifiers from within a threadwrapped function...

platformWriteMemory(address, bytes)

release()

Do cleanup when we’re done. This is mostly necissary because of the thread proxy holding a reference to this tracer... We need to let him die off and try to get garbage collected.

shouldRunAgain()

A unified place for the test as to weather this trace should be told to run again after reaching some stopping condition.

steploop()

Continue stepi’ing in a loop until shouldRunAgain() returns false (like RunForever mode or something)

wait()

Wait for the trace target to have something happen... If the trace is in NonBlocking mode, this will fire a thread to wait for you and return control immediately.

class vtrace.platforms.base.TracerThread

Bases: threading.Thread

Ok... so here’s the catch... most debug APIs do not allow one thread to do the attach and another to do continue and another to do wait... they just dont. So there. I have to make a thread per-tracer (on most platforms) and proxy requests (for some trace API methods) to it for actual execution. SUCK!

However, this lets async things like GUIs and threaded things like cobra not have to be aware of which one is allowed and not allowed to make particular calls and on what platforms... YAY!

run()

Run in a circle getting requests from our queue and executing them based on the thread.

vtrace.platforms.base.threadwrap(func)

freebsd Module

gdbstub Module

GDB support

exception vtrace.platforms.gdbstub.GdbServerDisconnected

Bases: exceptions.Exception

class vtrace.platforms.gdbstub.GdbStubMixin(host=None, port=None)

platformAttach(pid)

platformContinue()

platformDetach()

platformGetMaps()

platformGetRegCtx(tid)

Get an envi register context from the target stub.

platformGetThreads()

platformProcessEvent(event)

platformReadMemory(addr, size)

platformSendBreak()

For now, the only way I know how to re-break the target is to disconnect and re-connect... TOTALLY GHETTO HACK!

platformSetRegCtx(tid, ctx)

Set the target stub’s register context from the envi register context

platformStepi()

platformWait()

platformWriteMemory(addr, mbytes)

class vtrace.platforms.gdbstub.GdbStubMixin_old

Bases: envi.registers.RegisterContext

normFileName(fname)

platformParseBinary(filename, baseaddr, normname)

platformParseBinaryPe(filename, baseaddr, normname)

platformPs()

class vtrace.platforms.gdbstub.GdbStubTrace(archname)

Bases: vtrace.Trace, vtrace.platforms.gdbstub.GdbStubMixin, vtrace.platforms.base.TracerBase

buildNewTrace()

class vtrace.platforms.gdbstub.KeBugCheckBreak(symname)

Bases: vtrace.breakpoints.Breakpoint

notify(event, trace)

vtrace.platforms.gdbstub.csum(bytes)

vtrace.platforms.gdbstub.pkt(cmd)

linux Module

posix Module

Posix Signaling Module

class vtrace.platforms.posix.ElfMixin

A platform mixin to parse Elf binaries

platformParseBinary(filename, baseaddr, normname)

class vtrace.platforms.posix.PosixMixin

A mixin for systems which use POSIX signals and things like wait()

handleAttach()

handlePosixSignal(sig)

Handle a basic posix signal for this trace. This was seperated from platformProcessEvent so extenders could skim events and still use this logic.

platformKill()

platformProcessEvent(status)

platformSendBreak()

platformWait()

sendSignal(signo)

class vtrace.platforms.posix.PtraceMixin

A platform mixin for using the ptrace functions to attach/detach/continue/stepi etc. Many *nix systems will probably use this...

NOTE: if you get a PT_FOO undefined, it probably means that the PT_FOO macro isn’t defined for that platform (which means it need to be done another way like PT_GETREGS on darwin doesn’t exist... but the darwin mixin over-rides platformGetRegs)

platformExec(*args, **kwargs)

platformWriteMemory(*args, **kwargs)

vtrace.platforms.posix.ptrace(code, pid, addr, data)

The contents of this call are basically cleanly passed to the libc implementation of ptrace.

solaris Module

Solaris Platform Module (Incomplete)

class vtrace.platforms.solaris.SolarisIntelMixin

Handle register formats for the intel solaris stuff

getRegisterFormat()

getRegisterNames()

platformGetMaps()

platformReadMemory(addr, size)

platformWriteMemory(addr, bytes)

class vtrace.platforms.solaris.SolarisMixin

initMixin()

platformAttach(pid)

platformContinue()

Tell the process to continue running

platformDetach()

platformGetRegs()

platformWait()

wait for the process to do someting “interesting”

writeCtl(bytes)

vmware Module

Underlying platform implementation for kernel debugging with vmware gdbserver.

win32 Module

Submodules

• darwin Package
  • darwin Package