[thirdparty/gcc.git] /

..
  Copyright 1988-2022 Free Software Foundation, Inc.
  This is part of the GCC manual.
  For copying conditions, see the copyright.rst file.

.. _exception-region-output:

Assembler Commands for Exception Regions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. prevent bad page break with this line

This describes commands marking the start and the end of an exception
region.

.. c:macro:: EH_FRAME_SECTION_NAME

  If defined, a C string constant for the name of the section containing
  exception handling frame unwind information.  If not defined, GCC will
  provide a default definition if the target supports named sections.
  :samp:`crtstuff.c` uses this macro to switch to the appropriate section.

  You should define this symbol if your target supports DWARF 2 frame
  unwind information and the default definition does not work.

.. c:macro:: EH_FRAME_THROUGH_COLLECT2

  If defined, DWARF 2 frame unwind information will identified by
  specially named labels.  The collect2 process will locate these
  labels and generate code to register the frames.

  This might be necessary, for instance, if the system linker will not
  place the eh_frames in-between the sentinals from :samp:`crtstuff.c`,
  or if the system linker does garbage collection and sections cannot
  be marked as not to be collected.

.. c:macro:: EH_TABLES_CAN_BE_READ_ONLY

  Define this macro to 1 if your target is such that no frame unwind
  information encoding used with non-PIC code will ever require a
  runtime relocation, but the linker may not support merging read-only
  and read-write sections into a single read-write section.

.. c:macro:: MASK_RETURN_ADDR

  An rtx used to mask the return address found via ``RETURN_ADDR_RTX``, so
  that it does not contain any extraneous set bits in it.

.. c:macro:: DWARF2_UNWIND_INFO

  Define this macro to 0 if your target supports DWARF 2 frame unwind
  information, but it does not yet work with exception handling.
  Otherwise, if your target supports this information (if it defines
  ``INCOMING_RETURN_ADDR_RTX`` and ``OBJECT_FORMAT_ELF``),
  GCC will provide a default definition of 1.

.. function:: enum unwind_info_type TARGET_EXCEPT_UNWIND_INFO (struct gcc_options *opts)

  .. hook-start:TARGET_EXCEPT_UNWIND_INFO

  .. hook-end

  This hook defines the mechanism that will be used for exception handling
  by the target.  If the target has ABI specified unwind tables, the hook
  should return ``UI_TARGET``.  If the target is to use the
  ``setjmp`` / ``longjmp`` -based exception handling scheme, the hook
  should return ``UI_SJLJ``.  If the target supports DWARF 2 frame unwind
  information, the hook should return ``UI_DWARF2``.

  A target may, if exceptions are disabled, choose to return ``UI_NONE``.
  This may end up simplifying other parts of target-specific code.  The
  default implementation of this hook never returns ``UI_NONE``.

  Note that the value returned by this hook should be constant.  It should
  not depend on anything except the command-line switches described by
  :samp:`{opts}`.  In particular, the
  setting ``UI_SJLJ`` must be fixed at compiler start-up as C pre-processor
  macros and builtin functions related to exception handling are set up
  depending on this setting.

  The default implementation of the hook first honors the
  :option:`--enable-sjlj-exceptions` configure option, then
  ``DWARF2_UNWIND_INFO``, and finally defaults to ``UI_SJLJ``.  If
  ``DWARF2_UNWIND_INFO`` depends on command-line options, the target
  must define this hook so that :samp:`{opts}` is used correctly.

.. c:var:: bool TARGET_UNWIND_TABLES_DEFAULT

  .. hook-start:TARGET_UNWIND_TABLES_DEFAULT

  .. hook-end

  This variable should be set to ``true`` if the target ABI requires unwinding
  tables even when exceptions are not used.  It must not be modified by
  command-line option processing.

.. c:macro:: DONT_USE_BUILTIN_SETJMP

  Define this macro to 1 if the ``setjmp`` / ``longjmp`` -based scheme
  should use the ``setjmp`` / ``longjmp`` functions from the C library
  instead of the ``__builtin_setjmp`` / ``__builtin_longjmp`` machinery.

.. c:macro:: JMP_BUF_SIZE

  This macro has no effect unless ``DONT_USE_BUILTIN_SETJMP`` is also
  defined.  Define this macro if the default size of ``jmp_buf`` buffer
  for the ``setjmp`` / ``longjmp`` -based exception handling mechanism
  is not large enough, or if it is much too large.
  The default size is ``FIRST_PSEUDO_REGISTER * sizeof(void *)``.

.. c:macro:: DWARF_CIE_DATA_ALIGNMENT

  This macro need only be defined if the target might save registers in the
  function prologue at an offset to the stack pointer that is not aligned to
  ``UNITS_PER_WORD``.  The definition should be the negative minimum
  alignment if ``STACK_GROWS_DOWNWARD`` is true, and the positive
  minimum alignment otherwise.  See :ref:`dwarf`.  Only applicable if
  the target supports DWARF 2 frame unwind information.

.. c:var:: bool TARGET_TERMINATE_DW2_EH_FRAME_INFO

  .. hook-start:TARGET_TERMINATE_DW2_EH_FRAME_INFO

  Contains the value true if the target should add a zero word onto the
  end of a Dwarf-2 frame info section when used for exception handling.
  Default value is false if ``EH_FRAME_SECTION_NAME`` is defined, and
  true otherwise.

.. hook-end

.. function:: rtx TARGET_DWARF_REGISTER_SPAN (rtx reg)

  .. hook-start:TARGET_DWARF_REGISTER_SPAN

  Given a register, this hook should return a parallel of registers to
  represent where to find the register pieces.  Define this hook if the
  register and its mode are represented in Dwarf in non-contiguous
  locations, or if the register should be represented in more than one
  register in Dwarf.  Otherwise, this hook should return ``NULL_RTX``.
  If not defined, the default is to return ``NULL_RTX``.

.. hook-end

.. function:: machine_mode TARGET_DWARF_FRAME_REG_MODE (int regno)

  .. hook-start:TARGET_DWARF_FRAME_REG_MODE

  Given a register, this hook should return the mode which the
  corresponding Dwarf frame register should have.  This is normally
  used to return a smaller mode than the raw mode to prevent call
  clobbered parts of a register altering the frame register size

.. hook-end

.. function:: void TARGET_INIT_DWARF_REG_SIZES_EXTRA (tree address)

  .. hook-start:TARGET_INIT_DWARF_REG_SIZES_EXTRA

  If some registers are represented in Dwarf-2 unwind information in
  multiple pieces, define this hook to fill in information about the
  sizes of those pieces in the table used by the unwinder at runtime.
  It will be called by ``expand_builtin_init_dwarf_reg_sizes`` after
  filling in a single size corresponding to each hard register;
  :samp:`{address}` is the address of the table.

.. hook-end

.. function:: bool TARGET_ASM_TTYPE (rtx sym)

  .. hook-start:TARGET_ASM_TTYPE

  This hook is used to output a reference from a frame unwinding table to
  the type_info object identified by :samp:`{sym}`.  It should return ``true``
  if the reference was output.  Returning ``false`` will cause the
  reference to be output using the normal Dwarf2 routines.

.. hook-end

.. c:var:: bool TARGET_ARM_EABI_UNWINDER

  .. hook-start:TARGET_ARM_EABI_UNWINDER

  This flag should be set to ``true`` on targets that use an ARM EABI
  based unwinding library, and ``false`` on other targets.  This effects
  the format of unwinding tables, and how the unwinder in entered after
  running a cleanup.  The default is ``false``.

.. hook-end