1.. _DEV:Debugging:
2
3Debugging
4#########
5
6Simulation and runtime debugging options
7========================================
8
9Besides the options described in :ref:`GHDL:options`, `GHDL` passes any debugging options (those that begin with
10``-g``) and optimizations options (those that begin with ``-O`` or ``-f``) to `GCC`. Refer to the `GCC` manual for
11details. Moreover, some debugging options are also available, but not described here. The :option:`--help` option lists
12all options available, including the debugging ones.
13
14.. option:: --trace-signals
15
16  Display signals after each cycle.
17
18.. option:: --trace-processes
19
20  Display process name before each cycle.
21
22.. option:: --stats
23
24  Display run-time statistics.
25
26.. option:: --disp-order
27
28  Display signals order.
29
30.. option:: --disp-sources
31
32  Display sources while displaying signals.
33
34.. option:: --disp-sig-types
35
36  Display signal types.
37
38.. option:: --disp-signals-map
39
40  Display map bw declared signals and internal signals.
41
42.. option:: --disp-signals-table
43
44  Display internal signals.
45
46.. option:: --checks
47
48  Do internal checks after each process run.
49
50.. option:: --activity=<LEVEL>
51
52  Watch activity of LEVEL signals: LEVEL is ``all``, ``min`` (default) or ``none`` (unsafe).
53
54.. option:: --dump-rti
55
56  Dump Run Time Information (RTI).
57
58.. option:: --bootstrap
59
60  Allow ``--work=std``
61
62GNU Debugger (GDB)
63------------------
64
65.. index:: `__ghdl_fatal`
66
67.. WARNING:: Debugging VHDL programs using `GDB` is possible only with GCC/LLVM.
68
69GDB is a general purpose debugger for programs compiled by GCC. Currently, there is no VHDL support for GDB. It may be difficult to inspect variables or signals in GDB. However, it is still able to display the stack frame in case of error or to set a breakpoint at a specified line.
70
71GDB can be useful to catch a runtime error, such as indexing an array beyond its bounds. All error check subprograms call the ``__ghdl_fatal`` procedure. Therefore, to a catch runtime error, set a breakpoint like this::
72
73  (gdb) break __ghdl_fatal
74
75When the breakpoint is hit, use the ``where`` or ``bt`` command to display the stack frames.
76