1===============
2LLVM Extensions
3===============
4
5.. contents::
6   :local:
7
8.. toctree::
9   :hidden:
10
11Introduction
12============
13
14This document describes extensions to tools and formats LLVM seeks compatibility
15with.
16
17General Assembly Syntax
18===========================
19
20C99-style Hexadecimal Floating-point Constants
21----------------------------------------------
22
23LLVM's assemblers allow floating-point constants to be written in C99's
24hexadecimal format instead of decimal if desired.
25
26.. code-block:: gas
27
28  .section .data
29  .float 0x1c2.2ap3
30
31Machine-specific Assembly Syntax
32================================
33
34X86/COFF-Dependent
35------------------
36
37Relocations
38^^^^^^^^^^^
39
40The following additional relocation types are supported:
41
42**@IMGREL** (AT&T syntax only) generates an image-relative relocation that
43corresponds to the COFF relocation types ``IMAGE_REL_I386_DIR32NB`` (32-bit) or
44``IMAGE_REL_AMD64_ADDR32NB`` (64-bit).
45
46.. code-block:: text
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
58types ``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
61the 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 + 0
71    .secidx   _function_name
72    ...
73
74``.linkonce`` Directive
75^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
76
77Syntax:
78
79   ``.linkonce [ comdat type ]``
80
81Supported 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
114MC 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
132Note that in the combined form the COMDAT symbol is explicit. This
133extension exists to support multiple sections with the same name in
134different 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
149In addition to the types allowed with ``.linkonce``, ``.section`` also accepts
150``associative``. The meaning is that the section is linked  if a certain other
151COMDAT section is linked. This other section is indicated by the comdat symbol
152in this directive. It can be any symbol defined in the associated section, but
153is 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
160In the following example the symobl ``sym`` is the comdat symbol of ``.foo``
161and ``.bar`` is associated to ``.foo``.
162
163.. code-block:: gas
164
165	.section	.foo,"bw",discard, "sym"
166	.section	.bar,"rd",associative, "sym"
167
168MC supports these flags in the COFF ``.section`` directive:
169
170  - ``b``: BSS section (``IMAGE_SCN_CNT_INITIALIZED_DATA``)
171  - ``d``: Data section (``IMAGE_SCN_CNT_UNINITIALIZED_DATA``)
172  - ``n``: Section is not loaded (``IMAGE_SCN_LNK_REMOVE``)
173  - ``r``: Read-only
174  - ``s``: Shared section
175  - ``w``: Writable
176  - ``x``: Executable section
177  - ``y``: Not readable
178  - ``D``: Discardable (``IMAGE_SCN_MEM_DISCARDABLE``)
179
180These flags are all compatible with gas, with the exception of the ``D`` flag,
181which gnu as does not support. For gas compatibility, sections with a name
182starting with ".debug" are implicitly discardable.
183
184
185ELF-Dependent
186-------------
187
188``.section`` Directive
189^^^^^^^^^^^^^^^^^^^^^^
190
191In order to support creating multiple sections with the same name and comdat,
192it is possible to add an unique number at the end of the ``.seciton`` directive.
193For example, the following code creates two sections named ``.text``.
194
195.. code-block:: gas
196
197	.section	.text,"ax",@progbits,unique,1
198        nop
199
200	.section	.text,"ax",@progbits,unique,2
201        nop
202
203
204The unique number is not present in the resulting object at all. It is just used
205in the assembler to differentiate the sections.
206
207Target Specific Behaviour
208=========================
209
210Windows on ARM
211--------------
212
213Stack Probe Emission
214^^^^^^^^^^^^^^^^^^^^
215
216The reference implementation (Microsoft Visual Studio 2012) emits stack probes
217in the following fashion:
218
219.. code-block:: gas
220
221  movw r4, #constant
222  bl __chkstk
223  sub.w sp, sp, r4
224
225However, this has the limitation of 32 MiB (±16MiB).  In order to accommodate
226larger binaries, LLVM supports the use of ``-mcode-model=large`` to allow a 4GiB
227range via a slight deviation.  It will generate an indirect jump as follows:
228
229.. code-block:: gas
230
231  movw r4, #constant
232  movw r12, :lower16:__chkstk
233  movt r12, :upper16:__chkstk
234  blx r12
235  sub.w sp, sp, r4
236
237Variable Length Arrays
238^^^^^^^^^^^^^^^^^^^^^^
239
240The reference implementation (Microsoft Visual Studio 2012) does not permit the
241emission of Variable Length Arrays (VLAs).
242
243The Windows ARM Itanium ABI extends the base ABI by adding support for emitting
244a dynamic stack allocation.  When emitting a variable stack allocation, a call
245to ``__chkstk`` is emitted unconditionally to ensure that guard pages are setup
246properly.  The emission of this stack probe emission is handled similar to the
247standard stack probe emission.
248
249The MSVC environment does not emit code for VLAs currently.
250
251