These instructions are intended for use with the Scratchbox build environment provided with the ACCESS Linux Platform SDK. These instructions can be used with either the UML ("Simulator") target environment or an ARM target device.
There are three types of binaries that we care about debugging: Linux executables (e.g., servers or daemons), Linux shared libraries, and ACCESS Linux Platform applications. ACCESS Linux Platform applications are really Linux shared libraries, although they are usually built and packaged (along with resources, an icon, and an XML manifest file) into a single .bar file. For this reason ACCESS Linux Platform applications are more than just a Linux shared library.
These instructions focus on debugging ACCESS Linux Platform applications. With minor modifications (where noted), the information here should also be useful for debugging servers.
The Scratchbox environment is for building native target executables and ACCESS Linux Platform applications. Scratchbox is not for executing any built executables except for those required to run as part of the build process. Because the building and running of ACCESS Linux Platform applications is not supported on the Ubuntu host, all debugging is effectively "remote" debugging.
The Simulator is a remote target, with its own (private) IP address of 192.168.3.101. The target hardware is a remote target as well, with its own (private) IP address of 192.168.1.101.
GDB
Each Scratchbox toolchain is delivered along with a GDB (6.1) executable configured and built for the specific target architecture. This "scratchbox-gdb" is somewhat dated, but it does run in Scratchbox. This is important since any fully-specified paths that it gets from the target or symbol information for sources can easily be located within Scratchbox.
Note that there is, of course, a generic host-provided GDB, but it only works for x86 binaries and is not necessarily configured to work with the same gcc and glibc that ACCESS Linux Platform uses. Accordingly, it isn't used in ACCESS Linux Platform application development.
gdbserver
gdbserver is a control program which allows you to connect your program with a remote GDB connection. gdbserver runs on your remote target, while GDB runs on your host and talks to the remote gdbserver. For complete information on remote debugging using GDB and gdbserver, see http://sources.redhat.com/gdb/current/onlinedocs/gdb_18.html#SEC162.
On ACCESS Linux Platform all debugging is remote debugging. That means that you'll be running gdbserver against a Linux executable (or attaching to an already-running process) on the target device (or Simulator or Emulator), and then connecting to that gdbserver via TCP/IP from GDB running in Scratchbox.
Debugging ACCESS Linux Platform Applications
ACCESS Linux Platform applications are Linux shared libraries, therefore, they cannot be launched in a process from a shell or by gdbserver.Instead, they must be launched by the Application Manager. Fortunately, the Application Manager knows how to launch an ACCESS Linux Platform application as well as how to hold it for debugging. Note that before you can launch or debug an application, the package must be installed into the target file system (/opt/alp/packages) and registered with the Package Manager. By using a makefile similar to those employed by the sample applications, all of the details of communicating with your remote target are handled for you. Simply issue the following commands in a Scratchbox shell to build and begin debugging your application:
sbox$ make install sbox$ make debug
The first command, make install, builds, copies, and registers the application with the Package Manager. The make debug command then launches the application for debugging, attaches to gdbserver, and runs GDB.
TUI Mode
GDB is a command-line debugger. For a somewhat more graphical experience, you can enable "Text User Interface" (TUI) mode. TUI is a terminal interface which uses the curses library to show the source file, the assembly output, the program registers, and GDB commands in separate text windows. From within GDB, you can enter TUI mode by pressing CTRL+X and then pressing the "A" key. (There are a number of ways to enter TUI mode; see TUI Key Bindings at http://sources.redhat.com/gdb/current/onlinedocs/gdb_23.html#SEC235.)
Documentation on TUI mode can be found at http://sources.redhat.com/gdb/current/onlinedocs/gdb_23.html#SEC233.
Debugging Executables
When debugging, you usually will be debugging an ACCESS Linux Platform application as described above. However, there are times when you need to debug a Linux executable or attach to an existing process. This section describes how to do that.
Starting gdbserver on the Remote Target
There are two ways to start a gdbserver session on your remote target: you can either launch a process, or you can attach to a running process. Either way, you will need some sort of target shell to do this.
Launch a Process
To use the server, you must tell it how to communicate with GDB, the name of your program, and the arguments for your program. The usual syntax is:
gdbserver :portNo program [ args ... ]
portNo is the port number on which to passively wait, waiting for a host GDB to communicate with it. Use a port such as 5050 if you are doing this manually.
Attach to a Running Process
This is accomplished via the --attach argument. The syntax is:
gdbserver :portNo --attach pid
where pid is the process ID of a currently running process and portNo is the port number on which to passively wait, waiting for a host GDB to communicate with it. Note that when attaching to a running process, you needn't indicate a binary for the running process.
NOTE: Remember the port number used to start the
gdbserver session. You will need it during your host GDB session.
Starting GDB
In Scratchbox, launch GDB. You must provide the name of the executable that you are debugging. If you are debugging an ACCESS Linux Platform executable (that is, a server; not an ACCESS Linux Platform application), the executable is probably located in /opt/alp/bin.
sbox$ gdb /opt/alp/bin/my_server
Once in GDB, you may need to type the following to tell GDB how to locate any libraries that aren't in the standard (target) LD_LIBRARY_PATH:
(gdb) set solib-search-path /home/user.name/path/to/my_libraries
Note that when running GDB inside Scratchbox, you will get the correct GDB for the currently selected Scratchbox target configuration (x86 or ARM, as per your sb-conf current target setting).
Creating a .gdbinit file
If you find yourself typing a lot of the same text over and over again each time you launch GDB, you may wish to create a .gdbinit (for example, uml.gdbinit) setup file and specify it when launching GDB:
host$ alp-gdb /opt/alp/bin/my_server --command=my_server.gdbinit
Connecting GDB to gdbserver
From within GDB, connect to a particular gdbserver by supplying its IP address and port to the target remote command, like this:
(gdb) target remote 192.168.3.101:5050
Set a breakpoint on your entry point (or wherever you wish to stop), and tell the target to continue:
(gdb) b file.c:main (gdb) cont
Following this, the target should hit the specified breakpoint and you should be able to use GDB to debug the target.
