llvm.org GIT mirror llvm / d04e60e
docs: Document function-attached metadata and IR changes from r252219. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@252268 91177308-0d34-0410-b5e6-96231b3b80d8 Peter Collingbourne 3 years ago
2 changed file(s) with 40 addition(s) and 25 deletion(s). Raw diff Collapse all Expand all
639639 an optional :ref:`garbage collector name `, an optional :ref:`prefix `,
640640 an optional :ref:`prologue `,
641641 an optional :ref:`personality `,
642 an optional list of attached :ref:`metadata `,
642643 an opening curly brace, a list of basic blocks, and a closing curly brace.
643644
644645 LLVM function declarations consist of the "``declare``" keyword, an
687688 @ ([argument list])
688689 [unnamed_addr] [fn Attrs] [section "name"] [comdat [($name)]]
689690 [align N] [gc] [prefix Constant] [prologue Constant]
690 [personality Constant] { ... }
691 [personality Constant] (!name !N)* { ... }
691692
692693 The argument list is a comma separated sequence of arguments where each
693694 argument is of the following form:
36233624
36243625 call void @llvm.dbg.value(metadata !24, i64 0, metadata !25)
36253626
3626 Metadata can be attached with an instruction. Here metadata ``!21`` is
3627 attached to the ``add`` instruction using the ``!dbg`` identifier:
3627 Metadata can be attached to an instruction. Here metadata ``!21`` is attached
3628 to the ``add`` instruction using the ``!dbg`` identifier:
36283629
36293630 .. code-block:: llvm
36303631
36313632 %indvar.next = add i64 %indvar, 1, !dbg !21
3633
3634 Metadata can also be attached to a function definition. Here metadata ``!22``
3635 is attached to the ``foo`` function using the ``!dbg`` identifier:
3636
3637 .. code-block:: llvm
3638
3639 define void @foo() !dbg !22 {
3640 ret void
3641 }
36323642
36333643 More information about specific metadata nodes recognized by the
36343644 optimizers and code generator is found below.
39003910 DISubprogram
39013911 """"""""""""
39023912
3903 ``DISubprogram`` nodes represent functions from the source language. The
3904 ``variables:`` field points at :ref:`variables ` that must be
3905 retained, even if their IR counterparts are optimized out of the IR. The
3906 ``type:`` field must point at an :ref:`DISubroutineType`.
3907
3908 .. code-block:: llvm
3909
3910 !0 = !DISubprogram(name: "foo", linkageName: "_Zfoov", scope: !1,
3911 file: !2, line: 7, type: !3, isLocal: true,
3912 isDefinition: false, scopeLine: 8, containingType: !4,
3913 virtuality: DW_VIRTUALITY_pure_virtual, virtualIndex: 10,
3914 flags: DIFlagPrototyped, isOptimized: true,
3915 function: void ()* @_Z3foov,
3916 templateParams: !5, declaration: !6, variables: !7)
3913 ``DISubprogram`` nodes represent functions from the source language. A
3914 ``DISubprogram`` may be attached to a function definition using ``!dbg``
3915 metadata. The ``variables:`` field points at :ref:`variables `
3916 that must be retained, even if their IR counterparts are optimized out of
3917 the IR. The ``type:`` field must point at an :ref:`DISubroutineType`.
3918
3919 .. code-block:: llvm
3920
3921 define void @_Z3foov() !dbg !0 {
3922 ...
3923 }
3924
3925 !0 = distinct !DISubprogram(name: "foo", linkageName: "_Zfoov", scope: !1,
3926 file: !2, line: 7, type: !3, isLocal: true,
3927 isDefinition: false, scopeLine: 8,
3928 containingType: !4,
3929 virtuality: DW_VIRTUALITY_pure_virtual,
3930 virtualIndex: 10, flags: DIFlagPrototyped,
3931 isOptimized: true, templateParams: !5,
3932 declaration: !6, variables: !7)
39173933
39183934 .. _DILexicalBlock:
39193935
230230 .. code-block:: llvm
231231
232232 ; Function Attrs: nounwind ssp uwtable
233 define void @foo() #0 {
233 define void @foo() #0 !dbg !4 {
234234 entry:
235235 %X = alloca i32, align 4
236236 %Y = alloca i32, align 4
262262 !1 = !DIFile(filename: "/dev/stdin", directory: "/Users/dexonsmith/data/llvm/debug-info")
263263 !2 = !{}
264264 !3 = !{!4}
265 !4 = distinct !DISubprogram(name: "foo", scope: !1, file: !1, line: 1, type: !5, isLocal: false, isDefinition: true, scopeLine: 1, isOptimized: false, function: void ()* @foo, variables: !2)
265 !4 = distinct !DISubprogram(name: "foo", scope: !1, file: !1, line: 1, type: !5, isLocal: false, isDefinition: true, scopeLine: 1, isOptimized: false, variables: !2)
266266 !5 = !DISubroutineType(types: !6)
267267 !6 = !{null}
268268 !7 = !{i32 2, !"Dwarf Version", i32 2}
303303 .. code-block:: llvm
304304
305305 !14 = !DILocation(line: 2, column: 9, scope: !4)
306 !4 = !DISubprogram(name: "foo", scope: !1, file: !1, line: 1, type: !5,
307 isLocal: false, isDefinition: true, scopeLine: 1,
308 isOptimized: false, function: void ()* @foo,
309 variables: !2)
306 !4 = distinct !DISubprogram(name: "foo", scope: !1, file: !1, line: 1, type: !5,
307 isLocal: false, isDefinition: true, scopeLine: 1,
308 isOptimized: false, variables: !2)
310309
311310 Here ``!14`` is metadata providing `location information
312311 `_. In this example, scope is encoded by ``!4``, a
462461 !4 = !DISubprogram(name: "main", scope: !1, file: !1, line: 1, type: !5,
463462 isLocal: false, isDefinition: true, scopeLine: 1,
464463 flags: DIFlagPrototyped, isOptimized: false,
465 function: i32 (i32, i8**)* @main, variables: !2)
464 variables: !2)
466465
467466 ;;
468467 ;; Define the subprogram itself.
469468 ;;
470 define i32 @main(i32 %argc, i8** %argv) {
469 define i32 @main(i32 %argc, i8** %argv) !dbg !4 {
471470 ...
472471 }
473472