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 .. _stack-checking:
   7
   8 Specifying How Stack Checking is Done
   9 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  10
  11 GCC will check that stack references are within the boundaries of the
  12 stack, if the option :option:`-fstack-check` is specified, in one of
  13 three ways:
  14
  15 * If the value of the ``STACK_CHECK_BUILTIN`` macro is nonzero, GCC
  16   will assume that you have arranged for full stack checking to be done
  17   at appropriate places in the configuration files.  GCC will not do
  18   other special processing.
  19
  20 * If ``STACK_CHECK_BUILTIN`` is zero and the value of the
  21   ``STACK_CHECK_STATIC_BUILTIN`` macro is nonzero, GCC will assume
  22   that you have arranged for static stack checking (checking of the
  23   static stack frame of functions) to be done at appropriate places
  24   in the configuration files.  GCC will only emit code to do dynamic
  25   stack checking (checking on dynamic stack allocations) using the third
  26   approach below.
  27
  28 * If neither of the above are true, GCC will generate code to periodically
  29   'probe' the stack pointer using the values of the macros defined below.
  30
  31 If neither STACK_CHECK_BUILTIN nor STACK_CHECK_STATIC_BUILTIN is defined,
  32 GCC will change its allocation strategy for large objects if the option
  33 :option:`-fstack-check` is specified: they will always be allocated
  34 dynamically if their size exceeds ``STACK_CHECK_MAX_VAR_SIZE`` bytes.
  35
  36 .. c:macro:: STACK_CHECK_BUILTIN
  37
  38   A nonzero value if stack checking is done by the configuration files in a
  39   machine-dependent manner.  You should define this macro if stack checking
  40   is required by the ABI of your machine or if you would like to do stack
  41   checking in some more efficient way than the generic approach.  The default
  42   value of this macro is zero.
  43
  44 .. c:macro:: STACK_CHECK_STATIC_BUILTIN
  45
  46   A nonzero value if static stack checking is done by the configuration files
  47   in a machine-dependent manner.  You should define this macro if you would
  48   like to do static stack checking in some more efficient way than the generic
  49   approach.  The default value of this macro is zero.
  50
  51 .. c:macro:: STACK_CHECK_PROBE_INTERVAL_EXP
  52
  53   An integer specifying the interval at which GCC must generate stack probe
  54   instructions, defined as 2 raised to this integer.  You will normally
  55   define this macro so that the interval be no larger than the size of
  56   the 'guard pages' at the end of a stack area.  The default value
  57   of 12 (4096-byte interval) is suitable for most systems.
  58
  59 .. c:macro:: STACK_CHECK_MOVING_SP
  60
  61   An integer which is nonzero if GCC should move the stack pointer page by page
  62   when doing probes.  This can be necessary on systems where the stack pointer
  63   contains the bottom address of the memory area accessible to the executing
  64   thread at any point in time.  In this situation an alternate signal stack
  65   is required in order to be able to recover from a stack overflow.  The
  66   default value of this macro is zero.
  67
  68 .. c:macro:: STACK_CHECK_PROTECT
  69
  70   The number of bytes of stack needed to recover from a stack overflow, for
  71   languages where such a recovery is supported.  The default value of 4KB/8KB
  72   with the ``setjmp`` / ``longjmp`` -based exception handling mechanism and
  73   8KB/12KB with other exception handling mechanisms should be adequate for most
  74   architectures and operating systems.
  75
  76 The following macros are relevant only if neither STACK_CHECK_BUILTIN
  77 nor STACK_CHECK_STATIC_BUILTIN is defined; you can omit them altogether
  78 in the opposite case.
  79
  80 .. c:macro:: STACK_CHECK_MAX_FRAME_SIZE
  81
  82   The maximum size of a stack frame, in bytes.  GCC will generate probe
  83   instructions in non-leaf functions to ensure at least this many bytes of
  84   stack are available.  If a stack frame is larger than this size, stack
  85   checking will not be reliable and GCC will issue a warning.  The
  86   default is chosen so that GCC only generates one instruction on most
  87   systems.  You should normally not change the default value of this macro.
  88
  89 .. c:macro:: STACK_CHECK_FIXED_FRAME_SIZE
  90
  91   GCC uses this value to generate the above warning message.  It
  92   represents the amount of fixed frame used by a function, not including
  93   space for any callee-saved registers, temporaries and user variables.
  94   You need only specify an upper bound for this amount and will normally
  95   use the default of four words.
  96
  97 .. c:macro:: STACK_CHECK_MAX_VAR_SIZE
  98
  99   The maximum size, in bytes, of an object that GCC will place in the
 100   fixed area of the stack frame when the user specifies
 101   :option:`-fstack-check`.
 102   GCC computed the default from the values of the above macros and you will
 103   normally not need to override that default.
 104
 105 .. include:: ../tm.rst.in
 106   :start-after: [TARGET_STACK_CLASH_PROTECTION_ALLOCA_PROBE_RANGE]
 107   :end-before: [TARGET_STACK_CLASH_PROTECTION_ALLOCA_PROBE_RANGE]