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 235
