gcc/doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/epiphany-function-attributes.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 .. _epiphany-function-attributes:
   7
   8 Epiphany Function Attributes
   9 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  10
  11 These function attributes are supported by the Epiphany back end:
  12
  13 .. index:: disinterrupt function attribute, Epiphany
  14
  15 .. epiphany-fn-attr:: disinterrupt
  16
  17   This attribute causes the compiler to emit
  18   instructions to disable interrupts for the duration of the given
  19   function.
  20
  21 .. index:: forwarder_section function attribute, Epiphany
  22
  23 .. epiphany-fn-attr:: forwarder_section
  24
  25   This attribute modifies the behavior of an interrupt handler.
  26   The interrupt handler may be in external memory which cannot be
  27   reached by a branch instruction, so generate a local memory trampoline
  28   to transfer control.  The single parameter identifies the section where
  29   the trampoline is placed.
  30
  31 .. index:: interrupt function attribute, Epiphany
  32
  33 .. epiphany-fn-attr:: interrupt
  34
  35   Use this attribute to indicate
  36   that the specified function is an interrupt handler.  The compiler generates
  37   function entry and exit sequences suitable for use in an interrupt handler
  38   when this attribute is present.  It may also generate
  39   a special section with code to initialize the interrupt vector table.
  40
  41   On Epiphany targets one or more optional parameters can be added like this:
  42
  43   .. code-block:: c++
  44
  45     void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
  46
  47   Permissible values for these parameters are: :epiphany-fn-attr:`reset`,
  48   ``software_exception``, ``page_miss``,
  49   ``timer0``, ``timer1``, ``message``,
  50   ``dma0``, ``dma1``, ``wand`` and ``swi``.
  51   Multiple parameters indicate that multiple entries in the interrupt
  52   vector table should be initialized for this function, i.e. for each
  53   parameter :samp:`{name}`, a jump to the function is emitted in
  54   the section ivt_entry\_ :samp:`{name}`.  The parameter(s) may be omitted
  55   entirely, in which case no interrupt vector table entry is provided.
  56
  57   Note that interrupts are enabled inside the function
  58   unless the :epiphany-fn-attr:`disinterrupt` attribute is also specified.
  59
  60   The following examples are all valid uses of these attributes on
  61   Epiphany targets:
  62
  63   .. code-block:: c++
  64
  65     void __attribute__ ((interrupt)) universal_handler ();
  66     void __attribute__ ((interrupt ("dma1"))) dma1_handler ();
  67     void __attribute__ ((interrupt ("dma0, dma1")))
  68       universal_dma_handler ();
  69     void __attribute__ ((interrupt ("timer0"), disinterrupt))
  70       fast_timer_handler ();
  71     void __attribute__ ((interrupt ("dma0, dma1"),
  72                          forwarder_section ("tramp")))
  73       external_dma_handler ();
  74
  75 .. index:: long_call function attribute, Epiphany, short_call function attribute, Epiphany, indirect calls, Epiphany
  76
  77 .. epiphany-fn-attr:: long_call, short_call
  78
  79   These attributes specify how a particular function is called.
  80   These attributes override the
  81   :option:`-mlong-calls` (see :ref:`adapteva-epiphany-options`)
  82   command-line switch and ``#pragma long_calls`` settings.