llvm.org GIT mirror llvm / 88ea57f
[docs] Fixing Sphinx warnings to unclog the buildbot Lots of blocks had "llvm" or "nasm" syntax types but either weren't following the syntax, or the syntax has changed (and sphinx hasn't keep up) or the type doesn't even exist (nasm?). Other documents had :options: what were invalid. I only removed those that had warnings, and left the ones that didn't, in order to follow the principle of least surprise. This is like this for ages, but the buildbot is now failing on errors. It may take a while to upgrade the buildbot's sphinx, if that's even possible, but that shouldn't stop us from getting docs updates (which seem down for quite a while). Also, we're not losing any syntax highlight, since when it doesn't parse, it doesn't colour. Ie. those blocks are not being highlighted anyway. I'm trying to get all docs in one go, so that it's easy to revert later if we do fix, or at least easy to know what's to fix. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@276109 91177308-0d34-0410-b5e6-96231b3b80d8 Renato Golin 3 years ago
22 changed file(s) with 185 addition(s) and 187 deletion(s). Raw diff Collapse all Expand all
435435 The X86 instruction selector might produce this machine code for the ``div`` and
436436 ``ret``:
437437
438 .. code-block:: llvm
438 .. code-block:: text
439439
440440 ;; Start of div
441441 %EAX = mov %reg1024 ;; Copy X (in reg1024) into EAX
452452 registers and delete the resultant identity moves producing the following
453453 code:
454454
455 .. code-block:: llvm
455 .. code-block:: text
456456
457457 ;; X is in EAX, Y is in ECX
458458 mov %EAX, %EDX
964964
965965 This LLVM code corresponds to a SelectionDAG that looks basically like this:
966966
967 .. code-block:: llvm
967 .. code-block:: text
968968
969969 (fadd:f32 (fmul:f32 (fadd:f32 W, X), Y), Z)
970970
143143 The FileCheck -check-prefix option
144144 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
145145
146 The FileCheck :option:`-check-prefix` option allows multiple test
146 The FileCheck `-check-prefix` option allows multiple test
147147 configurations to be driven from one `.ll` file. This is useful in many
148148 circumstances, for example, testing different architectural variants with
149149 :program:`llc`. Here's a simple example:
302302
303303 So, for instance, the code below will pass:
304304
305 .. code-block:: llvm
305 .. code-block:: text
306306
307307 ; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0]
308308 ; CHECK-DAG: vmov.32 [[REG2]][1]
311311
312312 While this other code, will not:
313313
314 .. code-block:: llvm
314 .. code-block:: text
315315
316316 ; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0]
317317 ; CHECK-DAG: vmov.32 [[REG2]][1]
472472
473473 matches output of the form (from llvm-dwarfdump):
474474
475 .. code-block:: llvm
475 .. code-block:: text
476476
477477 DW_AT_location [DW_FORM_sec_offset] (0x00000233)
478478 DW_AT_name [DW_FORM_strp] ( .debug_str[0x000000c9] = "intd")
6767
6868 .. option:: -B (default)
6969
70 Use BSD output format. Alias for :option:`--format=bsd`.
70 Use BSD output format. Alias for `--format=bsd`.
7171
7272 .. option:: -P
7373
74 Use POSIX.2 output format. Alias for :option:`--format=posix`.
74 Use POSIX.2 output format. Alias for `--format=posix`.
7575
7676 .. option:: --debug-syms, -a
7777
1111 The :program:`opt` command is the modular LLVM optimizer and analyzer. It
1212 takes LLVM source files as input, runs the specified optimizations or analyses
1313 on it, and then outputs the optimized file or the analysis results. The
14 function of :program:`opt` depends on whether the :option:`-analyze` option is
14 function of :program:`opt` depends on whether the `-analyze` option is
1515 given.
1616
17 When :option:`-analyze` is specified, :program:`opt` performs various analyses
17 When `-analyze` is specified, :program:`opt` performs various analyses
1818 of the input source. It will usually print the results on standard output, but
1919 in a few cases, it will print output to standard error or generate a file with
2020 the analysis output, which is usually done when the output is meant for another
2121 program.
2222
23 While :option:`-analyze` is *not* given, :program:`opt` attempts to produce an
23 While `-analyze` is *not* given, :program:`opt` attempts to produce an
2424 optimized output file. The optimizations available via :program:`opt` depend
2525 upon what libraries were linked into it as well as any additional libraries
2626 that have been loaded with the :option:`-load` option. Use the :option:`-help`
6767
6868 .. option:: -disable-opt
6969
70 This option is only meaningful when :option:`-std-link-opts` is given. It
70 This option is only meaningful when `-std-link-opts` is given. It
7171 disables most passes.
7272
7373 .. option:: -strip-debug
7474
7575 This option causes opt to strip debug information from the module before
76 applying other optimizations. It is essentially the same as :option:`-strip`
76 applying other optimizations. It is essentially the same as `-strip`
7777 but it ensures that stripping of debug information is done first.
7878
7979 .. option:: -verify-each
8080
8181 This option causes opt to add a verify pass after every pass otherwise
82 specified on the command line (including :option:`-verify`). This is useful
82 specified on the command line (including `-verify`). This is useful
8383 for cases where it is suspected that a pass is creating an invalid module but
8484 it is not clear which pass is doing it.
8585
405405 ``llvm.eh.exceptionpointer``
406406 ----------------------------
407407
408 .. code-block:: llvm
408 .. code-block:: text
409409
410410 i8 addrspace(N)* @llvm.eh.padparam.pNi8(token %catchpad)
411411
426426 ``llvm.eh.sjlj.setjmp``
427427 ~~~~~~~~~~~~~~~~~~~~~~~
428428
429 .. code-block:: llvm
429 .. code-block:: text
430430
431431 i32 @llvm.eh.sjlj.setjmp(i8* %setjmp_buf)
432432
663663 return 0;
664664 }
665665
666 .. code-block:: llvm
666 .. code-block:: text
667667
668668 define i32 @f() nounwind personality i32 (...)* @__CxxFrameHandler3 {
669669 entry:
740740 }
741741 }
742742
743 .. code-block:: llvm
743 .. code-block:: text
744744
745745 define void @f() #0 personality i8* bitcast (i32 (...)* @__CxxFrameHandler3 to i8*) {
746746 entry:
4242 corresponds to the COFF relocation types ``IMAGE_REL_I386_DIR32NB`` (32-bit) or
4343 ``IMAGE_REL_AMD64_ADDR32NB`` (64-bit).
4444
45 .. code-block:: gas
45 .. code-block:: text
4646
4747 .text
4848 fun:
203203 Specifying GC code generation: ``gc "..."``
204204 -------------------------------------------
205205
206 .. code-block:: llvm
206 .. code-block:: text
207207
208208 define @name(...) gc "name" { ... }
209209
104104
105105 To make this clear, let's consider a more obtuse example:
106106
107 .. code-block:: llvm
107 .. code-block:: text
108108
109109 %MyVar = uninitialized global i32
110110 ...
141141 This question arises most often when the GEP instruction is applied to a global
142142 variable which is always a pointer type. For example, consider this:
143143
144 .. code-block:: llvm
144 .. code-block:: text
145145
146146 %MyStruct = uninitialized global { float*, i32 }
147147 ...
177177 memory in any way. That's what the Load and Store instructions are for. GEP is
178178 only involved in the computation of addresses. For example, consider this:
179179
180 .. code-block:: llvm
180 .. code-block:: text
181181
182182 %MyVar = uninitialized global { [40 x i32 ]* }
183183 ...
194194 In order to access the 18th integer in the array, you would need to do the
195195 following:
196196
197 .. code-block:: llvm
197 .. code-block:: text
198198
199199 %idx = getelementptr { [40 x i32]* }, { [40 x i32]* }* %, i64 0, i32 0
200200 %arr = load [40 x i32]** %idx
203203 In this case, we have to load the pointer in the structure with a load
204204 instruction before we can index into the array. If the example was changed to:
205205
206 .. code-block:: llvm
206 .. code-block:: text
207207
208208 %MyVar = uninitialized global { [40 x i32 ] }
209209 ...
2929 ``XXXInstrInfo.inc`` file along with the functions to query them. Following
3030 is the definition of ``InstrMapping`` class definied in Target.td file:
3131
32 .. code-block:: llvm
32 .. code-block:: text
3333
3434 class InstrMapping {
3535 // Used to reduce search space only to the instructions using this
6868 fields. For this relationship, non-predicated instructions are treated as key
6969 instruction since they are the one used to query the interface function.
7070
71 .. code-block:: llvm
71 .. code-block:: text
7272
7373 def getPredOpcode : InstrMapping {
7474 // Choose a FilterClass that is used as a base class for all the
115115 following to be the current definitions of ADD, ADD_pt (true) and ADD_pf (false)
116116 instructions:
117117
118 .. code-block:: llvm
118 .. code-block:: text
119119
120120 def ADD : ALU32_rr<(outs IntRegs:$dst), (ins IntRegs:$a, IntRegs:$b),
121121 "$dst = add($a, $b)",
136136 required by the relationship model, getPredOpcode, so that they can
137137 be related.
138138
139 .. code-block:: llvm
139 .. code-block:: text
140140
141141 def ADD : PredRel, ALU32_rr<(outs IntRegs:$dst), (ins IntRegs:$a, IntRegs:$b),
142142 "$dst = add($a, $b)",
4040 g(Foo(), Foo());
4141 }
4242
43 .. code-block:: llvm
43 .. code-block:: text
4444
4545 %struct.Foo = type { i32, i32 }
4646 declare void @Foo_ctor(%struct.Foo* %this)
838838 Here is an example of a COMDAT group where a function will only be selected if
839839 the COMDAT key's section is the largest:
840840
841 .. code-block:: llvm
841 .. code-block:: text
842842
843843 $foo = comdat largest
844844 @foo = global i32 2, comdat($foo)
850850 As a syntactic sugar the ``$name`` can be omitted if the name is the same as
851851 the global name:
852852
853 .. code-block:: llvm
853 .. code-block:: text
854854
855855 $foo = comdat any
856856 @foo = global i32 2, comdat
874874 The combined use of COMDATS and section attributes may yield surprising results.
875875 For example:
876876
877 .. code-block:: llvm
877 .. code-block:: text
878878
879879 $foo = comdat any
880880 $bar = comdat any
12041204 A trivial example of valid prologue data for the x86 architecture is ``i8 144``,
12051205 which encodes the ``nop`` instruction:
12061206
1207 .. code-block:: llvm
1207 .. code-block:: text
12081208
12091209 define void @f() prologue i8 144 { ... }
12101210
12121212 which skips the metadata, as in this example of valid prologue data for the
12131213 x86_64 architecture, where the first two bytes encode ``jmp .+10``:
12141214
1215 .. code-block:: llvm
1215 .. code-block:: text
12161216
12171217 %0 = type <{ i8, i8, i8* }>
12181218
22362236
22372237 The syntax for the source file name is simply:
22382238
2239 .. code-block:: llvm
2239 .. code-block:: text
22402240
22412241 source_filename = "/path/to/source.c"
22422242
28462846 allowed to assume that the '``undef``' operand could be the same as
28472847 ``%Y``, allowing the whole '``select``' to be eliminated.
28482848
2849 .. code-block:: llvm
2849 .. code-block:: text
28502850
28512851 %A = xor undef, undef
28522852
28982898 code after it. Because the undefined operation "can't happen", the
28992899 optimizer can assume that it occurs in dead code.
29002900
2901 .. code-block:: llvm
2901 .. code-block:: text
29022902
29032903 a: store undef -> %X
29042904 b: store %X -> undef
38833883
38843884 Metadata nodes that aren't uniqued use the ``distinct`` keyword. For example:
38853885
3886 .. code-block:: llvm
3886 .. code-block:: text
38873887
38883888 !0 = distinct !{!"test\00", i32 10}
38893889
39483948 unit, regardless of code optimizations (some nodes are only emitted if there are
39493949 references to them from instructions).
39503950
3951 .. code-block:: llvm
3951 .. code-block:: text
39523952
39533953 !0 = !DICompileUnit(language: DW_LANG_C99, file: !1, producer: "clang",
39543954 isOptimized: true, flags: "-O2", runtimeVersion: 2,
39843984 ``DIBasicType`` nodes represent primitive types, such as ``int``, ``bool`` and
39853985 ``float``. ``tag:`` defaults to ``DW_TAG_base_type``.
39863986
3987 .. code-block:: llvm
3987 .. code-block:: text
39883988
39893989 !0 = !DIBasicType(name: "unsigned char", size: 8, align: 8,
39903990 encoding: DW_ATE_unsigned_char)
39933993 The ``encoding:`` describes the details of the type. Usually it's one of the
39943994 following:
39953995
3996 .. code-block:: llvm
3996 .. code-block:: text
39973997
39983998 DW_ATE_address = 1
39993999 DW_ATE_boolean = 2
40134013 types of the formal arguments in order. If the first operand is ``null``, that
40144014 represents a function with no return value (such as ``void foo() {}`` in C++).
40154015
4016 .. code-block:: llvm
4016 .. code-block:: text
40174017
40184018 !0 = !BasicType(name: "int", size: 32, align: 32, DW_ATE_signed)
40194019 !1 = !BasicType(name: "char", size: 8, align: 8, DW_ATE_signed_char)
40274027 ``DIDerivedType`` nodes represent types derived from other types, such as
40284028 qualified types.
40294029
4030 .. code-block:: llvm
4030 .. code-block:: text
40314031
40324032 !0 = !DIBasicType(name: "unsigned char", size: 8, align: 8,
40334033 encoding: DW_ATE_unsigned_char)
40364036
40374037 The following ``tag:`` values are valid:
40384038
4039 .. code-block:: llvm
4039 .. code-block:: text
40404040
40414041 DW_TAG_member = 13
40424042 DW_TAG_pointer_type = 15
40884088 together will unique such definitions at parse time via the ``identifier:``
40894089 field, even if the nodes are ``distinct``.
40904090
4091 .. code-block:: llvm
4091 .. code-block:: text
40924092
40934093 !0 = !DIEnumerator(name: "SixKind", value: 7)
40944094 !1 = !DIEnumerator(name: "SevenKind", value: 7)
40994099
41004100 The following ``tag:`` values are valid:
41014101
4102 .. code-block:: llvm
4102 .. code-block:: text
41034103
41044104 DW_TAG_array_type = 1
41054105 DW_TAG_class_type = 2
42184218 then the subprogram declaration is uniqued based only on its ``linkageName:``
42194219 and ``scope:``.
42204220
4221 .. code-block:: llvm
4221 .. code-block:: text
42224222
42234223 define void @_Z3foov() !dbg !0 {
42244224 ...
42434243 two lexical blocks at same depth. They are valid targets for ``scope:``
42444244 fields.
42454245
4246 .. code-block:: llvm
4246 .. code-block:: text
42474247
42484248 !0 = distinct !DILexicalBlock(scope: !1, file: !2, line: 7, column: 35)
42494249
42894289 parameter, and it will be included in the ``variables:`` field of its
42904290 :ref:`DISubprogram`.
42914291
4292 .. code-block:: llvm
4292 .. code-block:: text
42934293
42944294 !0 = !DILocalVariable(name: "this", arg: 1, scope: !3, file: !2, line: 7,
42954295 type: !3, flags: DIFlagArtificial)
43124312 - ``DW_OP_bit_piece, 16, 8`` specifies the offset and size (``16`` and ``8``
43134313 here, respectively) of the variable piece from the working expression.
43144314
4315 .. code-block:: llvm
4315 .. code-block:: text
43164316
43174317 !0 = !DIExpression(DW_OP_deref)
43184318 !1 = !DIExpression(DW_OP_plus, 3)
43354335 ``DIImportedEntity`` nodes represent entities (such as modules) imported into a
43364336 compile unit.
43374337
4338 .. code-block:: llvm
4338 .. code-block:: text
43394339
43404340 !2 = !DIImportedEntity(tag: DW_TAG_imported_module, name: "foo", scope: !0,
43414341 entity: !1, line: 7)
43484348 defining a function-like macro, and the ``value`` field is the token-string
43494349 used to expand the macro identifier.
43504350
4351 .. code-block:: llvm
4351 .. code-block:: text
43524352
43534353 !2 = !DIMacro(macinfo: DW_MACINFO_define, line: 7, name: "foo(x)",
43544354 value: "((x) + 1)")
43614361 The ``nodes:`` field is a list of ``DIMacro`` and ``DIMacroFile`` nodes that
43624362 appear in the included source file.
43634363
4364 .. code-block:: llvm
4364 .. code-block:: text
43654365
43664366 !2 = !DIMacroFile(macinfo: DW_MACINFO_start_file, line: 7, file: !2,
43674367 nodes: !3)
56595659 Example:
56605660 """"""""
56615661
5662 .. code-block:: llvm
5662 .. code-block:: text
56635663
56645664 dispatch1:
56655665 %cs1 = catchswitch within none [label %handler0, label %handler1] unwind to caller
57105710 Example:
57115711 """"""""
57125712
5713 .. code-block:: llvm
5713 .. code-block:: text
57145714
57155715 catchret from %catch label %continue
57165716
57605760 Example:
57615761 """"""""
57625762
5763 .. code-block:: llvm
5763 .. code-block:: text
57645764
57655765 cleanupret from %cleanup unwind to caller
57665766 cleanupret from %cleanup unwind label %continue
58505850 Example:
58515851 """"""""
58525852
5853 .. code-block:: llvm
5853 .. code-block:: text
58545854
58555855 = add i32 4, %var ; yields i32:result = 4 + %var
58565856
58895889 Example:
58905890 """"""""
58915891
5892 .. code-block:: llvm
5892 .. code-block:: text
58935893
58945894 = fadd float 4.0, %var ; yields float:result = 4.0 + %var
58955895
59415941 Example:
59425942 """"""""
59435943
5944 .. code-block:: llvm
5944 .. code-block:: text
59455945
59465946 = sub i32 4, %var ; yields i32:result = 4 - %var
59475947 = sub i32 0, %val ; yields i32:result = -%var
59845984 Example:
59855985 """"""""
59865986
5987 .. code-block:: llvm
5987 .. code-block:: text
59885988
59895989 = fsub float 4.0, %var ; yields float:result = 4.0 - %var
59905990 = fsub float -0.0, %val ; yields float:result = -%var
60386038 Example:
60396039 """"""""
60406040
6041 .. code-block:: llvm
6041 .. code-block:: text
60426042
60436043 = mul i32 4, %var ; yields i32:result = 4 * %var
60446044
60776077 Example:
60786078 """"""""
60796079
6080 .. code-block:: llvm
6080 .. code-block:: text
60816081
60826082 = fmul float 4.0, %var ; yields float:result = 4.0 * %var
60836083
61216121 Example:
61226122 """"""""
61236123
6124 .. code-block:: llvm
6124 .. code-block:: text
61256125
61266126 = udiv i32 4, %var ; yields i32:result = 4 / %var
61276127
61676167 Example:
61686168 """"""""
61696169
6170 .. code-block:: llvm
6170 .. code-block:: text
61716171
61726172 = sdiv i32 4, %var ; yields i32:result = 4 / %var
61736173
62066206 Example:
62076207 """"""""
62086208
6209 .. code-block:: llvm
6209 .. code-block:: text
62106210
62116211 = fdiv float 4.0, %var ; yields float:result = 4.0 / %var
62126212
62486248 Example:
62496249 """"""""
62506250
6251 .. code-block:: llvm
6251 .. code-block:: text
62526252
62536253 = urem i32 4, %var ; yields i32:result = 4 % %var
62546254
63036303 Example:
63046304 """"""""
63056305
6306 .. code-block:: llvm
6306 .. code-block:: text
63076307
63086308 = srem i32 4, %var ; yields i32:result = 4 % %var
63096309
63436343 Example:
63446344 """"""""
63456345
6346 .. code-block:: llvm
6346 .. code-block:: text
63476347
63486348 = frem float 4.0, %var ; yields float:result = 4.0 % %var
63496349
64056405 Example:
64066406 """"""""
64076407
6408 .. code-block:: llvm
6408 .. code-block:: text
64096409
64106410 = shl i32 4, %var ; yields i32: 4 << %var
64116411 = shl i32 4, 2 ; yields i32: 16
64546454 Example:
64556455 """"""""
64566456
6457 .. code-block:: llvm
6457 .. code-block:: text
64586458
64596459 = lshr i32 4, 1 ; yields i32:result = 2
64606460 = lshr i32 4, 2 ; yields i32:result = 1
65056505 Example:
65066506 """"""""
65076507
6508 .. code-block:: llvm
6508 .. code-block:: text
65096509
65106510 = ashr i32 4, 1 ; yields i32:result = 2
65116511 = ashr i32 4, 2 ; yields i32:result = 1
65576557 Example:
65586558 """"""""
65596559
6560 .. code-block:: llvm
6560 .. code-block:: text
65616561
65626562 = and i32 4, %var ; yields i32:result = 4 & %var
65636563 = and i32 15, 40 ; yields i32:result = 8
66566656 Example:
66576657 """"""""
66586658
6659 .. code-block:: llvm
6659 .. code-block:: text
66606660
66616661 = xor i32 4, %var ; yields i32:result = 4 ^ %var
66626662 = xor i32 15, 40 ; yields i32:result = 39
67096709 Example:
67106710 """"""""
67116711
6712 .. code-block:: llvm
6712 .. code-block:: text
67136713
67146714 = extractelement <4 x i32> %vec, i32 0 ; yields i32
67156715
67516751 Example:
67526752 """"""""
67536753
6754 .. code-block:: llvm
6754 .. code-block:: text
67556755
67566756 = insertelement <4 x i32> %vec, i32 1, i32 0 ; yields <4 x i32>
67576757
67996799 Example:
68006800 """"""""
68016801
6802 .. code-block:: llvm
6802 .. code-block:: text
68036803
68046804 = shufflevector <4 x i32> %v1, <4 x i32> %v2,
68056805 <4 x i32> ; yields <4 x i32>
68586858 Example:
68596859 """"""""
68606860
6861 .. code-block:: llvm
6861 .. code-block:: text
68626862
68636863 = extractvalue {i32, float} %agg, 0 ; yields i32
68646864
81258125 Example:
81268126 """"""""
81278127
8128 .. code-block:: llvm
8128 .. code-block:: text
81298129
81308130 %X = bitcast i8 255 to i8 ; yields i8 :-1
81318131 %Y = bitcast i32* %x to sint* ; yields sint*:%x
82648264 Example:
82658265 """"""""
82668266
8267 .. code-block:: llvm
8267 .. code-block:: text
82688268
82698269 = icmp eq i32 4, 5 ; yields: result=false
82708270 = icmp ne float* %X, %X ; yields: result=false
83788378 Example:
83798379 """"""""
83808380
8381 .. code-block:: llvm
8381 .. code-block:: text
83828382
83838383 = fcmp oeq float 4.0, 5.0 ; yields: result=false
83848384 = fcmp one float 4.0, 5.0 ; yields: result=true
88148814 Example:
88158815 """"""""
88168816
8817 .. code-block:: llvm
8817 .. code-block:: text
88188818
88198819 dispatch:
88208820 %cs = catchswitch within none [label %handler0] unwind to caller
88848884 Example:
88858885 """"""""
88868886
8887 .. code-block:: llvm
8887 .. code-block:: text
88888888
88898889 %tok = cleanuppad within %cs []
88908890
1248012480 ``@llvm.experimental.deoptimize`` -- its body is defined to be
1248112481 equivalent to:
1248212482
12483 .. code-block:: llvm
12484
12485 define void @llvm.experimental.guard(i1 %pred, ) {
12486 %realPred = and i1 %pred, undef
12487 br i1 %realPred, label %continue, label %leave [, !make.implicit !{}]
12488
12489 leave:
12490 call void @llvm.experimental.deoptimize() [ "deopt"() ]
12491 ret void
12492
12493 continue:
12494 ret void
12495 }
12483 .. code-block:: text
12484
12485 define void @llvm.experimental.guard(i1 %pred, ) {
12486 %realPred = and i1 %pred, undef
12487 br i1 %realPred, label %continue, label %leave [, !make.implicit !{}]
12488
12489 leave:
12490 call void @llvm.experimental.deoptimize() [ "deopt"() ]
12491 ret void
12492
12493 continue:
12494 ret void
12495 }
1249612496
1249712497
1249812498 with the optional ``[, !make.implicit !{}]`` present if and only if it
110110
111111 .. code-block:: llvm
112112
113 --- |
114113 define i32 @inc(i32* %x) {
115114 entry:
116115 %0 = load i32, i32* %x
118117 store i32 %1, i32* %x
119118 ret i32 %1
120119 }
121 ...
122120
123121 .. _YAML block literal string: http://www.yaml.org/spec/1.2/spec.html#id2795688
124122
128126 The remaining YAML documents contain the machine functions. This is an example
129127 of such YAML document:
130128
131 .. code-block:: llvm
129 .. code-block:: text
132130
133131 ---
134132 name: inc
171169 that contains the block's ID.
172170 The example below defines two blocks that have an ID of zero and one:
173171
174 .. code-block:: llvm
172 .. code-block:: text
175173
176174 bb.0:
177175
181179 A machine basic block can also have a name. It should be specified after the ID
182180 in the block's definition:
183181
184 .. code-block:: llvm
182 .. code-block:: text
185183
186184 bb.0.entry: ; This block's name is "entry"
187185
195193 The machine basic blocks are identified by their ID numbers. Individual
196194 blocks are referenced using the following syntax:
197195
198 .. code-block:: llvm
196 .. code-block:: text
199197
200198 %bb.[.]
201199
212210 The machine basic block's successors have to be specified before any of the
213211 instructions:
214212
215 .. code-block:: llvm
213 .. code-block:: text
216214
217215 bb.0.entry:
218216 successors: %bb.1.then, %bb.2.else
226224 The example below defines a block that has two successors with branch weights
227225 of 32 and 16:
228226
229 .. code-block:: llvm
227 .. code-block:: text
230228
231229 bb.0.entry:
232230 successors: %bb.1.then(32), %bb.2.else(16)
239237 The machine basic block's live in registers have to be specified before any of
240238 the instructions:
241239
242 .. code-block:: llvm
240 .. code-block:: text
243241
244242 bb.0.entry:
245243 liveins: %edi, %esi
254252 The attributes ``IsAddressTaken``, ``IsLandingPad`` and ``Alignment`` can be
255253 specified in brackets after the block's definition:
256254
257 .. code-block:: llvm
255 .. code-block:: text
258256
259257 bb.0.entry (address-taken):
260258
277275 below shows an instance of the X86 ``RETQ`` instruction with a single machine
278276 operand:
279277
280 .. code-block:: llvm
278 .. code-block:: text
281279
282280 RETQ %eax
283281
286284 below shows an instance of the AArch64 ``LDPXpost`` instruction with three
287285 defined register operands:
288286
289 .. code-block:: llvm
287 .. code-block:: text
290288
291289 %sp, %fp, %lr = LDPXpost %sp, 2
292290
302300
303301 The flag ``frame-setup`` can be specified before the instruction's name:
304302
305 .. code-block:: llvm
303 .. code-block:: text
306304
307305 %fp = frame-setup ADDXri %sp, 0, 0
308306
320318 The physical registers are identified by their name. They use the following
321319 syntax:
322320
323 .. code-block:: llvm
321 .. code-block:: text
324322
325323 %
326324
327325 The example below shows three X86 physical registers:
328326
329 .. code-block:: llvm
327 .. code-block:: text
330328
331329 %eax
332330 %r15
335333 The virtual registers are identified by their ID number. They use the following
336334 syntax:
337335
338 .. code-block:: llvm
336 .. code-block:: text
339337
340338 %
341339
342340 Example:
343341
344 .. code-block:: llvm
342 .. code-block:: text
345343
346344 %0
347345
365363 example below shows an instance of the X86 ``MOV32ri`` instruction that has an
366364 immediate machine operand ``-42``:
367365
368 .. code-block:: llvm
366 .. code-block:: text
369367
370368 %eax = MOV32ri -42
371369
383381 and a reference to the tied register operand.
384382 The full syntax of a register operand is shown below:
385383
386 .. code-block:: llvm
384 .. code-block:: text
387385
388386 [] [ : ] [ (tied-def ) ]
389387
390388 This example shows an instance of the X86 ``XOR32rr`` instruction that has
391389 5 register operands with different register flags:
392390
393 .. code-block:: llvm
391 .. code-block:: text
394392
395393 dead %eax = XOR32rr undef %eax, undef %eax, implicit-def dead %eflags, implicit-def %al
396394
445443 pseudo instruction that uses the X86 ``sub_8bit`` subregister index to copy 8
446444 lower bits from the 32-bit virtual register 0 to the 8-bit virtual register 1:
447445
448 .. code-block:: llvm
446 .. code-block:: text
449447
450448 %1 = COPY %0:sub_8bit
451449
460458 The example below shows an instance of the X86 ``MOV64rm`` instruction that has
461459 a global value operand named ``G``:
462460
463 .. code-block:: llvm
461 .. code-block:: text
464462
465463 %rax = MOV64rm %rip, 1, _, @G, _
466464
6969 For example, a possible annotation of an ARM load of a stack-relative location
7070 might be annotated as:
7171
72 .. code-block:: nasm
72 .. code-block:: text
7373
7474 ldr , , ]>
7575
393393 corresponding part of *right* place, and (!) both parts use *Value* instances,
394394 for example:
395395
396 .. code-block:: llvm
396 .. code-block:: text
397397
398398 instr0 i32 %LV ; left side, function FL
399399 instr0 i32 %RV ; right side, function FR
408408
409409 Consider small example here:
410410
411 .. code-block:: llvm
411 .. code-block:: text
412412
413413 define void %f(i32 %pf0, i32 %pf1) {
414414 instr0 i32 %pf0 instr1 i32 %pf1 instr2 i32 123
415415 }
416416
417 .. code-block:: llvm
417 .. code-block:: text
418418
419419 define void %g(i32 %pg0, i32 %pg1) {
420420 instr0 i32 %pg0 instr1 i32 %pg0 instr2 i32 123
3636 declare a function as a kernel function. This metadata is attached to the
3737 ``nvvm.annotations`` named metadata object, and has the following format:
3838
39 .. code-block:: llvm
39 .. code-block:: text
4040
4141 !0 = !{, metadata !"kernel", i32 1}
4242
3232 this slot's offset is again dictated by ``libgcc``. The generated
3333 assembly looks like this on x86-64:
3434
35 .. code-block:: nasm
35 .. code-block:: text
3636
3737 leaq -8(%rsp), %r10
3838 cmpq %fs:112, %r10
229229
230230 Compiled to LLVM, this function would be represented like this:
231231
232 .. code-block:: llvm
232 .. code-block:: text
233233
234234 ; Function Attrs: nounwind ssp uwtable
235235 define void @foo() #0 !dbg !4 {
302302 variable ``X``. The metadata ``!dbg !14`` attached to the intrinsic provides
303303 scope information for the variable ``X``.
304304
305 .. code-block:: llvm
305 .. code-block:: text
306306
307307 !14 = !DILocation(line: 2, column: 9, scope: !4)
308308 !4 = distinct !DISubprogram(name: "foo", scope: !1, file: !1, line: 1, type: !5,
326326 variable ``Z``. The metadata ``!dbg !19`` attached to the intrinsic provides
327327 scope information for the variable ``Z``.
328328
329 .. code-block:: llvm
329 .. code-block:: text
330330
331331 !18 = distinct !DILexicalBlock(scope: !4, file: !1, line: 4, column: 5)
332332 !19 = !DILocation(line: 5, column: 11, scope: !18)
389389
390390 a C/C++ front-end would generate the following descriptors:
391391
392 .. code-block:: llvm
392 .. code-block:: text
393393
394394 ;;
395395 ;; Define the global itself.
455455
456456 a C/C++ front-end would generate the following descriptors:
457457
458 .. code-block:: llvm
458 .. code-block:: text
459459
460460 ;;
461461 ;; Define the anchor for subprograms.
137137 ``%obj`` after the safepoint and update any following uses appropriately. The
138138 resulting relocation sequence is:
139139
140 .. code-block:: llvm
140 .. code-block:: text
141141
142142 define i8 addrspace(1)* @test1(i8 addrspace(1)* %obj)
143143 gc "statepoint-example" {
236236 If we extend our previous example to include a pointless derived pointer,
237237 we get:
238238
239 .. code-block:: llvm
239 .. code-block:: text
240240
241241 define i8 addrspace(1)* @test1(i8 addrspace(1)* %obj)
242242 gc "statepoint-example" {
282282 --that requires that a TLS variable must be written to before and after a call
283283 to unmanaged code. The resulting relocation sequence is:
284284
285 .. code-block:: llvm
285 .. code-block:: text
286286
287287 @flag = thread_local global i32 0, align 4
288288
661661
662662 As an example, given this code:
663663
664 .. code-block:: llvm
664 .. code-block:: text
665665
666666 define i8 addrspace(1)* @test1(i8 addrspace(1)* %obj)
667667 gc "statepoint-example" {
671671
672672 The pass would produce this IR:
673673
674 .. code-block:: llvm
674 .. code-block:: text
675675
676676 define i8 addrspace(1)* @test1(i8 addrspace(1)* %obj)
677677 gc "statepoint-example" {
736736
737737 This pass would produce the following IR:
738738
739 .. code-block:: llvm
739 .. code-block:: text
740740
741741 define void @test() gc "statepoint-example" {
742742 %safepoint_token = call token (i64, i32, void ()*, i32, i32, ...)* @llvm.experimental.gc.statepoint.p0f_isVoidf(i64 2882400000, i32 0, void ()* @do_safepoint, i32 0, i32 0, i32 0, i32 0)
231231
232232 Here is a simple TableGen file:
233233
234 .. code-block:: llvm
234 .. code-block:: text
235235
236236 class C { bit V = 1; }
237237 def X : C;
275275 value. For example, a new class could be added to the example above, redefining
276276 the ``V`` field for all of its subclasses:
277277
278 .. code-block:: llvm
278 .. code-block:: text
279279
280280 class D : C { let V = 0; }
281281 def Z : D;
294294 bindings (which may optionally have defaults) that are bound when used. Here is
295295 a simple example:
296296
297 .. code-block:: llvm
297 .. code-block:: text
298298
299299 class FPFormat val> {
300300 bits<3> Value = val;
315315 The more esoteric forms of `TableGen expressions`_ are useful in conjunction
316316 with template arguments. As an example:
317317
318 .. code-block:: llvm
318 .. code-block:: text
319319
320320 class ModRefVal val> {
321321 bits<2> Value = val;
345345 actual internal data representation expected by the class. In this case,
346346 running ``llvm-tblgen`` on the example prints the following definitions:
347347
348 .. code-block:: llvm
348 .. code-block:: text
349349
350350 def bork { // Value
351351 bit isMod = 1;
378378
379379 Here is an example TableGen fragment that shows this idea:
380380
381 .. code-block:: llvm
381 .. code-block:: text
382382
383383 def ops;
384384 def GPR;
404404 multiclass. Using a multiclass this way is exactly equivalent to instantiating
405405 the classes multiple times yourself, e.g. by writing:
406406
407 .. code-block:: llvm
407 .. code-block:: text
408408
409409 def ops;
410410 def GPR;
431431 A ``defm`` can also be used inside a multiclass providing several levels of
432432 multiclass instantiations.
433433
434 .. code-block:: llvm
434 .. code-block:: text
435435
436436 class Instruction opc, string Name> {
437437 bits<4> opcode = opc;
472472 the class list must start after the last multiclass, and there must be at least
473473 one multiclass before them.
474474
475 .. code-block:: llvm
475 .. code-block:: text
476476
477477 class XD { bits<4> Prefix = 11; }
478478 class XS { bits<4> Prefix = 12; }
515515 specified as a double quoted string immediately after the '``include``' keyword.
516516 Example:
517517
518 .. code-block:: llvm
518 .. code-block:: text
519519
520520 include "foo.td"
521521
531531 File-scope "let" expressions take a comma-separated list of bindings to apply,
532532 and one or more records to bind the values in. Here are some examples:
533533
534 .. code-block:: llvm
534 .. code-block:: text
535535
536536 let isTerminator = 1, isReturn = 1, isBarrier = 1, hasCtrlDep = 1 in
537537 def RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;
558558 levels of multiclass instantiations. This also avoids the need of using "let"
559559 expressions within subsequent records inside a multiclass.
560560
561 .. code-block:: llvm
561 .. code-block:: text
562562
563563 multiclass basic_r opc> {
564564 let Predicates = [HasSSE2] in {
586586 body, substituting iterator values for iterator references in the body.
587587 Example:
588588
589 .. code-block:: llvm
589 .. code-block:: text
590590
591591 foreach i = [0, 1, 2, 3] in {
592592 def R#i : Register<...>;
597597 may be nested. If there is only one item in the body the braces may be
598598 elided:
599599
600 .. code-block:: llvm
600 .. code-block:: text
601601
602602 foreach i = [0, 1, 2, 3] in
603603 def R#i : Register<...>;
8989 various definitions expand to fully. Running this on the ``X86.td`` file prints
9090 this (at the time of this writing):
9191
92 .. code-block:: llvm
92 .. code-block:: text
9393
9494 ...
9595 def ADD32rr { // Instruction X86Inst I
154154 prone to bugs, and tiring to do in the first place. Because we are using
155155 TableGen, all of the information was derived from the following definition:
156156
157 .. code-block:: llvm
157 .. code-block:: text
158158
159159 let Defs = [EFLAGS],
160160 isCommutable = 1, // X = ADD Y,Z --> X = ADD Z,Y
200200 **TableGen definitions** are the concrete form of 'records'. These generally do
201201 not have any undefined values, and are marked with the '``def``' keyword.
202202
203 .. code-block:: llvm
203 .. code-block:: text
204204
205205 def FeatureFPARMv8 : SubtargetFeature<"fp-armv8", "HasFPARMv8", "true",
206206 "Enable ARMv8 FP">;
219219 the classes that are used to build up a definition, so the backend can find all
220220 definitions of a particular class, such as "Instruction".
221221
222 .. code-block:: llvm
222 .. code-block:: text
223223
224224 class ProcNoItin Features>
225225 : Processor;
234234 sub-multiclass become part of the current multiclass, as if they were declared
235235 in the current multiclass.
236236
237 .. code-block:: llvm
237 .. code-block:: text
238238
239239 multiclass ro_signed_pats
240240 dag address, ValueType sty> {
344344 ``Name`` of the register. The basic ``Register`` object does not have any
345345 subregisters and does not specify any aliases.
346346
347 .. code-block:: llvm
347 .. code-block:: text
348348
349349 class Register {
350350 string Namespace = "";
360360 For example, in the ``X86RegisterInfo.td`` file, there are register definitions
361361 that utilize the ``Register`` class, such as:
362362
363 .. code-block:: llvm
363 .. code-block:: text
364364
365365 def AL : Register<"AL">, DwarfRegNum<[0, 0, 0]>;
366366
413413 ``RegisterWithSubRegs`` class that is used to define registers that need to
414414 specify subregisters in the ``SubRegs`` list, as shown here:
415415
416 .. code-block:: llvm
416 .. code-block:: text
417417
418418 class RegisterWithSubRegs subregs> : Register {
419419 let SubRegs = subregs;
426426 override values that are initially defined in a superclass (such as ``SubRegs``
427427 field in the ``Rd`` class).
428428
429 .. code-block:: llvm
429 .. code-block:: text
430430
431431 class SparcReg : Register {
432432 field bits<5> Num;
451451 In the ``SparcRegisterInfo.td`` file, there are register definitions that
452452 utilize these subclasses of ``Register``, such as:
453453
454 .. code-block:: llvm
454 .. code-block:: text
455455
456456 def G0 : Ri< 0, "G0">, DwarfRegNum<[0]>;
457457 def G1 : Ri< 1, "G1">, DwarfRegNum<[1]>;
477477 ``XXXRegisterInfo.td`` that uses ``Target.td`` can construct register classes
478478 using the following class:
479479
480 .. code-block:: llvm
480 .. code-block:: text
481481
482482 class RegisterClass
483483 list regTypes, int alignment, dag regList> {
531531 ``F31``); ``DFPRegs`` defines a group of 16 double-precision registers
532532 (``D0-D15``).
533533
534 .. code-block:: llvm
534 .. code-block:: text
535535
536536 // F0, F1, F2, ..., F31
537537 def FPRegs : RegisterClass<"SP", [f32], 32, (sequence "F%u", 0, 31)>;
702702 The Instruction class (defined in ``Target.td``) is mostly used as a base for
703703 more complex instruction classes.
704704
705 .. code-block:: llvm
705 .. code-block:: text
706706
707707 class Instruction {
708708 string Namespace = "";
759759 output destination, which is a register operand and defined in the ``Register``
760760 target description file (``IntRegs``).
761761
762 .. code-block:: llvm
762 .. code-block:: text
763763
764764 def LDrr : F3_1 <3, 0b000000, (outs IntRegs:$dst), (ins MEMrr:$addr),
765765 "ld [$addr], $dst",
768768 The fourth parameter is the input source, which uses the address operand
769769 ``MEMrr`` that is defined earlier in ``SparcInstrInfo.td``:
770770
771 .. code-block:: llvm
771 .. code-block:: text
772772
773773 def MEMrr : Operand {
774774 let PrintMethod = "printMemOperand";
787787 for a Word from an immediate operand to a register, the following instruction
788788 class is defined:
789789
790 .. code-block:: llvm
790 .. code-block:: text
791791
792792 def LDri : F3_2 <3, 0b000000, (outs IntRegs:$dst), (ins MEMri:$addr),
793793 "ld [$addr], $dst",
800800 pattern ``F3_12`` is defined to create 2 instruction classes each time
801801 ``F3_12`` is invoked:
802802
803 .. code-block:: llvm
803 .. code-block:: text
804804
805805 multiclass F3_12 Op3Val, SDNode OpNode> {
806806 def rr : F3_1 <2, Op3Val,
817817 instructions, as seen below, it creates four instruction objects: ``XORrr``,
818818 ``XORri``, ``ADDrr``, and ``ADDri``.
819819
820 .. code-block:: llvm
820 .. code-block:: text
821821
822822 defm XOR : F3_12<"xor", 0b000011, xor>;
823823 defm ADD : F3_12<"add", 0b000000, add>;
829829 integers, and the 22\ :sup:`nd` bit represents the "greater than" condition for
830830 floats.
831831
832 .. code-block:: llvm
832 .. code-block:: text
833833
834834 def ICC_NE : ICC_VAL< 9>; // Not Equal
835835 def ICC_E : ICC_VAL< 1>; // Equal
854854 example, the Sparc target defines the ``XNORrr`` instruction as a ``F3_1``
855855 format instruction having three operands.
856856
857 .. code-block:: llvm
857 .. code-block:: text
858858
859859 def XNORrr : F3_1<2, 0b000111,
860860 (outs IntRegs:$dst), (ins IntRegs:$b, IntRegs:$c),
864864 The instruction templates in ``SparcInstrFormats.td`` show the base class for
865865 ``F3_1`` is ``InstSP``.
866866
867 .. code-block:: llvm
867 .. code-block:: text
868868
869869 class InstSP pattern> : Instruction {
870870 field bits<32> Inst;
879879
880880 ``InstSP`` leaves the ``op`` field unbound.
881881
882 .. code-block:: llvm
882 .. code-block:: text
883883
884884 class F3 pattern>
885885 : InstSP {
896896 fields. ``F3`` format instructions will bind the operands ``rd``, ``op3``, and
897897 ``rs1`` fields.
898898
899 .. code-block:: llvm
899 .. code-block:: text
900900
901901 class F3_1 opVal, bits<6> op3val, dag outs, dag ins,
902902 string asmstr, list pattern> : F3 {
924924 llvm::XXX:OpName namespace and also add an entry for it into the OperandMap
925925 table, which can be queried using getNamedOperandIdx()
926926
927 .. code-block:: llvm
927 .. code-block:: text
928928
929929 int DstIndex = SP::getNamedOperandIdx(SP::XNORrr, SP::OpName::dst); // => 0
930930 int BIndex = SP::getNamedOperandIdx(SP::XNORrr, SP::OpName::b); // => 1
971971 instances of the TableGen ``Operand`` class, which represent branch target
972972 operands:
973973
974 .. code-block:: llvm
974 .. code-block:: text
975975
976976 def brtarget : Operand;
977977 def brtarget8 : Operand;
12211221 this entry defines a register store operation, and the last parameter describes
12221222 a pattern with the store DAG operator.
12231223
1224 .. code-block:: llvm
1224 .. code-block:: text
12251225
12261226 def STrr : F3_1< 3, 0b000100, (outs), (ins MEMrr:$addr, IntRegs:$src),
12271227 "st $src, [$addr]", [(store i32:$src, ADDRrr:$addr)]>;
12281228
12291229 ``ADDRrr`` is a memory mode that is also defined in ``SparcInstrInfo.td``:
12301230
1231 .. code-block:: llvm
1231 .. code-block:: text
12321232
12331233 def ADDRrr : ComplexPattern;
12341234
12391239 In ``lib/Target/TargetSelectionDAG.td``, the DAG operator for store is defined
12401240 below:
12411241
1242 .. code-block:: llvm
1242 .. code-block:: text
12431243
12441244 def store : PatFrag<(ops node:$val, node:$ptr),
12451245 (st node:$val, node:$ptr), [{
14571457 performed. In this case, the ``CCAssignToReg`` action assigns the argument
14581458 value to the first available register: either ``R0`` or ``R1``.
14591459
1460 .. code-block:: llvm
1460 .. code-block:: text
14611461
14621462 CCIfType<[f32,f64], CCAssignToReg<[R0, R1]>>
14631463
14681468 float is returned to register ``F0``, and a double-precision float goes to
14691469 register ``D0``. A 32-bit integer is returned in register ``I0`` or ``I1``.
14701470
1471 .. code-block:: llvm
1471 .. code-block:: text
14721472
14731473 def RetCC_Sparc32 : CallingConv<[
14741474 CCIfType<[i32], CCAssignToReg<[I0, I1]>>,
14831483 alignment along 4-byte units. (Special cases: if size is zero, then the ABI
14841484 size is used; if alignment is zero, then the ABI alignment is used.)
14851485
1486 .. code-block:: llvm
1486 .. code-block:: text
14871487
14881488 def CC_Sparc32 : CallingConv<[
14891489 // All arguments get passed in integer registers if there is space.
14981498 assigned to the register ``ST0`` or ``ST1``, the ``RetCC_X86Common`` is
14991499 invoked.
15001500
1501 .. code-block:: llvm
1501 .. code-block:: text
15021502
15031503 def RetCC_X86_32_C : CallingConv<[
15041504 CCIfType<[f32], CCAssignToReg<[ST0, ST1]>>,
15131513 ``RetCC_X86_32_Fast`` is invoked. If the ``SSECall`` calling convention is in
15141514 use, then ``RetCC_X86_32_SSE`` is invoked.
15151515
1516 .. code-block:: llvm
1516 .. code-block:: text
15171517
15181518 def RetCC_X86_32 : CallingConv<[
15191519 CCIfCC<"CallingConv::Fast", CCDelegateTo>,
16811681 fifth parameter is a list of features whose presence is implied, and its
16821682 default value is an empty array.)
16831683
1684 .. code-block:: llvm
1684 .. code-block:: text
16851685
16861686 class SubtargetFeature
16871687 list i = []> {
16951695 In the ``Sparc.td`` file, the ``SubtargetFeature`` is used to define the
16961696 following features.
16971697
1698 .. code-block:: llvm
1698 .. code-block:: text
16991699
17001700 def FeatureV9 : SubtargetFeature<"v9", "IsV9", "true",
17011701 "Enable SPARC-V9 instructions">;
17091709 define particular SPARC processor subtypes that may have the previously
17101710 described features.
17111711
1712 .. code-block:: llvm
1712 .. code-block:: text
17131713
17141714 class Proc Features>
17151715 : Processor;
746746 line to specify that the pass should be added to a program (for example, with
747747 :program:`opt` or :program:`bugpoint`). The first argument is the name of the
748748 pass, which is to be used for the :option:`-help` output of programs, as well
749 as for debug output generated by the :option:`--debug-pass` option.
749 as for debug output generated by the `--debug-pass` option.
750750
751751 If you want your pass to be easily dumpable, you should implement the virtual
752752 print method: