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 [ section identifier ] ]``
  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 ``associative``
  99    Links the section if a certain other COMDAT section is linked. This other
 100    section is indicated by its section identifier following the comdat type.
 101    The following restrictions apply to the associated section:
 102
 103    1. It must be the name of a section already defined.
 104    2. It must differ from the current section.
 105    3. It must be a COMDAT section.
 106    4. It cannot be another associative COMDAT section.
 107
 108 ``largest``
 109    Links the largest section from among the duplicates.
 110
 111 ``newest``
 112    Links the newest section from among the duplicates.
 113
 114
 115 .. code-block:: gas
 116
 117   .section .text$foo
 118   .linkonce
 119     ...
 120
 121   .section .xdata$foo
 122   .linkonce associative .text$foo
 123     ...
 124
 125 ``.section`` Directive
 126 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 127
 128 MC supports passing the information in ``.linkonce`` at the end of
 129 ``.section``. For example,  these two codes are equivalent
 130
 131 .. code-block:: gas
 132
 133   .section secName, "dr", discard, "Symbol1"
 134   .globl Symbol1
 135   Symbol1:
 136   .long 1
 137
 138 .. code-block:: gas
 139
 140   .section secName, "dr"
 141   .linkonce discard
 142   .globl Symbol1
 143   Symbol1:
 144   .long 1
 145
 146 Note that in the combined form the COMDAT symbol is explicit. This
 147 extension exists to support multiple sections with the same name in
 148 different COMDATs:
 149
 150
 151 .. code-block:: gas
 152
 153   .section secName, "dr", discard, "Symbol1"
 154   .globl Symbol1
 155   Symbol1:
 156   .long 1
 157
 158   .section secName, "dr", discard, "Symbol2"
 159   .globl Symbol2
 160   Symbol2:
 161   .long 1
 162
 163 Target Specific Behaviour
 164 =========================
 165
 166 Windows on ARM
 167 --------------
 168
 169 Stack Probe Emission
 170 ^^^^^^^^^^^^^^^^^^^^
 171
 172 The reference implementation (Microsoft Visual Studio 2012) emits stack probes
 173 in the following fashion:
 174
 175 .. code-block:: gas
 176
 177   movw r4, #constant
 178   bl __chkstk
 179   sub.w sp, sp, r4
 180
 181 However, this has the limitation of 32 MiB (±16MiB).  In order to accommodate
 182 larger binaries, LLVM supports the use of ``-mcode-model=large`` to allow a 4GiB
 183 range via a slight deviation.  It will generate an indirect jump as follows:
 184
 185 .. code-block:: gas
 186
 187   movw r4, #constant
 188   movw r12, :lower16:__chkstk
 189   movt r12, :upper16:__chkstk
 190   blx r12
 191   sub.w sp, sp, r4
 192