.. _debugging:

Debugging
#########

Overview
********
Zephyr offers multiple tools to debug user applications. Application runtime tools offer visibility into
threads/CPU loading while debugger tools such as GDB can be used for online/offline debug.

Application runtime tools
*************************
Applications can be built to analyze thread information as well as CPU load runtime.
Refer to `Zephyr documentation <https://docs.zephyrproject.org/latest/services/debugging/index.html>`_ for further details.

Debug using the GNU Debugger (GDB)
**********************************

GDB command reference
=====================
GDB command documentation can be found `here <https://sourceware.org/gdb/current/onlinedocs/gdb.html/index.html>`_

Attach debugger to running program
==================================

Debugger can be attached to a running program using 'west attach' option ::

  $ west attach -d build/ATMEVK-3430e-YQN-5_ns/zephyr/samples/bluetooth/peripheral --jlink --device 000900039134

GDB commands can be used after attaching to the end device ::

  -- west attach: rebuilding
  Change Dir: 'build/ATMEVK-3430e-YQN-5_ns/zephyr/samples/bluetooth/peripheral'

  Run Build Command(s): /people/lab/.local/bin/ninja -v
  ninja: no work to do.

  -- west attach: using runner atmisp
  Open On-Chip Debugger 0.12.0-00020-gaf2e30d6d (2024-04-23-15:55)
  Licensed under GNU GPL v2
  For bug reports, read
    http://openocd.org/doc/doxygen/bugs.html
  Using JLINK
  ...
      TargetName         Type       Endian TapName            State
  --  ------------------ ---------- ------ ------------------ ------------
      0* Paris.cpu          cortex_m   little Paris.cpu          running

  [Paris.cpu] halted due to debug-request, current mode: Thread
  xPSR: 0x41000000 pc: 0x0004dd88 psp: 0x20008e20
  Info : Listening on port 6333 for tcl connections
  Info : Listening on port 4444 for telnet connections
  adapter speed: 300 kHz

  Remote debugging using :3333
  Info : accepting 'gdb' connection on tcp/3333
  ...
  Warn : Prefer GDB command "target extended-remote :3333" instead of "target remote :3333"
  __enable_irq ()
      at /data/labor/lab/zephyrproject/modules/hal/cmsis/CMSIS/Core/Include/cmsis_gcc.h:951
  951	  __ASM volatile ("cpsie i" : : : "memory");
  (gdb)  bt
  #0  __enable_irq ()
      at /data/labor/lab/zephyrproject/modules/hal/cmsis/CMSIS/Core/Include/cmsis_gcc.h:951
  #1  arch_cpu_idle () at /data/labor/lab/zephyrproject/zephyr/arch/arm/core/cortex_m/cpu_idle.c:97
  #2  0x000510b0 in k_cpu_idle ()
      at /data/labor/lab/zephyrproject/zephyr/include/zephyr/kernel.h:5998
  #3  idle (unused1=<optimized out>, unused2=<optimized out>, unused3=<optimized out>)
      at /data/labor/lab/zephyrproject/zephyr/kernel/idle.c:74
  #4  0x000239e6 in z_thread_entry (entry=0x5109d <idle>, p1=0x20006374 <_kernel>, p2=0x0, p3=0x0)
      at /data/labor/lab/zephyrproject/zephyr/lib/os/thread_entry.c:48
  #5  0x0103e970 in ?? ()
  Backtrace stopped: previous frame identical to this frame (corrupt stack?)

Coredump Collection/Analysis
============================

The Zephyr Coredump module
--------------------------

Zephyr Coredump modules allows a running program to capture coredump and log it via various backends such as serial port or a flash partition.
Refer to `Zephyr documentation <https://docs.zephyrproject.org/latest/services/debugging/coredump.html>`_ for further information.


Collecting a live coredump with GDB
-----------------------------------

A coredump can be collected from a running system using the *gcore* command in gdb ::

    $ west attach -d build/ATMEVK-3430e-YQN-5_ns/zephyr/samples/bluetooth/peripheral --jlink --device 000900039134
    -- west attach: rebuilding
    (gdb) gcore dump_file
    Saved corefile dump_file
    (gdb) quit
    A debugging session is active.

Offline analysis of a coredump file
-----------------------------------

The coredump file collected from the step above can be analyzed offline with the corresponding program elf file. This is demonstrated below. ::

  $ /tools/zephyr/0.16.4/arm-zephyr-eabi/bin/arm-zephyr-eabi-gdb build/ATMEVK-3430e-YQN-5_ns/zephyr/samples/bluetooth/peripheral/zephyr/zephyr.elf
  GNU gdb (Zephyr SDK 0.16.4) 12.1
  Copyright (C) 2022 Free Software Foundation, Inc.
  ...

  For help, type "help".
  Type "apropos word" to search for commands related to "word"...
  Reading symbols from build/ATMEVK-3430e-YQN-5_ns/zephyr/samples/bluetooth/peripheral/zephyr/zephyr.elf...
  (gdb) core ./dump_file
  [New <main task>]
  Core was generated by `build/ATMEVK-3430e-YQN-5_ns/zephyr/samples/bluet'.
  Program terminated with signal SIGINT, Interrupt.
  #0  __enable_irq ()
      at /data/labor/lab/zephyrproject/modules/hal/cmsis/CMSIS/Core/Include/cmsis_gcc.h:951
  951	  __ASM volatile ("cpsie i" : : : "memory");
  (gdb) bt
  #0  __enable_irq ()
      at /data/labor/lab/zephyrproject/modules/hal/cmsis/CMSIS/Core/Include/cmsis_gcc.h:951
  #1  arch_cpu_idle () at /data/labor/lab/zephyrproject/zephyr/arch/arm/core/cortex_m/cpu_idle.c:97
  #2  0x000510b0 in k_cpu_idle ()
      at /data/labor/lab/zephyrproject/zephyr/include/zephyr/kernel.h:5998
  #3  idle (unused1=<optimized out>, unused2=<optimized out>, unused3=<optimized out>)
      at /data/labor/lab/zephyrproject/zephyr/kernel/idle.c:74
  #4  0x000239e6 in z_thread_entry (entry=0x5109d <idle>, p1=0x20006374 <_kernel>, p2=0x0, p3=0x0)
      at /data/labor/lab/zephyrproject/zephyr/lib/os/thread_entry.c:48
  #5  0x0103e970 in ?? ()
  Backtrace stopped: previous frame identical to this frame (corrupt stack?)
  (gdb)