[llvm-debuginfo-analyzer] Add --output-sort=(none|id) option (#145761)

- The output for `--output-sort=id` matches `--output-sort=offset` for
the available readers. Tests were updated accordingly.

- For `--output-sort=none`, and per `LVReader::sortScopes()`,
`LVScope::sort()` is called on the root scope.
`LVScope::sort()` has no effect if `getSortFunction() == nullptr`, and
thus the elements are currently traversed in the order in which they
were initially added. This should change, however, after
`LVScope::Children` is removed.

Author: jalopezg-git

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

@@ -365,6 +365,8 @@ output for a single compilation unit.
 
  .. code-block:: text
 
+   =none: Unsorted output (i.e. as read from input).
+   =id: Sort by unique element ID.
    =kind: Sort by element kind.
    =line: Sort by element line number.
    =name: Sort by element name.

llvm/include/llvm/DebugInfo/LogicalView/Core/LVSort.h

@@ -23,6 +23,7 @@ class LVObject;
 // Object Sorting Mode.
 enum class LVSortMode {
   None = 0, // No given sort.
+  ID,       // Sort by ID.
   Kind,     // Sort by kind.
   Line,     // Sort by line.
   Name,     // Sort by name.
@@ -38,6 +39,7 @@ using LVSortFunction = LVSortValue (*)(const LVObject *LHS,
 LLVM_ABI LVSortFunction getSortFunction();
 
 // Comparator functions that can be used for sorting.
+LLVM_ABI LVSortValue compareID(const LVObject *LHS, const LVObject *RHS);
 LLVM_ABI LVSortValue compareKind(const LVObject *LHS, const LVObject *RHS);
 LLVM_ABI LVSortValue compareLine(const LVObject *LHS, const LVObject *RHS);
 LLVM_ABI LVSortValue compareName(const LVObject *LHS, const LVObject *RHS);

llvm/lib/DebugInfo/LogicalView/Core/LVSort.cpp

@@ -22,6 +22,12 @@ using namespace llvm::logicalview;
 //===----------------------------------------------------------------------===//
 // Callback functions to sort objects.
 //===----------------------------------------------------------------------===//
+// Callback comparator based on ID.
+LVSortValue llvm::logicalview::compareID(const LVObject *LHS,
+                                         const LVObject *RHS) {
+  return LHS->getID() < RHS->getID();
+}
+
 // Callback comparator based on kind.
 LVSortValue llvm::logicalview::compareKind(const LVObject *LHS,
                                            const LVObject *RHS) {
@@ -99,9 +105,9 @@ LVSortValue llvm::logicalview::sortByName(const LVObject *LHS,
 LVSortFunction llvm::logicalview::getSortFunction() {
   using LVSortInfo = std::map<LVSortMode, LVSortFunction>;
   static LVSortInfo SortInfo = {
-      {LVSortMode::None, nullptr},         {LVSortMode::Kind, sortByKind},
-      {LVSortMode::Line, sortByLine},      {LVSortMode::Name, sortByName},
-      {LVSortMode::Offset, compareOffset},
+      {LVSortMode::None, nullptr},    {LVSortMode::ID, compareID},
+      {LVSortMode::Kind, sortByKind}, {LVSortMode::Line, sortByLine},
+      {LVSortMode::Name, sortByName}, {LVSortMode::Offset, compareOffset},
   };
 
   LVSortFunction SortFunction = nullptr;

llvm/test/tools/llvm-debuginfo-analyzer/COFF/01-coff-print-basic-details.test

@@ -24,6 +24,23 @@
 ; RUN:                         %p/Inputs/test-codeview-clang.o 2>&1 | \
 ; RUN: FileCheck --strict-whitespace -check-prefix=ONE %s
 
+; If `--output-sort=id`, elements are iterated in the order in which they were
+; added (which matches the increasing offset of the reference output).
+; RUN: llvm-debuginfo-analyzer --attribute=level,format \
+; RUN:                         --output-sort=id \
+; RUN:                         --print=scopes,symbols,types,lines,instructions \
+; RUN:                         %p/Inputs/test-codeview-clang.o 2>&1 | \
+; RUN: FileCheck --strict-whitespace -check-prefix=ONE %s
+
+; If `--output-sort=none`, `LVScope::Children` is not sorted; it, however,
+; reflects the order in which elements were added (same as `--output-sort=id`).
+; This is expected to change once #69160 is resolved though.
+; RUN: llvm-debuginfo-analyzer --attribute=level,format \
+; RUN:                         --output-sort=none \
+; RUN:                         --print=scopes,symbols,types,lines,instructions \
+; RUN:                         %p/Inputs/test-codeview-clang.o 2>&1 | \
+; RUN: FileCheck --strict-whitespace -check-prefix=ONE %s
+
 ; RUN: llvm-debuginfo-analyzer --attribute=level,format \
 ; RUN:                         --output-sort=offset \
 ; RUN:                         --print=elements \

llvm/test/tools/llvm-debuginfo-analyzer/DWARF/01-dwarf-print-basic-details.test

@@ -24,6 +24,23 @@
 ; RUN:                         %p/Inputs/test-dwarf-clang.o 2>&1 | \
 ; RUN: FileCheck --strict-whitespace -check-prefix=ONE %s
 
+; If `--output-sort=id`, elements are iterated in the order in which they
+; were added (which matches the increasing offset of the reference output).
+; RUN: llvm-debuginfo-analyzer --attribute=level,format \
+; RUN:                         --output-sort=id \
+; RUN:                         --print=scopes,symbols,types,lines,instructions \
+; RUN:                         %p/Inputs/test-dwarf-clang.o 2>&1 | \
+; RUN: FileCheck --strict-whitespace -check-prefix=ONE %s
+
+; If `--output-sort=none`, `LVScope::Children` is not sorted; it, however,
+; reflects the order in which elements were added (same as `--output-sort=id`).
+; This is expected to change once #69160 is resolved though.
+; RUN: llvm-debuginfo-analyzer --attribute=level,format \
+; RUN:                         --output-sort=none \
+; RUN:                         --print=scopes,symbols,types,lines,instructions \
+; RUN:                         %p/Inputs/test-dwarf-clang.o 2>&1 | \
+; RUN: FileCheck --strict-whitespace -check-prefix=ONE %s
+
 ; RUN: llvm-debuginfo-analyzer --attribute=level,format \
 ; RUN:                         --output-sort=offset \
 ; RUN:                         --print=elements \

llvm/test/tools/llvm-debuginfo-analyzer/cmdline.test

@@ -110,6 +110,8 @@ HELP-ALL:   --output-file=<filename>   - Redirect output to the specified file.
 HELP-ALL:   --output-folder=<pathname> - Folder name for view splitting.
 HELP-ALL:   --output-level=<N>         - Only print to a depth of N elements.
 HELP-ALL:   --output-sort=<value>      - Primary key when ordering logical view (default: line).
+HELP-ALL:     =none                    -   Unsorted output (i.e. as read from input).
+HELP-ALL:     =id                      -   Sort by unique element ID.
 HELP-ALL:     =kind                    -   Sort by element kind.
 HELP-ALL:     =line                    -   Sort by element line number.
 HELP-ALL:     =name                    -   Sort by element name.

llvm/tools/llvm-debuginfo-analyzer/Options.cpp

@@ -198,7 +198,10 @@ static cl::opt<LVSortMode, true> OutputSort(
     "output-sort", cl::cat(OutputCategory),
     cl::desc("Primary key when ordering logical view (default: line)."),
     cl::Hidden, cl::ZeroOrMore,
-    values(clEnumValN(LVSortMode::Kind, "kind", "Sort by element kind."),
+    values(clEnumValN(LVSortMode::None, "none",
+                      "Unsorted output (i.e. as read from input)."),
+           clEnumValN(LVSortMode::ID, "id", "Sort by unique element ID."),
+           clEnumValN(LVSortMode::Kind, "kind", "Sort by element kind."),
            clEnumValN(LVSortMode::Line, "line", "Sort by element line number."),
            clEnumValN(LVSortMode::Name, "name", "Sort by element name."),
            clEnumValN(LVSortMode::Offset, "offset", "Sort by element offset.")),