nacl-gdb

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.

Contents

Concepts

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

Running nacl-gdb

To run nacl-gdb, you should have the following:

Example

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
$

Troubleshooting

Why don't I see C/C++ source code?

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

Why does nacl-gdb say "This version of Native Client has expired"?

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.

Startup options

In addition to the usual GDB options, nacl-gdb supports --loader.

--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

Commands

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.

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
...

Temporarily switching modes

Two commands let you temporarily switch modes and execute a command:

nacl apply-runtime command [args...]
Apply a command as if you were at a (sr-gdb) prompt
nacl apply command [args...]
Apply a command as if you were at a (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)

Setting sel_ldr arguments

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.