Skip to content

Commit c5a744f

Browse files
CarlosAlbertoEncisoCarlosAlbertoEnciso
committed
[llvm-debuginfo-analyzer][DOC] Convert 'README.txt' to markdown.
As part of the WebAssembly support work llvm#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'.
1 parent c1ccf07 commit c5a744f

File tree

6 files changed

+179
-225
lines changed

6 files changed

+179
-225
lines changed

‎llvm/docs/CommandGuide/llvm-debuginfo-analyzer.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2267,6 +2267,10 @@ EXIT STATUS
22672267
:program:`llvm-debuginfo-analyzer` returns 0 if the input files were
22682268
parsed and printed successfully. Otherwise, it returns 1.
22692269

2270+
LIMITATIONS AND KNOWN ISSUES
2271+
----------------------------
2272+
See :download:`Limitations <../../tools/llvm-debuginfo-analyzer/README.md>`.
2273+
22702274
SEE ALSO
22712275
--------
22722276
:manpage:`llvm-dwarfdump`

‎llvm/include/llvm/DebugInfo/LogicalView/Readers/LVCodeViewReader.h

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ class LVSymbolVisitorDelegate;
5858

5959
using LVNames = SmallVector<StringRef, 16>;
6060

61-
// The ELF reader uses the DWARF constants to create the logical elements.
61+
// The DWARF reader uses the DWARF constants to create the logical elements.
6262
// The DW_TAG_* and DW_AT_* are used to select the logical object and to
6363
// set specific attributes, such as name, type, etc.
6464
// As the CodeView constants are different to the DWARF constants, the

‎llvm/include/llvm/DebugInfo/LogicalView/Readers/LVDWARFReader.h

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ class LVDWARFReader final : public LVBinaryReader {
4949

5050
// In DWARF v4, the files are 1-indexed.
5151
// In DWARF v5, the files are 0-indexed.
52-
// The ELF reader expects the indexes as 1-indexed.
52+
// The DWARF reader expects the indexes as 1-indexed.
5353
bool IncrementFileIndex = false;
5454

5555
// Address ranges collected for current DIE.

‎llvm/lib/DebugInfo/LogicalView/Readers/LVDWARFReader.cpp

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -878,7 +878,7 @@ Error LVDWARFReader::createScopes() {
878878
// Additional discussions here:
879879
// https://www.mail-archive.com/[email protected]/msg00883.html
880880

881-
// The ELF Reader is expecting the files are 1-indexed, so using
881+
// The DWARF reader is expecting the files are 1-indexed, so using
882882
// the .debug_line header information decide if the indexed require
883883
// an internal adjustment.
884884

@@ -918,7 +918,7 @@ Error LVDWARFReader::createScopes() {
918918
// DWARF-5 -> Increment index.
919919
return true;
920920
};
921-
// The ELF reader expects the indexes as 1-indexed.
921+
// The DWARF reader expects the indexes as 1-indexed.
922922
IncrementFileIndex = DeduceIncrementFileIndex();
923923

924924
DWARFDie UnitDie = CU->getUnitDIE();

‎llvm/tools/llvm-debuginfo-analyzer/README.md

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# llvm-debuginfo-analyzer
2+
3+
These are the notes collected during the development, review and test.
4+
They describe limitations, know issues and future work.
5+
6+
### Remove the use of macros in *LVReader.h* that describe the *bumpallocators*.
7+
**[D137933](https://reviews.llvm.org/D137933#inline-1389904)**
8+
9+
Use a standard (or LLVM) **map** with **typeinfo** (would need a specialization
10+
to expose equality and hasher) for the allocators and the creation
11+
functions could be a function template.
12+
13+
.. _lit-test-label:
14+
### Use a *lit test* instead of a *unit test* for the *logical readers*.
15+
**[D125783](https://reviews.llvm.org/D125783#inline-1324376)**
16+
17+
As the **DebugInfoLogicalView** library is sufficiently exposed via the
18+
**llvm-debuginfo-analyzer** tool, follow the LLVM general approach and
19+
use **LIT** tests to validate the **logical readers**.
20+
21+
Convert the **unitests**:
22+
```
23+
llvm-project/llvm/unittests/DebugInfo/LogicalView/CodeViewReaderTest.cpp
24+
llvm-project/llvm/unittests/DebugInfo/LogicalView/DWARFReaderTest.cpp
25+
```
26+
into **LIT tests**:
27+
```
28+
llvm-project/llvm/test/DebugInfo/LogicalView/CodeViewReader.test
29+
llvm-project/llvm/test/DebugInfo/LogicalView/DWARFReader.test
30+
```
31+
32+
### Eliminate calls to *getInputFileDirectory()* in the unit tests.
33+
**[D125783](https://reviews.llvm.org/D125783#inline-1324359)**
34+
35+
Rewrite the unittests **ReaderTest** and **CodeViewReaderTest** to eliminate
36+
the call:
37+
```
38+
getInputFileDirectory()
39+
```
40+
as use of that call is discouraged.
41+
42+
### Fix mismatch between *%d/%x* format strings and *uint64_t* type.
43+
**[D137400](https://reviews.llvm.org/D137400) / [58758](https://github.com/llvm/llvm-project/issues/58758)**
44+
45+
Incorrect printing of **uint64_t** on **32-bit** platforms.
46+
Add the **PRIx64** specifier to the printing code (**format()**).
47+
48+
### Remove *LVScope::Children* container.
49+
**[D137933](https://reviews.llvm.org/D137933#inline-1373902)**
50+
51+
Use a **chaining iterator** over the other containers rather than keep a
52+
separate container **Children** that mirrors their contents.
53+
54+
### Use *TableGen* for command line options.
55+
**[D125777](https://reviews.llvm.org/D125777#inline-1291801)**
56+
57+
The current trend is to use **TableGen** for command-line options in tools.
58+
Change command line options to use **tablegen** as many other LLVM tools.
59+
60+
### *LVDoubleMap* to return *optional\<ValueType\>* instead of null pointer.
61+
**[D125783](https://reviews.llvm.org/D125783#inline-1294164)**
62+
63+
The more idiomatic LLVM way to handle this would be to have **find**
64+
return **Optional\<ValueType\>**.
65+
66+
### Pass references instead of pointers (*Comparison functions*).
67+
**[D125782](https://reviews.llvm.org/D125782#inline-1293920)**
68+
69+
In the **comparison functions**, pass references instead of pointers (when
70+
pointers cannot be null).
71+
72+
### Use *StringMap* where possible.
73+
**[D125783](https://reviews.llvm.org/D125783#inline-1294211)**
74+
75+
LLVM has a **StringMap** class that is advertised as more efficient than
76+
**std::map\<std::string, ValueType\>**. Mainly it does fewer allocations
77+
because the key is not a **std::string**.
78+
79+
Replace the use of **std::map\<std::string, ValueType\>** with **StringMap**.
80+
One specific case is the **LVSymbolNames** definitions.
81+
82+
### Calculate unique offset for *CodeView* elements.
83+
In order to have the same logical functionality as the **DWARF Reader**, such
84+
as:
85+
86+
* find scopes contribution to debug info
87+
* sort by its physical location
88+
89+
The logical elements must have an unique offset (similar like the **DWARF
90+
DIE offset**).
91+
92+
### Move *initializeFileAndStringTables* to the COFF Library.
93+
There is some code in the CodeView reader that was extracted/adapted
94+
from **tools/llvm-readobj/COFFDumper.cpp** that can be moved to the **COFF**
95+
library.
96+
97+
We had a similar case with code shared with llvm-pdbutil that was moved
98+
to the PDB library: **[D122226](https://reviews.llvm.org/D122226)**
99+
100+
### Move *getSymbolKindName* and *formatRegisterId* to the CodeView Library.
101+
There is some code in the CodeView reader that was extracted/adapted
102+
from **lib/DebugInfo/CodeView/SymbolDumper.cpp** that can be used.
103+
104+
### Use of *std::unordered_set* instead of *std::set*.
105+
**[D125784](https://reviews.llvm.org/D125784#inline-1221421)**
106+
107+
Replace the **std::set** usage for **DeducedScopes**, **UnresolvedScopes** and
108+
**IdentifiedNamespaces** with **std::unordered_set** and get the benefit
109+
of the O(1) while inserting/searching, as the order is not important.
110+
111+
### Optimize *LVNamespaceDeduction::find* funtion.
112+
**[D125784](https://reviews.llvm.org/D125784#inline-1296195)**
113+
114+
Optimize the **find** method to use the proposed code:
115+
116+
```
117+
LVStringRefs::iterator Iter = std::find_if(Components.begin(), Components.end(),
118+
[](StringRef Name) {
119+
return IdentifiedNamespaces.find(Name) == IdentifiedNamespaces.end();
120+
});
121+
LVStringRefs::size_type FirstNonNamespace = std::distance(Components.begin(), Iter);
122+
```
123+
124+
### Move all the printing support to a common module.
125+
Factor out printing functionality from the logical elements into a
126+
common module.
127+
128+
### Refactor *LVBinaryReader::processLines*.
129+
**[D125783](https://reviews.llvm.org/D125783#inline-1246155) /
130+
[D137156](https://reviews.llvm.org/D137156)**
131+
132+
During the traversal of the debug information sections, we created the
133+
logical lines representing the **disassembled instructions** from the **text
134+
section** and the logical lines representing the **line records** from the
135+
**debug line** section. Using the ranges associated with the logical scopes,
136+
we will allocate those logical lines to their logical scopes.
137+
138+
Consider the case when any of those lines become orphans, causing
139+
incorrect scope parent for disassembly or line records.
140+
141+
### Add support for *-ffunction-sections*.
142+
**[D125783](https://reviews.llvm.org/D125783#inline-1295012)**
143+
144+
Only linked executables are handled. It does not support relocatable
145+
files compiled with **-ffunction-sections**.
146+
147+
### Add support for DWARF v5 .debug_names section / CodeView public symbols stream.
148+
**[D125783](https://reviews.llvm.org/D125783#inline-1294142)**
149+
150+
The **DWARF** and **CodeView** readers use the public names information to create
151+
the instructions (**LVLineAssembler**). Instead of relying on **DWARF** section
152+
names (**.debug_pubnames**, **.debug_names**) and **CodeView** **public symbol** stream
153+
(**S_PUB32**), the readers should collect the needed information while processing
154+
the debug information.
155+
156+
If the object file supports the above section names and stream, use them
157+
to create the public names.
158+
159+
### Add support for some extra DWARF locations.
160+
The following DWARF debug location operands are not supported:
161+
162+
* DW_OP_const_type
163+
* DW_OP_entry_value
164+
* DW_OP_implicit_value
165+
166+
### Add support for additional binary formats.
167+
* Extended COFF (XCOFF)
168+
169+
### Add support for *JSON* or *YAML*.
170+
The logical view uses its own and non-standard free form text when
171+
displaying information on logical elements.

0 commit comments

Comments
 (0)