reference, declarationdefinition
definition → references, declarations, derived classes, virtual overrides
reference to multiple definitions → definitions
unreferenced
    1
    2
    3
    4
    5
    6
    7
    8
    9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
  100
  101
  102
  103
  104
  105
  106
  107
  108
  109
  110
  111
  112
  113
  114
  115
  116
  117
  118
  119
  120
  121
  122
  123
  124
  125
  126
  127
  128
  129
  130
  131
  132
  133
  134
  135
  136
  137
  138
  139
  140
  141
  142
  143
  144
  145
  146
  147
  148
  149
  150
  151
  152
  153
  154
  155
  156
  157
  158
  159
  160
  161
  162
  163
  164
  165
  166
  167
  168
  169
  170
  171
  172
  173
  174
  175
  176
  177
  178
  179
  180
  181
  182
  183
  184
  185
  186
  187
  188
  189
  190
  191
  192
  193
  194
  195
  196
  197
  198
  199
  200
  201
  202
  203
  204
  205
  206
  207
  208
  209
  210
  211
  212
  213
  214
  215
  216
  217
  218
  219
  220
  221
  222
  223
  224
  225
  226
  227
  228
  229
  230
  231
  232
  233
  234
  235
  236
  237
  238
  239
  240
  241
  242
  243
  244
  245
  246
  247
  248
  249
  250
  251
  252
  253
  254
  255
  256
  257
  258
  259
  260
  261
  262
  263
  264
  265
  266
  267
  268
  269
  270
  271
  272
  273
  274
  275
  276
  277
  278
  279
  280
  281
  282
  283
  284
  285
  286
  287
  288
  289
  290
===============
LLVM Extensions
===============

.. contents::
   :local:

.. toctree::
   :hidden:

Introduction
============

This document describes extensions to tools and formats LLVM seeks compatibility
with.

General Assembly Syntax
===========================

C99-style Hexadecimal Floating-point Constants
----------------------------------------------

LLVM's assemblers allow floating-point constants to be written in C99's
hexadecimal format instead of decimal if desired.

.. code-block:: gas

  .section .data
  .float 0x1c2.2ap3

Machine-specific Assembly Syntax
================================

X86/COFF-Dependent
------------------

Relocations
^^^^^^^^^^^

The following additional relocation types are supported:

**@IMGREL** (AT&T syntax only) generates an image-relative relocation that
corresponds to the COFF relocation types ``IMAGE_REL_I386_DIR32NB`` (32-bit) or
``IMAGE_REL_AMD64_ADDR32NB`` (64-bit).

.. code-block:: text

  .text
  fun:
    mov foo@IMGREL(%ebx, %ecx, 4), %eax

  .section .pdata
    .long fun@IMGREL
    .long (fun@imgrel + 0x3F)
    .long $unwind$fun@imgrel

**.secrel32** generates a relocation that corresponds to the COFF relocation
types ``IMAGE_REL_I386_SECREL`` (32-bit) or ``IMAGE_REL_AMD64_SECREL`` (64-bit).

**.secidx** relocation generates an index of the section that contains
the target.  It corresponds to the COFF relocation types
``IMAGE_REL_I386_SECTION`` (32-bit) or ``IMAGE_REL_AMD64_SECTION`` (64-bit).

.. code-block:: none

  .section .debug$S,"rn"
    .long 4
    .long 242
    .long 40
    .secrel32 _function_name + 0
    .secidx   _function_name
    ...

``.linkonce`` Directive
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:

   ``.linkonce [ comdat type ]``

Supported COMDAT types:

``discard``
   Discards duplicate sections with the same COMDAT symbol. This is the default
   if no type is specified.

``one_only``
   If the symbol is defined multiple times, the linker issues an error.

``same_size``
   Duplicates are discarded, but the linker issues an error if any have
   different sizes.

``same_contents``
   Duplicates are discarded, but the linker issues an error if any duplicates
   do not have exactly the same content.

``largest``
   Links the largest section from among the duplicates.

``newest``
   Links the newest section from among the duplicates.


.. code-block:: gas

  .section .text$foo
  .linkonce
    ...

``.section`` Directive
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

MC supports passing the information in ``.linkonce`` at the end of
``.section``. For example,  these two codes are equivalent

.. code-block:: gas

  .section secName, "dr", discard, "Symbol1"
  .globl Symbol1
  Symbol1:
  .long 1

.. code-block:: gas

  .section secName, "dr"
  .linkonce discard
  .globl Symbol1
  Symbol1:
  .long 1

Note that in the combined form the COMDAT symbol is explicit. This
extension exists to support multiple sections with the same name in
different COMDATs:


