[haiku-development] Re: Debugging API - Is It Documented?
- From: Ingo Weinhold <ingo_weinhold@xxxxxx>
- To: haiku-development@xxxxxxxxxxxxx
- Date: Fri, 04 Feb 2011 16:54:22 +0100
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
Other related posts:
