[llvm] [llvm-debuginfo-analyzer][DOC] Convert 'README.txt' to markdown. (PR #86394)
via llvm-commits
llvm-commits at lists.llvm.org
Sat Mar 23 07:08:39 PDT 2024
llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-llvm-binary-utilities
Author: Carlos Alberto Enciso (CarlosAlbertoEnciso)
<details>
<summary>Changes</summary>
As part of the WebAssembly support work
https://github.com/llvm/llvm-project/pull/85566
The README.txt is a bit odd since it only lists issues and problems without talking about what works. It’s also hard to read on the GitHub web view.
- Convert to Markdown and linking to the command docs https://llvm.org/docs/CommandGuide/llvm-debuginfo-analyzer
- Rename some left 'elf reader' to 'DWARF reader'.
---
Patch is 20.72 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/86394.diff
6 Files Affected:
- (modified) llvm/docs/CommandGuide/llvm-debuginfo-analyzer.rst (+4)
- (modified) llvm/include/llvm/DebugInfo/LogicalView/Readers/LVCodeViewReader.h (+1-1)
- (modified) llvm/include/llvm/DebugInfo/LogicalView/Readers/LVDWARFReader.h (+1-1)
- (modified) llvm/lib/DebugInfo/LogicalView/Readers/LVDWARFReader.cpp (+2-2)
- (added) llvm/tools/llvm-debuginfo-analyzer/README.md (+171)
- (removed) llvm/tools/llvm-debuginfo-analyzer/README.txt (-221)
``````````diff
diff --git a/llvm/docs/CommandGuide/llvm-debuginfo-analyzer.rst b/llvm/docs/CommandGuide/llvm-debuginfo-analyzer.rst
index 54622cc61fdfda..5b3200a4b78235 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 8a32210bac3c9c..4dd7c967ddc17d 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<StringRef, 16>;
-// 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 22e804a459f873..fdc97249d8e5a9 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 91e5a037054da0..6a97bed9e3a838 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 00000000000000..cc8df4ee13a6fe
--- /dev/null
+++ b/llvm/tools/llvm-debuginfo-analyzer/README.md
@@ -0,0 +1,171 @@
+# llvm-debuginfo-analyzer
+
+These are the notes collected during the development, review and test.
+They describe limitations, know 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.
+
+.. _lit-test-label:
+### 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 unit tests.
+**[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\<ValueType\>* 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\<ValueType\>**.
+
+### 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\<std::string, ValueType\>**. Mainly it does fewer allocations
+because the key is not a **std::string**.
+
+Replace the use of **std::map\<std::string, ValueType\>** 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 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: **[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 ce7569d2722452..00000000000000
--- 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<ValueType> 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<ValueType>.
-
-//===----------------------------------------------------------------------===//
-// 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<std::string, ValueType>. Mainly it does fewer allocations
-because the key is not a std::string.
-
-Replace the use of std::map<std::string, ValueType> 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 deb...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/86394
More information about the llvm-commits
mailing list