From ffd2f5051ef6c5ee95f974ccefff67db38ed2ed8 Mon Sep 17 00:00:00 2001 From: "Duncan P. N. Exon Smith" Date: Sat, 4 Oct 2014 14:56:56 +0000 Subject: [PATCH] DI: Update and prune metadata examples Update a couple of the examples of debug info metadata, and prune the rest. Point to the true reference implementation in the source. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@219051 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/SourceLevelDebugging.rst | 588 +++++----------------------------- 1 file changed, 86 insertions(+), 502 deletions(-) diff --git a/docs/SourceLevelDebugging.rst b/docs/SourceLevelDebugging.rst index 6bdfea0e27b..577e0000176 100644 --- a/docs/SourceLevelDebugging.rst +++ b/docs/SourceLevelDebugging.rst @@ -849,8 +849,11 @@ to provide completely different forms if they don't fit into the DWARF model. As support for debugging information gets added to the various LLVM source-language front-ends, the information used should be documented here. -The following sections provide examples of various C/C++ constructs and the -debug information that would best describe those constructs. +The following sections provide examples of a few C/C++ constructs and the debug +information that would best describe those constructs. The canonical +references are the ``DIDescriptor`` classes defined in +``include/llvm/IR/DebugInfo.h`` and the implementations of the helper functions +in ``lib/IR/DIBuilder.cpp``. C/C++ source file information ----------------------------- @@ -955,25 +958,35 @@ a C/C++ front-end would generate the following descriptors: ;; Define the compile unit. !0 = metadata !{ - i32 786449, ;; Tag - i32 0, ;; Context - i32 4, ;; Language - metadata !"foo.cpp", ;; File - metadata !"/Volumes/Data/tmp", ;; Directory - metadata !"clang version 3.1 ", ;; Producer - i1 true, ;; Deprecated field - i1 false, ;; "isOptimized"? - metadata !"", ;; Flags - i32 0, ;; Runtime Version - metadata !1, ;; Enum Types - metadata !1, ;; Retained Types - metadata !1, ;; Subprograms - metadata !3, ;; Global Variables - metadata !1, ;; Imported entities - "", ;; Split debug filename - 1, ;; Full debug info + ; Header( + ; i32 17, ;; Tag + ; i32 0, ;; Context + ; i32 4, ;; Language + ; metadata !"clang version 3.6.0 ", ;; Producer + ; i1 false, ;; "isOptimized"? + ; metadata !"", ;; Flags + ; i32 0, ;; Runtime Version + ; "", ;; Split debug filename + ; 1 ;; Full debug info + ; ) + metadata !"0x11\0012\00clang version 3.6.0 \000\00\000\00\001", + metadata !1, ;; File + metadata !2, ;; Enum Types + metadata !2, ;; Retained Types + metadata !2, ;; Subprograms + metadata !3, ;; Global Variables + metadata !2 ;; Imported entities } ; [ DW_TAG_compile_unit ] + ;; The file/directory pair. + !1 = metadata !{ + metadata !"foo.c", ;; Filename + metadata !"/Users/dexonsmith/data/llvm/debug-info" ;; Directory + } + + ;; An empty array. + !2 = metadata !{} + ;; The Array of Global Variables !3 = metadata !{ metadata !4 @@ -983,17 +996,19 @@ a C/C++ front-end would generate the following descriptors: ;; Define the global variable itself. ;; !4 = metadata !{ - i32 786484, ;; Tag - i32 0, ;; Unused + ; Header( + ; i32 52, ;; Tag + ; metadata !"MyGlobal", ;; Name + ; metadata !"MyGlobal", ;; Display Name + ; metadata !"", ;; Linkage Name + ; i32 1, ;; Line + ; i32 0, ;; IsLocalToUnit + ; i32 1 ;; IsDefinition + ; ) + metadata !"0x34\00MyGlobal\00MyGlobal\00\001\000\001", null, ;; Unused - metadata !"MyGlobal", ;; Name - metadata !"MyGlobal", ;; Display Name - metadata !"", ;; Linkage Name - metadata !6, ;; File - i32 1, ;; Line - metadata !7, ;; Type - i32 0, ;; IsLocalToUnit - i32 1, ;; IsDefinition + metadata !5, ;; File + metadata !6, ;; Type i32* @MyGlobal, ;; LLVM-IR Value null ;; Static member declaration } ; [ DW_TAG_variable ] @@ -1002,28 +1017,29 @@ a C/C++ front-end would generate the following descriptors: ;; Define the file ;; !5 = metadata !{ - metadata !"foo.cpp", ;; File - metadata !"/Volumes/Data/tmp", ;; Directory - } - !6 = metadata !{ - i32 786473, ;; Tag - metadata !5 ;; Unused + Header( + i32 41 ;; Tag + ), ;; metadata !"0x29" + metadata !1 ;; File/directory pair } ; [ DW_TAG_file_type ] ;; ;; Define the type ;; - !7 = metadata !{ - i32 786468, ;; Tag - null, ;; Unused - null, ;; Unused - metadata !"int", ;; Name - i32 0, ;; Line - i64 32, ;; Size in Bits - i64 32, ;; Align in Bits - i64 0, ;; Offset - i32 0, ;; Flags - i32 5 ;; Encoding + !6 = metadata !{ + ; Header( + ; i32 36, ;; Tag + ; metadata !"int", ;; Name + ; i32 0, ;; Line + ; i64 32, ;; Size in Bits + ; i64 32, ;; Align in Bits + ; i64 0, ;; Offset + ; i32 0, ;; Flags + ; i32 5 ;; Encoding + ; ) + metadata !"0x24\00int\000\0032\0032\000\000\005", + null, ;; Unused + null ;; Unused } ; [ DW_TAG_base_type ] C/C++ function information @@ -1045,26 +1061,31 @@ a C/C++ front-end would generate the following descriptors: ;; Define the anchor for subprograms. ;; !6 = metadata !{ - i32 786484, ;; Tag - metadata !1, ;; File - metadata !1, ;; Context - metadata !"main", ;; Name - metadata !"main", ;; Display name - metadata !"main", ;; Linkage name - i32 1, ;; Line number - metadata !4, ;; Type - i1 false, ;; Is local - i1 true, ;; Is definition - i32 0, ;; Virtuality attribute, e.g. pure virtual function - i32 0, ;; Index into virtual table for C++ methods - i32 0, ;; Type that holds virtual table. - i32 0, ;; Flags - i1 false, ;; True if this function is optimized - Function *, ;; Pointer to llvm::Function - null, ;; Function template parameters - null, ;; List of function variables (emitted when optimizing) - 1 ;; Line number of the opening '{' of the function + ; Header( + ; i32 46, ;; Tag + ; metadata !"main", ;; Name + ; metadata !"main", ;; Display name + ; metadata !"", ;; Linkage name + ; i32 1, ;; Line number + ; i1 false, ;; Is local + ; i1 true, ;; Is definition + ; i32 0, ;; Virtuality attribute, e.g. pure virtual function + ; i32 0, ;; Index into virtual table for C++ methods + ; i32 256, ;; Flags + ; i1 0, ;; True if this function is optimized + ; 1 ;; Line number of the opening '{' of the function + ; ) + metadata !"0x2e\00main\00main\00\001\000\001\000\000\00256\000\001", + metadata !1, ;; File + metadata !5, ;; Context + metadata !6, ;; Type + null, ;; Containing type + i32 (i32, i8**)* @main, ;; Pointer to llvm::Function + null, ;; Function template parameters + null, ;; Function declaration + metadata !2 ;; List of function variables (emitted when optimizing) } + ;; ;; Define the subprogram itself. ;; @@ -1072,443 +1093,6 @@ a C/C++ front-end would generate the following descriptors: ... } -C/C++ basic types ------------------ - -The following are the basic type descriptors for C/C++ core types: - -bool -^^^^ - -.. code-block:: llvm - - !2 = metadata !{ - i32 786468, ;; Tag - null, ;; File - null, ;; Context - metadata !"bool", ;; Name - i32 0, ;; Line number - i64 8, ;; Size in Bits - i64 8, ;; Align in Bits - i64 0, ;; Offset in Bits - i32 0, ;; Flags - i32 2 ;; Encoding - } - -char -^^^^ - -.. code-block:: llvm - - !2 = metadata !{ - i32 786468, ;; Tag - null, ;; File - null, ;; Context - metadata !"char", ;; Name - i32 0, ;; Line number - i64 8, ;; Size in Bits - i64 8, ;; Align in Bits - i64 0, ;; Offset in Bits - i32 0, ;; Flags - i32 6 ;; Encoding - } - -unsigned char -^^^^^^^^^^^^^ - -.. code-block:: llvm - - !2 = metadata !{ - i32 786468, ;; Tag - null, ;; File - null, ;; Context - metadata !"unsigned char", - i32 0, ;; Line number - i64 8, ;; Size in Bits - i64 8, ;; Align in Bits - i64 0, ;; Offset in Bits - i32 0, ;; Flags - i32 8 ;; Encoding - } - -short -^^^^^ - -.. code-block:: llvm - - !2 = metadata !{ - i32 786468, ;; Tag - null, ;; File - null, ;; Context - metadata !"short int", - i32 0, ;; Line number - i64 16, ;; Size in Bits - i64 16, ;; Align in Bits - i64 0, ;; Offset in Bits - i32 0, ;; Flags - i32 5 ;; Encoding - } - -unsigned short -^^^^^^^^^^^^^^ - -.. code-block:: llvm - - !2 = metadata !{ - i32 786468, ;; Tag - null, ;; File - null, ;; Context - metadata !"short unsigned int", - i32 0, ;; Line number - i64 16, ;; Size in Bits - i64 16, ;; Align in Bits - i64 0, ;; Offset in Bits - i32 0, ;; Flags - i32 7 ;; Encoding - } - -int -^^^ - -.. code-block:: llvm - - !2 = metadata !{ - i32 786468, ;; Tag - null, ;; File - null, ;; Context - metadata !"int", ;; Name - i32 0, ;; Line number - i64 32, ;; Size in Bits - i64 32, ;; Align in Bits - i64 0, ;; Offset in Bits - i32 0, ;; Flags - i32 5 ;; Encoding - } - -unsigned int -^^^^^^^^^^^^ - -.. code-block:: llvm - - !2 = metadata !{ - i32 786468, ;; Tag - null, ;; File - null, ;; Context - metadata !"unsigned int", - i32 0, ;; Line number - i64 32, ;; Size in Bits - i64 32, ;; Align in Bits - i64 0, ;; Offset in Bits - i32 0, ;; Flags - i32 7 ;; Encoding - } - -long long -^^^^^^^^^ - -.. code-block:: llvm - - !2 = metadata !{ - i32 786468, ;; Tag - null, ;; File - null, ;; Context - metadata !"long long int", - i32 0, ;; Line number - i64 64, ;; Size in Bits - i64 64, ;; Align in Bits - i64 0, ;; Offset in Bits - i32 0, ;; Flags - i32 5 ;; Encoding - } - -unsigned long long -^^^^^^^^^^^^^^^^^^ - -.. code-block:: llvm - - !2 = metadata !{ - i32 786468, ;; Tag - null, ;; File - null, ;; Context - metadata !"long long unsigned int", - i32 0, ;; Line number - i64 64, ;; Size in Bits - i64 64, ;; Align in Bits - i64 0, ;; Offset in Bits - i32 0, ;; Flags - i32 7 ;; Encoding - } - -float -^^^^^ - -.. code-block:: llvm - - !2 = metadata !{ - i32 786468, ;; Tag - null, ;; File - null, ;; Context - metadata !"float", - i32 0, ;; Line number - i64 32, ;; Size in Bits - i64 32, ;; Align in Bits - i64 0, ;; Offset in Bits - i32 0, ;; Flags - i32 4 ;; Encoding - } - -double -^^^^^^ - -.. code-block:: llvm - - !2 = metadata !{ - i32 786468, ;; Tag - null, ;; File - null, ;; Context - metadata !"double",;; Name - i32 0, ;; Line number - i64 64, ;; Size in Bits - i64 64, ;; Align in Bits - i64 0, ;; Offset in Bits - i32 0, ;; Flags - i32 4 ;; Encoding - } - -C/C++ derived types -------------------- - -Given the following as an example of C/C++ derived type: - -.. code-block:: c - - typedef const int *IntPtr; - -a C/C++ front-end would generate the following descriptors: - -.. code-block:: llvm - - ;; - ;; Define the typedef "IntPtr". - ;; - !2 = metadata !{ - i32 786454, ;; Tag - metadata !3, ;; File - metadata !1, ;; Context - metadata !"IntPtr", ;; Name - i32 0, ;; Line number - i64 0, ;; Size in bits - i64 0, ;; Align in bits - i64 0, ;; Offset in bits - i32 0, ;; Flags - metadata !4 ;; Derived From type - } - ;; - ;; Define the pointer type. - ;; - !4 = metadata !{ - i32 786447, ;; Tag - null, ;; File - null, ;; Context - metadata !"", ;; Name - i32 0, ;; Line number - i64 64, ;; Size in bits - i64 64, ;; Align in bits - i64 0, ;; Offset in bits - i32 0, ;; Flags - metadata !5 ;; Derived From type - } - ;; - ;; Define the const type. - ;; - !5 = metadata !{ - i32 786470, ;; Tag - null, ;; File - null, ;; Context - metadata !"", ;; Name - i32 0, ;; Line number - i64 0, ;; Size in bits - i64 0, ;; Align in bits - i64 0, ;; Offset in bits - i32 0, ;; Flags - metadata !6 ;; Derived From type - } - ;; - ;; Define the int type. - ;; - !6 = metadata !{ - i32 786468, ;; Tag - null, ;; File - null, ;; Context - metadata !"int", ;; Name - i32 0, ;; Line number - i64 32, ;; Size in bits - i64 32, ;; Align in bits - i64 0, ;; Offset in bits - i32 0, ;; Flags - i32 5 ;; Encoding - } - -C/C++ struct/union types ------------------------- - -Given the following as an example of C/C++ struct type: - -.. code-block:: c - - struct Color { - unsigned Red; - unsigned Green; - unsigned Blue; - }; - -a C/C++ front-end would generate the following descriptors: - -.. code-block:: llvm - - ;; - ;; Define basic type for unsigned int. - ;; - !5 = metadata !{ - i32 786468, ;; Tag - null, ;; File - null, ;; Context - metadata !"unsigned int", - i32 0, ;; Line number - i64 32, ;; Size in Bits - i64 32, ;; Align in Bits - i64 0, ;; Offset in Bits - i32 0, ;; Flags - i32 7 ;; Encoding - } - ;; - ;; Define composite type for struct Color. - ;; - !2 = metadata !{ - i32 786451, ;; Tag - metadata !1, ;; Compile unit - null, ;; Context - metadata !"Color", ;; Name - i32 1, ;; Line number - i64 96, ;; Size in bits - i64 32, ;; Align in bits - i64 0, ;; Offset in bits - i32 0, ;; Flags - null, ;; Derived From - metadata !3, ;; Elements - i32 0, ;; Runtime Language - null, ;; Base type containing the vtable pointer for this type - null ;; Template parameters - } - - ;; - ;; Define the Red field. - ;; - !4 = metadata !{ - i32 786445, ;; Tag - metadata !1, ;; File - metadata !1, ;; Context - metadata !"Red", ;; Name - i32 2, ;; Line number - i64 32, ;; Size in bits - i64 32, ;; Align in bits - i64 0, ;; Offset in bits - i32 0, ;; Flags - metadata !5 ;; Derived From type - } - - ;; - ;; Define the Green field. - ;; - !6 = metadata !{ - i32 786445, ;; Tag - metadata !1, ;; File - metadata !1, ;; Context - metadata !"Green", ;; Name - i32 3, ;; Line number - i64 32, ;; Size in bits - i64 32, ;; Align in bits - i64 32, ;; Offset in bits - i32 0, ;; Flags - metadata !5 ;; Derived From type - } - - ;; - ;; Define the Blue field. - ;; - !7 = metadata !{ - i32 786445, ;; Tag - metadata !1, ;; File - metadata !1, ;; Context - metadata !"Blue", ;; Name - i32 4, ;; Line number - i64 32, ;; Size in bits - i64 32, ;; Align in bits - i64 64, ;; Offset in bits - i32 0, ;; Flags - metadata !5 ;; Derived From type - } - - ;; - ;; Define the array of fields used by the composite type Color. - ;; - !3 = metadata !{metadata !4, metadata !6, metadata !7} - -C/C++ enumeration types ------------------------ - -Given the following as an example of C/C++ enumeration type: - -.. code-block:: c - - enum Trees { - Spruce = 100, - Oak = 200, - Maple = 300 - }; - -a C/C++ front-end would generate the following descriptors: - -.. code-block:: llvm - - ;; - ;; Define composite type for enum Trees - ;; - !2 = metadata !{ - i32 786436, ;; Tag - metadata !1, ;; File - metadata !1, ;; Context - metadata !"Trees", ;; Name - i32 1, ;; Line number - i64 32, ;; Size in bits - i64 32, ;; Align in bits - i64 0, ;; Offset in bits - i32 0, ;; Flags - null, ;; Derived From type - metadata !3, ;; Elements - i32 0 ;; Runtime language - } - - ;; - ;; Define the array of enumerators used by composite type Trees. - ;; - !3 = metadata !{metadata !4, metadata !5, metadata !6} - - ;; - ;; Define Spruce enumerator. - ;; - !4 = metadata !{i32 786472, metadata !"Spruce", i64 100} - - ;; - ;; Define Oak enumerator. - ;; - !5 = metadata !{i32 786472, metadata !"Oak", i64 200} - - ;; - ;; Define Maple enumerator. - ;; - !6 = metadata !{i32 786472, metadata !"Maple", i64 300} - Debugging information format ============================ -- 2.34.1