aboutsummaryrefslogtreecommitdiff
path: root/llvm/docs/SourceLevelDebugging.rst
AgeCommit message (Collapse)AuthorFilesLines
2025-06-25[LangRef] Clarify definition of fragments (#145582)Scott Linder1-4/+53
Try to give a more complete description of what we call a "fragment", and how debug records interact when fragments are involved.
2025-04-04[DebugInfo] Preserve line and column number when merging debug info. (#129960)Snehasish Kumar1-0/+13
This patch introduces a new option `-preserve-merged-debug-info` to preserve an arbitrary but deterministic version of debug information when DILocations are merged. This is intended to be used in production environments from which sample based profiles are derived such as AutoFDO and MemProf. With this patch we have see a 0.2% improvement on an internal workload at Google when generating AutoFDO profiles. It also significantly improves the ability for MemProf by preserving debug info for merged call instructions used in the contextual profile. --------- Co-authored-by: Krzysztof Pszeniczny <kpszeniczny@google.com>
2025-04-04[Verifier] Require that dbg.declare variable is a ptr (#134355)Nikita Popov1-4/+4
As far as I understand, the first operand of dbg_declare should be a pointer (inside a metadata wrapper). However, using a non-pointer is currently not rejected, and we have some tests that use non-pointer types. As far as I can tell, these tests either meant to use dbg_value or are just incorrect hand-crafted tests. Ran into this while trying to `fix` #134008.
2024-07-30[docs] SourceLevelDebugging: fix metadata references (#101187)Michael Buch1-21/+21
The metadata was off-by-one in a couple of places, making the explanatory text incorrect.
2024-06-11[RemoveDIs] Update all docs to use debug records (#91768)Stephen Tozer1-181/+195
As we approach the state where support for debug intrinsics is dropping and we print and use debug records by default, the documentation should be updated to refer to debug records as the primary debug info representation, with debug intrinsics being relegated to an optional alternative. This patch performs a few updates: - Replace references to intrinsics with references to records across all the documentation. - Replace intrinsics with records in code examples. - Move debug records prior to debug intrinsics in the SourceLevelDebugging document, and change text to refer to them as the primary representation. - Add release notes describing the change.
2024-03-08[RemoveDIs] Add documentation for IR debug records (#81156)Stephen Tozer1-0/+66
This patch adds minimal documentation for the IR representation of the RemoveDIs model of debug info. This patch assumes that the default for all cases is still debug intrinsic functions, and so does not update all existing text to refer to debug records, but only adds a section in the LangRef and SourceLevelDebugging documents to explain the new format.
2023-11-27[docs] Fix issues in SourceLevelDebugging (#73528)Felipe de Azevedo Piovezan1-2/+2
An SSA register `value` was being defined twice. An "external" link was using the "internal" link syntax.
2023-05-12[llvm] Fix typos in documentationKazu Hirata1-2/+2
2023-04-26Fix docs bot after D140989OCHyams1-1/+1
Commit a93c4239719382e5b17335f3452e9095937ed6b7 broke docs buildbot: https://lab.llvm.org/buildbot/#/builders/30/builds/34525
2023-04-26[DebugInfo] Update SourceLevelDebugging.rst to better explain kill locationsOCHyams1-5/+22
Reviewed By: scott.linder, jryans Differential Revision: https://reviews.llvm.org/D140989
2023-03-02[DebugInfo][Docs] Remove `dbg.addr` from docsJ. Ryan Stinnett1-37/+17
Part of `dbg.addr` removal Discussed in https://discourse.llvm.org/t/what-is-the-status-of-dbg-addr/62898 Differential Revision: https://reviews.llvm.org/D144792
2022-11-02Fix LLVM sphinx build botAaron Ballman1-0/+4
This should address the issue found in: https://lab.llvm.org/buildbot/#/builders/30/builds/27824
2022-11-02Fix Assignment Tracking docs error from 33c7ae55e729069be754f56c4d4606cdeddd377bOCHyams1-1/+1
Buildbot link: https://lab.llvm.org/buildbot/#/builders/30/builds/27812
2022-11-02[Assignment Tracking][1/*] Add initial docs for Assignment TrackingOCHyams1-0/+30
The Assignment Tracking debug-info feature is outlined in this RFC: https://discourse.llvm.org/t/ rfc-assignment-tracking-a-better-way-of-specifying-variable-locations-in-ir Add documentation outlining the intent and design.
2022-04-15[DebugInfo] Add a TargetFuncName field in DISubprogram forChih-Ping Chen1-2/+21
specifying DW_AT_trampoline as a string. Also update the signature of DIBuilder::createFunction to reflect this addition. Differential Revision: https://reviews.llvm.org/D123697
2022-02-11Fix build broken by missing empty line in SourceLevelDebugging.rstYASHASVI KHATAVKAR1-0/+1
2022-02-11Adding DiBuilder interface for assumed length stringsYASHASVI KHATAVKAR1-0/+4
2022-02-10Reverting an entire stack of changes causing build failuresYASHASVI KHATAVKAR1-5/+0
2022-02-10Modified SourceLevelDebugging.rst to include information about memory ↵YASHASVI KHATAVKAR1-0/+5
location exp
2022-01-05[llvm] Add support for DW_TAG_immutable_typeLuís Ferreira1-0/+1
Added documentation about DW_TAG_immutable_type too. Reviewed By: probinson Differential Revision: https://reviews.llvm.org/D113633
2021-11-15[NFC] Trim trailing whitespace in *.rstShao-Ce SUN1-4/+4
2021-11-09Revert "[DebugInfo] Enforce implicit constraints on `distinct` MDNodes"Arthur Eubanks1-40/+41
This reverts commit ee7652569854af567ba83e5255d70e80cc8619a1. Causes crashes, see comments in D104827.
2021-11-09[DebugInfo] Enforce implicit constraints on `distinct` MDNodesScott Linder1-41/+40
Add UNIQUED and DISTINCT properties in Metadata.def and use them to implement restrictions on the `distinct` property of MDNodes: * DIExpression can currently be parsed from IR or read from bitcode as `distinct`, but this property is silently dropped when printing to IR. This causes accepted IR to fail to round-trip. As DIExpression appears inline at each use in the canonical form of IR, it cannot actually be `distinct` anyway, as there is no syntax to describe it. * Similarly, DIArgList is conceptually always uniqued. It is currently restricted to only appearing in contexts where there is no syntax for `distinct`, but for consistency it is treated equivalently to DIExpression in this patch. * DICompileUnit is already restricted to always being `distinct`, but along with adding general support for the inverse restriction I went ahead and described this in Metadata.def and updated the parser to be general. Future nodes which have this restriction can share this support. The new UNIQUED property applies to DIExpression and DIArgList, and forbids them to be `distinct`. It also implies they are canonically printed inline at each use, rather than via MDNode ID. The new DISTINCT property applies to DICompileUnit, and requires it to be `distinct`. A potential alternative change is to forbid the non-inline syntax for DIExpression entirely, as is done with DIArgList implicitly by requiring it appear in the context of a function. For example, we would forbid: !named = !{!0} !0 = !DIExpression() Instead we would only accept the equivalent inlined version: !named = !{!DIExpression()} This essentially removes the ability to create a `distinct` DIExpression by construction, as there is no syntax for `distinct` inline. If this patch is accepted as-is, the result would be that the non-canonical version is accepted, but the following would be an error and produce a diagnostic: !named = !{!0} ; error: 'distinct' not allowed for !DIExpression() !0 = distinct !DIExpression() Also update some documentation to consistently use the inline syntax for DIExpression, and to describe the restrictions on `distinct` for nodes where applicable. Reviewed By: StephenTozer, t-tye Differential Revision: https://reviews.llvm.org/D104827
2021-07-28[DebugInfo][docs] Fix DISubprogram fieldsEllis Hoag1-3/+3
D45024 renamed the field in `DISubprogram` from `variables:` to `retainedNodes:`. Some of the docs were updated in D89082 but this updates the rest. Reviewed By: scott.linder Differential Revision: https://reviews.llvm.org/D106926
2021-07-14[RemoveRedundantDebugValues] Add a Pass that removes redundant DBG_VALUEsDjordje Todorovic1-1/+3
This new MIR pass removes redundant DBG_VALUEs. After the register allocator is done, more precisely, after the Virtual Register Rewriter, we end up having duplicated DBG_VALUEs, since some virtual registers are being rewritten into the same physical register as some of existing DBG_VALUEs. Each DBG_VALUE should indicate (at least before the LiveDebugValues) variables assignment, but it is being clobbered for function parameters during the SelectionDAG since it generates new DBG_VALUEs after COPY instructions, even though the parameter has no assignment. For example, if we had a DBG_VALUE $regX as an entry debug value representing the parameter, and a COPY and after the COPY, DBG_VALUE $virt_reg, and after the virtregrewrite the $virt_reg gets rewritten into $regX, we'd end up having redundant DBG_VALUE. This breaks the definition of the DBG_VALUE since some analysis passes might be built on top of that premise..., and this patch tries to fix the MIR with the respect to that. This first patch performs bacward scan, by trying to detect a sequence of consecutive DBG_VALUEs, and to remove all DBG_VALUEs describing one variable but the last one: For example: (1) DBG_VALUE $edi, !"var1", ... (2) DBG_VALUE $esi, !"var2", ... (3) DBG_VALUE $edi, !"var1", ... ... in this case, we can remove (1). By combining the forward scan that will be introduced in the next patch (from this stack), by inspecting the statistics, the RemoveRedundantDebugValues removes 15032 instructions by using gdb-7.11 as a testbed. Differential Revision: https://reviews.llvm.org/D105279
2021-07-02Revert "[DebugInfo] Enforce implicit constraints on `distinct` MDNodes"Jonas Devlieghere1-40/+41
This reverts commit 8cd35ad854ab4458fd509447359066ea3578b494. It breaks `TestMembersAndLocalsWithSameName.py` on GreenDragon and Mikael Holmén points out in D104827 that bitcode files created with the patch cannot be parsed with binaries built before it.
2021-06-28[DebugInfo] Enforce implicit constraints on `distinct` MDNodesScott Linder1-41/+40
Add UNIQUED and DISTINCT properties in Metadata.def and use them to implement restrictions on the `distinct` property of MDNodes: * DIExpression can currently be parsed from IR or read from bitcode as `distinct`, but this property is silently dropped when printing to IR. This causes accepted IR to fail to round-trip. As DIExpression appears inline at each use in the canonical form of IR, it cannot actually be `distinct` anyway, as there is no syntax to describe it. * Similarly, DIArgList is conceptually always uniqued. It is currently restricted to only appearing in contexts where there is no syntax for `distinct`, but for consistency it is treated equivalently to DIExpression in this patch. * DICompileUnit is already restricted to always being `distinct`, but along with adding general support for the inverse restriction I went ahead and described this in Metadata.def and updated the parser to be general. Future nodes which have this restriction can share this support. The new UNIQUED property applies to DIExpression and DIArgList, and forbids them to be `distinct`. It also implies they are canonically printed inline at each use, rather than via MDNode ID. The new DISTINCT property applies to DICompileUnit, and requires it to be `distinct`. A potential alternative change is to forbid the non-inline syntax for DIExpression entirely, as is done with DIArgList implicitly by requiring it appear in the context of a function. For example, we would forbid: !named = !{!0} !0 = !DIExpression() Instead we would only accept the equivalent inlined version: !named = !{!DIExpression()} This essentially removes the ability to create a `distinct` DIExpression by construction, as there is no syntax for `distinct` inline. If this patch is accepted as-is, the result would be that the non-canonical version is accepted, but the following would be an error and produce a diagnostic: !named = !{!0} ; error: 'distinct' not allowed for !DIExpression() !0 = distinct !DIExpression() Also update some documentation to consistently use the inline syntax for DIExpression, and to describe the restrictions on `distinct` for nodes where applicable. Reviewed By: StephenTozer, t-tye Differential Revision: https://reviews.llvm.org/D104827
2021-03-05Reapply "[DebugInfo] Add new instruction and DIExpression operator for ↵Stephen Tozer1-2/+20
variadic debug values" Rewrites test to use correct architecture triple; fixes incorrect reference in SourceLevelDebugging doc; simplifies `spillReg` behaviour so as to not be dependent on changes elsewhere in the patch stack. This reverts commit d2000b45d033c06dc7973f59909a0ad12887ff51.
2021-03-04Revert "[DebugInfo] Add new instruction and DIExpression operator for ↵Stephen Tozer1-20/+2
variadic debug values" This reverts commit d07f106f4a48b6e941266525b6f7177834d7b74e.
2021-03-04[DebugInfo] Add new instruction and DIExpression operator for variadic debug ↵gbtozers1-2/+20
values This patch adds a new instruction that can represent variadic debug values, DBG_VALUE_VAR. This patch alone covers the addition of the instruction and a set of basic code changes in MachineInstr and a few adjacent areas, but does not correctly handle variadic debug values outside of these areas, nor does it generate them at any point. The new instruction is similar to the existing DBG_VALUE instruction, with the following differences: the operands are in a different order, any number of values may be used in the instruction following the Variable and Expression operands (these are referred to in code as “debug operands”) and are indexed from 0 so that getDebugOperand(X) == getOperand(X+2), and the Expression in a DBG_VALUE_VAR must use the DW_OP_LLVM_arg operator to pass arguments into the expression. The new DW_OP_LLVM_arg operator is only valid in expressions appearing in a DBG_VALUE_VAR; it takes a single argument and pushes the debug operand at the index given by the argument onto the Expression stack. For example the sub-expression `DW_OP_LLVM_arg, 0` has the meaning “Push the debug operand at index 0 onto the expression stack.” Differential Revision: https://reviews.llvm.org/D82363
2020-08-22[DebugInfo][flang]Added support for representing Fortran assumed length stringsSourabh Singh Tomar1-0/+26
This patch adds support for representing Fortran `character(n)`. Primarily patch is based out of D54114 with appropriate modifications. Test case IR is generated using our downstream classic-flang. We're in process of upstreaming flang PR's but classic-flang has dependencies on llvm, so this has to get in first. Patch includes functional test case for both IR and corresponding dwarf, furthermore it has been manually tested as well using GDB. Source snippet: ``` program assumedLength call sub('Hello') call sub('Goodbye') contains subroutine sub(string) implicit none character(len=*), intent(in) :: string print *, string end subroutine sub end program assumedLength ``` GDB: ``` (gdb) ptype string type = character (5) (gdb) p string $1 = 'Hello' ``` Reviewed By: aprantl, schweitz Differential Revision: https://reviews.llvm.org/D86305
2020-06-01[docs] Sketch outline for HowToUpdateDebugInfo.rstVedant Kumar1-182/+6
Summary: Sketch the outline for a new document that explains how to update debug info in various kinds of code transformations. Some of the guidelines that belong in HowToUpdateDebugInfo.rst were in SourceLevelDebugging.rst already under the debugify section. It seems like the distinction between the two docs ought to be that the former is more prescriptive, while the latter is more descriptive. To that end I've consolidated the "how to update debug info" guidelines which were in SourceLevelDebugging.rst into the new doc, along with the information about using "debugify" to test transformations. Since we've added a mir-debugify pass, I've described that as well. Reviewers: aprantl, jmorse, chrisjackson, dsanders Subscribers: llvm-commits Tags: #llvm Differential Revision: https://reviews.llvm.org/D80052
2020-01-22[llvm] NFC: fix trivial typos in documentsKazuaki Ishizaki1-3/+3
Reviewers: hans, Jim Reviewed By: Jim Subscribers: jvesely, nhaehnle, mgorny, arphaman, bmahjour, kerbowa, llvm-commits Tags: #llvm Differential Revision: https://reviews.llvm.org/D73017
2020-01-07[docs] NFC: Fix typos in documentsHans Wennborg1-1/+1
"the the" -> "the" "an" -> "a" Patch by Kazuaki Ishizaki <ishizaki@jp.ibm.com>! Differential revision: https://reviews.llvm.org/D72091
2019-12-24Migrate function attribute "no-frame-pointer-elim" to "frame-pointer"="all" ↵Fangrui Song1-1/+1
as cleanups after D56351
2019-10-31Fix a few typos in SourceLevelDebugging.rstAdrian Prantl1-5/+5
2019-10-29[DWARF5] Added support for deleted C++ special member functions.Adrian Prantl1-0/+33
This patch adds support for deleted C++ special member functions in clang and llvm. Also added Defaulted member encodings for future support for defaulted member functions. Patch by Sourabh Singh Tomar! Differential Revision: https://reviews.llvm.org/D69215
2019-09-11Update link to the DWARF spec.Adrian Prantl1-6/+6
llvm-svn: 371650
2019-09-11Update documentation.Adrian Prantl1-6/+6
llvm-svn: 371648
2019-06-18[DebugInfo][Docs] Document that prologue/epilogue variable location changes ↵Jeremy Morse1-4/+13
are ignored This patch documents that LLVM does not describe all changes in variable locations during the prologue and the epilogue. The debugger doesn't / shouldn't step through that portion of the function anyway, and describing every location through such stages would bloat location lists. Perform some minor cleanup at the same time, * Fix an enumerated list * Document that dbg.declare intrinsics have their variable location recorded in a MachineFunction table, not with DBG_VALUE meta-insts * Adds frame-indexes to the list of things that can be operands to DBG_VALUEs. Differential Revision: https://reviews.llvm.org/D63083 llvm-svn: 363654
2019-05-01[llvm-readobj] Change -long-option to --long-option in tests. NFCFangrui Song1-2/+2
We use both -long-option and --long-option in tests. Switch to --long-option for consistency. In the "llvm-readelf" mode, -long-option is discouraged as it conflicts with grouped short options and it is not accepted by GNU readelf. While updating the tests, change llvm-readobj -s to llvm-readobj -S to reduce confusion ("s" is --section-headers in llvm-readobj but --symbols in llvm-readelf). llvm-svn: 359649
2019-04-15[Docs] Switch a code block from LLVM to textJeremy Morse1-1/+1
While I can't replicate this locally, it looks like the buildbots don't recognize the IR block in r358385 l764 as IR. Downgrade it to being just text while I look into it. http://lab.llvm.org:8011/builders/llvm-sphinx-docs/builds/30132 llvm-svn: 358391
2019-04-15[Docs] Correct some indentation muppetry that trips buildbotsJeremy Morse1-3/+3
llvm-svn: 358388
2019-04-15[DebugInfo][Docs] Document variable location metadata transformationsJeremy Morse1-0/+310
This patch adds documentation explaining how variable location information is compiled from the IR representation down to the end of the codegen pipeline, but avoiding discussion of file formats and encoding. This should make it clearer how the dbg.value / dbg.declare etc intrinsics are transformed and arranged into DBG_VALUE instructions, and their meaning. Differential Revision: https://reviews.llvm.org/D59790 llvm-svn: 358385
2019-03-14Add IR debug info support for Elemental, Pure, and Recursive Procedures.Adrian Prantl1-0/+31
Patch by Eric Schweitz! Differential Revision: https://reviews.llvm.org/D54043 llvm-svn: 356163
2019-03-13[DebugInfo][Docs] Document how dbg.value intrinsics are interpreted in ↵Jeremy Morse1-0/+125
optimized code This patch adds a section, ``Object lifetime in optimized code'', that documents how such intrinsics are supposed to be handled. It sets out some of the principles of how they specify variable locations, and how long those locations are valid for. This patch also documents one of the objectives behind the variable-location design, that we should never allow the debugger to observe a state of the program that would not have appeared without optimization. Differential Revision: https://reviews.llvm.org/D58726 llvm-svn: 356041
2019-01-15Remove irrelevant references to legacy git repositories fromJames Y Knight1-2/+2
compiler identification lines in test-cases. (Doing so only because it's then easier to search for references which are actually important and need fixing.) llvm-svn: 351200
2018-11-19It's itsPaul Robinson1-1/+1
llvm-svn: 347271
2018-09-20[IR] Add a boolean field in DILocation to know if a line must covered or notCalixte Denizet1-0/+15
Summary: Some lines have a hit counter where they should not have one. For example, in C++, some cleanup is adding at the end of a scope represented by a '}'. So such a line has a hit counter where a user expects to not have one. The goal of the patch is to add this information in DILocation which is used to get the covered lines in GCOVProfiling.cpp. A following patch in clang will add this information when generating IR (https://reviews.llvm.org/D49916). Reviewers: marco-c, davidxl, vsk, javed.absar, rnk Reviewed By: rnk Subscribers: eraman, xur, danielcdh, aprantl, rnk, dblaikie, #debug-info, vsk, llvm-commits, sylvestre.ledru Tags: #debug-info Differential Revision: https://reviews.llvm.org/D49915 llvm-svn: 342631
2018-08-31Revamp test-suite documentationMatthias Braun1-2/+3
- Remove duplication: Both TestingGuide and TestSuiteMakefileGuide would give a similar overview over the test-suite. - Present cmake/lit as the default/normal way of running the test-suite: - Move information about the cmake/lit testsuite into the new TestSuiteGuide.rst file. Mark the remaining information in TestSuiteMakefilesGuide.rst as deprecated. - General simplification and shorting of language. - Remove paragraphs about tests known to fail as everything should pass nowadays. - Remove paragraph about zlib requirement; it's not required anymore since we copied a zlib source snapshot into the test-suite. - Remove paragraph about comparison with "native compiler". Correctness is always checked against reference outputs nowadays. - Change cmake/lit quickstart section to recommend `pip` for installing lit and use `CMAKE_C_COMPILER` and a cache file in the example as that is what most people will end up doing anyway. Also a section about compare.py to quickstart. - Document `Bitcode` and `MicroBenchmarks` directories. - Add section with commonly used cmake configuration options. - Add section about showing and comparing result files via compare.py. - Add section about using external benchmark suites. - Add section about using custom benchmark suites. - Add section about profile guided optimization. - Add section about cross-compilation and running on external devices. Differential Revision: https://reviews.llvm.org/D51465 llvm-svn: 341260