The nacl-gdb
debugger is
a version of GDB that you can use
to debug your Native Client modules.
This page concentrates on how nacl-gdb
differs from most versions of GDB.
In addition to reading this page,
you might want to refer to
Debugging Tips and to
online
GDB documentation.
Note:
nacl-gdb
runs only on Linux.
Using nacl-gdb
is similar to using other GDB versions,
with one exception:
nacl-gdb
has two modes,
service runtime and native client.
The modes are necessary because,
from nacl-gdb
's point of view,
a running Native Client module is actually two programs —
the service runtime (sel_ldr
)
and the Native Client module (*.nexe
).
The Native Client module runs in its own protected space,
with the assumption that its symbols
won't collide with the service runtime.
To keep the symbols separate,
nacl-gdb
is modal.
You can tell which mode nacl-gdb
is in
by looking at the prompt.
Prompt | Mode |
---|---|
(sr-gdb) |
service runtime |
(nc-gdb) |
native client |
To run nacl-gdb
, you should have the following:
An installed, up-to-date version of Native Client.
PATH
that includes the Native Client toolchain tools directory,
so that you can easily execute
nacl-gdb
.
The tools directory is here:
install_dir/build/native_client/src/third_party/nacl_sdk/linux/sdk/nacl-sdk/bin
$ cd install_dir/build/native_client/tests/hello_world $ nacl-gcc -g -o hello_world.nexe hello_world.c
Here's an example of running nacl-gdb
.
$ nacl-gdb hello_world.nexe GNU gdb 6.8-nacl-beta1 ... (nc-gdb) break hello_world Breakpoint 1 at 0x202c6: file hello_world.c, line 39. (nc-gdb) run Starting program: /whatever/build/native_client/tests/hello_world/hello_world.nexe [Thread debugging using libthread_db enabled] [New Thread 0xf7fdd6c0 (LWP 17377)] [New Thread 0xf7ffbbb0 (LWP 17380)] [Switching to Thread 0xf7ffbbb0 (LWP 17380)] Breakpoint 1, hello_world () at hello_world.c:39 39 printf("Hello, World!\n"); (nc-gdb) backtrace #0 hello_world () at hello_world.c:39 #1 0x00020320 in main () at hello_world.c:43 (nc-gdb) display/i $pc 1: x/i $pc 0x202c6 <hello_world+6>: movl $0x26000,(%esp) (nc-gdb) stepi 0x000202cd 39 printf("Hello, World!\n"); 1: x/i $pc 0x202cd <hello_world+13>: lea 0x0(%esi,%eiz,1),%esi (nc-gdb) <Enter> 0x000202d4 39 printf("Hello, World!\n"); 1: x/i $pc 0x202d4 <hello_world+20>: lea 0x0(%edi,%eiz,1),%edi (nc-gdb) <Enter> 0x000202db 39 printf("Hello, World!\n"); 1: x/i $pc 0x202db <hello_world+27>: call 0x204e0 <puts> (nc-gdb) continue Continuing. Hello, World! Program exited normally. (nc-gdb) q $
If you don't see any references to the source file —
for example, hello_world.c
—
and you don't see C or C++ source code,
then you're probably using an executable
that doesn't have debugging symbols.
Recompile with the -g
flag.
An example:
$ nacl-gcc -g -o my_prog.nexe my_prog.c
By default, nacl-gdb
uses the service runtime that's in
~/.mozilla/plugins/sel_ldr_bin
.
Even if you've downloaded the latest Native Client release,
if you haven't installed the plug-in yet,
the debugger might be trying to run the module
using an old, expired version of the service runtime.
You should
install
the
latest version
of Native Client.
Alternatively, you can specify the location of the service runtime using the
--loader
startup option.
In addition to the usual GDB options,
nacl-gdb
supports --loader
.
Use the --loader
option
to specify a different path for sel_ldr_bin
from the default, which is
~/.mozilla/plugins/sel_ldr_bin
.
An example:
nacl-gdb --loader=.../scons-out/dbg-linux/staging/sel_ldr hello.nexe
The nacl-gdb
debugger supports all the usual GDB commands,
such as
break
(b
),
run
(r
), and
backtrace
(bt
).
It also supports the following commands,
which are specific to Native Client.
nacl apply-runtime
:
Execute a command in service-runtime mode nacl apply
:
Execute a command in native-client mode set nacl native-client-path
:
Set the path of the Native Client module set nacl prompt
:
Set the prompt to use when debugging native-client code set nacl service-runtime-args
:
Set the arguments of the sel_ldr
program show nacl native-client-path
:
Show the path of the Native Client module show nacl prompt
:
Show the prompt used in native-client mode show nacl service-runtime-args
:
Show the arguments of the sel_ldr
program show nacl service-runtime-path
:
Show the path of the sel_ldr
program
To get information about these commands
while you're running the debugger,
you can use the
apropos
and help
commands.
An example:
(nc-gdb) apropos nacl nacl -- Commands for nacl set nacl -- Generic command for setting nacl flags set nacl native-client-path -- Set the path of the native client program show nacl -- Generic command for showing nacl flags show nacl native-client-path -- Show the path of the nacl program ... (nc-gdb) help show nacl ...
Two commands let you temporarily switch modes and execute a command:
nacl apply-runtime command [args...]
(sr-gdb)
prompt
nacl apply command [args...]
(nc-gdb)
prompt
These commands are useful for tasks such as
examining the state of the Native Client module or the service runtime,
or setting a breakpoint in the module
when it's stopped in service-runtime code.
The following example illustrates
switching modes to enable setting breakpoints
in the main
methods of both the service runtime
and the Native Client module.
$ nacl-gdb --loader=scons-out/dbg-linux/staging/sel_ldr tests/hello_world/hello_world.nexe ... (nc-gdb) nacl apply-runtime break main Breakpoint 1 at 0x804a5c5: file service_runtime/sel_main.c, line 185. (nc-gdb) info break Num Type Disp Enb Address What 1 breakpoint keep y sr:0x0804a5c5 service_runtime/sel_main.c:185 (nc-gdb) run Starting program: /whatever/build/native_client/tests/hello_world/hello_world.nexe [Thread debugging using libthread_db enabled] [New Thread 0xf7fdd6c0 (LWP 12522)] nacl [Switching to Thread 0xf7fdd6c0 (LWP 12522)] Breakpoint 1, main (ac=2, av=0xffffd8d4) at service_runtime/sel_main.c:194 194 char *nacl_file = 0; (sr-gdb) nacl apply break main Breakpoint 2 at 0x20300: file hello_world.c, line 42. (sr-gdb) info break Num Type Disp Enb Address What 1 breakpoint keep y sr:0x0804a5e5 in main at service_runtime/sel_main.c:185 breakpoint already hit 1 time 2 breakpoint keep y nc:0x00020300 hello_world.c:42 (sr-gdb)
set nacl service-runtime-args [args...]
This command sets the arguments to sel_ldr
,
not including the Native Client module or its arguments.
Use this command to specify arguments for sel_ldr
itself —
for example, -h d:D
.
Do not specify the -f
argument;
nacl-gdb
supplies that itself.
Except as otherwise noted, the content of this page is licensed under a Creative Commons Attribution 2.5 license.