gcc/doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/sh-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 .. _sh-function-attributes:
   7
   8 SH Function Attributes
   9 ^^^^^^^^^^^^^^^^^^^^^^
  10
  11 These function attributes are supported on the SH family of processors:
  12
  13 .. index:: function_vector function attribute, SH, calling functions through the function vector on SH2A
  14
  15 .. sh-fn-attr:: function_vector
  16
  17   On SH2A targets, this attribute declares a function to be called using the
  18   TBR relative addressing mode.  The argument to this attribute is the entry
  19   number of the same function in a vector table containing all the TBR
  20   relative addressable functions.  For correct operation the TBR must be setup
  21   accordingly to point to the start of the vector table before any functions with
  22   this attribute are invoked.  Usually a good place to do the initialization is
  23   the startup routine.  The TBR relative vector table can have at max 256 function
  24   entries.  The jumps to these functions are generated using a SH2A specific,
  25   non delayed branch instruction JSR/N @(disp8,TBR).  You must use GAS and GLD
  26   from GNU binutils version 2.7 or later for this attribute to work correctly.
  27
  28   In an application, for a function being called once, this attribute
  29   saves at least 8 bytes of code; and if other successive calls are being
  30   made to the same function, it saves 2 bytes of code per each of these
  31   calls.
  32
  33 .. index:: interrupt_handler function attribute, SH
  34
  35 .. sh-fn-attr:: interrupt_handler
  36
  37   Use this attribute to
  38   indicate that the specified function is an interrupt handler.  The compiler
  39   generates function entry and exit sequences suitable for use in an
  40   interrupt handler when this attribute is present.
  41
  42 .. index:: nosave_low_regs function attribute, SH
  43
  44 .. sh-fn-attr:: nosave_low_regs
  45
  46   Use this attribute on SH targets to indicate that an :sh-fn-attr:`interrupt_handler`
  47   function should not save and restore registers R0..R7.  This can be used on SH3\*
  48   and SH4\* targets that have a second R0..R7 register bank for non-reentrant
  49   interrupt handlers.
  50
  51 .. index:: renesas function attribute, SH
  52
  53 .. sh-fn-attr:: renesas
  54
  55   On SH targets this attribute specifies that the function or struct follows the
  56   Renesas ABI.
  57
  58 .. index:: resbank function attribute, SH
  59
  60 .. sh-fn-attr:: resbank
  61
  62   On the SH2A target, this attribute enables the high-speed register
  63   saving and restoration using a register bank for :sh-fn-attr:`interrupt_handler`
  64   routines.  Saving to the bank is performed automatically after the CPU
  65   accepts an interrupt that uses a register bank.
  66
  67   The nineteen 32-bit registers comprising general register R0 to R14,
  68   control register GBR, and system registers MACH, MACL, and PR and the
  69   vector table address offset are saved into a register bank.  Register
  70   banks are stacked in first-in last-out (FILO) sequence.  Restoration
  71   from the bank is executed by issuing a RESBANK instruction.
  72
  73 .. index:: sp_switch function attribute, SH
  74
  75 .. sh-fn-attr:: sp_switch
  76
  77   Use this attribute on the SH to indicate an :sh-fn-attr:`interrupt_handler`
  78   function should switch to an alternate stack.  It expects a string
  79   argument that names a global variable holding the address of the
  80   alternate stack.
  81
  82   .. code-block:: c++
  83
  84     void *alt_stack;
  85     void f () __attribute__ ((interrupt_handler,
  86                               sp_switch ("alt_stack")));
  87
  88 .. index:: trap_exit function attribute, SH
  89
  90 .. sh-fn-attr:: trap_exit
  91
  92   Use this attribute on the SH for an :sh-fn-attr:`interrupt_handler` to return using
  93   ``trapa`` instead of ``rte``.  This attribute expects an integer
  94   argument specifying the trap number to be used.
  95
  96 .. index:: trapa_handler function attribute, SH
  97
  98 .. sh-fn-attr:: trapa_handler
  99
 100   On SH targets this function attribute is similar to :sh-fn-attr:`interrupt_handler`
 101   but it does not save and restore all registers.