diff options
Diffstat (limited to 'user/exe/debugging.rst')
-rw-r--r-- | user/exe/debugging.rst | 119 |
1 files changed, 119 insertions, 0 deletions
diff --git a/user/exe/debugging.rst b/user/exe/debugging.rst new file mode 100644 index 0000000..3d1aa38 --- /dev/null +++ b/user/exe/debugging.rst @@ -0,0 +1,119 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment: Copyright (c) 2018 Chris Johns <chrisj@rtems.org> +.. comment: All rights reserved. + +Debugging +========= +.. index:: Debugging + +An RTEMS executable is debugged by loading the code, data and read-only data +into a target with a debugger connected. The debugger running on a host +computer accesses the ELF file reading the debug information it contains. + +The executable being debugged needs to be built with the compiler and linker +debug options enabled. Debug information makes the ELF executable file large +but it does not change the binary footprint of the executable when resident in +the target. Target boot loaders and file conversion tools extract the binary +code, data and read-only data to create the file embedded on the target. + +An ELF executable built with debug information contains DWARF debug +information. DWARF is a detailed description of the executable a debugger uses +to locate functions, find data, understand the type and structure of a +variable, and know how much entry code every call has. The debugger uses this +information to set breaks points, step functions, step instructions, view the +data and much more. + +We recommend the compiler and linker debug options are always enabled. An ELF +file with debug information can be used to investigate a crash report from a +production system if the production ELF image is archived. The RTEMS tools +chain provides tools that can take an address from a crash dump and find the +corresponding instruction and source line. The extra size the debug information +adds does not effect the target footprint and the extra size on a host is small +compared to the benefits it brings. + +A desktop or server operating system's kernel hosts the executable being +debugged handling the interaction with the executable and the debugger. The +debugger knows how to communicate to the kernel to get the information it +needs. Debugging an embedded executable needs an extra piece called an agent to +connect the target to the debugger. The agent provides a standard remote interface to +the debugger and an agent specific connection to the target. + +.. _fig-exe-debug: + +.. figure:: ../../images/user/exe-debug.png + :width: 80% + :alt: Embedded Executable Debugging + :figclass: align-center + + Embedded Executable Debugging + +The RTEMS tool chain provides the GNU debugger GDB. GDB has a remote protocol +that can run over networks using TCP and UDP protocols. The GDB remote protocol +is available in a number of open source and commercial debugging +solutions. Network debugging using the remote protocol helps setting up a +laboratory, the targets can be remote from the developers desktop allowing for +better control of the target hardware while avoiding the need to plug devices +in to an expensive desktop or server machine. + +The following are some examples of GDB and GDB server environments RTEMS +supports. + +.. index:: QEMU + +QEMU contains a debugging agent for the target being simulated. A QEMU command +line option enables a GDB server and the simulator manages the interaction with +the target processor and it's memory and caches. + +.. _fig-exe-debug-qemu: + +.. figure:: ../../images/user/exe-debug-qemu.png + :width: 70% + :alt: QEMU Executable Debugging + :figclass: align-center + + QEMU Executable Debugging + +.. index:: OpenOCD +.. index:: JTAG + +OpenOCD is a JTAG debugging package that interfaces to a wide of JTAG +pods. JTAG is a low level high speed serial interface modern processors provide +as a means of controlling the core processing logic. The features available depend on +the architecture and processor. Typical functions include: + +#. Processor control and register access + +#. System level register access to allow SOC initialization + +#. General address space access + +#. Cache and MMU control + +#. Break and watch points + +.. _fig-exe-debug-qemu: + +.. figure:: ../../images/user/exe-debug-jtag.png + :width: 70% + :alt: OpenOCD JTAG Executable Debugging + :figclass: align-center + + OpenOCD JTAG Executable Debugging + +.. index:: libdebugger + +The RTEMS kernel has a debugging agent called ``libdebugger``. This is a +software based agent that runs within RTEMS using network services to provide a +remote GDB protocol interface. A growing number of architectures are +supported. The RTEMS debugging agent is for application development providing +thread aware stop model debug experience. + +.. _fig-exe-debug-libdebugger: + +.. figure:: ../../images/user/exe-debug-libdebugger.png + :width: 70% + :alt: Libdebugger Executable Debugging + :figclass: align-center + + Libdebugger Executable Debugging |