gcc/doc/gccint/target-macros/defining-the-output-assembler-language/output-of-uninitialized-variables.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 .. _uninitialized-data:
   7
   8 Output of Uninitialized Variables
   9 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  10
  11 Each of the macros in this section is used to do the whole job of
  12 outputting a single uninitialized variable.
  13
  14 .. c:macro:: ASM_OUTPUT_COMMON (stream, name, size, rounded)
  15
  16   A C statement (sans semicolon) to output to the stdio stream
  17   :samp:`{stream}` the assembler definition of a common-label named
  18   :samp:`{name}` whose size is :samp:`{size}` bytes.  The variable :samp:`{rounded}`
  19   is the size rounded up to whatever alignment the caller wants.  It is
  20   possible that :samp:`{size}` may be zero, for instance if a struct with no
  21   other member than a zero-length array is defined.  In this case, the
  22   backend must output a symbol definition that allocates at least one
  23   byte, both so that the address of the resulting object does not compare
  24   equal to any other, and because some object formats cannot even express
  25   the concept of a zero-sized common symbol, as that is how they represent
  26   an ordinary undefined external.
  27
  28   Use the expression ``assemble_name (stream, name)`` to
  29   output the name itself; before and after that, output the additional
  30   assembler syntax for defining the name, and a newline.
  31
  32   This macro controls how the assembler definitions of uninitialized
  33   common global variables are output.
  34
  35 .. c:macro:: ASM_OUTPUT_ALIGNED_COMMON (stream, name, size, alignment)
  36
  37   Like ``ASM_OUTPUT_COMMON`` except takes the required alignment as a
  38   separate, explicit argument.  If you define this macro, it is used in
  39   place of ``ASM_OUTPUT_COMMON``, and gives you more flexibility in
  40   handling the required alignment of the variable.  The alignment is specified
  41   as the number of bits.
  42
  43 .. c:macro:: ASM_OUTPUT_ALIGNED_DECL_COMMON (stream, decl, name, size, alignment)
  44
  45   Like ``ASM_OUTPUT_ALIGNED_COMMON`` except that :samp:`{decl}` of the
  46   variable to be output, if there is one, or ``NULL_TREE`` if there
  47   is no corresponding variable.  If you define this macro, GCC will use it
  48   in place of both ``ASM_OUTPUT_COMMON`` and
  49   ``ASM_OUTPUT_ALIGNED_COMMON``.  Define this macro when you need to see
  50   the variable's decl in order to chose what to output.
  51
  52 .. c:macro:: ASM_OUTPUT_ALIGNED_BSS (stream, decl, name, size, alignment)
  53
  54   A C statement (sans semicolon) to output to the stdio stream
  55   :samp:`{stream}` the assembler definition of uninitialized global :samp:`{decl}` named
  56   :samp:`{name}` whose size is :samp:`{size}` bytes.  The variable :samp:`{alignment}`
  57   is the alignment specified as the number of bits.
  58
  59   Try to use function ``asm_output_aligned_bss`` defined in file
  60   :samp:`varasm.cc` when defining this macro.  If unable, use the expression
  61   ``assemble_name (stream, name)`` to output the name itself;
  62   before and after that, output the additional assembler syntax for defining
  63   the name, and a newline.
  64
  65   There are two ways of handling global BSS.  One is to define this macro.
  66   The other is to have ``TARGET_ASM_SELECT_SECTION`` return a
  67   switchable BSS section (see :ref:`target_have_switchable_bss_sections`).
  68   You do not need to do both.
  69
  70   Some languages do not have ``common`` data, and require a
  71   non-common form of global BSS in order to handle uninitialized globals
  72   efficiently.  C++ is one example of this.  However, if the target does
  73   not support global BSS, the front end may choose to make globals
  74   common in order to save space in the object file.
  75
  76 .. c:macro:: ASM_OUTPUT_LOCAL (stream, name, size, rounded)
  77
  78   A C statement (sans semicolon) to output to the stdio stream
  79   :samp:`{stream}` the assembler definition of a local-common-label named
  80   :samp:`{name}` whose size is :samp:`{size}` bytes.  The variable :samp:`{rounded}`
  81   is the size rounded up to whatever alignment the caller wants.
  82
  83   Use the expression ``assemble_name (stream, name)`` to
  84   output the name itself; before and after that, output the additional
  85   assembler syntax for defining the name, and a newline.
  86
  87   This macro controls how the assembler definitions of uninitialized
  88   static variables are output.
  89
  90 .. c:macro:: ASM_OUTPUT_ALIGNED_LOCAL (stream, name, size, alignment)
  91
  92   Like ``ASM_OUTPUT_LOCAL`` except takes the required alignment as a
  93   separate, explicit argument.  If you define this macro, it is used in
  94   place of ``ASM_OUTPUT_LOCAL``, and gives you more flexibility in
  95   handling the required alignment of the variable.  The alignment is specified
  96   as the number of bits.
  97
  98 .. c:macro:: ASM_OUTPUT_ALIGNED_DECL_LOCAL (stream, decl, name, size, alignment)
  99
 100   Like ``ASM_OUTPUT_ALIGNED_LOCAL`` except that :samp:`{decl}` of the
 101   variable to be output, if there is one, or ``NULL_TREE`` if there
 102   is no corresponding variable.  If you define this macro, GCC will use it
 103   in place of both ``ASM_OUTPUT_LOCAL`` and
 104   ``ASM_OUTPUT_ALIGNED_LOCAL``.  Define this macro when you need to see
 105   the variable's decl in order to chose what to output.