git.ipfire.org Git - thirdparty/gcc.git/blob

   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 .. _exception-region-output:
   7
   8 Assembler Commands for Exception Regions
   9 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  10
  11 .. prevent bad page break with this line
  12
  13 This describes commands marking the start and the end of an exception
  14 region.
  15
  16 .. c:macro:: EH_FRAME_SECTION_NAME
  17
  18   If defined, a C string constant for the name of the section containing
  19   exception handling frame unwind information.  If not defined, GCC will
  20   provide a default definition if the target supports named sections.
  21   :samp:`crtstuff.c` uses this macro to switch to the appropriate section.
  22
  23   You should define this symbol if your target supports DWARF 2 frame
  24   unwind information and the default definition does not work.
  25
  26 .. c:macro:: EH_FRAME_THROUGH_COLLECT2
  27
  28   If defined, DWARF 2 frame unwind information will identified by
  29   specially named labels.  The collect2 process will locate these
  30   labels and generate code to register the frames.
  31
  32   This might be necessary, for instance, if the system linker will not
  33   place the eh_frames in-between the sentinals from :samp:`crtstuff.c`,
  34   or if the system linker does garbage collection and sections cannot
  35   be marked as not to be collected.
  36
  37 .. c:macro:: EH_TABLES_CAN_BE_READ_ONLY
  38
  39   Define this macro to 1 if your target is such that no frame unwind
  40   information encoding used with non-PIC code will ever require a
  41   runtime relocation, but the linker may not support merging read-only
  42   and read-write sections into a single read-write section.
  43
  44 .. c:macro:: MASK_RETURN_ADDR
  45
  46   An rtx used to mask the return address found via ``RETURN_ADDR_RTX``, so
  47   that it does not contain any extraneous set bits in it.
  48
  49 .. c:macro:: DWARF2_UNWIND_INFO
  50
  51   Define this macro to 0 if your target supports DWARF 2 frame unwind
  52   information, but it does not yet work with exception handling.
  53   Otherwise, if your target supports this information (if it defines
  54   ``INCOMING_RETURN_ADDR_RTX`` and ``OBJECT_FORMAT_ELF``),
  55   GCC will provide a default definition of 1.
  56
  57 .. include:: ../tm.rst.in
  58   :start-after: [TARGET_EXCEPT_UNWIND_INFO]
  59   :end-before: [TARGET_EXCEPT_UNWIND_INFO]
  60
  61
  62   This hook defines the mechanism that will be used for exception handling
  63   by the target.  If the target has ABI specified unwind tables, the hook
  64   should return ``UI_TARGET``.  If the target is to use the
  65   ``setjmp`` / ``longjmp`` -based exception handling scheme, the hook
  66   should return ``UI_SJLJ``.  If the target supports DWARF 2 frame unwind
  67   information, the hook should return ``UI_DWARF2``.
  68
  69   A target may, if exceptions are disabled, choose to return ``UI_NONE``.
  70   This may end up simplifying other parts of target-specific code.  The
  71   default implementation of this hook never returns ``UI_NONE``.
  72
  73   Note that the value returned by this hook should be constant.  It should
  74   not depend on anything except the command-line switches described by
  75   :samp:`{opts}`.  In particular, the
  76   setting ``UI_SJLJ`` must be fixed at compiler start-up as C pre-processor
  77   macros and builtin functions related to exception handling are set up
  78   depending on this setting.
  79
  80   The default implementation of the hook first honors the
  81   :option:`--enable-sjlj-exceptions` configure option, then
  82   ``DWARF2_UNWIND_INFO``, and finally defaults to ``UI_SJLJ``.  If
  83   ``DWARF2_UNWIND_INFO`` depends on command-line options, the target
  84   must define this hook so that :samp:`{opts}` is used correctly.
  85
  86 .. include:: ../tm.rst.in
  87   :start-after: [TARGET_UNWIND_TABLES_DEFAULT]
  88   :end-before: [TARGET_UNWIND_TABLES_DEFAULT]
  89
  90
  91   This variable should be set to ``true`` if the target ABI requires unwinding
  92   tables even when exceptions are not used.  It must not be modified by
  93   command-line option processing.
  94
  95 .. c:macro:: DONT_USE_BUILTIN_SETJMP
  96
  97   Define this macro to 1 if the ``setjmp`` / ``longjmp`` -based scheme
  98   should use the ``setjmp`` / ``longjmp`` functions from the C library
  99   instead of the ``__builtin_setjmp`` / ``__builtin_longjmp`` machinery.
 100
 101 .. c:macro:: JMP_BUF_SIZE
 102
 103   This macro has no effect unless ``DONT_USE_BUILTIN_SETJMP`` is also
 104   defined.  Define this macro if the default size of ``jmp_buf`` buffer
 105   for the ``setjmp`` / ``longjmp`` -based exception handling mechanism
 106   is not large enough, or if it is much too large.
 107   The default size is ``FIRST_PSEUDO_REGISTER * sizeof(void *)``.
 108
 109 .. c:macro:: DWARF_CIE_DATA_ALIGNMENT
 110
 111   This macro need only be defined if the target might save registers in the
 112   function prologue at an offset to the stack pointer that is not aligned to
 113   ``UNITS_PER_WORD``.  The definition should be the negative minimum
 114   alignment if ``STACK_GROWS_DOWNWARD`` is true, and the positive
 115   minimum alignment otherwise.  See :ref:`dwarf`.  Only applicable if
 116   the target supports DWARF 2 frame unwind information.
 117
 118 .. include:: ../tm.rst.in
 119   :start-after: [TARGET_TERMINATE_DW2_EH_FRAME_INFO]
 120   :end-before: [TARGET_TERMINATE_DW2_EH_FRAME_INFO]
 121
 122
 123 .. include:: ../tm.rst.in
 124   :start-after: [TARGET_DWARF_REGISTER_SPAN]
 125   :end-before: [TARGET_DWARF_REGISTER_SPAN]
 126
 127
 128 .. include:: ../tm.rst.in
 129   :start-after: [TARGET_DWARF_FRAME_REG_MODE]
 130   :end-before: [TARGET_DWARF_FRAME_REG_MODE]
 131
 132
 133 .. include:: ../tm.rst.in
 134   :start-after: [TARGET_INIT_DWARF_REG_SIZES_EXTRA]
 135   :end-before: [TARGET_INIT_DWARF_REG_SIZES_EXTRA]
 136
 137
 138 .. include:: ../tm.rst.in
 139   :start-after: [TARGET_ASM_TTYPE]
 140   :end-before: [TARGET_ASM_TTYPE]
 141
 142
 143 .. include:: ../tm.rst.in
 144   :start-after: [TARGET_ARM_EABI_UNWINDER]
 145   :end-before: [TARGET_ARM_EABI_UNWINDER]