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
168Target Specific Behaviour
169=========================
170
171Windows on ARM
172--------------
173
174Stack Probe Emission
175^^^^^^^^^^^^^^^^^^^^
176
177The reference implementation (Microsoft Visual Studio 2012) emits stack probes
178in the following fashion:
179
180.. code-block:: gas
181
182  movw r4, #constant
183  bl __chkstk
184  sub.w sp, sp, r4
185
186However, this has the limitation of 32 MiB (±16MiB).  In order to accommodate
187larger binaries, LLVM supports the use of ``-mcode-model=large`` to allow a 4GiB
188range via a slight deviation.  It will generate an indirect jump as follows:
189
190.. code-block:: gas
191
192  movw r4, #constant
193  movw r12, :lower16:__chkstk
194  movt r12, :upper16:__chkstk
195  blx r12
196  sub.w sp, sp, r4
197
198Variable Length Arrays
199^^^^^^^^^^^^^^^^^^^^^^
200
201The reference implementation (Microsoft Visual Studio 2012) does not permit the
202emission of Variable Length Arrays (VLAs).
203
204The Windows ARM Itanium ABI extends the base ABI by adding support for emitting
205a dynamic stack allocation.  When emitting a variable stack allocation, a call
206to ``__chkstk`` is emitted unconditionally to ensure that guard pages are setup
207properly.  The emission of this stack probe emission is handled similar to the
208standard stack probe emission.
209
210The MSVC environment does not emit code for VLAs currently.
211
212