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.