diff --git a/llvm/docs/CommandGuide/llvm-debuginfo-analyzer.rst b/llvm/docs/CommandGuide/llvm-debuginfo-analyzer.rst index 54622cc61fdfd..5b3200a4b7823 100644 --- a/llvm/docs/CommandGuide/llvm-debuginfo-analyzer.rst +++ b/llvm/docs/CommandGuide/llvm-debuginfo-analyzer.rst @@ -2267,6 +2267,10 @@ EXIT STATUS :program:`llvm-debuginfo-analyzer` returns 0 if the input files were parsed and printed successfully. Otherwise, it returns 1. +LIMITATIONS AND KNOWN ISSUES +---------------------------- +See :download:`Limitations <../../tools/llvm-debuginfo-analyzer/README.md>`. + SEE ALSO -------- :manpage:`llvm-dwarfdump` diff --git a/llvm/include/llvm/DebugInfo/LogicalView/Readers/LVCodeViewReader.h b/llvm/include/llvm/DebugInfo/LogicalView/Readers/LVCodeViewReader.h index 8a32210bac3c9..4dd7c967ddc17 100644 --- a/llvm/include/llvm/DebugInfo/LogicalView/Readers/LVCodeViewReader.h +++ b/llvm/include/llvm/DebugInfo/LogicalView/Readers/LVCodeViewReader.h @@ -58,7 +58,7 @@ class LVSymbolVisitorDelegate; using LVNames = SmallVector; -// The ELF reader uses the DWARF constants to create the logical elements. +// The DWARF reader uses the DWARF constants to create the logical elements. // The DW_TAG_* and DW_AT_* are used to select the logical object and to // set specific attributes, such as name, type, etc. // As the CodeView constants are different to the DWARF constants, the diff --git a/llvm/include/llvm/DebugInfo/LogicalView/Readers/LVDWARFReader.h b/llvm/include/llvm/DebugInfo/LogicalView/Readers/LVDWARFReader.h index 22e804a459f87..fdc97249d8e5a 100644 --- a/llvm/include/llvm/DebugInfo/LogicalView/Readers/LVDWARFReader.h +++ b/llvm/include/llvm/DebugInfo/LogicalView/Readers/LVDWARFReader.h @@ -49,7 +49,7 @@ class LVDWARFReader final : public LVBinaryReader { // In DWARF v4, the files are 1-indexed. // In DWARF v5, the files are 0-indexed. - // The ELF reader expects the indexes as 1-indexed. + // The DWARF reader expects the indexes as 1-indexed. bool IncrementFileIndex = false; // Address ranges collected for current DIE. diff --git a/llvm/lib/DebugInfo/LogicalView/Readers/LVDWARFReader.cpp b/llvm/lib/DebugInfo/LogicalView/Readers/LVDWARFReader.cpp index 91e5a037054da..6a97bed9e3a83 100644 --- a/llvm/lib/DebugInfo/LogicalView/Readers/LVDWARFReader.cpp +++ b/llvm/lib/DebugInfo/LogicalView/Readers/LVDWARFReader.cpp @@ -878,7 +878,7 @@ Error LVDWARFReader::createScopes() { // Additional discussions here: // https://www.mail-archive.com/dwarf-discuss@lists.dwarfstd.org/msg00883.html - // The ELF Reader is expecting the files are 1-indexed, so using + // The DWARF reader is expecting the files are 1-indexed, so using // the .debug_line header information decide if the indexed require // an internal adjustment. @@ -918,7 +918,7 @@ Error LVDWARFReader::createScopes() { // DWARF-5 -> Increment index. return true; }; - // The ELF reader expects the indexes as 1-indexed. + // The DWARF reader expects the indexes as 1-indexed. IncrementFileIndex = DeduceIncrementFileIndex(); DWARFDie UnitDie = CU->getUnitDIE(); diff --git a/llvm/tools/llvm-debuginfo-analyzer/README.md b/llvm/tools/llvm-debuginfo-analyzer/README.md new file mode 100644 index 0000000000000..28c4be6f73229 --- /dev/null +++ b/llvm/tools/llvm-debuginfo-analyzer/README.md @@ -0,0 +1,170 @@ +# `llvm-debuginfo-analyzer` + +These are the notes collected during the development, review and test. +They describe limitations, known issues and future work. + +### Remove the use of macros in ``LVReader.h`` that describe the ``bumpallocators``. +**[D137933](https://reviews.llvm.org/D137933#inline-1389904)** + +Use a standard (or LLVM) ``map`` with ``typeinfo`` (would need a specialization +to expose equality and hasher) for the allocators and the creation +functions could be a function template. + +### Use a **lit test** instead of a **unit test** for the **logical readers**. +**[D125783](https://reviews.llvm.org/D125783#inline-1324376)** + +As the ``DebugInfoLogicalView`` library is sufficiently exposed via the +``llvm-debuginfo-analyzer`` tool, follow the LLVM general approach and +use ``lit`` tests to validate the **logical readers**. + +Convert the ``unitests``: +``` +llvm-project/llvm/unittests/DebugInfo/LogicalView/CodeViewReaderTest.cpp +llvm-project/llvm/unittests/DebugInfo/LogicalView/DWARFReaderTest.cpp +``` +into ``lit`` tests: +``` +llvm-project/llvm/test/DebugInfo/LogicalView/CodeViewReader.test +llvm-project/llvm/test/DebugInfo/LogicalView/DWARFReader.test +``` + +### Eliminate calls to ``getInputFileDirectory()`` in the ``unittests``. +**[D125783](https://reviews.llvm.org/D125783#inline-1324359)** + +Rewrite the unittests ``ReaderTest`` and ``CodeViewReaderTest`` to eliminate +the call: +``` + getInputFileDirectory() +``` +as use of that call is discouraged. + +### Fix mismatch between ``%d/%x`` format strings and ``uint64_t`` type. +**[D137400](https://reviews.llvm.org/D137400) / [58758](https://github.com/llvm/llvm-project/issues/58758)** + +Incorrect printing of ``uint64_t`` on ``32-bit`` platforms. +Add the ``PRIx64`` specifier to the printing code (``format()``). + +### Remove ``LVScope::Children`` container. +**[D137933](https://reviews.llvm.org/D137933#inline-1373902)** + +Use a **chaining iterator** over the other containers rather than keep a +separate container ``Children`` that mirrors their contents. + +### Use ``TableGen`` for command line options. +**[D125777](https://reviews.llvm.org/D125777#inline-1291801)** + +The current trend is to use ``TableGen`` for command-line options in tools. +Change command line options to use ``tablegen`` as many other LLVM tools. + +### ``LVDoubleMap`` to return ``optional`` instead of ``null pointer``. +**[D125783](https://reviews.llvm.org/D125783#inline-1294164)** + +The more idiomatic LLVM way to handle this would be to have ``find`` +return ``Optional``. + +### Pass references instead of pointers (**Comparison functions**). +**[D125782](https://reviews.llvm.org/D125782#inline-1293920)** + +In the **comparison functions**, pass references instead of pointers (when +pointers cannot be null). + +### Use ``StringMap`` where possible. +**[D125783](https://reviews.llvm.org/D125783#inline-1294211)** + +LLVM has a ``StringMap`` class that is advertised as more efficient than +``std::map``. Mainly it does fewer allocations +because the key is not a ``std::string``. + +Replace the use of ``std::map`` with ``StringMap``. +One specific case is the ``LVSymbolNames`` definitions. + +### Calculate unique offset for CodeView elements. +In order to have the same logical functionality as the DWARF reader, such +as: + +* find scopes contribution to debug info +* sort by its physical location + +The logical elements must have an unique offset (similar like the DWARF +``DIE`` offset). + +### Move ``initializeFileAndStringTables`` to the CodeView Library. +There is some code in the CodeView reader that was extracted/adapted +from ``tools/llvm-readobj/COFFDumper.cpp`` that can be moved to the CodeView +library. + +We had a similar case with code shared with ``llvm-pdbutil`` that was moved +to the PDB library: **[D122226](https://reviews.llvm.org/D122226)** + +### Move ``getSymbolKindName`` and ``formatRegisterId`` to the CodeView Library. +There is some code in the CodeView reader that was extracted/adapted +from ``lib/DebugInfo/CodeView/SymbolDumper.cpp`` that can be used. + +### Use of ``std::unordered_set`` instead of ``std::set``. +**[D125784](https://reviews.llvm.org/D125784#inline-1221421)** + +Replace the ``std::set`` usage for ``DeducedScopes``, ``UnresolvedScopes`` and +``IdentifiedNamespaces`` with ``std::unordered_set`` and get the benefit +of the O(1) while inserting/searching, as the order is not important. + +### Optimize ``LVNamespaceDeduction::find`` funtion. +**[D125784](https://reviews.llvm.org/D125784#inline-1296195)** + +Optimize the ``find`` method to use the proposed code: + +``` + LVStringRefs::iterator Iter = std::find_if(Components.begin(), Components.end(), + [](StringRef Name) { + return IdentifiedNamespaces.find(Name) == IdentifiedNamespaces.end(); + }); + LVStringRefs::size_type FirstNonNamespace = std::distance(Components.begin(), Iter); +``` + +### Move all the printing support to a common module. +Factor out printing functionality from the logical elements into a +common module. + +### Refactor ``LVBinaryReader::processLines``. +**[D125783](https://reviews.llvm.org/D125783#inline-1246155) / +[D137156](https://reviews.llvm.org/D137156)** + +During the traversal of the debug information sections, we created the +logical lines representing the **disassembled instructions** from the **text +section** and the logical lines representing the **line records** from the +**debug line** section. Using the ranges associated with the logical scopes, +we will allocate those logical lines to their logical scopes. + +Consider the case when any of those lines become orphans, causing +incorrect scope parent for disassembly or line records. + +### Add support for ``-ffunction-sections``. +**[D125783](https://reviews.llvm.org/D125783#inline-1295012)** + +Only linked executables are handled. It does not support relocatable +files compiled with ``-ffunction-sections``. + +### Add support for DWARF v5 `.debug_names` section / CodeView public symbols stream. +**[D125783](https://reviews.llvm.org/D125783#inline-1294142)** + +The DWARF and CodeView readers use the public names information to create +the instructions (``LVLineAssembler``). Instead of relying on DWARF section +names (``.debug_pubnames``, ``.debug_names``) and CodeView public symbol stream +(``S_PUB32``), the readers should collect the needed information while processing +the debug information. + +If the object file supports the above section names and stream, use them +to create the public names. + +### Add support for some extra DWARF locations. +The following DWARF debug location operands are not supported: + +* `DW_OP_const_type` +* `DW_OP_entry_value` +* `DW_OP_implicit_value` + +### Add support for additional binary formats. +* Extended COFF (`XCOFF`) + +### Add support for ``JSON`` or ``YAML`` +The logical view uses its own and non-standard free form text when +displaying information on logical elements. diff --git a/llvm/tools/llvm-debuginfo-analyzer/README.txt b/llvm/tools/llvm-debuginfo-analyzer/README.txt deleted file mode 100644 index ce7569d272245..0000000000000 --- a/llvm/tools/llvm-debuginfo-analyzer/README.txt +++ /dev/null @@ -1,221 +0,0 @@ -//===- llvm/tools/llvm-debuginfo-analyzer/README.txt ----------------------===// -// -// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. -// See https://llvm.org/LICENSE.txt for license information. -// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception -// -//===----------------------------------------------------------------------===// -// -// This file contains notes collected during the development, review and test. -// It describes limitations, know issues and future work. -// -//===----------------------------------------------------------------------===// - -//===----------------------------------------------------------------------===// -// Remove the use of macros in 'LVReader.h' that describe the bumpallocators. -//===----------------------------------------------------------------------===// -https://reviews.llvm.org/D137933#inline-1389904 - -Use a standard (or LLVM) map with typeinfo (would need a specialization -to expose equality and hasher) for the allocators and the creation -functions could be a function template. - -//===----------------------------------------------------------------------===// -// Use a lit test instead of a unit test for the logical readers. -//===----------------------------------------------------------------------===// -https://reviews.llvm.org/D125783#inline-1324376 - -As the DebugInfoLogicalView library is sufficiently exposed via the -llvm-debuginfo-analyzer tool, follow the LLVM general approach and -use LIT tests to validate the logical readers. - -Convert the unitests: - llvm-project/llvm/unittests/DebugInfo/LogicalView/CodeViewReaderTest.cpp - llvm-project/llvm/unittests/DebugInfo/LogicalView/DWARFReaderTest.cpp - -into LIT tests: - llvm-project/llvm/test/DebugInfo/LogicalView/CodeViewReader.test - llvm-project/llvm/test/DebugInfo/LogicalView/DWARFReader.test - -//===----------------------------------------------------------------------===// -// Eliminate calls to 'getInputFileDirectory()' in the unit tests. -//===----------------------------------------------------------------------===// -https://reviews.llvm.org/D125783#inline-1324359 - -Rewrite the unittests 'LFReaderTest' and 'CodeViewReaderTest'to eliminate -the call: - - getInputFileDirectory() - -as use of that call is discouraged. - -See: Use a lit test instead of a unit test for the logical readers. - -//===----------------------------------------------------------------------===// -// Fix mismatch between %d/%x format strings and uint64_t type. -//===----------------------------------------------------------------------===// -https://reviews.llvm.org/D137400 -https://github.com/llvm/llvm-project/issues/58758 - -Incorrect printing of uint64_t on 32-bit platforms. -Add the PRIx64 specifier to the printing code (format()). - -//===----------------------------------------------------------------------===// -// Remove 'LVScope::Children' container. -//===----------------------------------------------------------------------===// -https://reviews.llvm.org/D137933#inline-1373902 - -Use a chaining iterator over the other containers rather than keep a -separate container 'Children' that mirrors their contents. - -//===----------------------------------------------------------------------===// -// Use TableGen for command line options. -//===----------------------------------------------------------------------===// -https://reviews.llvm.org/D125777#inline-1291801 - -The current trend is to use TableGen for command-line options in tools. -Change command line options to use tablegen as many other LLVM tools. - -//===----------------------------------------------------------------------===// -// LVDoubleMap to return optional instead of null pointer. -//===----------------------------------------------------------------------===// -https://reviews.llvm.org/D125783#inline-1294164 - -The more idiomatic LLVM way to handle this would be to have 'find ' -return Optional. - -//===----------------------------------------------------------------------===// -// Pass references instead of pointers (Comparison functions). -//===----------------------------------------------------------------------===// -https://reviews.llvm.org/D125782#inline-1293920 - -In the comparison functions, pass references instead of pointers (when -pointers cannot be null). - -//===----------------------------------------------------------------------===// -// Use StringMap where possible. -//===----------------------------------------------------------------------===// -https://reviews.llvm.org/D125783#inline-1294211 - -LLVM has a StringMap class that is advertised as more efficient than -std::map. Mainly it does fewer allocations -because the key is not a std::string. - -Replace the use of std::map with String Map. -One specific case is the LVSymbolNames definitions. - -//===----------------------------------------------------------------------===// -// Calculate unique offset for CodeView elements. -//===----------------------------------------------------------------------===// -In order to have the same logical functionality as the ELF Reader, such -as: - -- find scopes contribution to debug info -- sort by its physical location - -The logical elements must have an unique offset (similar like the DWARF -DIE offset). - -//===----------------------------------------------------------------------===// -// Move 'initializeFileAndStringTables' to the COFF Library. -//===----------------------------------------------------------------------===// -There is some code in the CodeView reader that was extracted/adapted -from 'tools/llvm-readobj/COFFDumper.cpp' that can be moved to the COFF -library. - -We had a similar case with code shared with llvm-pdbutil that was moved -to the PDB library: https://reviews.llvm.org/D122226 - -//===----------------------------------------------------------------------===// -// Move 'getSymbolKindName'/'formatRegisterId' to the CodeView Library. -//===----------------------------------------------------------------------===// -There is some code in the CodeView reader that was extracted/adapted -from 'lib/DebugInfo/CodeView/SymbolDumper.cpp' that can be used. - -//===----------------------------------------------------------------------===// -// Use of std::unordered_set instead of std::set. -//===----------------------------------------------------------------------===// -https://reviews.llvm.org/D125784#inline-1221421 - -Replace the std::set usage for DeducedScopes, UnresolvedScopes and -IdentifiedNamespaces with std::unordered_set and get the benefit -of the O(1) while inserting/searching, as the order is not important. - -//===----------------------------------------------------------------------===// -// Optimize 'LVNamespaceDeduction::find' funtion. -//===----------------------------------------------------------------------===// -https://reviews.llvm.org/D125784#inline-1296195 - -Optimize the 'find' method to use the proposed code: - - LVStringRefs::iterator Iter = std::find_if(Components.begin(), Components.end(), - [](StringRef Name) { - return IdentifiedNamespaces.find(Name) == IdentifiedNamespaces.end(); - }); - LVStringRefs::size_type FirstNonNamespace = std::distance(Components.begin(), Iter); - -//===----------------------------------------------------------------------===// -// Move all the printing support to a common module. -//===----------------------------------------------------------------------===// -Factor out printing functionality from the logical elements into a -common module. - -//===----------------------------------------------------------------------===// -// Refactor 'LVBinaryReader::processLines'. -//===----------------------------------------------------------------------===// -https://reviews.llvm.org/D125783#inline-1246155 -https://reviews.llvm.org/D137156 - -During the traversal of the debug information sections, we created the -logical lines representing the disassembled instructions from the text -section and the logical lines representing the line records from the -debug line section. Using the ranges associated with the logical scopes, -we will allocate those logical lines to their logical scopes. - -Consider the case when any of those lines become orphans, causing -incorrect scope parent for disassembly or line records. - -//===----------------------------------------------------------------------===// -// Add support for '-ffunction-sections'. -//===----------------------------------------------------------------------===// -https://reviews.llvm.org/D125783#inline-1295012 - -Only linked executables are handled. It does not support relocatable -files compiled with -ffunction-sections. - -//===----------------------------------------------------------------------===// -// Add support for DWARF v5 .debug_names section. -// Add support for CodeView public symbols stream. -//===----------------------------------------------------------------------===// -https://reviews.llvm.org/D125783#inline-1294142 - -The ELF and CodeView readers use the public names information to create -the instructions (LVLineAssembler). Instead of relying on DWARF section -names (.debug_pubnames, .debug_names) and CodeView public symbol stream -(S_PUB32), the readers collects the needed information while processing -the debug information. - -If the object file supports the above section names and stream, use them -to create the public names. - -//===----------------------------------------------------------------------===// -// Add support for some extra DWARF locations. -//===----------------------------------------------------------------------===// -The following DWARF debug location operands are not supported: - -- DW_OP_const_type -- DW_OP_entry_value -- DW_OP_implicit_value - -//===----------------------------------------------------------------------===// -// Add support for additional binary formats. -//===----------------------------------------------------------------------===// -- Extended COFF (XCOFF) - -//===----------------------------------------------------------------------===// -// Add support for JSON or YAML. -//===----------------------------------------------------------------------===// -The logical view uses its own and non-standard free form text when -displaying information on logical elements. - -//===----------------------------------------------------------------------===//