llvm.org GIT mirror llvm / 8906493
docs: Update LangRef and SourceLevelDebugging Cleanup some bitrot in SourceLevelDebugging.rst. - Pull the still-relevant details about individual descriptors into LangRef.rst. Cut a lot of it to avoid over-describing the fields, as the C++ classes and assembly format are mostly self-describing now. If there's anything specific that I shouldn't have cut, let me know and I'll add it back. - Rewrite the remaining sections to refer to the new debug info hierarchy in LangRef.rst. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@232566 91177308-0d34-0410-b5e6-96231b3b80d8 Duncan P. N. Exon Smith 4 years ago
2 changed file(s) with 215 addition(s) and 677 deletion(s). Raw diff Collapse all Expand all
28962896 More information about specific metadata nodes recognized by the
28972897 optimizers and code generator is found below.
28982898
2899 .. _specialized-metadata:
2900
28992901 Specialized Metadata Nodes
29002902 ^^^^^^^^^^^^^^^^^^^^^^^^^^
29012903
29052907
29062908 These aren't inherently debug info centric, but currently all the specialized
29072909 metadata nodes are related to debug info.
2910
2911 .. _MDCompileUnit:
29082912
29092913 MDCompileUnit
29102914 """""""""""""
29232927 enums: !2, retainedTypes: !3, subprograms: !4,
29242928 globals: !5, imports: !6)
29252929
2930 Compile unit descriptors provide the root scope for objects declared in a
2931 specific compilation unit. File descriptors are defined using this scope.
2932 These descriptors are collected by a named metadata ``!llvm.dbg.cu``. They
2933 keep track of subprograms, global variables, type information, and imported
2934 entities (declarations and namespaces).
2935
2936 .. _MDFile:
2937
29262938 MDFile
29272939 """"""
29282940
29322944
29332945 !0 = !MDFile(filename: "path/to/file", directory: "/path/to/dir")
29342946
2947 Files are sometimes used in ``scope:`` fields, and are the only valid target
2948 for ``file:`` fields.
2949
29352950 .. _MDLocation:
29362951
29372952 MDBasicType
29382953 """""""""""
29392954
2940 ``MDBasicType`` nodes represent primitive types. ``tag:`` defaults to
2941 ``DW_TAG_base_type``.
2955 ``MDBasicType`` nodes represent primitive types, such as ``int``, ``bool`` and
2956 ``float``. ``tag:`` defaults to ``DW_TAG_base_type``.
29422957
29432958 .. code-block:: llvm
29442959
29452960 !0 = !MDBasicType(name: "unsigned char", size: 8, align: 8,
29462961 encoding: DW_ATE_unsigned_char)
29472962 !1 = !MDBasicType(tag: DW_TAG_unspecified_type, name: "decltype(nullptr)")
2963
2964 The ``encoding:`` describes the details of the type. Usually it's one of the
2965 following:
2966
2967 .. code-block:: llvm
2968
2969 DW_ATE_address = 1
2970 DW_ATE_boolean = 2
2971 DW_ATE_float = 4
2972 DW_ATE_signed = 5
2973 DW_ATE_signed_char = 6
2974 DW_ATE_unsigned = 7
2975 DW_ATE_unsigned_char = 8
29482976
29492977 .. _MDSubroutineType:
29502978
29622990 !1 = !BasicType(name: "char", size: 8, align: 8, DW_ATE_signed_char)
29632991 !2 = !MDSubroutineType(types: !{null, !0, !1}) ; void (int, char)
29642992
2993 .. _MDDerivedType:
2994
29652995 MDDerivedType
29662996 """""""""""""
29672997
29743004 encoding: DW_ATE_unsigned_char)
29753005 !1 = !MDDerivedType(tag: DW_TAG_pointer_type, baseType: !0, size: 32,
29763006 align: 32)
3007
3008 The following ``tag:`` values are valid:
3009
3010 .. code-block:: llvm
3011
3012 DW_TAG_formal_parameter = 5
3013 DW_TAG_member = 13
3014 DW_TAG_pointer_type = 15
3015 DW_TAG_reference_type = 16
3016 DW_TAG_typedef = 22
3017 DW_TAG_ptr_to_member_type = 31
3018 DW_TAG_const_type = 38
3019 DW_TAG_volatile_type = 53
3020 DW_TAG_restrict_type = 55
3021
3022 ``DW_TAG_member`` is used to define a member of a :ref:`composite type
3023 ` or :ref:`subprogram `. The type of the member
3024 is the ``baseType:``. The ``offset:`` is the member's bit offset.
3025 ``DW_TAG_formal_parameter`` is used to define a member which is a formal
3026 argument of a subprogram.
3027
3028 ``DW_TAG_typedef`` is used to provide a name for the ``baseType:``.
3029
3030 ``DW_TAG_pointer_type``, ``DW_TAG_reference_type``, ``DW_TAG_const_type``,
3031 ``DW_TAG_volatile_type`` and ``DW_TAG_restrict_type`` are used to qualify the
3032 ``baseType:``.
3033
3034 Note that the ``void *`` type is expressed as a type derived from NULL.
29773035
29783036 .. _MDCompositeType:
29793037
29973055 line: 2, size: 32, align: 32, identifier: "_M4Enum",
29983056 elements: !{!0, !1, !2})
29993057
3058 The following ``tag:`` values are valid:
3059
3060 .. code-block:: llvm
3061
3062 DW_TAG_array_type = 1
3063 DW_TAG_class_type = 2
3064 DW_TAG_enumeration_type = 4
3065 DW_TAG_structure_type = 19
3066 DW_TAG_union_type = 23
3067 DW_TAG_subroutine_type = 21
3068 DW_TAG_inheritance = 28
3069
3070
3071 For ``DW_TAG_array_type``, the ``elements:`` should be :ref:`subrange
3072 descriptors `, each representing the range of subscripts at that
3073 level of indexing. The ``DIFlagVector`` flag to ``flags:`` indicates that an
3074 array type is a native packed vector.
3075
3076 For ``DW_TAG_enumeration_type``, the ``elements:`` should be :ref:`enumerator
3077 descriptors `, each representing the definition of an enumeration
3078 value for the set. All enumeration type descriptors are collected in the
3079 ``enums:`` field of the :ref:`compile unit `.
3080
3081 For ``DW_TAG_structure_type``, ``DW_TAG_class_type``, and
3082 ``DW_TAG_union_type``, the ``elements:`` should be :ref:`derived types
3083 ` with ``tag: DW_TAG_member`` or ``tag: DW_TAG_inheritance``.
3084
3085 .. _MDSubrange:
3086
30003087 MDSubrange
30013088 """"""""""
30023089
30083095 !0 = !MDSubrange(count: 5, lowerBound: 0) ; array counting from 0
30093096 !1 = !MDSubrange(count: 5, lowerBound: 1) ; array counting from 1
30103097 !2 = !MDSubrange(count: -1) ; empty array.
3098
3099 .. _MDEnumerator:
30113100
30123101 MDEnumerator
30133102 """"""""""""
30653154 file: !2, line: 7, type: !3, isLocal: true,
30663155 isDefinition: false, variable: i32* @foo,
30673156 declaration: !4)
3157
3158 All global variables should be referenced by the `globals:` field of a
3159 :ref:`compile unit `.
30683160
30693161 .. _MDSubprogram:
30703162
30913183 MDLexicalBlock
30923184 """"""""""""""
30933185
3094 ``MDLexicalBlock`` nodes represent lexical blocks in the source language (a
3095 scope).
3096
3097 .. code-block:: llvm
3098
3099 !0 = !MDLexicalBlock(scope: !1, file: !2, line: 7, column: 35)
3186 ``MDLexicalBlock`` nodes describe nested blocks within a :ref:`subprogram
3187 `. The line number and column numbers are used to dinstinguish
3188 two lexical blocks at same depth. They are valid targets for ``scope:``
3189 fields.
3190
3191 .. code-block:: llvm
3192
3193 !0 = distinct !MDLexicalBlock(scope: !1, file: !2, line: 7, column: 35)
3194
3195 Usually lexical blocks are ``distinct`` to prevent node merging based on
3196 operands.
31003197
31013198 .. _MDLexicalBlockFile:
31023199
152152 To provide basic functionality, the LLVM debugger does have to make some
153153 assumptions about the source-level language being debugged, though it keeps
154154 these to a minimum. The only common features that the LLVM debugger assumes
155 exist are :ref:`source files `, and :ref:`program objects
156 `. These abstract objects are used by a debugger to
157 form stack traces, show information about local variables, etc.
155 exist are `source files `_, and `program objects
156 `_. These abstract objects are used by a
157 debugger to form stack traces, show information about local variables, etc.
158158
159159 This section of the documentation first describes the representation aspects
160160 common to any source-language. :ref:`ccxx_frontend` describes the data layout
161161 conventions used by the C and C++ front-ends.
162162
163 Debug information descriptors
164 -----------------------------
165
166 In consideration of the complexity and volume of debug information, LLVM
167 provides a specification for well formed debug descriptors.
168
169 Consumers of LLVM debug information expect the descriptors for program objects
170 to start in a canonical format, but the descriptors can include additional
171 information appended at the end that is source-language specific. All debugging
172 information objects start with a tag to indicate what type of object it is.
173 The source-language is allowed to define its own objects, by using unreserved
174 tag numbers. We recommend using with tags in the range 0x1000 through 0x2000
175 (there is a defined ``enum DW_TAG_user_base = 0x1000``.)
176
177 The fields of debug descriptors used internally by LLVM are restricted to only
178 the simple data types ``i32``, ``i1``, ``float``, ``double``, ``mdstring`` and
179 ``mdnode``.
180
181 .. code-block:: llvm
182
183 !1 = metadata !{
184 i32, ;; A tag
185 ...
186 }
187
188 Most of the string and integer fields in descriptors are packed into a single,
189 null-separated ``mdstring``. The first field of the header is always an
190 ``i32`` containing the DWARF tag value identifying the content of the
191 descriptor.
192
193 For clarity of definition in this document, these header fields are described
194 below split inside an imaginary ``DIHeader`` construct. This is invalid
195 assembly syntax. In valid IR, these fields are stringified and concatenated,
196 separated by ``\00``.
197
198 The details of the various descriptors follow.
199
200 Compile unit descriptors
201 ^^^^^^^^^^^^^^^^^^^^^^^^
202
203 .. code-block:: llvm
204
205 !0 = metadata !{
206 DIHeader(
207 i32, ;; Tag = 17 (DW_TAG_compile_unit)
208 i32, ;; DWARF language identifier (ex. DW_LANG_C89)
209 mdstring, ;; Producer (ex. "4.0.1 LLVM (LLVM research group)")
210 i1, ;; True if this is optimized.
211 mdstring, ;; Flags
212 i32, ;; Runtime version
213 mdstring, ;; Split debug filename
214 i32 ;; Debug info emission kind (1 = Full Debug Info, 2 = Line Tables Only)
215 ),
216 metadata, ;; Source directory (including trailing slash) & file pair
217 metadata, ;; List of enums types
218 metadata, ;; List of retained types
219 metadata, ;; List of subprograms
220 metadata, ;; List of global variables
221 metadata ;; List of imported entities
222 }
223
224 These descriptors contain a source language ID for the file (we use the DWARF
225 3.0 ID numbers, such as ``DW_LANG_C89``, ``DW_LANG_C_plus_plus``,
226 ``DW_LANG_Cobol74``, etc), a reference to a metadata node containing a pair of
227 strings for the source file name and the working directory, as well as an
228 identifier string for the compiler that produced it.
229
230 Compile unit descriptors provide the root context for objects declared in a
231 specific compilation unit. File descriptors are defined using this context.
232 These descriptors are collected by a named metadata ``!llvm.dbg.cu``. They
233 keep track of subprograms, global variables, type information, and imported
234 entities (declarations and namespaces).
235
236 .. _format_files:
237
238 File descriptors
239 ^^^^^^^^^^^^^^^^
240
241 .. code-block:: llvm
242
243 !0 = metadata !{
244 DIHeader(
245 i32 ;; Tag = 41 (DW_TAG_file_type)
246 ),
247 metadata ;; Source directory (including trailing slash) & file pair
248 }
249
250 These descriptors contain information for a file. Global variables and top
251 level functions would be defined using this context. File descriptors also
252 provide context for source line correspondence.
253
254 Each input file is encoded as a separate file descriptor in LLVM debugging
255 information output.
256
257 .. _format_global_variables:
258
259 Global variable descriptors
260 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
261
262 .. code-block:: llvm
263
264 !1 = metadata !{
265 DIHeader(
266 i32, ;; Tag = 52 (DW_TAG_variable)
267 mdstring, ;; Name
268 mdstring, ;; Display name (fully qualified C++ name)
269 mdstring, ;; MIPS linkage name (for C++)
270 i32, ;; Line number where defined
271 i1, ;; True if the global is local to compile unit (static)
272 i1 ;; True if the global is defined in the compile unit (not extern)
273 ),
274 metadata, ;; Reference to context descriptor
275 metadata, ;; Reference to file where defined
276 metadata, ;; Reference to type descriptor
277 {}*, ;; Reference to the global variable
278 metadata, ;; The static member declaration, if any
279 }
280
281 These descriptors provide debug information about global variables. They
282 provide details such as name, type and where the variable is defined. All
283 global variables are collected inside the named metadata ``!llvm.dbg.cu``.
284
285 .. _format_subprograms:
286
287 Subprogram descriptors
288 ^^^^^^^^^^^^^^^^^^^^^^
289
290 .. code-block:: llvm
291
292 !2 = metadata !{
293 DIHeader(
294 i32, ;; Tag = 46 (DW_TAG_subprogram)
295 mdstring, ;; Name
296 mdstring, ;; Display name (fully qualified C++ name)
297 mdstring, ;; MIPS linkage name (for C++)
298 i32, ;; Line number where defined
299 i1, ;; True if the global is local to compile unit (static)
300 i1, ;; True if the global is defined in the compile unit (not extern)
301 i32, ;; Virtuality, e.g. dwarf::DW_VIRTUALITY__virtual
302 i32, ;; Index into a virtual function
303 i32, ;; Flags - Artificial, Private, Protected, Explicit, Prototyped.
304 i1, ;; isOptimized
305 i32 ;; Line number where the scope of the subprogram begins
306 ),
307 metadata, ;; Source directory (including trailing slash) & file pair
308 metadata, ;; Reference to context descriptor
309 metadata, ;; Reference to type descriptor
310 metadata, ;; indicates which base type contains the vtable pointer for the
311 ;; derived class
312 {}*, ;; Reference to the LLVM function
313 metadata, ;; Lists function template parameters
314 metadata, ;; Function declaration descriptor
315 metadata ;; List of function variables
316 }
317
318 These descriptors provide debug information about functions, methods and
319 subprograms. They provide details such as name, return types and the source
320 location where the subprogram is defined.
321
322 Block descriptors
323 ^^^^^^^^^^^^^^^^^
324
325 .. code-block:: llvm
326
327 !3 = metadata !{
328 DIHeader(
329 i32, ;; Tag = 11 (DW_TAG_lexical_block)
330 i32, ;; Line number
331 i32, ;; Column number
332 i32 ;; Unique ID to identify blocks from a template function
333 ),
334 metadata, ;; Source directory (including trailing slash) & file pair
335 metadata ;; Reference to context descriptor
336 }
337
338 This descriptor provides debug information about nested blocks within a
339 subprogram. The line number and column numbers are used to dinstinguish two
340 lexical blocks at same depth.
341
342 .. code-block:: llvm
343
344 !3 = metadata !{
345 DIHeader(
346 i32, ;; Tag = 11 (DW_TAG_lexical_block)
347 i32 ;; DWARF path discriminator value
348 ),
349 metadata, ;; Source directory (including trailing slash) & file pair
350 metadata ;; Reference to the scope we're annotating with a file change
351 }
352
353 This descriptor provides a wrapper around a lexical scope to handle file
354 changes in the middle of a lexical block.
355
356 .. _format_basic_type:
357
358 Basic type descriptors
359 ^^^^^^^^^^^^^^^^^^^^^^
360
361 .. code-block:: llvm
362
363 !4 = metadata !{
364 DIHeader(
365 i32, ;; Tag = 36 (DW_TAG_base_type)
366 mdstring, ;; Name (may be "" for anonymous types)
367 i32, ;; Line number where defined (may be 0)
368 i64, ;; Size in bits
369 i64, ;; Alignment in bits
370 i64, ;; Offset in bits
371 i32, ;; Flags
372 i32 ;; DWARF type encoding
373 ),
374 metadata, ;; Source directory (including trailing slash) & file pair (may be null)
375 metadata ;; Reference to context
376 }
377
378 These descriptors define primitive types used in the code. Example ``int``,
379 ``bool`` and ``float``. The context provides the scope of the type, which is
380 usually the top level. Since basic types are not usually user defined the
381 context and line number can be left as NULL and 0. The size, alignment and
382 offset are expressed in bits and can be 64 bit values. The alignment is used
383 to round the offset when embedded in a :ref:`composite type
384 ` (example to keep float doubles on 64 bit boundaries).
385 The offset is the bit offset if embedded in a :ref:`composite type
386 `.
387
388 The type encoding provides the details of the type. The values are typically
389 one of the following:
390
391 .. code-block:: llvm
392
393 DW_ATE_address = 1
394 DW_ATE_boolean = 2
395 DW_ATE_float = 4
396 DW_ATE_signed = 5
397 DW_ATE_signed_char = 6
398 DW_ATE_unsigned = 7
399 DW_ATE_unsigned_char = 8
400
401 .. _format_derived_type:
402
403 Derived type descriptors
404 ^^^^^^^^^^^^^^^^^^^^^^^^
405
406 .. code-block:: llvm
407
408 !5 = metadata !{
409 DIHeader(
410 i32, ;; Tag (see below)
411 mdstring, ;; Name (may be "" for anonymous types)
412 i32, ;; Line number where defined (may be 0)
413 i64, ;; Size in bits
414 i64, ;; Alignment in bits
415 i64, ;; Offset in bits
416 i32 ;; Flags to encode attributes, e.g. private
417 ),
418 metadata, ;; Source directory (including trailing slash) & file pair (may be null)
419 metadata, ;; Reference to context
420 metadata, ;; Reference to type derived from
421 metadata ;; (optional) Objective C property node
422 }
423
424 These descriptors are used to define types derived from other types. The value
425 of the tag varies depending on the meaning. The following are possible tag
426 values:
427
428 .. code-block:: llvm
429
430 DW_TAG_formal_parameter = 5
431 DW_TAG_member = 13
432 DW_TAG_pointer_type = 15
433 DW_TAG_reference_type = 16
434 DW_TAG_typedef = 22
435 DW_TAG_ptr_to_member_type = 31
436 DW_TAG_const_type = 38
437 DW_TAG_volatile_type = 53
438 DW_TAG_restrict_type = 55
439
440 ``DW_TAG_member`` is used to define a member of a :ref:`composite type
441 ` or :ref:`subprogram `. The type
442 of the member is the :ref:`derived type `.
443 ``DW_TAG_formal_parameter`` is used to define a member which is a formal
444 argument of a subprogram.
445
446 ``DW_TAG_typedef`` is used to provide a name for the derived type.
447
448 ``DW_TAG_pointer_type``, ``DW_TAG_reference_type``, ``DW_TAG_const_type``,
449 ``DW_TAG_volatile_type`` and ``DW_TAG_restrict_type`` are used to qualify the
450 :ref:`derived type `.
451
452 :ref:`Derived type ` location can be determined from the
453 context and line number. The size, alignment and offset are expressed in bits
454 and can be 64 bit values. The alignment is used to round the offset when
455 embedded in a :ref:`composite type ` (example to keep
456 float doubles on 64 bit boundaries.) The offset is the bit offset if embedded
457 in a :ref:`composite type `.
458
459 Note that the ``void *`` type is expressed as a type derived from NULL.
460
461 .. _format_composite_type:
462
463 Composite type descriptors
464 ^^^^^^^^^^^^^^^^^^^^^^^^^^
465
466 .. code-block:: llvm
467
468 !6 = metadata !{
469 DIHeader(
470 i32, ;; Tag (see below)
471 mdstring, ;; Name (may be "" for anonymous types)
472 i32, ;; Line number where defined (may be 0)
473 i64, ;; Size in bits
474 i64, ;; Alignment in bits
475 i64, ;; Offset in bits
476 i32, ;; Flags
477 i32 ;; Runtime languages
478 ),
479 metadata, ;; Source directory (including trailing slash) & file pair (may be null)
480 metadata, ;; Reference to context
481 metadata, ;; Reference to type derived from
482 metadata, ;; Reference to array of member descriptors
483 metadata, ;; Base type containing the vtable pointer for this type
484 metadata, ;; Template parameters
485 mdstring ;; A unique identifier for type uniquing purpose (may be null)
486 }
487
488 These descriptors are used to define types that are composed of 0 or more
489 elements. The value of the tag varies depending on the meaning. The following
490 are possible tag values:
491
492 .. code-block:: llvm
493
494 DW_TAG_array_type = 1
495 DW_TAG_enumeration_type = 4
496 DW_TAG_structure_type = 19
497 DW_TAG_union_type = 23
498 DW_TAG_subroutine_type = 21
499 DW_TAG_inheritance = 28
500
501 The vector flag indicates that an array type is a native packed vector.
502
503 The members of array types (tag = ``DW_TAG_array_type``) are
504 :ref:`subrange descriptors `, each
505 representing the range of subscripts at that level of indexing.
506
507 The members of enumeration types (tag = ``DW_TAG_enumeration_type``) are
508 :ref:`enumerator descriptors `, each representing the
509 definition of enumeration value for the set. All enumeration type descriptors
510 are collected inside the named metadata ``!llvm.dbg.cu``.
511
512 The members of structure (tag = ``DW_TAG_structure_type``) or union (tag =
513 ``DW_TAG_union_type``) types are any one of the :ref:`basic
514 `, :ref:`derived ` or :ref:`composite
515 ` type descriptors, each representing a field member of
516 the structure or union.
517
518 For C++ classes (tag = ``DW_TAG_structure_type``), member descriptors provide
519 information about base classes, static members and member functions. If a
520 member is a :ref:`derived type descriptor ` and has a tag
521 of ``DW_TAG_inheritance``, then the type represents a base class. If the member
522 of is a :ref:`global variable descriptor ` then it
523 represents a static member. And, if the member is a :ref:`subprogram
524 descriptor ` then it represents a member function. For
525 static members and member functions, ``getName()`` returns the members link or
526 the C++ mangled name. ``getDisplayName()`` the simplied version of the name.
527
528 The first member of subroutine (tag = ``DW_TAG_subroutine_type``) type elements
529 is the return type for the subroutine. The remaining elements are the formal
530 arguments to the subroutine.
531
532 :ref:`Composite type ` location can be determined from
533 the context and line number. The size, alignment and offset are expressed in
534 bits and can be 64 bit values. The alignment is used to round the offset when
535 embedded in a :ref:`composite type ` (as an example, to
536 keep float doubles on 64 bit boundaries). The offset is the bit offset if
537 embedded in a :ref:`composite type `.
538
539 .. _format_subrange:
540
541 Subrange descriptors
542 ^^^^^^^^^^^^^^^^^^^^
543
544 .. code-block:: llvm
545
546 !42 = metadata !{
547 DIHeader(
548 i32, ;; Tag = 33 (DW_TAG_subrange_type)
549 i64, ;; Low value
550 i64 ;; High value
551 )
552 }
553
554 These descriptors are used to define ranges of array subscripts for an array
555 :ref:`composite type `. The low value defines the lower
556 bounds typically zero for C/C++. The high value is the upper bounds. Values
557 are 64 bit. ``High - Low + 1`` is the size of the array. If ``Low > High``
558 the array bounds are not included in generated debugging information.
559
560 .. _format_enumerator:
561
562 Enumerator descriptors
563 ^^^^^^^^^^^^^^^^^^^^^^
564
565 .. code-block:: llvm
566
567 !6 = metadata !{
568 DIHeader(
569 i32, ;; Tag = 40 (DW_TAG_enumerator)
570 mdstring, ;; Name
571 i64 ;; Value
572 )
573 }
574
575 These descriptors are used to define members of an enumeration :ref:`composite
576 type `, it associates the name to the value.
577
578 Local variables
579 ^^^^^^^^^^^^^^^
580
581 .. code-block:: llvm
582
583 !7 = metadata !{
584 DIHeader(
585 i32, ;; Tag (see below)
586 mdstring, ;; Name
587 i32, ;; 24 bit - Line number where defined
588 ;; 8 bit - Argument number. 1 indicates 1st argument.
589 i32 ;; flags
590 ),
591 metadata, ;; Context
592 metadata, ;; Reference to file where defined
593 metadata, ;; Reference to the type descriptor
594 metadata ;; (optional) Reference to inline location
595 }
596
597 These descriptors are used to define variables local to a sub program. The
598 value of the tag depends on the usage of the variable:
599
600 .. code-block:: llvm
601
602 DW_TAG_auto_variable = 256
603 DW_TAG_arg_variable = 257
604
605 An auto variable is any variable declared in the body of the function. An
606 argument variable is any variable that appears as a formal argument to the
607 function.
608
609 The context is either the subprogram or block where the variable is defined.
610 Name the source variable name. Context and line indicate where the variable
611 was defined. Type descriptor defines the declared type of the variable.
612
613 Complex Expressions
614 ^^^^^^^^^^^^^^^^^^^
615 .. code-block:: llvm
616
617 !8 = metadata !{
618 i32, ;; DW_TAG_expression
619 ...
620 }
621
622 Complex expressions describe variable storage locations in terms of
623 prefix-notated DWARF expressions. Currently the only supported
624 operators are ``DW_OP_plus``, ``DW_OP_deref``, and ``DW_OP_piece``.
625
626 The ``DW_OP_piece`` operator is used for (typically larger aggregate)
627 variables that are fragmented across several locations. It takes two
628 i32 arguments, an offset and a size in bytes to describe which piece
629 of the variable is at this location.
630
163 Debug information descriptors are `specialized metadata nodes
164 `_, first-class subclasses of ``Metadata``.
631165
632166 .. _format_common_intrinsics:
633167
634168 Debugger intrinsic functions
635 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
169 ----------------------------
636170
637171 LLVM uses several intrinsic functions (name prefixed with "``llvm.dbg``") to
638172 provide debug information at various points in generated code.
642176
643177 .. code-block:: llvm
644178
645 void %llvm.dbg.declare(metadata, metadata)
179 void %llvm.dbg.declare(metadata, metadata, metadata)
646180
647181 This intrinsic provides information about a local element (e.g., variable).
648182 The first argument is metadata holding the alloca for the variable. The second
649 argument is metadata containing a description of the variable.
183 argument is a `local variable `_ containing a
184 description of the variable. The third argument is a `complex expression
185 `_.
650186
651187 ``llvm.dbg.value``
652188 ^^^^^^^^^^^^^^^^^^
653189
654190 .. code-block:: llvm
655191
656 void %llvm.dbg.value(metadata, i64, metadata)
192 void %llvm.dbg.value(metadata, i64, metadata, metadata)
657193
658194 This intrinsic provides information when a user source variable is set to a new
659195 value. The first argument is the new value (wrapped as metadata). The second
660196 argument is the offset in the user source variable where the new value is
661 written. The third argument is metadata containing a description of the user
662 source variable.
197 written. The third argument is a `local variable
198 `_ containing a description of the variable. The
199 third argument is a `complex expression `_.
663200
664201 Object lifetimes and scoping
665202 ============================
692229
693230 .. code-block:: llvm
694231
232 ; Function Attrs: nounwind ssp uwtable
695233 define void @foo() #0 {
696234 entry:
697 %X = alloca i32, align 4
235 %X = alloca i32, align 4
698236 %Y = alloca i32, align 4
699237 %Z = alloca i32, align 4
700 call void @llvm.dbg.declare(metadata !{i32* %X}, metadata !10), !dbg !12
701 ; [debug line = 2:7] [debug variable = X]
702 store i32 21, i32* %X, align 4, !dbg !12
703 call void @llvm.dbg.declare(metadata !{i32* %Y}, metadata !13), !dbg !14
704 ; [debug line = 3:7] [debug variable = Y]
705 store i32 22, i32* %Y, align 4, !dbg !14
706 call void @llvm.dbg.declare(metadata !{i32* %Z}, metadata !15), !dbg !17
707 ; [debug line = 5:9] [debug variable = Z]
708 store i32 23, i32* %Z, align 4, !dbg !17
709 %0 = load i32* %X, align 4, !dbg !18
710 [debug line = 6:5]
711 store i32 %0, i32* %Z, align 4, !dbg !18
712 %1 = load i32* %Y, align 4, !dbg !19
713 [debug line = 8:3]
714 store i32 %1, i32* %X, align 4, !dbg !19
715 ret void, !dbg !20
238 call void @llvm.dbg.declare(metadata i32* %X, metadata !11, metadata !13), !dbg !14
239 store i32 21, i32* %X, align 4, !dbg !14
240 call void @llvm.dbg.declare(metadata i32* %Y, metadata !15, metadata !13), !dbg !16
241 store i32 22, i32* %Y, align 4, !dbg !16
242 call void @llvm.dbg.declare(metadata i32* %Z, metadata !17, metadata !13), !dbg !19
243 store i32 23, i32* %Z, align 4, !dbg !19
244 %0 = load i32, i32* %X, align 4, !dbg !20
245 store i32 %0, i32* %Z, align 4, !dbg !21
246 %1 = load i32, i32* %Y, align 4, !dbg !22
247 store i32 %1, i32* %X, align 4, !dbg !23
248 ret void, !dbg !24
716249 }
717250
718251 ; Function Attrs: nounwind readnone
719 declare void @llvm.dbg.declare(metadata, metadata) #1
720
721 attributes #0 = { nounwind ssp uwtable "less-precise-fpmad"="false"
722 "no-frame-pointer-elim"="true" "no-frame-pointer-elim-non-leaf"
723 "no-infs-fp-math"="false" "no-nans-fp-math"="false"
724 "stack-protector-buffer-size"="8" "unsafe-fp-math"="false"
725 "use-soft-float"="false" }
252 declare void @llvm.dbg.declare(metadata, metadata, metadata) #1
253
254 attributes #0 = { nounwind ssp uwtable "less-precise-fpmad"="false" "no-frame-pointer-elim"="true" "no-frame-pointer-elim-non-leaf" "no-infs-fp-math"="false" "no-nans-fp-math"="false" "stack-protector-buffer-size"="8" "unsafe-fp-math"="false" "use-soft-float"="false" }
726255 attributes #1 = { nounwind readnone }
727256
728257 !llvm.dbg.cu = !{!0}
729 !llvm.module.flags = !{!8}
730 !llvm.ident = !{!9}
731
732 !0 = metadata !{i32 786449, metadata !1, i32 12,
733 metadata !"clang version 3.4 (trunk 193128) (llvm/trunk 193139)",
734 i1 false, metadata !"", i32 0, metadata !2, metadata !2, metadata !3,
735 metadata !2, metadata !2, metadata !""} ; [ DW_TAG_compile_unit ] \
736 [/private/tmp/foo.c] \
737 [DW_LANG_C99]
738 !1 = metadata !{metadata !"t.c", metadata !"/private/tmp"}
739 !2 = metadata !{i32 0}
740 !3 = metadata !{metadata !4}
741 !4 = metadata !{i32 786478, metadata !1, metadata !5, metadata !"foo",
742 metadata !"foo", metadata !"", i32 1, metadata !6,
743 i1 false, i1 true, i32 0, i32 0, null, i32 0, i1 false,
744 void ()* @foo, null, null, metadata !2, i32 1}
745 ; [ DW_TAG_subprogram ] [line 1] [def] [foo]
746 !5 = metadata !{i32 786473, metadata !1} ; [ DW_TAG_file_type ] \
747 [/private/tmp/t.c]
748 !6 = metadata !{i32 786453, i32 0, null, metadata !"", i32 0, i64 0, i64 0,
749 i64 0, i32 0, null, metadata !7, i32 0, null, null, null}
750 ; [ DW_TAG_subroutine_type ] \
751 [line 0, size 0, align 0, offset 0] [from ]
752 !7 = metadata !{null}
753 !8 = metadata !{i32 2, metadata !"Dwarf Version", i32 2}
754 !9 = metadata !{metadata !"clang version 3.4 (trunk 193128) (llvm/trunk 193139)"}
755 !10 = metadata !{i32 786688, metadata !4, metadata !"X", metadata !5, i32 2,
756 metadata !11, i32 0, i32 0} ; [ DW_TAG_auto_variable ] [X] \
757 [line 2]
758 !11 = metadata !{i32 786468, null, null, metadata !"int", i32 0, i64 32,
759 i64 32, i64 0, i32 0, i32 5} ; [ DW_TAG_base_type ] [int] \
760 [line 0, size 32, align 32, offset 0, enc DW_ATE_signed]
761 !12 = metadata !{i32 2, i32 0, metadata !4, null}
762 !13 = metadata !{i32 786688, metadata !4, metadata !"Y", metadata !5, i32 3,
763 metadata !11, i32 0, i32 0} ; [ DW_TAG_auto_variable ] [Y] \
764 [line 3]
765 !14 = metadata !{i32 3, i32 0, metadata !4, null}
766 !15 = metadata !{i32 786688, metadata !16, metadata !"Z", metadata !5, i32 5,
767 metadata !11, i32 0, i32 0} ; [ DW_TAG_auto_variable ] [Z] \
768 [line 5]
769 !16 = metadata !{i32 786443, metadata !1, metadata !4, i32 4, i32 0, i32 0} \
770 ; [ DW_TAG_lexical_block ] [/private/tmp/t.c]
771 !17 = metadata !{i32 5, i32 0, metadata !16, null}
772 !18 = metadata !{i32 6, i32 0, metadata !16, null}
773 !19 = metadata !{i32 8, i32 0, metadata !4, null} ; [ DW_TAG_imported_declaration ]
774 !20 = metadata !{i32 9, i32 0, metadata !4, null}
258 !llvm.module.flags = !{!7, !8, !9}
259 !llvm.ident = !{!10}
260
261 !0 = !MDCompileUnit(language: DW_LANG_C99, file: !1, producer: "clang version 3.7.0 (trunk 231150) (llvm/trunk 231154)", isOptimized: false, runtimeVersion: 0, emissionKind: 1, enums: !2, retainedTypes: !2, subprograms: !3, globals: !2, imports: !2)
262 !1 = !MDFile(filename: "/dev/stdin", directory: "/Users/dexonsmith/data/llvm/debug-info")
263 !2 = !{}
264 !3 = !{!4}
265 !4 = !MDSubprogram(name: "foo", scope: !1, file: !1, line: 1, type: !5, isLocal: false, isDefinition: true, scopeLine: 1, isOptimized: false, function: void ()* @foo, variables: !2)
266 !5 = !MDSubroutineType(types: !6)
267 !6 = !{null}
268 !7 = !{i32 2, !"Dwarf Version", i32 2}
269 !8 = !{i32 2, !"Debug Info Version", i32 3}
270 !9 = !{i32 1, !"PIC Level", i32 2}
271 !10 = !{!"clang version 3.7.0 (trunk 231150) (llvm/trunk 231154)"}
272 !11 = !MDLocalVariable(tag: DW_TAG_auto_variable, name: "X", scope: !4, file: !1, line: 2, type: !12)
273 !12 = !MDBasicType(name: "int", size: 32, align: 32, encoding: DW_ATE_signed)
274 !13 = !MDExpression()
275 !14 = !MDLocation(line: 2, column: 9, scope: !4)
276 !15 = !MDLocalVariable(tag: DW_TAG_auto_variable, name: "Y", scope: !4, file: !1, line: 3, type: !12)
277 !16 = !MDLocation(line: 3, column: 9, scope: !4)
278 !17 = !MDLocalVariable(tag: DW_TAG_auto_variable, name: "Z", scope: !18, file: !1, line: 5, type: !12)
279 !18 = distinct !MDLexicalBlock(scope: !4, file: !1, line: 4, column: 5)
280 !19 = !MDLocation(line: 5, column: 11, scope: !18)
281 !20 = !MDLocation(line: 6, column: 11, scope: !18)
282 !21 = !MDLocation(line: 6, column: 9, scope: !18)
283 !22 = !MDLocation(line: 8, column: 9, scope: !4)
284 !23 = !MDLocation(line: 8, column: 7, scope: !4)
285 !24 = !MDLocation(line: 9, column: 3, scope: !4)
286
775287
776288 This example illustrates a few important details about LLVM debugging
777289 information. In particular, it shows how the ``llvm.dbg.declare`` intrinsic and
781293
782294 .. code-block:: llvm
783295
784 call void @llvm.dbg.declare(metadata !{i32* %X}, metadata !10), !dbg !12
296 call void @llvm.dbg.declare(metadata i32* %X, metadata !11, metadata !13), !dbg !14
785297 ; [debug line = 2:7] [debug variable = X]
786298
787299 The first intrinsic ``%llvm.dbg.declare`` encodes debugging information for the
788 variable ``X``. The metadata ``!dbg !12`` attached to the intrinsic provides
300 variable ``X``. The metadata ``!dbg !14`` attached to the intrinsic provides
789301 scope information for the variable ``X``.
790302
791303 .. code-block:: llvm
792304
793 !12 = metadata !{i32 2, i32 0, metadata !4, null}
794 !4 = metadata !{i32 786478, metadata !1, metadata !5, metadata !"foo",
795 metadata !"foo", metadata !"", i32 1, metadata !6,
796 i1 false, i1 true, i32 0, i32 0, null, i32 0, i1 false,
797 void ()* @foo, null, null, metadata !2, i32 1}
798 ; [ DW_TAG_subprogram ] [line 1] [def] [foo]
799
800 Here ``!12`` is metadata providing location information. It has four fields:
801 line number, column number, scope, and original scope. The original scope
802 represents inline location if this instruction is inlined inside a caller, and
803 is null otherwise. In this example, scope is encoded by ``!4``, a
804 :ref:`subprogram descriptor `. This way the location
305 !14 = !MDLocation(line: 2, column: 9, scope: !4)
306 !4 = !MDSubprogram(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)
310
311 Here ``!14`` is metadata providing `location information
312 `_. In this example, scope is encoded by ``!4``, a
313 `subprogram descriptor `_. This way the location
805314 information attached to the intrinsics indicates that the variable ``X`` is
806315 declared at line number 2 at a function level scope in function ``foo``.
807316
809318
810319 .. code-block:: llvm
811320
812 call void @llvm.dbg.declare(metadata !{i32* %Z}, metadata !15), !dbg !17
321 call void @llvm.dbg.declare(metadata i32* %Z, metadata !17, metadata !13), !dbg !19
813322 ; [debug line = 5:9] [debug variable = Z]
814323
815324 The third intrinsic ``%llvm.dbg.declare`` encodes debugging information for
816 variable ``Z``. The metadata ``!dbg !17`` attached to the intrinsic provides
325 variable ``Z``. The metadata ``!dbg !19`` attached to the intrinsic provides
817326 scope information for the variable ``Z``.
818327
819328 .. code-block:: llvm
820329
821 !16 = metadata !{i32 786443, metadata !1, metadata !4, i32 4, i32 0, i32 0} \
822 ; [ DW_TAG_lexical_block ] [/private/tmp/t.c]
823 !17 = metadata !{i32 5, i32 0, metadata !16, null}
824
825 Here ``!15`` indicates that ``Z`` is declared at line number 5 and
826 column number 0 inside of lexical scope ``!16``. The lexical scope itself
827 resides inside of subprogram ``!4`` described above.
330 !18 = distinct !MDLexicalBlock(scope: !4, file: !1, line: 4, column: 5)
331 !19 = !MDLocation(line: 5, column: 11, scope: !18)
332
333 Here ``!19`` indicates that ``Z`` is declared at line number 5 and column
334 number 0 inside of lexical scope ``!18``. The lexical scope itself resides
335 inside of subprogram ``!4`` described above.
828336
829337 The scope information attached with each instruction provides a straightforward
830338 way to find instructions covered by a scope.
887395 ;; Define the global itself.
888396 ;;
889397 @MyGlobal = global i32 100, align 4
890 ...
398
891399 ;;
892400 ;; List of debug info of globals
893401 ;;
894402 !llvm.dbg.cu = !{!0}
895403
404 ;; Some unrelated metadata.
405 !llvm.module.flags = !{!6, !7}
406
896407 ;; Define the compile unit.
897 !0 = metadata !{
898 ; Header(
899 ; i32 17, ;; Tag
900 ; i32 0, ;; Context
901 ; i32 4, ;; Language
902 ; metadata !"clang version 3.6.0 ", ;; Producer
903 ; i1 false, ;; "isOptimized"?
904 ; metadata !"", ;; Flags
905 ; i32 0, ;; Runtime Version
906 ; "", ;; Split debug filename
907 ; 1 ;; Full debug info
908 ; )
909 metadata !"0x11\0012\00clang version 3.6.0 \000\00\000\00\001",
910 metadata !1, ;; File
911 metadata !2, ;; Enum Types
912 metadata !2, ;; Retained Types
913 metadata !2, ;; Subprograms
914 metadata !3, ;; Global Variables
915 metadata !2 ;; Imported entities
916 } ; [ DW_TAG_compile_unit ]
917
918 ;; The file/directory pair.
919 !1 = metadata !{
920 metadata !"foo.c", ;; Filename
921 metadata !"/Users/dexonsmith/data/llvm/debug-info" ;; Directory
922 }
408 !0 = !MDCompileUnit(language: DW_LANG_C99, file: !1,
409 producer:
410 "clang version 3.7.0 (trunk 231150) (llvm/trunk 231154)",
411 isOptimized: false, runtimeVersion: 0, emissionKind: 1,
412 enums: !2, retainedTypes: !2, subprograms: !2, globals:
413 !3, imports: !2)
414
415 ;;
416 ;; Define the file
417 ;;
418 !1 = !MDFile(filename: "/dev/stdin",
419 directory: "/Users/dexonsmith/data/llvm/debug-info")
923420
924421 ;; An empty array.
925 !2 = metadata !{}
422 !2 = !{}
926423
927424 ;; The Array of Global Variables
928 !3 = metadata !{
929 metadata !4
930 }
425 !3 = !{!4}
931426
932427 ;;
933428 ;; Define the global variable itself.
934429 ;;
935 !4 = metadata !{
936 ; Header(
937 ; i32 52, ;; Tag
938 ; metadata !"MyGlobal", ;; Name
939 ; metadata !"MyGlobal", ;; Display Name
940 ; metadata !"", ;; Linkage Name
941 ; i32 1, ;; Line
942 ; i32 0, ;; IsLocalToUnit
943 ; i32 1 ;; IsDefinition
944 ; )
945 metadata !"0x34\00MyGlobal\00MyGlobal\00\001\000\001",
946 null, ;; Unused
947 metadata !5, ;; File
948 metadata !6, ;; Type
949 i32* @MyGlobal, ;; LLVM-IR Value
950 null ;; Static member declaration
951 } ; [ DW_TAG_variable ]
952
953 ;;
954 ;; Define the file
955 ;;
956 !5 = metadata !{
957 ; Header(
958 ; i32 41 ;; Tag
959 ; )
960 metadata !"0x29",
961 metadata !1 ;; File/directory pair
962 } ; [ DW_TAG_file_type ]
430 !4 = !MDGlobalVariable(name: "MyGlobal", scope: !0, file: !1, line: 1,
431 type: !5, isLocal: false, isDefinition: true,
432 variable: i32* @MyGlobal)
963433
964434 ;;
965435 ;; Define the type
966436 ;;
967 !6 = metadata !{
968 ; Header(
969 ; i32 36, ;; Tag
970 ; metadata !"int", ;; Name
971 ; i32 0, ;; Line
972 ; i64 32, ;; Size in Bits
973 ; i64 32, ;; Align in Bits
974 ; i64 0, ;; Offset
975 ; i32 0, ;; Flags
976 ; i32 5 ;; Encoding
977 ; )
978 metadata !"0x24\00int\000\0032\0032\000\000\005",
979 null, ;; Unused
980 null ;; Unused
981 } ; [ DW_TAG_base_type ]
437 !5 = !MDBasicType(name: "int", size: 32, align: 32, encoding: DW_ATE_signed)
438
439 ;; Dwarf version to output.
440 !6 = !{i32 2, !"Dwarf Version", i32 2}
441
442 ;; Debug info schema version.
443 !7 = !{i32 2, !"Debug Info Version", i32 3}
982444
983445 C/C++ function information
984446 --------------------------
998460 ;;
999461 ;; Define the anchor for subprograms.
1000462 ;;
1001 !6 = metadata !{
1002 ; Header(
1003 ; i32 46, ;; Tag
1004 ; metadata !"main", ;; Name
1005 ; metadata !"main", ;; Display name
1006 ; metadata !"", ;; Linkage name
1007 ; i32 1, ;; Line number
1008 ; i1 false, ;; Is local
1009 ; i1 true, ;; Is definition
1010 ; i32 0, ;; Virtuality attribute, e.g. pure virtual function
1011 ; i32 0, ;; Index into virtual table for C++ methods
1012 ; i32 256, ;; Flags
1013 ; i1 0, ;; True if this function is optimized
1014 ; 1 ;; Line number of the opening '{' of the function
1015 ; )
1016 metadata !"0x2e\00main\00main\00\001\000\001\000\000\00256\000\001",
1017 metadata !1, ;; File
1018 metadata !5, ;; Context
1019 metadata !6, ;; Type
1020 null, ;; Containing type
1021 i32 (i32, i8**)* @main, ;; Pointer to llvm::Function
1022 null, ;; Function template parameters
1023 null, ;; Function declaration
1024 metadata !2 ;; List of function variables (emitted when optimizing)
1025 }
463 !4 = !MDSubprogram(name: "main", scope: !1, file: !1, line: 1, type: !5,
464 isLocal: false, isDefinition: true, scopeLine: 1,
465 flags: DIFlagPrototyped, isOptimized: false,
466 function: i32 (i32, i8**)* @main, variables: !2)
1026467
1027468 ;;
1028469 ;; Define the subprogram itself.