1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. Copyright (C) 2018 Chris Johns <chrisj@rtems.org> |
---|
4 | |
---|
5 | Debugging |
---|
6 | ========= |
---|
7 | .. index:: Debugging |
---|
8 | |
---|
9 | An RTEMS executable is debugged by loading the code, data and read-only data |
---|
10 | into a target with a debugger connected. The debugger running on a host |
---|
11 | computer accesses the ELF file reading the debug information it contains. |
---|
12 | |
---|
13 | The executable being debugged needs to be built with the compiler and linker |
---|
14 | debug options enabled. Debug information makes the ELF executable file large |
---|
15 | but it does not change the binary footprint of the executable when resident in |
---|
16 | the target. Target boot loaders and file conversion tools extract the binary |
---|
17 | code, data and read-only data to create the file embedded on the target. |
---|
18 | |
---|
19 | An ELF executable built with debug information contains DWARF debug |
---|
20 | information. DWARF is a detailed description of the executable a debugger uses |
---|
21 | to locate functions, find data, understand the type and structure of a |
---|
22 | variable, and know how much entry code every call has. The debugger uses this |
---|
23 | information to set breaks points, step functions, step instructions, view the |
---|
24 | data and much more. |
---|
25 | |
---|
26 | We recommend the compiler and linker debug options are always enabled. An ELF |
---|
27 | file with debug information can be used to investigate a crash report from a |
---|
28 | production system if the production ELF image is archived. The RTEMS tools |
---|
29 | chain provides tools that can take an address from a crash dump and find the |
---|
30 | corresponding instruction and source line. The extra size the debug information |
---|
31 | adds does not effect the target footprint and the extra size on a host is small |
---|
32 | compared to the benefits it brings. |
---|
33 | |
---|
34 | A desktop or server operating system's kernel hosts the executable being |
---|
35 | debugged handling the interaction with the executable and the debugger. The |
---|
36 | debugger knows how to communicate to the kernel to get the information it |
---|
37 | needs. Debugging an embedded executable needs an extra piece called an agent to |
---|
38 | connect the target to the debugger. The agent provides a standard remote interface to |
---|
39 | the 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 | |
---|
50 | The RTEMS tool chain provides the GNU debugger GDB. GDB has a remote protocol |
---|
51 | that can run over networks using TCP and UDP protocols. The GDB remote protocol |
---|
52 | is available in a number of open source and commercial debugging |
---|
53 | solutions. Network debugging using the remote protocol helps setting up a |
---|
54 | laboratory, the targets can be remote from the developers desktop allowing for |
---|
55 | better control of the target hardware while avoiding the need to plug devices |
---|
56 | in to an expensive desktop or server machine. |
---|
57 | |
---|
58 | The following are some examples of GDB and GDB server environments RTEMS |
---|
59 | supports. |
---|
60 | |
---|
61 | .. index:: QEMU |
---|
62 | |
---|
63 | QEMU contains a debugging agent for the target being simulated. A QEMU command |
---|
64 | line option enables a GDB server and the simulator manages the interaction with |
---|
65 | the 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 | |
---|
79 | OpenOCD is a JTAG debugging package that interfaces to a wide of JTAG |
---|
80 | pods. JTAG is a low level high speed serial interface modern processors provide |
---|
81 | as a means of controlling the core processing logic. The features available depend on |
---|
82 | the 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 | |
---|
105 | The RTEMS kernel has a debugging agent called ``libdebugger``. This is a |
---|
106 | software based agent that runs within RTEMS using network services to provide a |
---|
107 | remote GDB protocol interface. A growing number of architectures are |
---|
108 | supported. The RTEMS debugging agent is for application development providing |
---|
109 | thread 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 |
---|