/
LangRef.rst
24125 lines (17534 loc) · 846 KB
/
LangRef.rst
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
==============================
LLVM Language Reference Manual
==============================
.. contents::
:local:
:depth: 4
Abstract
========
This document is a reference manual for the LLVM assembly language. LLVM
is a Static Single Assignment (SSA) based representation that provides
type safety, low-level operations, flexibility, and the capability of
representing 'all' high-level languages cleanly. It is the common code
representation used throughout all phases of the LLVM compilation
strategy.
Introduction
============
The LLVM code representation is designed to be used in three different
forms: as an in-memory compiler IR, as an on-disk bitcode representation
(suitable for fast loading by a Just-In-Time compiler), and as a human
readable assembly language representation. This allows LLVM to provide a
powerful intermediate representation for efficient compiler
transformations and analysis, while providing a natural means to debug
and visualize the transformations. The three different forms of LLVM are
all equivalent. This document describes the human readable
representation and notation.
The LLVM representation aims to be light-weight and low-level while
being expressive, typed, and extensible at the same time. It aims to be
a "universal IR" of sorts, by being at a low enough level that
high-level ideas may be cleanly mapped to it (similar to how
microprocessors are "universal IR's", allowing many source languages to
be mapped to them). By providing type information, LLVM can be used as
the target of optimizations: for example, through pointer analysis, it
can be proven that a C automatic variable is never accessed outside of
the current function, allowing it to be promoted to a simple SSA value
instead of a memory location.
.. _wellformed:
Well-Formedness
---------------
It is important to note that this document describes 'well formed' LLVM
assembly language. There is a difference between what the parser accepts
and what is considered 'well formed'. For example, the following
instruction is syntactically okay, but not well formed:
.. code-block:: llvm
%x = add i32 1, %x
because the definition of ``%x`` does not dominate all of its uses. The
LLVM infrastructure provides a verification pass that may be used to
verify that an LLVM module is well formed. This pass is automatically
run by the parser after parsing input assembly and by the optimizer
before it outputs bitcode. The violations pointed out by the verifier
pass indicate bugs in transformation passes or input to the parser.
.. _identifiers:
Identifiers
===========
LLVM identifiers come in two basic types: global and local. Global
identifiers (functions, global variables) begin with the ``'@'``
character. Local identifiers (register names, types) begin with the
``'%'`` character. Additionally, there are three different formats for
identifiers, for different purposes:
#. Named values are represented as a string of characters with their
prefix. For example, ``%foo``, ``@DivisionByZero``,
``%a.really.long.identifier``. The actual regular expression used is
'``[%@][-a-zA-Z$._][-a-zA-Z$._0-9]*``'. Identifiers that require other
characters in their names can be surrounded with quotes. Special
characters may be escaped using ``"\xx"`` where ``xx`` is the ASCII
code for the character in hexadecimal. In this way, any character can
be used in a name value, even quotes themselves. The ``"\01"`` prefix
can be used on global values to suppress mangling.
#. Unnamed values are represented as an unsigned numeric value with
their prefix. For example, ``%12``, ``@2``, ``%44``.
#. Constants, which are described in the section Constants_ below.
LLVM requires that values start with a prefix for two reasons: Compilers
don't need to worry about name clashes with reserved words, and the set
of reserved words may be expanded in the future without penalty.
Additionally, unnamed identifiers allow a compiler to quickly come up
with a temporary variable without having to avoid symbol table
conflicts.
Reserved words in LLVM are very similar to reserved words in other
languages. There are keywords for different opcodes ('``add``',
'``bitcast``', '``ret``', etc...), for primitive type names ('``void``',
'``i32``', etc...), and others. These reserved words cannot conflict
with variable names, because none of them start with a prefix character
(``'%'`` or ``'@'``).
Here is an example of LLVM code to multiply the integer variable
'``%X``' by 8:
The easy way:
.. code-block:: llvm
%result = mul i32 %X, 8
After strength reduction:
.. code-block:: llvm
%result = shl i32 %X, 3
And the hard way:
.. code-block:: llvm
%0 = add i32 %X, %X ; yields i32:%0
%1 = add i32 %0, %0 ; yields i32:%1
%result = add i32 %1, %1
This last way of multiplying ``%X`` by 8 illustrates several important
lexical features of LLVM:
#. Comments are delimited with a '``;``' and go until the end of line.
#. Unnamed temporaries are created when the result of a computation is
not assigned to a named value.
#. Unnamed temporaries are numbered sequentially (using a per-function
incrementing counter, starting with 0). Note that basic blocks and unnamed
function parameters are included in this numbering. For example, if the
entry basic block is not given a label name and all function parameters are
named, then it will get number 0.
It also shows a convention that we follow in this document. When
demonstrating instructions, we will follow an instruction with a comment
that defines the type and name of value produced.
High Level Structure
====================
Module Structure
----------------
LLVM programs are composed of ``Module``'s, each of which is a
translation unit of the input programs. Each module consists of
functions, global variables, and symbol table entries. Modules may be
combined together with the LLVM linker, which merges function (and
global variable) definitions, resolves forward declarations, and merges
symbol table entries. Here is an example of the "hello world" module:
.. code-block:: llvm
; Declare the string constant as a global constant.
@.str = private unnamed_addr constant [13 x i8] c"hello world\0A\00"
; External declaration of the puts function
declare i32 @puts(i8* nocapture) nounwind
; Definition of main function
define i32 @main() { ; i32()*
; Convert [13 x i8]* to i8*...
%cast210 = getelementptr [13 x i8], [13 x i8]* @.str, i64 0, i64 0
; Call puts function to write out the string to stdout.
call i32 @puts(i8* %cast210)
ret i32 0
}
; Named metadata
!0 = !{i32 42, null, !"string"}
!foo = !{!0}
This example is made up of a :ref:`global variable <globalvars>` named
"``.str``", an external declaration of the "``puts``" function, a
:ref:`function definition <functionstructure>` for "``main``" and
:ref:`named metadata <namedmetadatastructure>` "``foo``".
In general, a module is made up of a list of global values (where both
functions and global variables are global values). Global values are
represented by a pointer to a memory location (in this case, a pointer
to an array of char, and a pointer to a function), and have one of the
following :ref:`linkage types <linkage>`.
.. _linkage:
Linkage Types
-------------
All Global Variables and Functions have one of the following types of
linkage:
``private``
Global values with "``private``" linkage are only directly
accessible by objects in the current module. In particular, linking
code into a module with a private global value may cause the
private to be renamed as necessary to avoid collisions. Because the
symbol is private to the module, all references can be updated. This
doesn't show up in any symbol table in the object file.
``internal``
Similar to private, but the value shows as a local symbol
(``STB_LOCAL`` in the case of ELF) in the object file. This
corresponds to the notion of the '``static``' keyword in C.
``available_externally``
Globals with "``available_externally``" linkage are never emitted into
the object file corresponding to the LLVM module. From the linker's
perspective, an ``available_externally`` global is equivalent to
an external declaration. They exist to allow inlining and other
optimizations to take place given knowledge of the definition of the
global, which is known to be somewhere outside the module. Globals
with ``available_externally`` linkage are allowed to be discarded at
will, and allow inlining and other optimizations. This linkage type is
only allowed on definitions, not declarations.
``linkonce``
Globals with "``linkonce``" linkage are merged with other globals of
the same name when linkage occurs. This can be used to implement
some forms of inline functions, templates, or other code which must
be generated in each translation unit that uses it, but where the
body may be overridden with a more definitive definition later.
Unreferenced ``linkonce`` globals are allowed to be discarded. Note
that ``linkonce`` linkage does not actually allow the optimizer to
inline the body of this function into callers because it doesn't
know if this definition of the function is the definitive definition
within the program or whether it will be overridden by a stronger
definition. To enable inlining and other optimizations, use
"``linkonce_odr``" linkage.
``weak``
"``weak``" linkage has the same merging semantics as ``linkonce``
linkage, except that unreferenced globals with ``weak`` linkage may
not be discarded. This is used for globals that are declared "weak"
in C source code.
``common``
"``common``" linkage is most similar to "``weak``" linkage, but they
are used for tentative definitions in C, such as "``int X;``" at
global scope. Symbols with "``common``" linkage are merged in the
same way as ``weak symbols``, and they may not be deleted if
unreferenced. ``common`` symbols may not have an explicit section,
must have a zero initializer, and may not be marked
':ref:`constant <globalvars>`'. Functions and aliases may not have
common linkage.
.. _linkage_appending:
``appending``
"``appending``" linkage may only be applied to global variables of
pointer to array type. When two global variables with appending
linkage are linked together, the two global arrays are appended
together. This is the LLVM, typesafe, equivalent of having the
system linker append together "sections" with identical names when
.o files are linked.
Unfortunately this doesn't correspond to any feature in .o files, so it
can only be used for variables like ``llvm.global_ctors`` which llvm
interprets specially.
``extern_weak``
The semantics of this linkage follow the ELF object file model: the
symbol is weak until linked, if not linked, the symbol becomes null
instead of being an undefined reference.
``linkonce_odr``, ``weak_odr``
Some languages allow differing globals to be merged, such as two
functions with different semantics. Other languages, such as
``C++``, ensure that only equivalent globals are ever merged (the
"one definition rule" --- "ODR"). Such languages can use the
``linkonce_odr`` and ``weak_odr`` linkage types to indicate that the
global will only be merged with equivalent globals. These linkage
types are otherwise the same as their non-``odr`` versions.
``external``
If none of the above identifiers are used, the global is externally
visible, meaning that it participates in linkage and can be used to
resolve external symbol references.
It is illegal for a global variable or function *declaration* to have any
linkage type other than ``external`` or ``extern_weak``.
.. _callingconv:
Calling Conventions
-------------------
LLVM :ref:`functions <functionstructure>`, :ref:`calls <i_call>` and
:ref:`invokes <i_invoke>` can all have an optional calling convention
specified for the call. The calling convention of any pair of dynamic
caller/callee must match, or the behavior of the program is undefined.
The following calling conventions are supported by LLVM, and more may be
added in the future:
"``ccc``" - The C calling convention
This calling convention (the default if no other calling convention
is specified) matches the target C calling conventions. This calling
convention supports varargs function calls and tolerates some
mismatch in the declared prototype and implemented declaration of
the function (as does normal C).
"``fastcc``" - The fast calling convention
This calling convention attempts to make calls as fast as possible
(e.g. by passing things in registers). This calling convention
allows the target to use whatever tricks it wants to produce fast
code for the target, without having to conform to an externally
specified ABI (Application Binary Interface). `Tail calls can only
be optimized when this, the tailcc, the GHC or the HiPE convention is
used. <CodeGenerator.html#tail-call-optimization>`_ This calling
convention does not support varargs and requires the prototype of all
callees to exactly match the prototype of the function definition.
"``coldcc``" - The cold calling convention
This calling convention attempts to make code in the caller as
efficient as possible under the assumption that the call is not
commonly executed. As such, these calls often preserve all registers
so that the call does not break any live ranges in the caller side.
This calling convention does not support varargs and requires the
prototype of all callees to exactly match the prototype of the
function definition. Furthermore the inliner doesn't consider such function
calls for inlining.
"``cc 10``" - GHC convention
This calling convention has been implemented specifically for use by
the `Glasgow Haskell Compiler (GHC) <http://www.haskell.org/ghc>`_.
It passes everything in registers, going to extremes to achieve this
by disabling callee save registers. This calling convention should
not be used lightly but only for specific situations such as an
alternative to the *register pinning* performance technique often
used when implementing functional programming languages. At the
moment only X86 supports this convention and it has the following
limitations:
- On *X86-32* only supports up to 4 bit type parameters. No
floating-point types are supported.
- On *X86-64* only supports up to 10 bit type parameters and 6
floating-point parameters.
This calling convention supports `tail call
optimization <CodeGenerator.html#tail-call-optimization>`_ but requires
both the caller and callee are using it.
"``cc 11``" - The HiPE calling convention
This calling convention has been implemented specifically for use by
the `High-Performance Erlang
(HiPE) <http://www.it.uu.se/research/group/hipe/>`_ compiler, *the*
native code compiler of the `Ericsson's Open Source Erlang/OTP
system <http://www.erlang.org/download.shtml>`_. It uses more
registers for argument passing than the ordinary C calling
convention and defines no callee-saved registers. The calling
convention properly supports `tail call
optimization <CodeGenerator.html#tail-call-optimization>`_ but requires
that both the caller and the callee use it. It uses a *register pinning*
mechanism, similar to GHC's convention, for keeping frequently
accessed runtime components pinned to specific hardware registers.
At the moment only X86 supports this convention (both 32 and 64
bit).
"``webkit_jscc``" - WebKit's JavaScript calling convention
This calling convention has been implemented for `WebKit FTL JIT
<https://trac.webkit.org/wiki/FTLJIT>`_. It passes arguments on the
stack right to left (as cdecl does), and returns a value in the
platform's customary return register.
"``anyregcc``" - Dynamic calling convention for code patching
This is a special convention that supports patching an arbitrary code
sequence in place of a call site. This convention forces the call
arguments into registers but allows them to be dynamically
allocated. This can currently only be used with calls to
llvm.experimental.patchpoint because only this intrinsic records
the location of its arguments in a side table. See :doc:`StackMaps`.
"``preserve_mostcc``" - The `PreserveMost` calling convention
This calling convention attempts to make the code in the caller as
unintrusive as possible. This convention behaves identically to the `C`
calling convention on how arguments and return values are passed, but it
uses a different set of caller/callee-saved registers. This alleviates the
burden of saving and recovering a large register set before and after the
call in the caller. If the arguments are passed in callee-saved registers,
then they will be preserved by the callee across the call. This doesn't
apply for values returned in callee-saved registers.
- On X86-64 the callee preserves all general purpose registers, except for
R11. R11 can be used as a scratch register. Floating-point registers
(XMMs/YMMs) are not preserved and need to be saved by the caller.
The idea behind this convention is to support calls to runtime functions
that have a hot path and a cold path. The hot path is usually a small piece
of code that doesn't use many registers. The cold path might need to call out to
another function and therefore only needs to preserve the caller-saved
registers, which haven't already been saved by the caller. The
`PreserveMost` calling convention is very similar to the `cold` calling
convention in terms of caller/callee-saved registers, but they are used for
different types of function calls. `coldcc` is for function calls that are
rarely executed, whereas `preserve_mostcc` function calls are intended to be
on the hot path and definitely executed a lot. Furthermore `preserve_mostcc`
doesn't prevent the inliner from inlining the function call.
This calling convention will be used by a future version of the ObjectiveC
runtime and should therefore still be considered experimental at this time.
Although this convention was created to optimize certain runtime calls to
the ObjectiveC runtime, it is not limited to this runtime and might be used
by other runtimes in the future too. The current implementation only
supports X86-64, but the intention is to support more architectures in the
future.
"``preserve_allcc``" - The `PreserveAll` calling convention
This calling convention attempts to make the code in the caller even less
intrusive than the `PreserveMost` calling convention. This calling
convention also behaves identical to the `C` calling convention on how
arguments and return values are passed, but it uses a different set of
caller/callee-saved registers. This removes the burden of saving and
recovering a large register set before and after the call in the caller. If
the arguments are passed in callee-saved registers, then they will be
preserved by the callee across the call. This doesn't apply for values
returned in callee-saved registers.
- On X86-64 the callee preserves all general purpose registers, except for
R11. R11 can be used as a scratch register. Furthermore it also preserves
all floating-point registers (XMMs/YMMs).
The idea behind this convention is to support calls to runtime functions
that don't need to call out to any other functions.
This calling convention, like the `PreserveMost` calling convention, will be
used by a future version of the ObjectiveC runtime and should be considered
experimental at this time.
"``cxx_fast_tlscc``" - The `CXX_FAST_TLS` calling convention for access functions
Clang generates an access function to access C++-style TLS. The access
function generally has an entry block, an exit block and an initialization
block that is run at the first time. The entry and exit blocks can access
a few TLS IR variables, each access will be lowered to a platform-specific
sequence.
This calling convention aims to minimize overhead in the caller by
preserving as many registers as possible (all the registers that are
preserved on the fast path, composed of the entry and exit blocks).
This calling convention behaves identical to the `C` calling convention on
how arguments and return values are passed, but it uses a different set of
caller/callee-saved registers.
Given that each platform has its own lowering sequence, hence its own set
of preserved registers, we can't use the existing `PreserveMost`.
- On X86-64 the callee preserves all general purpose registers, except for
RDI and RAX.
"``tailcc``" - Tail callable calling convention
This calling convention ensures that calls in tail position will always be
tail call optimized. This calling convention is equivalent to fastcc,
except for an additional guarantee that tail calls will be produced
whenever possible. `Tail calls can only be optimized when this, the fastcc,
the GHC or the HiPE convention is used. <CodeGenerator.html#tail-call-optimization>`_
This calling convention does not support varargs and requires the prototype of
all callees to exactly match the prototype of the function definition.
"``swiftcc``" - This calling convention is used for Swift language.
- On X86-64 RCX and R8 are available for additional integer returns, and
XMM2 and XMM3 are available for additional FP/vector returns.
- On iOS platforms, we use AAPCS-VFP calling convention.
"``swifttailcc``"
This calling convention is like ``swiftcc`` in most respects, but also the
callee pops the argument area of the stack so that mandatory tail calls are
possible as in ``tailcc``.
"``cfguard_checkcc``" - Windows Control Flow Guard (Check mechanism)
This calling convention is used for the Control Flow Guard check function,
calls to which can be inserted before indirect calls to check that the call
target is a valid function address. The check function has no return value,
but it will trigger an OS-level error if the address is not a valid target.
The set of registers preserved by the check function, and the register
containing the target address are architecture-specific.
- On X86 the target address is passed in ECX.
- On ARM the target address is passed in R0.
- On AArch64 the target address is passed in X15.
"``cc <n>``" - Numbered convention
Any calling convention may be specified by number, allowing
target-specific calling conventions to be used. Target specific
calling conventions start at 64.
More calling conventions can be added/defined on an as-needed basis, to
support Pascal conventions or any other well-known target-independent
convention.
.. _visibilitystyles:
Visibility Styles
-----------------
All Global Variables and Functions have one of the following visibility
styles:
"``default``" - Default style
On targets that use the ELF object file format, default visibility
means that the declaration is visible to other modules and, in
shared libraries, means that the declared entity may be overridden.
On Darwin, default visibility means that the declaration is visible
to other modules. Default visibility corresponds to "external
linkage" in the language.
"``hidden``" - Hidden style
Two declarations of an object with hidden visibility refer to the
same object if they are in the same shared object. Usually, hidden
visibility indicates that the symbol will not be placed into the
dynamic symbol table, so no other module (executable or shared
library) can reference it directly.
"``protected``" - Protected style
On ELF, protected visibility indicates that the symbol will be
placed in the dynamic symbol table, but that references within the
defining module will bind to the local symbol. That is, the symbol
cannot be overridden by another module.
A symbol with ``internal`` or ``private`` linkage must have ``default``
visibility.
.. _dllstorageclass:
DLL Storage Classes
-------------------
All Global Variables, Functions and Aliases can have one of the following
DLL storage class:
``dllimport``
"``dllimport``" causes the compiler to reference a function or variable via
a global pointer to a pointer that is set up by the DLL exporting the
symbol. On Microsoft Windows targets, the pointer name is formed by
combining ``__imp_`` and the function or variable name.
``dllexport``
"``dllexport``" causes the compiler to provide a global pointer to a pointer
in a DLL, so that it can be referenced with the ``dllimport`` attribute. On
Microsoft Windows targets, the pointer name is formed by combining
``__imp_`` and the function or variable name. Since this storage class
exists for defining a dll interface, the compiler, assembler and linker know
it is externally referenced and must refrain from deleting the symbol.
.. _tls_model:
Thread Local Storage Models
---------------------------
A variable may be defined as ``thread_local``, which means that it will
not be shared by threads (each thread will have a separated copy of the
variable). Not all targets support thread-local variables. Optionally, a
TLS model may be specified:
``localdynamic``
For variables that are only used within the current shared library.
``initialexec``
For variables in modules that will not be loaded dynamically.
``localexec``
For variables defined in the executable and only used within it.
If no explicit model is given, the "general dynamic" model is used.
The models correspond to the ELF TLS models; see `ELF Handling For
Thread-Local Storage <http://people.redhat.com/drepper/tls.pdf>`_ for
more information on under which circumstances the different models may
be used. The target may choose a different TLS model if the specified
model is not supported, or if a better choice of model can be made.
A model can also be specified in an alias, but then it only governs how
the alias is accessed. It will not have any effect in the aliasee.
For platforms without linker support of ELF TLS model, the -femulated-tls
flag can be used to generate GCC compatible emulated TLS code.
.. _runtime_preemption_model:
Runtime Preemption Specifiers
-----------------------------
Global variables, functions and aliases may have an optional runtime preemption
specifier. If a preemption specifier isn't given explicitly, then a
symbol is assumed to be ``dso_preemptable``.
``dso_preemptable``
Indicates that the function or variable may be replaced by a symbol from
outside the linkage unit at runtime.
``dso_local``
The compiler may assume that a function or variable marked as ``dso_local``
will resolve to a symbol within the same linkage unit. Direct access will
be generated even if the definition is not within this compilation unit.
.. _namedtypes:
Structure Types
---------------
LLVM IR allows you to specify both "identified" and "literal" :ref:`structure
types <t_struct>`. Literal types are uniqued structurally, but identified types
are never uniqued. An :ref:`opaque structural type <t_opaque>` can also be used
to forward declare a type that is not yet available.
An example of an identified structure specification is:
.. code-block:: llvm
%mytype = type { %mytype*, i32 }
Prior to the LLVM 3.0 release, identified types were structurally uniqued. Only
literal types are uniqued in recent versions of LLVM.
.. _nointptrtype:
Non-Integral Pointer Type
-------------------------
Note: non-integral pointer types are a work in progress, and they should be
considered experimental at this time.
LLVM IR optionally allows the frontend to denote pointers in certain address
spaces as "non-integral" via the :ref:`datalayout string<langref_datalayout>`.
Non-integral pointer types represent pointers that have an *unspecified* bitwise
representation; that is, the integral representation may be target dependent or
unstable (not backed by a fixed integer).
``inttoptr`` and ``ptrtoint`` instructions have the same semantics as for
integral (i.e. normal) pointers in that they convert integers to and from
corresponding pointer types, but there are additional implications to be
aware of. Because the bit-representation of a non-integral pointer may
not be stable, two identical casts of the same operand may or may not
return the same value. Said differently, the conversion to or from the
non-integral type depends on environmental state in an implementation
defined manner.
If the frontend wishes to observe a *particular* value following a cast, the
generated IR must fence with the underlying environment in an implementation
defined manner. (In practice, this tends to require ``noinline`` routines for
such operations.)
From the perspective of the optimizer, ``inttoptr`` and ``ptrtoint`` for
non-integral types are analogous to ones on integral types with one
key exception: the optimizer may not, in general, insert new dynamic
occurrences of such casts. If a new cast is inserted, the optimizer would
need to either ensure that a) all possible values are valid, or b)
appropriate fencing is inserted. Since the appropriate fencing is
implementation defined, the optimizer can't do the latter. The former is
challenging as many commonly expected properties, such as
``ptrtoint(v)-ptrtoint(v) == 0``, don't hold for non-integral types.
.. _globalvars:
Global Variables
----------------
Global variables define regions of memory allocated at compilation time
instead of run-time.
Global variable definitions must be initialized.
Global variables in other translation units can also be declared, in which
case they don't have an initializer.
Global variables can optionally specify a :ref:`linkage type <linkage>`.
Either global variable definitions or declarations may have an explicit section
to be placed in and may have an optional explicit alignment specified. If there
is a mismatch between the explicit or inferred section information for the
variable declaration and its definition the resulting behavior is undefined.
A variable may be defined as a global ``constant``, which indicates that
the contents of the variable will **never** be modified (enabling better
optimization, allowing the global data to be placed in the read-only
section of an executable, etc). Note that variables that need runtime
initialization cannot be marked ``constant`` as there is a store to the
variable.
LLVM explicitly allows *declarations* of global variables to be marked
constant, even if the final definition of the global is not. This
capability can be used to enable slightly better optimization of the
program, but requires the language definition to guarantee that
optimizations based on the 'constantness' are valid for the translation
units that do not include the definition.
As SSA values, global variables define pointer values that are in scope
(i.e. they dominate) all basic blocks in the program. Global variables
always define a pointer to their "content" type because they describe a
region of memory, and all memory objects in LLVM are accessed through
pointers.
Global variables can be marked with ``unnamed_addr`` which indicates
that the address is not significant, only the content. Constants marked
like this can be merged with other constants if they have the same
initializer. Note that a constant with significant address *can* be
merged with a ``unnamed_addr`` constant, the result being a constant
whose address is significant.
If the ``local_unnamed_addr`` attribute is given, the address is known to
not be significant within the module.
A global variable may be declared to reside in a target-specific
numbered address space. For targets that support them, address spaces
may affect how optimizations are performed and/or what target
instructions are used to access the variable. The default address space
is zero. The address space qualifier must precede any other attributes.
LLVM allows an explicit section to be specified for globals. If the
target supports it, it will emit globals to the section specified.
Additionally, the global can placed in a comdat if the target has the necessary
support.
External declarations may have an explicit section specified. Section
information is retained in LLVM IR for targets that make use of this
information. Attaching section information to an external declaration is an
assertion that its definition is located in the specified section. If the
definition is located in a different section, the behavior is undefined.
By default, global initializers are optimized by assuming that global
variables defined within the module are not modified from their
initial values before the start of the global initializer. This is
true even for variables potentially accessible from outside the
module, including those with external linkage or appearing in
``@llvm.used`` or dllexported variables. This assumption may be suppressed
by marking the variable with ``externally_initialized``.
An explicit alignment may be specified for a global, which must be a
power of 2. If not present, or if the alignment is set to zero, the
alignment of the global is set by the target to whatever it feels
convenient. If an explicit alignment is specified, the global is forced
to have exactly that alignment. Targets and optimizers are not allowed
to over-align the global if the global has an assigned section. In this
case, the extra alignment could be observable: for example, code could
assume that the globals are densely packed in their section and try to
iterate over them as an array, alignment padding would break this
iteration. The maximum alignment is ``1 << 32``.
For global variables declarations, as well as definitions that may be
replaced at link time (``linkonce``, ``weak``, ``extern_weak`` and ``common``
linkage types), LLVM makes no assumptions about the allocation size of the
variables, except that they may not overlap. The alignment of a global variable
declaration or replaceable definition must not be greater than the alignment of
the definition it resolves to.
Globals can also have a :ref:`DLL storage class <dllstorageclass>`,
an optional :ref:`runtime preemption specifier <runtime_preemption_model>`,
an optional :ref:`global attributes <glattrs>` and
an optional list of attached :ref:`metadata <metadata>`.
Variables and aliases can have a
:ref:`Thread Local Storage Model <tls_model>`.
:ref:`Scalable vectors <t_vector>` cannot be global variables or members of
arrays because their size is unknown at compile time. They are allowed in
structs to facilitate intrinsics returning multiple values. Structs containing
scalable vectors cannot be used in loads, stores, allocas, or GEPs.
Syntax::
@<GlobalVarName> = [Linkage] [PreemptionSpecifier] [Visibility]
[DLLStorageClass] [ThreadLocal]
[(unnamed_addr|local_unnamed_addr)] [AddrSpace]
[ExternallyInitialized]
<global | constant> <Type> [<InitializerConstant>]
[, section "name"] [, partition "name"]
[, comdat [($name)]] [, align <Alignment>]
(, !name !N)*
For example, the following defines a global in a numbered address space
with an initializer, section, and alignment:
.. code-block:: llvm
@G = addrspace(5) constant float 1.0, section "foo", align 4
The following example just declares a global variable
.. code-block:: llvm
@G = external global i32
The following example defines a thread-local global with the
``initialexec`` TLS model:
.. code-block:: llvm
@G = thread_local(initialexec) global i32 0, align 4
.. _functionstructure:
Functions
---------
LLVM function definitions consist of the "``define``" keyword, an
optional :ref:`linkage type <linkage>`, an optional :ref:`runtime preemption
specifier <runtime_preemption_model>`, an optional :ref:`visibility
style <visibility>`, an optional :ref:`DLL storage class <dllstorageclass>`,
an optional :ref:`calling convention <callingconv>`,
an optional ``unnamed_addr`` attribute, a return type, an optional
:ref:`parameter attribute <paramattrs>` for the return type, a function
name, a (possibly empty) argument list (each with optional :ref:`parameter
attributes <paramattrs>`), optional :ref:`function attributes <fnattrs>`,
an optional address space, an optional section, an optional alignment,
an optional :ref:`comdat <langref_comdats>`,
an optional :ref:`garbage collector name <gc>`, an optional :ref:`prefix <prefixdata>`,
an optional :ref:`prologue <prologuedata>`,
an optional :ref:`personality <personalityfn>`,
an optional list of attached :ref:`metadata <metadata>`,
an opening curly brace, a list of basic blocks, and a closing curly brace.
LLVM function declarations consist of the "``declare``" keyword, an
optional :ref:`linkage type <linkage>`, an optional :ref:`visibility style
<visibility>`, an optional :ref:`DLL storage class <dllstorageclass>`, an
optional :ref:`calling convention <callingconv>`, an optional ``unnamed_addr``
or ``local_unnamed_addr`` attribute, an optional address space, a return type,
an optional :ref:`parameter attribute <paramattrs>` for the return type, a function name, a possibly
empty list of arguments, an optional alignment, an optional :ref:`garbage
collector name <gc>`, an optional :ref:`prefix <prefixdata>`, and an optional
:ref:`prologue <prologuedata>`.
A function definition contains a list of basic blocks, forming the CFG (Control
Flow Graph) for the function. Each basic block may optionally start with a label
(giving the basic block a symbol table entry), contains a list of instructions,
and ends with a :ref:`terminator <terminators>` instruction (such as a branch or
function return). If an explicit label name is not provided, a block is assigned
an implicit numbered label, using the next value from the same counter as used
for unnamed temporaries (:ref:`see above<identifiers>`). For example, if a
function entry block does not have an explicit label, it will be assigned label
"%0", then the first unnamed temporary in that block will be "%1", etc. If a
numeric label is explicitly specified, it must match the numeric label that
would be used implicitly.
The first basic block in a function is special in two ways: it is
immediately executed on entrance to the function, and it is not allowed
to have predecessor basic blocks (i.e. there can not be any branches to
the entry block of a function). Because the block can have no
predecessors, it also cannot have any :ref:`PHI nodes <i_phi>`.
LLVM allows an explicit section to be specified for functions. If the
target supports it, it will emit functions to the section specified.
Additionally, the function can be placed in a COMDAT.
An explicit alignment may be specified for a function. If not present,
or if the alignment is set to zero, the alignment of the function is set
by the target to whatever it feels convenient. If an explicit alignment
is specified, the function is forced to have at least that much
alignment. All alignments must be a power of 2.
If the ``unnamed_addr`` attribute is given, the address is known to not
be significant and two identical functions can be merged.
If the ``local_unnamed_addr`` attribute is given, the address is known to
not be significant within the module.
If an explicit address space is not given, it will default to the program
address space from the :ref:`datalayout string<langref_datalayout>`.
Syntax::
define [linkage] [PreemptionSpecifier] [visibility] [DLLStorageClass]
[cconv] [ret attrs]
<ResultType> @<FunctionName> ([argument list])
[(unnamed_addr|local_unnamed_addr)] [AddrSpace] [fn Attrs]
[section "name"] [partition "name"] [comdat [($name)]] [align N]
[gc] [prefix Constant] [prologue Constant] [personality Constant]
(!name !N)* { ... }
The argument list is a comma separated sequence of arguments where each
argument is of the following form:
Syntax::
<type> [parameter Attrs] [name]
.. _langref_aliases:
Aliases
-------
Aliases, unlike function or variables, don't create any new data. They
are just a new symbol and metadata for an existing position.
Aliases have a name and an aliasee that is either a global value or a
constant expression.
Aliases may have an optional :ref:`linkage type <linkage>`, an optional
:ref:`runtime preemption specifier <runtime_preemption_model>`, an optional
:ref:`visibility style <visibility>`, an optional :ref:`DLL storage class
<dllstorageclass>` and an optional :ref:`tls model <tls_model>`.
Syntax::
@<Name> = [Linkage] [PreemptionSpecifier] [Visibility] [DLLStorageClass] [ThreadLocal] [(unnamed_addr|local_unnamed_addr)] alias <AliaseeTy>, <AliaseeTy>* @<Aliasee>
[, partition "name"]
The linkage must be one of ``private``, ``internal``, ``linkonce``, ``weak``,
``linkonce_odr``, ``weak_odr``, ``external``. Note that some system linkers
might not correctly handle dropping a weak symbol that is aliased.
Aliases that are not ``unnamed_addr`` are guaranteed to have the same address as
the aliasee expression. ``unnamed_addr`` ones are only guaranteed to point
to the same content.
If the ``local_unnamed_addr`` attribute is given, the address is known to
not be significant within the module.
Since aliases are only a second name, some restrictions apply, of which
some can only be checked when producing an object file:
* The expression defining the aliasee must be computable at assembly
time. Since it is just a name, no relocations can be used.
* No alias in the expression can be weak as the possibility of the
intermediate alias being overridden cannot be represented in an
object file.
* No global value in the expression can be a declaration, since that
would require a relocation, which is not possible.
* If either the alias or the aliasee may be replaced by a symbol outside the
module at link time or runtime, any optimization cannot replace the alias with
the aliasee, since the behavior may be different. The alias may be used as a
name guaranteed to point to the content in the current module.
.. _langref_ifunc:
IFuncs
-------
IFuncs, like as aliases, don't create any new data or func. They are just a new
symbol that dynamic linker resolves at runtime by calling a resolver function.
IFuncs have a name and a resolver that is a function called by dynamic linker
that returns address of another function associated with the name.
IFunc may have an optional :ref:`linkage type <linkage>` and an optional
:ref:`visibility style <visibility>`.
Syntax::
@<Name> = [Linkage] [PreemptionSpecifier] [Visibility] ifunc <IFuncTy>, <ResolverTy>* @<Resolver>
[, partition "name"]
.. _langref_comdats:
Comdats
-------
Comdat IR provides access to object file COMDAT/section group functionality
which represents interrelated sections.
Comdats have a name which represents the COMDAT key and a selection kind to
provide input on how the linker deduplicates comdats with the same key in two
different object files. A comdat must be included or omitted as a unit.
Discarding the whole comdat is allowed but discarding a subset is not.
A global object may be a member of at most one comdat. Aliases are placed in the
same COMDAT that their aliasee computes to, if any.
Syntax::
$<Name> = comdat SelectionKind
For selection kinds other than ``nodeduplicate``, only one of the duplicate
comdats may be retained by the linker and the members of the remaining comdats
must be discarded. The following selection kinds are supported:
``any``
The linker may choose any COMDAT key, the choice is arbitrary.
``exactmatch``
The linker may choose any COMDAT key but the sections must contain the
same data.
``largest``
The linker will choose the section containing the largest COMDAT key.
``nodeduplicate``
No deduplication is performed.
``samesize``
The linker may choose any COMDAT key but the sections must contain the
same amount of data.
- XCOFF and Mach-O don't support COMDATs.
- COFF supports all selection kinds. Non-``nodeduplicate`` selection kinds need
a non-local linkage COMDAT symbol.
- ELF supports ``any`` and ``nodeduplicate``.
- WebAssembly only supports ``any``.
Here is an example of a COFF COMDAT where a function will only be selected if
the COMDAT key's section is the largest:
.. code-block:: text
$foo = comdat largest
@foo = global i32 2, comdat($foo)
define void @bar() comdat($foo) {
ret void
}
In a COFF object file, this will create a COMDAT section with selection kind
``IMAGE_COMDAT_SELECT_LARGEST`` containing the contents of the ``@foo`` symbol
and another COMDAT section with selection kind
``IMAGE_COMDAT_SELECT_ASSOCIATIVE`` which is associated with the first COMDAT
section and contains the contents of the ``@bar`` symbol.
As a syntactic sugar the ``$name`` can be omitted if the name is the same as
the global name:
.. code-block:: llvm
$foo = comdat any
@foo = global i32 2, comdat
@bar = global i32 3, comdat($foo)
There are some restrictions on the properties of the global object.
It, or an alias to it, must have the same name as the COMDAT group when
targeting COFF.
The contents and size of this object may be used during link-time to determine
which COMDAT groups get selected depending on the selection kind.
Because the name of the object must match the name of the COMDAT group, the
linkage of the global object must not be local; local symbols can get renamed
if a collision occurs in the symbol table.