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 .. _mips-function-attributes:
   7
   8 MIPS Function Attributes
   9 ^^^^^^^^^^^^^^^^^^^^^^^^
  10
  11 These function attributes are supported by the MIPS back end:
  12
  13 .. index:: interrupt function attribute, MIPS
  14
  15 .. mips-fn-attr:: interrupt
  16
  17   Use this attribute to indicate that the specified function is an interrupt
  18   handler.  The compiler generates function entry and exit sequences suitable
  19   for use in an interrupt handler when this attribute is present.
  20   An optional argument is supported for the interrupt attribute which allows
  21   the interrupt mode to be described.  By default GCC assumes the external
  22   interrupt controller (EIC) mode is in use, this can be explicitly set using
  23   ``eic``.  When interrupts are non-masked then the requested Interrupt
  24   Priority Level (IPL) is copied to the current IPL which has the effect of only
  25   enabling higher priority interrupts.  To use vectored interrupt mode use
  26   the argument ``vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]``, this will change
  27   the behavior of the non-masked interrupt support and GCC will arrange to mask
  28   all interrupts from sw0 up to and including the specified interrupt vector.
  29
  30   You can use the following attributes to modify the behavior
  31   of an interrupt handler:
  32
  33   ``use_shadow_register_set``
  34
  35     .. index:: use_shadow_register_set function attribute, MIPS
  36
  37     Assume that the handler uses a shadow register set, instead of
  38     the main general-purpose registers.  An optional argument ``intstack`` is
  39     supported to indicate that the shadow register set contains a valid stack
  40     pointer.
  41
  42   ``keep_interrupts_masked``
  43
  44     .. index:: keep_interrupts_masked function attribute, MIPS
  45
  46     Keep interrupts masked for the whole function.  Without this attribute,
  47     GCC tries to reenable interrupts for as much of the function as it can.
  48
  49   ``use_debug_exception_return``
  50
  51     .. index:: use_debug_exception_return function attribute, MIPS
  52
  53     Return using the ``deret`` instruction.  Interrupt handlers that don't
  54     have this attribute return using ``eret`` instead.
  55
  56     You can use any combination of these attributes, as shown below:
  57
  58   .. code-block:: c++
  59
  60     void __attribute__ ((interrupt)) v0 ();
  61     void __attribute__ ((interrupt, use_shadow_register_set)) v1 ();
  62     void __attribute__ ((interrupt, keep_interrupts_masked)) v2 ();
  63     void __attribute__ ((interrupt, use_debug_exception_return)) v3 ();
  64     void __attribute__ ((interrupt, use_shadow_register_set,
  65                          keep_interrupts_masked)) v4 ();
  66     void __attribute__ ((interrupt, use_shadow_register_set,
  67                          use_debug_exception_return)) v5 ();
  68     void __attribute__ ((interrupt, keep_interrupts_masked,
  69                          use_debug_exception_return)) v6 ();
  70     void __attribute__ ((interrupt, use_shadow_register_set,
  71                          keep_interrupts_masked,
  72                          use_debug_exception_return)) v7 ();
  73     void __attribute__ ((interrupt("eic"))) v8 ();
  74     void __attribute__ ((interrupt("vector=hw3"))) v9 ();
  75
  76 .. index:: indirect calls, MIPS, long_call function attribute, MIPS, short_call function attribute, MIPS, near function attribute, MIPS, far function attribute, MIPS
  77
  78 .. mips-fn-attr:: long_call, short_call, near, far
  79
  80   These attributes specify how a particular function is called on MIPS.
  81   The attributes override the :option:`-mlong-calls` (see :ref:`mips-options`)
  82   command-line switch.  The :mips-fn-attr:`long_call` and :mips-fn-attr:`far` attributes are
  83   synonyms, and cause the compiler to always call
  84   the function by first loading its address into a register, and then using
  85   the contents of that register.  The ``short_call`` and :mips-fn-attr:`near`
  86   attributes are synonyms, and have the opposite
  87   effect; they specify that non-PIC calls should be made using the more
  88   efficient ``jal`` instruction.
  89
  90 .. index:: mips16 function attribute, MIPS, nomips16 function attribute, MIPS
  91
  92 .. mips-fn-attr:: mips16, nomips16
  93
  94   On MIPS targets, you can use the :mips-fn-attr:`mips16` and ``nomips16``
  95   function attributes to locally select or turn off MIPS16 code generation.
  96   A function with the :mips-fn-attr:`mips16` attribute is emitted as MIPS16 code,
  97   while MIPS16 code generation is disabled for functions with the
  98   ``nomips16`` attribute.  These attributes override the
  99   :option:`-mips16` and :option:`-mno-mips16` options on the command line
 100   (see :ref:`mips-options`).
 101
 102   When compiling files containing mixed MIPS16 and non-MIPS16 code, the
 103   preprocessor symbol ``__mips16`` reflects the setting on the command line,
 104   not that within individual functions.  Mixed MIPS16 and non-MIPS16 code
 105   may interact badly with some GCC extensions such as ``__builtin_apply``
 106   (see :ref:`constructing-calls`).
 107
 108 .. index:: micromips function attribute, nomicromips function attribute
 109
 110 .. mips-fn-attr:: micromips, MIPS, nomicromips, MIPS
 111
 112   On MIPS targets, you can use the ``micromips`` and ``nomicromips``
 113   function attributes to locally select or turn off microMIPS code generation.
 114   A function with the ``micromips`` attribute is emitted as microMIPS code,
 115   while microMIPS code generation is disabled for functions with the
 116   ``nomicromips`` attribute.  These attributes override the
 117   :option:`-mmicromips` and :option:`-mno-micromips` options on the command line
 118   (see :ref:`mips-options`).
 119
 120   When compiling files containing mixed microMIPS and non-microMIPS code, the
 121   preprocessor symbol ``__mips_micromips`` reflects the setting on the
 122   command line,
 123   not that within individual functions.  Mixed microMIPS and non-microMIPS code
 124   may interact badly with some GCC extensions such as ``__builtin_apply``
 125   (see :ref:`constructing-calls`).
 126
 127 .. index:: nocompression function attribute, MIPS
 128
 129 .. mips-fn-attr:: nocompression
 130
 131   On MIPS targets, you can use the :mips-fn-attr:`nocompression` function attribute
 132   to locally turn off MIPS16 and microMIPS code generation.  This attribute
 133   overrides the :option:`-mips16` and :option:`-mmicromips` options on the
 134   command line (see :ref:`mips-options`).