source: rtems-docs/user/exe/debugging.rst @ e52906b

5
Last change on this file since e52906b was e52906b, checked in by Sebastian Huber <sebastian.huber@…>, on 01/09/19 at 15:14:06

Simplify SPDX-License-Identifier comment

  • Property mode set to 100644
File size: 4.5 KB
Line 
1.. SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. Copyright (C) 2018 Chris Johns <chrisj@rtems.org>
4
5Debugging
6=========
7.. index:: Debugging
8
9An RTEMS executable is debugged by loading the code, data and read-only data
10into a target with a debugger connected. The debugger running on a host
11computer accesses the ELF file reading the debug information it contains.
12
13The executable being debugged needs to be built with the compiler and linker
14debug options enabled. Debug information makes the ELF executable file large
15but it does not change the binary footprint of the executable when resident in
16the target. Target boot loaders and file conversion tools extract the binary
17code, data and read-only data to create the file embedded on the target.
18
19An ELF executable built with debug information contains DWARF debug
20information. DWARF is a detailed description of the executable a debugger uses
21to locate functions, find data, understand the type and structure of a
22variable, and know how much entry code every call has. The debugger uses this
23information to set breaks points, step functions, step instructions, view the
24data and much more.
25
26We recommend the compiler and linker debug options are always enabled. An ELF
27file with debug information can be used to investigate a crash report from a
28production system if the production ELF image is archived. The RTEMS tools
29chain provides tools that can take an address from a crash dump and find the
30corresponding instruction and source line. The extra size the debug information
31adds does not effect the target footprint and the extra size on a host is small
32compared to the benefits it brings.
33
34A desktop or server operating system's kernel hosts the executable being
35debugged handling the interaction with the executable and the debugger. The
36debugger knows how to communicate to the kernel to get the information it
37needs. Debugging an embedded executable needs an extra piece called an agent to
38connect the target to the debugger. The agent provides a standard remote interface to
39the debugger and an agent specific connection to the target.
40
41.. _fig-exe-debug:
42
43.. figure:: ../../images/user/exe-debug.png
44   :width: 80%
45   :alt: Embedded Executable Debugging
46   :figclass: align-center
47
48   Embedded Executable Debugging
49
50The RTEMS tool chain provides the GNU debugger GDB. GDB has a remote protocol
51that can run over networks using TCP and UDP protocols. The GDB remote protocol
52is available in a number of open source and commercial debugging
53solutions. Network debugging using the remote protocol helps setting up a
54laboratory, the targets can be remote from the developers desktop allowing for
55better control of the target hardware while avoiding the need to plug devices
56in to an expensive desktop or server machine.
57
58The following are some examples of GDB and GDB server environments RTEMS
59supports.
60
61.. index:: QEMU
62
63QEMU contains a debugging agent for the target being simulated. A QEMU command
64line option enables a GDB server and the simulator manages the interaction with
65the target processor and it's memory and caches.
66
67.. _fig-exe-debug-qemu:
68
69.. figure:: ../../images/user/exe-debug-qemu.png
70   :width: 70%
71   :alt: QEMU Executable Debugging
72   :figclass: align-center
73
74   QEMU Executable Debugging
75
76.. index:: OpenOCD
77.. index:: JTAG
78
79OpenOCD is a JTAG debugging package that interfaces to a wide of JTAG
80pods. JTAG is a low level high speed serial interface modern processors provide
81as a means of controlling the core processing logic. The features available depend on
82the architecture and processor. Typical functions include:
83
84#. Processor control and register access
85
86#. System level register access to allow SOC initialization
87
88#. General address space access
89
90#. Cache and MMU control
91
92#. Break and watch points
93
94.. _fig-exe-debug-qemu:
95
96.. figure:: ../../images/user/exe-debug-jtag.png
97   :width: 70%
98   :alt: OpenOCD JTAG Executable Debugging
99   :figclass: align-center
100
101   OpenOCD JTAG Executable Debugging
102
103.. index:: libdebugger
104
105The RTEMS kernel has a debugging agent called ``libdebugger``. This is a
106software based agent that runs within RTEMS using network services to provide a
107remote GDB protocol interface. A growing number of architectures are
108supported. The RTEMS debugging agent is for application development providing
109thread aware stop model debug experience.
110
111.. _fig-exe-debug-libdebugger:
112
113.. figure:: ../../images/user/exe-debug-libdebugger.png
114   :width: 70%
115   :alt: Libdebugger Executable Debugging
116   :figclass: align-center
117
118   Libdebugger Executable Debugging
Note: See TracBrowser for help on using the repository browser.