Explicitly report runtime stack realignment in StackMap section
[oota-llvm.git] / 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 ]``
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 Target Specific Behaviour
169 =========================
170
171 Windows on ARM
172 --------------
173
174 Stack Probe Emission
175 ^^^^^^^^^^^^^^^^^^^^
176
177 The reference implementation (Microsoft Visual Studio 2012) emits stack probes
178 in the following fashion:
179
180 .. code-block:: gas
181
182   movw r4, #constant
183   bl __chkstk
184   sub.w sp, sp, r4
185
186 However, this has the limitation of 32 MiB (±16MiB).  In order to accommodate
187 larger binaries, LLVM supports the use of ``-mcode-model=large`` to allow a 4GiB
188 range 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
198 Variable Length Arrays
199 ^^^^^^^^^^^^^^^^^^^^^^
200
201 The reference implementation (Microsoft Visual Studio 2012) does not permit the
202 emission of Variable Length Arrays (VLAs).
203
204 The Windows ARM Itanium ABI extends the base ABI by adding support for emitting
205 a dynamic stack allocation.  When emitting a variable stack allocation, a call
206 to ``__chkstk`` is emitted unconditionally to ensure that guard pages are setup
207 properly.  The emission of this stack probe emission is handled similar to the
208 standard stack probe emission.
209
210 The MSVC environment does not emit code for VLAs currently.
211