gcc/doc/gccint/target-macros/controlling-debugging-information-format.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. _debugging-info:
   7
   8 Controlling Debugging Information Format
   9 ****************************************
  10
  11 .. prevent bad page break with this line
  12
  13 This describes how to specify debugging information.
  14
  15 .. toctree::
  16   :maxdepth: 2
  17
  18 .. _all-debuggers:
  19
  20 Macros Affecting All Debugging Formats
  21 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  22
  23 .. prevent bad page break with this line
  24
  25 These macros affect all debugging formats.
  26
  27 .. c:macro:: DEBUGGER_REGNO (regno)
  28
  29   A C expression that returns the debugger register number for the compiler
  30   register number :samp:`{regno}`.  In the default macro provided, the value
  31   of this expression will be :samp:`{regno}` itself.  But sometimes there are
  32   some registers that the compiler knows about and debugger does not, or vice
  33   versa.  In such cases, some register may need to have one number in the
  34   compiler and another for debugger.
  35
  36   If two registers have consecutive numbers inside GCC, and they can be
  37   used as a pair to hold a multiword value, then they *must* have
  38   consecutive numbers after renumbering with ``DEBUGGER_REGNO``.
  39   Otherwise, debuggers will be unable to access such a pair, because they
  40   expect register pairs to be consecutive in their own numbering scheme.
  41
  42   If you find yourself defining ``DEBUGGER_REGNO`` in way that
  43   does not preserve register pairs, then what you must do instead is
  44   redefine the actual register numbering scheme.
  45
  46 .. c:macro:: DEBUGGER_AUTO_OFFSET (x)
  47
  48   A C expression that returns the integer offset value for an automatic
  49   variable having address :samp:`{x}` (an RTL expression).  The default
  50   computation assumes that :samp:`{x}` is based on the frame-pointer and
  51   gives the offset from the frame-pointer.  This is required for targets
  52   that produce debugging output for debugger and allow the frame-pointer to be
  53   eliminated when the :option:`-g` option is used.
  54
  55 .. c:macro:: DEBUGGER_ARG_OFFSET (offset, x)
  56
  57   A C expression that returns the integer offset value for an argument
  58   having address :samp:`{x}` (an RTL expression).  The nominal offset is
  59   :samp:`{offset}`.
  60
  61 .. c:macro:: PREFERRED_DEBUGGING_TYPE
  62
  63   A C expression that returns the type of debugging output GCC should
  64   produce when the user specifies just :option:`-g`.  Define
  65   this if you have arranged for GCC to support more than one format of
  66   debugging output.  Currently, the allowable values are
  67   ``DWARF2_DEBUG``, ``VMS_DEBUG``,
  68   and ``VMS_AND_DWARF2_DEBUG``.
  69
  70   When the user specifies :option:`-ggdb`, GCC normally also uses the
  71   value of this macro to select the debugging output format, but with two
  72   exceptions.  If ``DWARF2_DEBUGGING_INFO`` is defined, GCC uses the
  73   value ``DWARF2_DEBUG``.
  74
  75   The value of this macro only affects the default debugging output; the
  76   user can always get a specific type of output by using  :option:`-gdwarf-2`,
  77   or :option:`-gvms`.
  78
  79 .. c:macro:: DEFAULT_GDB_EXTENSIONS
  80
  81   Define this macro to control whether GCC should by default generate
  82   GDB's extended version of debugging information.  If you don't define the
  83   macro, the default is 1: always generate the extended information
  84   if there is any occasion to.
  85
  86 .. _dwarf:
  87
  88 Macros for DWARF Output
  89 ^^^^^^^^^^^^^^^^^^^^^^^
  90
  91 .. prevent bad page break with this line
  92
  93 Here are macros for DWARF output.
  94
  95 .. c:macro:: DWARF2_DEBUGGING_INFO
  96
  97   Define this macro if GCC should produce dwarf version 2 format
  98   debugging output in response to the :option:`-g` option.
  99
 100   To support optional call frame debugging information, you must also
 101   define ``INCOMING_RETURN_ADDR_RTX`` and either set
 102   ``RTX_FRAME_RELATED_P`` on the prologue insns if you use RTL for the
 103   prologue, or call ``dwarf2out_def_cfa`` and ``dwarf2out_reg_save``
 104   as appropriate from ``TARGET_ASM_FUNCTION_PROLOGUE`` if you don't.
 105
 106 .. include:: tm.rst.in
 107   :start-after: [TARGET_DWARF_CALLING_CONVENTION]
 108   :end-before: [TARGET_DWARF_CALLING_CONVENTION]
 109
 110
 111 .. function:: int TARGET_DWARF_CALLING_CONVENTION (const_tree function)
 112
 113   Define this to enable the dwarf attribute ``DW_AT_calling_convention`` to
 114   be emitted for each function.  Instead of an integer return the enum
 115   value for the ``DW_CC_`` tag.
 116
 117 .. c:macro:: DWARF2_FRAME_INFO
 118
 119   Define this macro to a nonzero value if GCC should always output
 120   Dwarf 2 frame information.  If ``TARGET_EXCEPT_UNWIND_INFO``
 121   (see :ref:`exception-region-output`) returns ``UI_DWARF2``, and
 122   exceptions are enabled, GCC will output this information not matter
 123   how you define ``DWARF2_FRAME_INFO``.
 124
 125 .. include:: tm.rst.in
 126   :start-after: [TARGET_DEBUG_UNWIND_INFO]
 127   :end-before: [TARGET_DEBUG_UNWIND_INFO]
 128
 129
 130 .. c:macro:: DWARF2_ASM_LINE_DEBUG_INFO
 131
 132   Define this macro to be a nonzero value if the assembler can generate Dwarf 2
 133   line debug info sections.  This will result in much more compact line number
 134   tables, and hence is desirable if it works.
 135
 136 .. c:macro:: DWARF2_ASM_VIEW_DEBUG_INFO
 137
 138   Define this macro to be a nonzero value if the assembler supports view
 139   assignment and verification in ``.loc``.  If it does not, but the
 140   user enables location views, the compiler may have to fallback to
 141   internal line number tables.
 142
 143 .. include:: tm.rst.in
 144   :start-after: [TARGET_RESET_LOCATION_VIEW]
 145   :end-before: [TARGET_RESET_LOCATION_VIEW]
 146
 147
 148 .. include:: tm.rst.in
 149   :start-after: [TARGET_WANT_DEBUG_PUB_SECTIONS]
 150   :end-before: [TARGET_WANT_DEBUG_PUB_SECTIONS]
 151
 152
 153 .. include:: tm.rst.in
 154   :start-after: [TARGET_DELAY_SCHED2]
 155   :end-before: [TARGET_DELAY_SCHED2]
 156
 157
 158 .. include:: tm.rst.in
 159   :start-after: [TARGET_DELAY_VARTRACK]
 160   :end-before: [TARGET_DELAY_VARTRACK]
 161
 162
 163 .. include:: tm.rst.in
 164   :start-after: [TARGET_NO_REGISTER_ALLOCATION]
 165   :end-before: [TARGET_NO_REGISTER_ALLOCATION]
 166
 167
 168 .. c:macro:: ASM_OUTPUT_DWARF_DELTA (stream, size, label1, label2)
 169
 170   A C statement to issue assembly directives that create a difference
 171   :samp:`{lab1}` minus :samp:`{lab2}`, using an integer of the given :samp:`{size}`.
 172
 173 .. c:macro:: ASM_OUTPUT_DWARF_VMS_DELTA (stream, size, label1, label2)
 174
 175   A C statement to issue assembly directives that create a difference
 176   between the two given labels in system defined units, e.g. instruction
 177   slots on IA64 VMS, using an integer of the given size.
 178
 179 .. c:macro:: ASM_OUTPUT_DWARF_OFFSET (stream, size, label, offset, section)
 180
 181   A C statement to issue assembly directives that create a
 182   section-relative reference to the given :samp:`{label}` plus :samp:`{offset}`, using
 183   an integer of the given :samp:`{size}`.  The label is known to be defined in the
 184   given :samp:`{section}`.
 185
 186 .. c:macro:: ASM_OUTPUT_DWARF_PCREL (stream, size, label)
 187
 188   A C statement to issue assembly directives that create a self-relative
 189   reference to the given :samp:`{label}`, using an integer of the given :samp:`{size}`.
 190
 191 .. c:macro:: ASM_OUTPUT_DWARF_DATAREL (stream, size, label)
 192
 193   A C statement to issue assembly directives that create a reference to the
 194   given :samp:`{label}` relative to the dbase, using an integer of the given :samp:`{size}`.
 195
 196 .. c:macro:: ASM_OUTPUT_DWARF_TABLE_REF (label)
 197
 198   A C statement to issue assembly directives that create a reference to
 199   the DWARF table identifier :samp:`{label}` from the current section.  This
 200   is used on some systems to avoid garbage collecting a DWARF table which
 201   is referenced by a function.
 202
 203 .. include:: tm.rst.in
 204   :start-after: [TARGET_ASM_OUTPUT_DWARF_DTPREL]
 205   :end-before: [TARGET_ASM_OUTPUT_DWARF_DTPREL]
 206
 207
 208 .. _vms-debug:
 209
 210 Macros for VMS Debug Format
 211 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 212
 213 .. prevent bad page break with this line
 214
 215 Here are macros for VMS debug format.
 216
 217 .. c:macro:: VMS_DEBUGGING_INFO
 218
 219   Define this macro if GCC should produce debugging output for VMS
 220   in response to the :option:`-g` option.  The default behavior for VMS
 221   is to generate minimal debug info for a traceback in the absence of
 222   :option:`-g` unless explicitly overridden with :option:`-g0`.  This
 223   behavior is controlled by ``TARGET_OPTION_OPTIMIZATION`` and
 224   ``TARGET_OPTION_OVERRIDE``.
 225
 226 .. _ctf-debug:
 227
 228 Macros for CTF Debug Format
 229 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 230
 231 .. prevent bad page break with this line
 232
 233 Here are macros for CTF debug format.
 234
 235 .. c:macro:: CTF_DEBUGGING_INFO
 236
 237   Define this macro if GCC should produce debugging output in CTF debug
 238   format in response to the :option:`-gctf` option.
 239
 240 .. _btf-debug:
 241
 242 Macros for BTF Debug Format
 243 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 244
 245 .. prevent bad page break with this line
 246
 247 Here are macros for BTF debug format.
 248
 249 .. c:macro:: BTF_DEBUGGING_INFO
 250
 251   Define this macro if GCC should produce debugging output in BTF debug
 252   format in response to the :option:`-gbtf` option.