# Debug using gdbserver

The gdbserver utility allows you to run the GDB tool remotely from the Linux host. This utility is helpful when there is a storage constraint for debug symbols on the device.

## Enable gdbserver on the device

By default, the build doesn't enable gdbserver. To enable gdbserver, do the following:

1. Go to the `layers/meta-qcom-hwe/recipes-devtools/packagegroups/`
directory and open the `packagegroup-core-tools-debug.bbappend` file.
2. Change the `packagegroup-core-tools-debug.bbappend` file to add the
`gdbserver` in the package list.
3. Recompile and flash the build on the device.

## Configure gdbserver on the device

To configure gdbserver on the device, run the following commands using SSH:

mount -o rw,remount /
    Copy to clipboard

gdbserver :8888 <path-to-binary>
    Copy to clipboard

For example:

gdbserver :8888 /usr/bin/tqftpserv
    Copy to clipboard

Sample output:

sh-5.1# gdbserver :8888 /usr/bin/tqftpservu
    Process /usr/bin/tqftpservu created; pid = 3214
    Listening on port 8888
    Remote debugging from host ::ffff:127.0.0.1, port 52814
    Remote side has terminated connection.  GDBserver will reopen the connection.
    Listening on port 8888
    Remote debugging from host ::ffff:127.0.0.1, port 47252
    Copy to clipboard

The sample output shows that the device is ready to communicate with the Linux host computer.

## Configure gdb on the Linux host computer

To configure the gdb tool on a Linux host, do the following:

1. Install gdb and gdb-multiarch tools.

sudo apt-get install gdb gdb-multiarch
        Copy to clipboard
2. Create a debug directory to capture all the symbols from the build.

mkdir test_gdbserver
        Copy to clipboard
3. Copy the rootfs having the debug symbols from the build location to the `test_gdbserver` debug directory.

cp -f <ENTER_PATH>/build-qcom-wayland/tmp-glibc/deploy/images/<chipset>/qcom-multimedia-image-<chipset>-dbg.rootfs.tar.bz2  test_gdbserver
        Copy to clipboard

cd test_gdbserver
        Copy to clipboard

tar -xvf qcom-multimedia-image-<chipset>-dbg.rootfs.tar.bz2
        Copy to clipboard

    While running these commands, replace `<chipset>` with the appropriate value as specified in the following table.

> 
> 
> | Chipset | Value |
>     | --- | --- |
>     | QCS6490 | <br>`qcm6490` |
>     | QCS5430 | <br>`qcm6490` |
>     | IQ-8275 | `IQ-8300` |
>     | IQ-9075 | `IQ-9100` |
>     | IQ-615 | `IQ-615` |
>     |  |  |

    The `test_gdbserver` is now ready with the symbols.
4. Start the gdb-multiarch tool using the `gdb-multiarch <EXECUTABLE_PATH>` command.

    For example,

gdb-multiarch test_gdbserver/usr/bin/tqftpserv
        Copy to clipboard

    The gdb-multiarch tool starts on the gdb console.
5. Run the following commands on the GDB console:

set gnutarget elf64-littleaarch64
        Copy to clipboard

    Set `sysroot <path-to-new-debug-directory>`.

set sysroot <ENTER_PATH>/test_gdbserver
        Copy to clipboard

target remote <target_ip>:8888
        Copy to clipboard

bt
        Copy to clipboard

b
        Copy to clipboard

info threads
        Copy to clipboard

The following are the sample outputs of the configuration process:

Sample output 1:

sh-5.1# ps -ef
    PID   USER   TIME   COMMAND
    1     root   0:04   {systemd} /sbin/init
    2     root   0:00   [kthreadd]
    3     root   0:00   [pool_workqueue_]
    4     root   0:00   [kworker/R-rcu_g]
    5     root   0:00   [kworker/R-rcu_p]
    Copy to clipboard

Sample output 2:

gdb-multiarch /test_gdbserver/usr/bin/.debug/tqftpserv
    GNU gdb (Ubuntu 9.2-0ubuntu1~20.04.2) 9.2
    Copyright (C) 2020 Free Software Foundation, Inc.
    License GPLv3+: GNU GPL version 3 or later http://gnu.org/licenses/gpl.html
    This is free software: you are free to change and redistribute it.
    There is NO WARRANTY, to the extent permitted by law.
    Type "show copying" and "show warranty" for details.
    This GDB was configured as "x86_64-linux-gnu".
    Type "show configuration" for configuration details.
    For bug reporting instructions, please see:
    http://www.gnu.org/software/gdb/bugs/.
    Find the GDB manual and other documentation resources online at:
    http://www.gnu.org/software/gdb/documentation/.
    Copy to clipboard

Sample output 3:

Reading symbols from /test_gdbserver/usr/bin/.debug/tqftpserv...
    (gdb) set gnutarget elf64-littleaarch64
    (gdb) set sysroot /test_gdbserver
    (gdb) target remote 10.92.168.78:8888
    Remote debugging using 10.92.168.78:8888
    warning: while parsing target description (at line 71): Vector "v8bf16" references undefined type "bfloat16"
    warning: Could not load XML target description; ignoring
    warning: Unable to find dynamic linker breakpoint function.
    Reading symbols from /test_gdbserver/lib/ld-linux-aarch64.so.1...
    (no debugging symbols found)...done.
    Reading symbols from /test_gdbserver/lib/.debug/ld-linux-aarch64.so.1...
    Loaded symbols for /test_gdbserver/lib/.debug/ld-linux-aarch64.so.1
    warning: no loadable sections found in added symbol-file system-supplied DSO at 0xfffff7ffb000
    0x0000fffff7fda870 in _start ()
    from /test_gdbserver/lib/.debug/ld-linux-aarch64.so.1
    (gdb) bt
    #0 0x0000fffff7fda870 in _start ()
    from /test_gdbserver/lib/.debug/ld-linux-aarch64.so.1
    #1 0x0000000000000000 in ?? ()
    (gdb) b
    Breakpoint 1 at 0xfffff7fda870
    (gdb) info threads
    Id   Target Id                     Frame
    * 1    Thread 3212                   0x0000fffff7fda870 in _start ()
    (gdb)
    Copy to clipboard

For more information, see [Linux manual page](https://man7.org/linux/man-pages/man1/gdbserver.1.html).

Last Published: Feb 12, 2026

[Previous Topic
Collect coredump](https://docs.qualcomm.com/bundle/publicresource/80-70023-12/topics/collect_coredumps.md) [Next Topic
Debug with user space logs](https://docs.qualcomm.com/bundle/publicresource/80-70023-12/topics/userspace_logs.md)

Source: [https://docs.qualcomm.com/doc/80-70023-12/topic/debug_using_gdbserver.html](https://docs.qualcomm.com/doc/80-70023-12/topic/debug_using_gdbserver.html)