Debug using GDB

This topic provides details on using the open-source GDB tool on a dev machine to debug sandboxed apps. This type of remote debugging is useful where resources are limited like in embedded apps.

The sample code uses an app named hw with one executable hw_exe and processes created in the same executable (hw_proc1, hw_proc2, etc.).

High-level steps to use GDB with a sandboxed app:

To debug a running app which is part of the default system:

  • On your dev machine, run
    $ remoteDebug appName processName targetIP
    .

To debug app startup, or app which is not part of default system: When compiling:

On the target device:

  • Make sure the devMode app is installed and running
  • Run the sandboxed app without the process you want to debug.
  • Start gdbserver in the sanboxed app.
  • Start the process in the sandboxed app with gdbserver.
  • Remove gdb from the sandboxed app after you're finished debugging.

On your dev machine:

See basicTargetConfigIP if you need to setup your host/target communications.

For ease of debugging you may want to disable watchdog. To do this turn off the watchdog option within KConfig and rebuild and update the framework. 

Services  --->
    [ ] Enable watchdog for Legato services
Note
It's also advisable to use absolute paths on both your dev machine and target. i.e.; /legato/systems/current/appsWriteable/devMode/bin/gdbserver to reference gdbserver.

Sample Code

The following simple app sample code is used in examples.

hw.adef

start: manual
 
executables:
{
    hw_exe = ( hw )
}
 
processes:
{
    run:
    {
        hw_proc1 = ( hw_exe )
        hw_proc2 = ( hw_exe )
        hw_proc3 = ( hw_exe )
        hw_proc4 = ( hw_exe )
    }
}

See Tutorials for more info.

.cdef

hw/Component.cdef 

sources:
{
    hello.c
}

hello.c

hw/hello.c 

#include "legato.h"
 
COMPONENT_INIT
{
    LE_INFO("HELLO WORLD.");
}

See Tutorials for more info.

Building with Debug Symbols

When building your app, build as normal, but add

-d <debug-path>

to the mkapp command-line to generate debug symbols in <debug-path>. You can use the same directory for all your apps -- each program or library will use a unique name.

When building the Legato framework from source, debug symbols for the legato framework are always generated and placed in build/ <target>/debug.

Running GDB on your Target Device

Running the App without a Process

To use GDB, start the sandboxed app excluding the process being debugged:

On the target, run the app excluding the process being debugged, hw_proc3: 

# app start hw --norun=hw_proc3

Start GDB on an App

On your dev machine, set up port forwarding from local host to the target. This bypasses the firewall on the target and allows GDB server to connect.

$ ssh -L 2000:localhost:2000 root@192.168.2.2
Warning
Do not end this session to the Target or the port forwarding will end. GDB won't be able to connect to the Target.

On the target, start gdbserver in the sandboxed /bin directory by running: 

# gdbCfg <app name>

For Example: 

# gdbCfg hw

Start the Process with GDB enabled

On the target, start gdbserver by starting the app with the arguments specified after -- (two dashes):

# app runProc <app name> --exe=/bin/gdbserver -- localhost:2000 /bin/<app bin dir>

For Example: 

# app runProc hw --exe=/bin/gdbserver -- localhost:2000 /bin/hw_exe

If started successfully, the following will be returned: 

Process /bin/hw_exe created; pid = 9783
Listening on port 2000

Launch GDB on your Dev Machine

To start GDB on your Dev Machine:

Launch gdb from Dev Machine

You need to run the commands from the directory where the hw app was made. The path _build_hw/wp85/app/hw/staging/read-only/bin/hw_exe is relative to the app directory; this build directory is generated when an app is made and the gdb commands must be run here.

In this example, we're running the gdb tool (arm-poky-linux-gnueabi-gdb) located in our target's toolchain path (/opt/swi/y17-ext/sysroots/x86_64-pokysdk-linux/usr/bin/arm-poky-linux-gnueabi for wp85). Use the findtoolchain command on your dev machine to determine the toolchain path.

Launch GDB from the toolchain using the following command (substitute your program and path for hw):

$ ~/LegatoApps/hw$ /opt/swi/y17-ext/sysroots/x86_64-pokysdk-linux/usr/bin/arm-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb _build_hw/wp85/app/hw/staging/read-only/bin/hw_exe

Remote Connect

After GDB is launched, use the target remote command to connect to the target: 

$ (gdb) target remote localhost:2000
Note
If you get an error about connecting make sure you have a ssh -L (port forwarding) session open between the dev machine and target.

The target will display: 

Remote debugging using localhost:2000

Now tell gdb to fetch the libraries to debug across the network, but use local debug symbols: 

$ (gdb) set debug-file-directory <debug-path>
$ (gdb) set sysroot remote:/
Note
By default the <debug-path> would be $LEGATO_ROOT/build/<target>/debug/ . It is recommanded to archive that directory along with your releases as to be able to process core dumps.

You should see GDB reading symbols for Legato components.

You can now run any of the standard gdb debugging commands on hw_exe.

Remove GDB from Sandbox

Once you've finished debugging, remove gdbserver from the sandbox /bin directory on the target: 

# gdbCfg hw --reset

Refer to the many available open source resources if you need help using gdb.

Copyright (C) Sierra Wireless Inc.