From d04e60e1665baf340d43a35b2c44f330b4a97b71 Mon Sep 17 00:00:00 2001 From: Peter Collingbourne Date: Fri, 6 Nov 2015 02:41:02 +0000 Subject: [PATCH] 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 --- docs/LangRef.rst | 44 ++++++++++++++++++++++++----------- docs/SourceLevelDebugging.rst | 15 ++++++------ 2 files changed, 37 insertions(+), 22 deletions(-) diff --git a/docs/LangRef.rst b/docs/LangRef.rst index 388bb6b1642..507c3bfd334 100644 --- a/docs/LangRef.rst +++ b/docs/LangRef.rst @@ -640,6 +640,7 @@ an optional :ref:`comdat `, an optional :ref:`garbage collector name `, an optional :ref:`prefix `, an optional :ref:`prologue `, an optional :ref:`personality `, +an optional list of attached :ref:`metadata `, an opening curly brace, a list of basic blocks, and a closing curly brace. LLVM function declarations consist of the "``declare``" keyword, an @@ -688,7 +689,7 @@ Syntax:: @ ([argument list]) [unnamed_addr] [fn Attrs] [section "name"] [comdat [($name)]] [align N] [gc] [prefix Constant] [prologue Constant] - [personality Constant] { ... } + [personality Constant] (!name !N)* { ... } The argument list is a comma separated sequence of arguments where each argument is of the following form: @@ -3624,13 +3625,22 @@ function is using two metadata arguments: call void @llvm.dbg.value(metadata !24, i64 0, metadata !25) -Metadata can be attached with an instruction. Here metadata ``!21`` is -attached to the ``add`` instruction using the ``!dbg`` identifier: +Metadata can be attached to an instruction. Here metadata ``!21`` is attached +to the ``add`` instruction using the ``!dbg`` identifier: .. code-block:: llvm %indvar.next = add i64 %indvar, 1, !dbg !21 +Metadata can also be attached to a function definition. Here metadata ``!22`` +is attached to the ``foo`` function using the ``!dbg`` identifier: + +.. code-block:: llvm + + define void @foo() !dbg !22 { + ret void + } + More information about specific metadata nodes recognized by the optimizers and code generator is found below. @@ -3901,20 +3911,26 @@ All global variables should be referenced by the `globals:` field of a DISubprogram """""""""""" -``DISubprogram`` nodes represent functions from the source language. The -``variables:`` field points at :ref:`variables ` that must be -retained, even if their IR counterparts are optimized out of the IR. The -``type:`` field must point at an :ref:`DISubroutineType`. +``DISubprogram`` nodes represent functions from the source language. A +``DISubprogram`` may be attached to a function definition using ``!dbg`` +metadata. The ``variables:`` field points at :ref:`variables ` +that must be retained, even if their IR counterparts are optimized out of +the IR. The ``type:`` field must point at an :ref:`DISubroutineType`. .. code-block:: llvm - !0 = !DISubprogram(name: "foo", linkageName: "_Zfoov", scope: !1, - file: !2, line: 7, type: !3, isLocal: true, - isDefinition: false, scopeLine: 8, containingType: !4, - virtuality: DW_VIRTUALITY_pure_virtual, virtualIndex: 10, - flags: DIFlagPrototyped, isOptimized: true, - function: void ()* @_Z3foov, - templateParams: !5, declaration: !6, variables: !7) + define void @_Z3foov() !dbg !0 { + ... + } + + !0 = distinct !DISubprogram(name: "foo", linkageName: "_Zfoov", scope: !1, + file: !2, line: 7, type: !3, isLocal: true, + isDefinition: false, scopeLine: 8, + containingType: !4, + virtuality: DW_VIRTUALITY_pure_virtual, + virtualIndex: 10, flags: DIFlagPrototyped, + isOptimized: true, templateParams: !5, + declaration: !6, variables: !7) .. _DILexicalBlock: diff --git a/docs/SourceLevelDebugging.rst b/docs/SourceLevelDebugging.rst index ad98abdc7b9..270c44eb50b 100644 --- a/docs/SourceLevelDebugging.rst +++ b/docs/SourceLevelDebugging.rst @@ -231,7 +231,7 @@ Compiled to LLVM, this function would be represented like this: .. code-block:: llvm ; Function Attrs: nounwind ssp uwtable - define void @foo() #0 { + define void @foo() #0 !dbg !4 { entry: %X = alloca i32, align 4 %Y = alloca i32, align 4 @@ -263,7 +263,7 @@ Compiled to LLVM, this function would be represented like this: !1 = !DIFile(filename: "/dev/stdin", directory: "/Users/dexonsmith/data/llvm/debug-info") !2 = !{} !3 = !{!4} - !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) + !4 = distinct !DISubprogram(name: "foo", scope: !1, file: !1, line: 1, type: !5, isLocal: false, isDefinition: true, scopeLine: 1, isOptimized: false, variables: !2) !5 = !DISubroutineType(types: !6) !6 = !{null} !7 = !{i32 2, !"Dwarf Version", i32 2} @@ -304,10 +304,9 @@ scope information for the variable ``X``. .. code-block:: llvm !14 = !DILocation(line: 2, column: 9, scope: !4) - !4 = !DISubprogram(name: "foo", scope: !1, file: !1, line: 1, type: !5, - isLocal: false, isDefinition: true, scopeLine: 1, - isOptimized: false, function: void ()* @foo, - variables: !2) + !4 = distinct !DISubprogram(name: "foo", scope: !1, file: !1, line: 1, type: !5, + isLocal: false, isDefinition: true, scopeLine: 1, + isOptimized: false, variables: !2) Here ``!14`` is metadata providing `location information `_. In this example, scope is encoded by ``!4``, a @@ -463,12 +462,12 @@ a C/C++ front-end would generate the following descriptors: !4 = !DISubprogram(name: "main", scope: !1, file: !1, line: 1, type: !5, isLocal: false, isDefinition: true, scopeLine: 1, flags: DIFlagPrototyped, isOptimized: false, - function: i32 (i32, i8**)* @main, variables: !2) + variables: !2) ;; ;; Define the subprogram itself. ;; - define i32 @main(i32 %argc, i8** %argv) { + define i32 @main(i32 %argc, i8** %argv) !dbg !4 { ... } -- 2.34.1