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:: 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
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
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
168
169ELF-Dependent
170-------------
171
172``.section`` Directive
173^^^^^^^^^^^^^^^^^^^^^^
174
175In order to support creating multiple sections with the same name and comdat,
176it is possible to add an unique number at the end of the ``.seciton`` directive.
177For 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
188The unique number is not present in the resulting object at all. It is just used
189in the assembler to differentiate the sections.
190
191Target Specific Behaviour
192=========================
193
194Windows on ARM
195--------------
196
197Stack Probe Emission
198^^^^^^^^^^^^^^^^^^^^
199
200The reference implementation (Microsoft Visual Studio 2012) emits stack probes
201in the following fashion:
202
203.. code-block:: gas
204
205  movw r4, #constant
206  bl __chkstk
207  sub.w sp, sp, r4
208
209However, this has the limitation of 32 MiB (±16MiB).  In order to accommodate
210larger binaries, LLVM supports the use of ``-mcode-model=large`` to allow a 4GiB
211range 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
221Variable Length Arrays
222^^^^^^^^^^^^^^^^^^^^^^
223
224The reference implementation (Microsoft Visual Studio 2012) does not permit the
225emission of Variable Length Arrays (VLAs).
226
227The Windows ARM Itanium ABI extends the base ABI by adding support for emitting
228a dynamic stack allocation.  When emitting a variable stack allocation, a call
229to ``__chkstk`` is emitted unconditionally to ensure that guard pages are setup
230properly.  The emission of this stack probe emission is handled similar to the
231standard stack probe emission.
232
233The MSVC environment does not emit code for VLAs currently.
234
235