[haiku-development] Re: Debugging API - Is It Documented?

On Fri, Feb 4, 2011 at 10:54 AM, Ingo Weinhold <ingo_weinhold@xxxxxx> wrote:

> On 2011-01-30 at 22:31:17 [+0100], Michael Franz <mvfranz@xxxxxxxxx>
> wrote:
> > I am looking for documentation on the debug API used within Haiku.  Is
> this
> > documented in anyway? My searching has only led me to bdb - a program and
> > not the documentation.
>
> First of all, please note that the API is not compatible with BeOS's and
> ATM
> it isn't even considered stable (i.e. it might change in an incompatible
> way, though probably not drastically). So, if you use this API in a
> program,
> now, you might have to adjust it to work properly in a later Haiku version.
>
> I believe there isn't any documentation besides what's in the header
> (kernel/debugger.h). There are a bunch of programs using the API, which you
> can use as a reference, e.g. strace and profile in src/bin/debug and, of
> course, gdb (particularly src/bin/gdb/gdb/haiku-nat.c) and Debugger
> (src/apps/debugger/debugger_interface/). Most of them use the private
> libdebug (headers/private/debug/, src/kits/debug/), which provides
> convenience functions for the debugging API.
>
> As super-short intro how to use the API: It is all based on port
> communication. There are two relevant port one needs to work with: The
> debugger port and the debug nub port. The former is created by the
> debugging
> program and is passed to install_team_debugger(). It is where all the debug
> events of the debugged program are sent to. The latter is serviced by the
> debug nub thread for the debugged program. Both thread and port are
> automatically created by the kernel when the program is being debugged. The
> debug nub port is returned by install_team_debugger() and it is the port
> where the debugging program can send commands (step/continue thread,
> (de)install breakpoint, read/write memory, etc.) for the debugged team to.
> For commands that have a reply a reply port is specified in the command
> message.
>
> Debug event messages sent to the debugger port are always "one-way", i.e.
> they aren't directly responded to. Most events cause the respective
> debugged
> thread to be stopped though, so these events can be considered synchronous
> and sending the thread a "continue" command
> (B_DEBUG_MESSAGE_CONTINUE_THREAD) is often the desired course of action.
> Whether an event is synchronous can be determined by the value of the
> debug_origin::nub_port of the debug event message. It is < 0, when the
> event
> is asynchronous.
>
> Debug events and debug commands is pretty much all there is to it. For
> details on individual events and commands have a look at the header.
>
> CU, Ingo
>
> Ingo,

This is great!  I was doing more research and was beginning to think most
systems were using ptrace.  Glad Haiku has put some thought into a good
debugging API.  I will take a closer look at this as time permits.

Thank you

Michael

Other related posts: