gcc/doc/gccint/target-macros/defining-the-output-assembler-language/assembler-commands-for-alignment.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 .. _alignment-output:
   7
   8 Assembler Commands for Alignment
   9 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  10
  11 .. prevent bad page break with this line
  12
  13 This describes commands for alignment.
  14
  15 .. c:macro:: JUMP_ALIGN (label)
  16
  17   The alignment (log base 2) to put in front of :samp:`{label}`, which is
  18   a common destination of jumps and has no fallthru incoming edge.
  19
  20   This macro need not be defined if you don't want any special alignment
  21   to be done at such a time.  Most machine descriptions do not currently
  22   define the macro.
  23
  24   Unless it's necessary to inspect the :samp:`{label}` parameter, it is better
  25   to set the variable :samp:`{align_jumps}` in the target's
  26   ``TARGET_OPTION_OVERRIDE``.  Otherwise, you should try to honor the user's
  27   selection in :samp:`{align_jumps}` in a ``JUMP_ALIGN`` implementation.
  28
  29 .. c:macro:: LABEL_ALIGN_AFTER_BARRIER (label)
  30
  31   The alignment (log base 2) to put in front of :samp:`{label}`, which follows
  32   a ``BARRIER``.
  33
  34   This macro need not be defined if you don't want any special alignment
  35   to be done at such a time.  Most machine descriptions do not currently
  36   define the macro.
  37
  38 .. c:macro:: LOOP_ALIGN (label)
  39
  40   The alignment (log base 2) to put in front of :samp:`{label}` that heads
  41   a frequently executed basic block (usually the header of a loop).
  42
  43   This macro need not be defined if you don't want any special alignment
  44   to be done at such a time.  Most machine descriptions do not currently
  45   define the macro.
  46
  47   Unless it's necessary to inspect the :samp:`{label}` parameter, it is better
  48   to set the variable ``align_loops`` in the target's
  49   ``TARGET_OPTION_OVERRIDE``.  Otherwise, you should try to honor the user's
  50   selection in ``align_loops`` in a ``LOOP_ALIGN`` implementation.
  51
  52 .. c:macro:: LABEL_ALIGN (label)
  53
  54   The alignment (log base 2) to put in front of :samp:`{label}`.
  55   If ``LABEL_ALIGN_AFTER_BARRIER`` / ``LOOP_ALIGN`` specify a different alignment,
  56   the maximum of the specified values is used.
  57
  58   Unless it's necessary to inspect the :samp:`{label}` parameter, it is better
  59   to set the variable ``align_labels`` in the target's
  60   ``TARGET_OPTION_OVERRIDE``.  Otherwise, you should try to honor the user's
  61   selection in ``align_labels`` in a ``LABEL_ALIGN`` implementation.
  62
  63 .. c:macro:: ASM_OUTPUT_SKIP (stream, nbytes)
  64
  65   A C statement to output to the stdio stream :samp:`{stream}` an assembler
  66   instruction to advance the location counter by :samp:`{nbytes}` bytes.
  67   Those bytes should be zero when loaded.  :samp:`{nbytes}` will be a C
  68   expression of type ``unsigned HOST_WIDE_INT``.
  69
  70 .. c:macro:: ASM_NO_SKIP_IN_TEXT
  71
  72   Define this macro if ``ASM_OUTPUT_SKIP`` should not be used in the
  73   text section because it fails to put zeros in the bytes that are skipped.
  74   This is true on many Unix systems, where the pseudo--op to skip bytes
  75   produces no-op instructions rather than zeros when used in the text
  76   section.
  77
  78 .. c:macro:: ASM_OUTPUT_ALIGN (stream, power)
  79
  80   A C statement to output to the stdio stream :samp:`{stream}` an assembler
  81   command to advance the location counter to a multiple of 2 to the
  82   :samp:`{power}` bytes.  :samp:`{power}` will be a C expression of type ``int``.
  83
  84 .. c:macro:: ASM_OUTPUT_ALIGN_WITH_NOP (stream, power)
  85
  86   Like ``ASM_OUTPUT_ALIGN``, except that the 'nop' instruction is used
  87   for padding, if necessary.
  88
  89 .. c:macro:: ASM_OUTPUT_MAX_SKIP_ALIGN (stream, power, max_skip)
  90
  91   A C statement to output to the stdio stream :samp:`{stream}` an assembler
  92   command to advance the location counter to a multiple of 2 to the
  93   :samp:`{power}` bytes, but only if :samp:`{max_skip}` or fewer bytes are needed to
  94   satisfy the alignment request.  :samp:`{power}` and :samp:`{max_skip}` will be
  95   a C expression of type ``int``.