gcc/doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/msp430-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 .. _msp430-function-attributes:
   7
   8 MSP430 Function Attributes
   9 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  10
  11 These function attributes are supported by the MSP430 back end:
  12
  13 .. index:: critical function attribute, MSP430
  14
  15 .. msp430-fn-attr:: critical
  16
  17   Critical functions disable interrupts upon entry and restore the
  18   previous interrupt state upon exit.  Critical functions cannot also
  19   have the :msp430-fn-attr:`naked`, :msp430-fn-attr:`reentrant` or :msp430-fn-attr:`interrupt` attributes.
  20
  21   The MSP430 hardware ensures that interrupts are disabled on entry to
  22   :msp430-fn-attr:`interrupt` functions, and restores the previous interrupt state
  23   on exit. The :msp430-fn-attr:`critical` attribute is therefore redundant on
  24   :msp430-fn-attr:`interrupt` functions.
  25
  26 .. index:: interrupt function attribute, MSP430
  27
  28 .. msp430-fn-attr:: interrupt
  29
  30   Use this attribute to indicate
  31   that the specified function is an interrupt handler.  The compiler generates
  32   function entry and exit sequences suitable for use in an interrupt handler
  33   when this attribute is present.
  34
  35   You can provide an argument to the interrupt
  36   attribute which specifies a name or number.  If the argument is a
  37   number it indicates the slot in the interrupt vector table (0 - 31) to
  38   which this handler should be assigned.  If the argument is a name it
  39   is treated as a symbolic name for the vector slot.  These names should
  40   match up with appropriate entries in the linker script.  By default
  41   the names ``watchdog`` for vector 26, ``nmi`` for vector 30 and
  42   :msp430-fn-attr:`reset` for vector 31 are recognized.
  43
  44 .. index:: naked function attribute, MSP430
  45
  46 .. msp430-fn-attr:: naked
  47
  48   This attribute allows the compiler to construct the
  49   requisite function declaration, while allowing the body of the
  50   function to be assembly code. The specified function will not have
  51   prologue/epilogue sequences generated by the compiler. Only basic
  52   ``asm`` statements can safely be included in naked functions
  53   (see :ref:`basic-asm`). While using extended ``asm`` or a mixture of
  54   basic ``asm`` and C code may appear to work, they cannot be
  55   depended upon to work reliably and are not supported.
  56
  57 .. index:: reentrant function attribute, MSP430
  58
  59 .. msp430-fn-attr:: reentrant
  60
  61   Reentrant functions disable interrupts upon entry and enable them
  62   upon exit.  Reentrant functions cannot also have the :msp430-fn-attr:`naked`
  63   or :msp430-fn-attr:`critical` attributes.  They can have the :msp430-fn-attr:`interrupt`
  64   attribute.
  65
  66 .. index:: wakeup function attribute, MSP430
  67
  68 .. msp430-fn-attr:: wakeup
  69
  70   This attribute only applies to interrupt functions.  It is silently
  71   ignored if applied to a non-interrupt function.  A wakeup interrupt
  72   function will rouse the processor from any low-power state that it
  73   might be in when the function exits.
  74
  75 .. index:: lower function attribute, MSP430, upper function attribute, MSP430, either function attribute, MSP430
  76
  77 .. msp430-fn-attr:: lower, upper, either
  78
  79   On the MSP430 target these attributes can be used to specify whether
  80   the function or variable should be placed into low memory, high
  81   memory, or the placement should be left to the linker to decide.  The
  82   attributes are only significant if compiling for the MSP430X
  83   architecture in the large memory model.
  84
  85   The attributes work in conjunction with a linker script that has been
  86   augmented to specify where to place sections with a ``.lower`` and
  87   a ``.upper`` prefix.  So, for example, as well as placing the
  88   ``.data`` section, the script also specifies the placement of a
  89   ``.lower.data`` and a ``.upper.data`` section.  The intention
  90   is that :msp430-fn-attr:`lower` sections are placed into a small but easier to
  91   access memory region and the upper sections are placed into a larger, but
  92   slower to access, region.
  93
  94   The ``either`` attribute is special.  It tells the linker to place
  95   the object into the corresponding :msp430-fn-attr:`lower` section if there is
  96   room for it.  If there is insufficient room then the object is placed
  97   into the corresponding :msp430-fn-attr:`upper` section instead.  Note that the
  98   placement algorithm is not very sophisticated.  It does not attempt to
  99   find an optimal packing of the :msp430-fn-attr:`lower` sections.  It just makes
 100   one pass over the objects and does the best that it can.  Using the
 101   :option:`-ffunction-sections` and :option:`-fdata-sections` command-line
 102   options can help the packing, however, since they produce smaller,
 103   easier to pack regions.