docs/Extensions.rst

   1 ===============
   2 LLVM Extensions
   3 ===============
   4
   5 .. contents::
   6    :local:
   7
   8 .. toctree::
   9    :hidden:
  10
  11 Introduction
  12 ============
  13
  14 This document describes extensions to tools and formats LLVM seeks compatibility
  15 with.
  16
  17 General Assembly Syntax
  18 ===========================
  19
  20 C99-style Hexadecimal Floating-point Constants
  21 ----------------------------------------------
  22
  23 LLVM's assemblers allow floating-point constants to be written in C99's
  24 hexadecimal format instead of decimal if desired.
  25
  26 .. code-block:: gas
  27
  28   .section .data
  29   .float 0x1c2.2ap3
  30
  31 Machine-specific Assembly Syntax
  32 ================================
  33
  34 X86/COFF-Dependent
  35 ------------------
  36
  37 Relocations
  38 ^^^^^^^^^^^
  39
  40 The following additional relocation types are supported:
  41
  42 **@IMGREL** (AT&T syntax only) generates an image-relative relocation that
  43 corresponds to the COFF relocation types ``IMAGE_REL_I386_DIR32NB`` (32-bit) or
  44 ``IMAGE_REL_AMD64_ADDR32NB`` (64-bit).
  45
  46 .. code-block:: gas
  47
  48   .text
  49   fun:
  50     mov foo@IMGREL(%ebx, %ecx, 4), %eax
  51
  52   .section .pdata
  53     .long fun@IMGREL
  54     .long (fun@imgrel + 0x3F)
  55     .long $unwind$fun@imgrel
  56
  57 **.secrel32** generates a relocation that corresponds to the COFF relocation
  58 types ``IMAGE_REL_I386_SECREL`` (32-bit) or ``IMAGE_REL_AMD64_SECREL`` (64-bit).
  59
  60 **.secidx** relocation generates an index of the section that contains
  61 the target.  It corresponds to the COFF relocation types
  62 ``IMAGE_REL_I386_SECTION`` (32-bit) or ``IMAGE_REL_AMD64_SECTION`` (64-bit).
  63
  64 .. code-block:: gas
  65
  66   .section .debug$S,"rn"
  67     .long 4
  68     .long 242
  69     .long 40
  70     .secrel32 _function_name
  71     .secidx   _function_name
  72     ...
  73
  74 ``.linkonce`` Directive
  75 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  76
  77 Syntax:
  78
  79    ``.linkonce [ comdat type ]``
  80
  81 Supported COMDAT types:
  82
  83 ``discard``
  84    Discards duplicate sections with the same COMDAT symbol. This is the default
  85    if no type is specified.
  86
  87 ``one_only``
  88    If the symbol is defined multiple times, the linker issues an error.
  89
  90 ``same_size``
  91    Duplicates are discarded, but the linker issues an error if any have
  92    different sizes.
  93
  94 ``same_contents``
  95    Duplicates are discarded, but the linker issues an error if any duplicates
  96    do not have exactly the same content.
  97
  98 ``largest``
  99    Links the largest section from among the duplicates.
 100
 101 ``newest``
 102    Links the newest section from among the duplicates.
 103
 104
 105 .. code-block:: gas
 106
 107   .section .text$foo
 108   .linkonce
 109     ...
 110
 111 ``.section`` Directive
 112 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 113
 114 MC supports passing the information in ``.linkonce`` at the end of
 115 ``.section``. For example,  these two codes are equivalent
 116
 117 .. code-block:: gas
 118
 119   .section secName, "dr", discard, "Symbol1"
 120   .globl Symbol1
 121   Symbol1:
 122   .long 1
 123
 124 .. code-block:: gas
 125
 126   .section secName, "dr"
 127   .linkonce discard
 128   .globl Symbol1
 129   Symbol1:
 130   .long 1
 131
 132 Note that in the combined form the COMDAT symbol is explicit. This
 133 extension exists to support multiple sections with the same name in
 134 different COMDATs:
 135
 136
 137 .. code-block:: gas
 138
 139   .section secName, "dr", discard, "Symbol1"
 140   .globl Symbol1
 141   Symbol1:
 142   .long 1
 143
 144   .section secName, "dr", discard, "Symbol2"
 145   .globl Symbol2
 146   Symbol2:
 147   .long 1
 148
 149 In addition to the types allowed with ``.linkonce``, ``.section`` also accepts
 150 ``associative``. The meaning is that the section is linked  if a certain other
 151 COMDAT section is linked. This other section is indicated by the comdat symbol
 152 in this directive. It can be any symbol defined in the associated section, but
 153 is usually the associated section's comdat.
 154
 155    The following restrictions apply to the associated section:
 156
 157    1. It must be a COMDAT section.
 158    2. It cannot be another associative COMDAT section.
 159
 160 In the following example the symobl ``sym`` is the comdat symbol of ``.foo``
 161 and ``.bar`` is associated to ``.foo``.
 162
 163 .. code-block:: gas
 164
 165         .section        .foo,"bw",discard, "sym"
 166         .section        .bar,"rd",associative, "sym"
 167
 168
 169 ELF-Dependent
 170 -------------
 171
 172 ``.section`` Directive
 173 ^^^^^^^^^^^^^^^^^^^^^^
 174
 175 In order to support creating multiple sections with the same name and comdat,
 176 it is possible to add an unique number at the end of the ``.seciton`` directive.
 177 For example, the following code creates two sections named ``.text``.
 178
 179 .. code-block:: gas
 180
 181         .section        .text,"ax",@progbits,unique,1
 182         nop
 183
 184         .section        .text,"ax",@progbits,unique,2
 185         nop
 186
 187
 188 The unique number is not present in the resulting object at all. It is just used
 189 in the assembler to differentiate the sections.
 190
 191 Target Specific Behaviour
 192 =========================
 193
 194 Windows on ARM
 195 --------------
 196
 197 Stack Probe Emission
 198 ^^^^^^^^^^^^^^^^^^^^
 199
 200 The reference implementation (Microsoft Visual Studio 2012) emits stack probes
 201 in the following fashion:
 202
 203 .. code-block:: gas
 204
 205   movw r4, #constant
 206   bl __chkstk
 207   sub.w sp, sp, r4
 208
 209 However, this has the limitation of 32 MiB (±16MiB).  In order to accommodate
 210 larger binaries, LLVM supports the use of ``-mcode-model=large`` to allow a 4GiB
 211 range via a slight deviation.  It will generate an indirect jump as follows:
 212
 213 .. code-block:: gas
 214
 215   movw r4, #constant
 216   movw r12, :lower16:__chkstk
 217   movt r12, :upper16:__chkstk
 218   blx r12
 219   sub.w sp, sp, r4
 220
 221 Variable Length Arrays
 222 ^^^^^^^^^^^^^^^^^^^^^^
 223
 224 The reference implementation (Microsoft Visual Studio 2012) does not permit the
 225 emission of Variable Length Arrays (VLAs).
 226
 227 The Windows ARM Itanium ABI extends the base ABI by adding support for emitting
 228 a dynamic stack allocation.  When emitting a variable stack allocation, a call
 229 to ``__chkstk`` is emitted unconditionally to ensure that guard pages are setup
 230 properly.  The emission of this stack probe emission is handled similar to the
 231 standard stack probe emission.
 232
 233 The MSVC environment does not emit code for VLAs currently.
 234