docs/manual/using-buildroot-debugger.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 ==== Using +gdb+ in Buildroot
   5
   6 Buildroot allows to do cross-debugging, where the debugger runs on the
   7 build machine and communicates with +gdbserver+ on the target to
   8 control the execution of the program.
   9
  10 To achieve this:
  11
  12 * If you are using an _internal toolchain_ (built by Buildroot), you
  13   must enable +BR2_PACKAGE_HOST_GDB+, +BR2_PACKAGE_GDB+ and
  14   +BR2_PACKAGE_GDB_SERVER+. This ensures that both the cross gdb and
  15   gdbserver get built, and that gdbserver gets installed to your target.
  16
  17 * If you are using an _external toolchain_, you should enable
  18   +BR2_TOOLCHAIN_EXTERNAL_GDB_SERVER_COPY+, which will copy the
  19   gdbserver included with the external toolchain to the target. If your
  20   external toolchain does not have a cross gdb or gdbserver, it is also
  21   possible to let Buildroot build them, by enabling the same options as
  22   for the _internal toolchain backend_.
  23
  24 Now, to start debugging a program called +foo+, you should run on the
  25 target:
  26
  27 ----------------------------
  28 gdbserver :2345 foo
  29 ----------------------------
  30
  31 This will cause +gdbserver+ to listen on TCP port 2345 for a connection
  32 from the cross gdb.
  33
  34 Then, on the host, you should start the cross gdb using the following
  35 command line:
  36
  37 ----------------------------
  38 <buildroot>/output/host/usr/bin/<tuple>-gdb -x <buildroot>/output/staging/usr/share/buildroot/gdbinit foo
  39 ----------------------------
  40
  41 Of course, +foo+ must be available in the current directory, built
  42 with debugging symbols. Typically you start this command from the
  43 directory where +foo+ is built (and not from +output/target/+ as the
  44 binaries in that directory are stripped).
  45
  46 The +<buildroot>/output/staging/usr/share/buildroot/gdbinit+ file will tell the
  47 cross gdb where to find the libraries of the target.
  48
  49 Finally, to connect to the target from the cross gdb:
  50
  51 ----------------------------
  52 (gdb) target remote <target ip address>:2345
  53 ----------------------------