This chapter describes how to use gdb-remote, a
Simics module that lets you connect a GDB session running on your host
machine to the simulated machine using GDB's remote debugging
protocol, and use GDB to debug software running on the target machine.
If you load the gdb-remote module in Simics, you can
use the remote debugging feature of GDB, the GNU debugger,
to connect one or more GDB processes to Simics over TCP/IP. In order
to do this, you need a GDB compiled to support the simulation's target
architecture on whichever host you're running. The
gdb-remote module has been tested with several
different versions of GDB 6 and 7.
A prebuilt GDB is distributed in the Simics GDB (#1031) package. In a Simics
project, the bin/gdb command (bin\gdb.bat on Windows) can
be used to launch GDB.
Note:
The bin/gdb or bin\gdb.bat commands will only work
if Simics GDB (#1031) is installed and available as addon package in the
Simics project.
To connect a GDB session to Simics, start your Simics session and run
the new-gdb-remote command, optionally followed by a TCP/IP
port number, which defaults to 9123 otherwise. This will automatically
load the gdb-remote module. You can also specify
which processor or context the remote debugger should be attached to with
the cpu and context arguments.
When a configuration is loaded, Simics will start listening to
incoming TCP/IP connections on the specified port. Run the simulated
machine up to the point where you want to connect GDB. To inspect a
user process or dynamically loaded parts of the kernel, the easiest
solution might be to insert magic instructions at carefully chosen
points. For static kernel debugging, a simple breakpoint on a suitable
address will solve the problem.
Note:
When debugging the start-up phase of an operating system, it
might happen that gdb gets confused by the machine state and
disconnects when you try to connect. In this case, execute a few
instructions and try again.
Once Simics is in the desired state, start your GDB session, load any
debugging information into it, and then connect it to Simics using the
target remote host:port command,
where host is the host Simics is running on, and
port is the TCP/IP port number as described above. Here is
a short sample session using firststeps:
(gdb) symbol-file targets/qsp-x86/images/yocto_linux/yocto-1.8-vmlinux
Reading symbols from targets/qsp-x86/images/yocto_linux/yocto-1.8-vmlinux...done.
(gdb) set endian little
The target is assumed to be little endian
(gdb) target remote localhost:9123
Remote debugging using localhost:9123
0x000000000000fff0 in unicast_sock ()
(gdb)
Note that yocto-1.8-vmlinux is internal file and not distributed in the package, so
the reader cannot run the example in simics.
Note:
The GDB supplied with Simics has builtin support for several target
architectures. The architecture will be set automatically when GDB connects,
but for little-endian architectures (such as x86 and x86_64), the following GDB
command has to be issued: set endian little.
From this point, you can use GDB to control the target machine by
entering normal GDB commands such as continue,
step, stepi, info regs,
breakpoint, etc.
Note:
GDB does not expect the target state to change while it is in control and has
asked for the simulation to be stopped. If the simulation is started from
another frontend (e.g., by the continue or reverse
commands from the Simics command line) then GDB will not be notified and will
still use cached information about the program location and register values.
To recover from such a situation, issue a GDB command that makes the
simulation run.
To force Simics to close a connection, use the gdb0.disconnect
command.
The gdb-remote module does not have any
high-level information about the OS being run inside Simics. This
means that in order to examine memory or disassemble code, the data or
code you want to look at has to be in the active TLB.
Note:
When using gdb-remote with targets supporting
multiple address sizes (such as x86-64 and SPARC), you must have a GDB
compiled for the larger address size. For SPARC, run GDB's configure
script with the --target=sparc64-sun-solaris2.8
option.