.. code-block:: gas

  .section secName, "dr", discard, "Symbol1"
  .globl Symbol1
  Symbol1:
  .long 1

  .section secName, "dr", discard, "Symbol2"
  .globl Symbol2
  Symbol2:
  .long 1

In addition to the types allowed with ``.linkonce``, ``.section`` also accepts
``associative``. The meaning is that the section is linked  if a certain other
COMDAT section is linked. This other section is indicated by the comdat symbol
in this directive. It can be any symbol defined in the associated section, but
is usually the associated section's comdat.

   The following restrictions apply to the associated section:

   1. It must be a COMDAT section.
   2. It cannot be another associative COMDAT section.

In the following example the symobl ``sym`` is the comdat symbol of ``.foo``
and ``.bar`` is associated to ``.foo``.

.. code-block:: gas

	.section	.foo,"bw",discard, "sym"
	.section	.bar,"rd",associative, "sym"

MC supports these flags in the COFF ``.section`` directive:

  - ``b``: BSS section (``IMAGE_SCN_CNT_INITIALIZED_DATA``)
  - ``d``: Data section (``IMAGE_SCN_CNT_UNINITIALIZED_DATA``)
  - ``n``: Section is not loaded (``IMAGE_SCN_LNK_REMOVE``)
  - ``r``: Read-only
  - ``s``: Shared section
  - ``w``: Writable
  - ``x``: Executable section
  - ``y``: Not readable
  - ``D``: Discardable (``IMAGE_SCN_MEM_DISCARDABLE``)

These flags are all compatible with gas, with the exception of the ``D`` flag,
which gnu as does not support. For gas compatibility, sections with a name
starting with ".debug" are implicitly discardable.


ELF-Dependent
-------------

``.section`` Directive
^^^^^^^^^^^^^^^^^^^^^^

In order to support creating multiple sections with the same name and comdat,
it is possible to add an unique number at the end of the ``.seciton`` directive.
For example, the following code creates two sections named ``.text``.

.. code-block:: gas

	.section	.text,"ax",@progbits,unique,1
        nop

	.section	.text,"ax",@progbits,unique,2
        nop


The unique number is not present in the resulting object at all. It is just used
in the assembler to differentiate the sections.

The 'o' flag is mapped to SHF_LINK_ORDER. If it is present, a symbol
must be given that identifies the section to be placed is the
.sh_link.

.. code-block:: gas

        .section .foo,"a",@progbits
        .Ltmp:
        .section .bar,"ao",@progbits,.Ltmp

which is equivalent to just

.. code-block:: gas

        .section .foo,"a",@progbits
        .section .bar,"ao",@progbits,.foo


Target Specific Behaviour
=========================

X86
---

Relocations
^^^^^^^^^^^

``@ABS8`` can be applied to symbols which appear as immediate operands to
instructions that have an 8-bit immediate form for that operand. It causes
the assembler to use the 8-bit form and an 8-bit relocation (e.g. ``R_386_8``
or ``R_X86_64_8``) for the symbol.

For example:

.. code-block:: gas

  cmpq $foo@ABS8, %rdi

This causes the assembler to select the form of the 64-bit ``cmpq`` instruction
that takes an 8-bit immediate operand that is sign extended to 64 bits, as
opposed to ``cmpq $foo, %rdi`` which takes a 32-bit immediate operand. This
is also not the same as ``cmpb $foo, %dil``, which is an 8-bit comparison.

Windows on ARM
--------------

Stack Probe Emission
^^^^^^^^^^^^^^^^^^^^

The reference implementation (Microsoft Visual Studio 2012) emits stack probes
in the following fashion:

.. code-block:: gas

  movw r4, #constant
  bl __chkstk
  sub.w sp, sp, r4

However, this has the limitation of 32 MiB (±16MiB).  In order to accommodate
larger binaries, LLVM supports the use of ``-mcode-model=large`` to allow a 4GiB
range via a slight deviation.  It will generate an indirect jump as follows:

.. code-block:: gas

  movw r4, #constant
  movw r12, :lower16:__chkstk
  movt r12, :upper16:__chkstk
  blx r12
  sub.w sp, sp, r4

Variable Length Arrays
^^^^^^^^^^^^^^^^^^^^^^

The reference implementation (Microsoft Visual Studio 2012) does not permit the
emission of Variable Length Arrays (VLAs).

The Windows ARM Itanium ABI extends the base ABI by adding support for emitting
a dynamic stack allocation.  When emitting a variable stack allocation, a call
to ``__chkstk`` is emitted unconditionally to ensure that guard pages are setup
properly.  The emission of this stack probe emission is handled similar to the
standard stack probe emission.

The MSVC environment does not emit code for VLAs currently.