[lldb] Add register field tables to the "register info" command

[DavidSpickett]

Summary

This teaches DumpRegisterInfo to generate a table from the register
flags type. It just calls a method on RegisterFlags.

As such, the extra tests are minimal and only show that the intergration
works. Exhaustive formatting tests are done with RegisterFlags itself.

Example:

(lldb) register info cpsr
       Name: cpsr
       Size: 4 bytes (32 bits)
    In sets: general (index 0)

| 31 | 30 | 29 | 28 | 27-26 | 25  | 24  | 23  | 22  | 21 | 20 | 19-13 |  12  | 11-10 | 9 | 8 | 7 | 6 | 5 |  4  | 3-2 | 1 | 0  |
|----|----|----|----|-------|-----|-----|-----|-----|----|----|-------|------|-------|---|---|---|---|---|-----|-----|---|----|
| N  | Z  | C  | V  |       | TCO | DIT | UAO | PAN | SS | IL |       | SSBS |       | D | A | I | F |   | nRW | EL  |   | SP |

LLDB limits the max terminal width to 80 chars by default.
So to get that full width output you will need to change the "term-width"
setting to something higher.

[DavidSpickett]

This is the major use case for the command. With these diagrams matching the architecture manual (mostly) you can use them to work out what mask/shift you need. You'll be able to print a register, see that the field isn't the right value, then "register info" and realise what you did wrong. The audience for it is small but when I was one of that audience (different debugger though) I really appreciated not having to leave the debugger to do this.

[jasonmolenda]

LGTM. Putting this in register info is good, it's not too easily discoverable (to be honest I didn't know this command existed today), but as you say, the number of people who want to see this are relatively small so putting it in a more mainstream command like register read may not be the best choice. We can start with only in register info.

lldb/include/lldb/Core/DumpRegisterInfo.h

 #include <utility>
 #include <vector>
 
 namespace lldb_private {
 
 class Stream;
 class RegisterContext;
 struct RegisterInfo;
+class RegisterFlags;
 
 void DumpRegisterInfo(Stream &strm, RegisterContext &ctx,
-                      const RegisterInfo &info);
+                      const RegisterInfo &info, uint32_t terminal_width);
 
 // For testing only. Use DumpRegisterInfo instead.
 void DoDumpRegisterInfo(
     Stream &strm, const char *name, const char *alt_name, uint32_t byte_size,
     const std::vector<const char *> &invalidates,
     const std::vector<const char *> &read_from,
-    const std::vector<std::pair<const char *, uint32_t>> &in_sets);
+    const std::vector<std::pair<const char *, uint32_t>> &in_sets,
+    const RegisterFlags *flags_type, uint32_t terminal_width);
 
 } // namespace lldb_private
 
 #endif // LLDB_CORE_DUMPREGISTERINFO_H

lldb/source/Commands/CommandObjectRegister.cpp

 //===-- CommandObjectRegister.cpp -----------------------------------------===//
 //
 // 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
 //
 //===----------------------------------------------------------------------===//
 
 #include "CommandObjectRegister.h"
 #include "lldb/Core/Debugger.h"
 #include "lldb/Core/DumpRegisterInfo.h"
 #include "lldb/Core/DumpRegisterValue.h"
 #include "lldb/Host/OptionParser.h"
+#include "lldb/Interpreter/CommandInterpreter.h"
 #include "lldb/Interpreter/CommandOptionArgumentTable.h"
 #include "lldb/Interpreter/CommandReturnObject.h"
 #include "lldb/Interpreter/OptionGroupFormat.h"
 #include "lldb/Interpreter/OptionValueArray.h"
 #include "lldb/Interpreter/OptionValueBoolean.h"
 #include "lldb/Interpreter/OptionValueUInt64.h"
 #include "lldb/Interpreter/Options.h"
 #include "lldb/Target/ExecutionContext.h"

 Invalidates (*)  The registers that would be changed if you wrote this
                  register. For example, writing to a narrower alias of a wider
                  register would change the value of the wider register.
 Read from   (*)  The registers that the value of this register is constructed
                  from. For example, a narrower alias of a wider register will be
                  read from the wider register.
 In sets     (*)  The register sets that contain this register. For example the
                  PC will be in the "General Purpose Register" set.
+Fields      (*)  A table of the names and bit positions of the values contained
+                 in this register.
 
 Fields marked with (*) may not always be present. Some information may be
 different for the same register when connected to different debug servers.)");
 
     CommandArgumentData register_arg;
     register_arg.arg_type = eArgTypeRegisterName;
     register_arg.arg_repetition = eArgRepeatPlain;
 
if (command.GetArgumentCount() != 1) {
       result.AppendError("register info takes exactly 1 argument: <reg-name>");
       return result.Succeeded();
     }
 
     llvm::StringRef reg_name = command[0].ref();
     RegisterContext *reg_ctx = m_exe_ctx.GetRegisterContext();
     const RegisterInfo *reg_info = reg_ctx->GetRegisterInfoByName(reg_name);
     if (reg_info) {
-      DumpRegisterInfo(result.GetOutputStream(), *reg_ctx, *reg_info);
+      DumpRegisterInfo(
+          result.GetOutputStream(), *reg_ctx, *reg_info,
+          GetCommandInterpreter().GetDebugger().GetTerminalWidth());
       result.SetStatus(eReturnStatusSuccessFinishResult);
     } else
       result.AppendErrorWithFormat("No register found with name '%s'.\n",
                                    reg_name.str().c_str());
 
     return result.Succeeded();
   }
 };

lldb/source/Core/DumpRegisterInfo.cpp

 //===-- DumpRegisterInfo.cpp ----------------------------------------------===//
 //
 // 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
 //
 //===----------------------------------------------------------------------===//
 
 #include "lldb/Core/DumpRegisterInfo.h"
 #include "lldb/Target/RegisterContext.h"
+#include "lldb/Target/RegisterFlags.h"
 #include "lldb/Utility/Stream.h"
 
 using namespace lldb;
 using namespace lldb_private;
 
 using SetInfo = std::pair<const char *, uint32_t>;
 
 void lldb_private::DumpRegisterInfo(Stream &strm, RegisterContext &ctx,
-                                    const RegisterInfo &info) {
+                                    const RegisterInfo &info,
+                                    uint32_t terminal_width) {
   std::vector<const char *> invalidates;
   if (info.invalidate_regs) {
     for (uint32_t *inv_regs = info.invalidate_regs;
          *inv_regs != LLDB_INVALID_REGNUM; ++inv_regs) {
       const RegisterInfo *inv_info =
           ctx.GetRegisterInfo(lldb::eRegisterKindLLDB, *inv_regs);
       assert(
           inv_info &&
for (uint32_t *read_regs = info.value_regs;
           ctx.GetRegisterInfo(lldb::eRegisterKindLLDB, *read_regs);
       assert(read_info && "Register value registers list refers to a register "
                           "that does not exist.");
       read_from.push_back(read_info->name);
     }
   }
 
   DoDumpRegisterInfo(strm, info.name, info.alt_name, info.byte_size,
-                     invalidates, read_from, in_sets);
+                     invalidates, read_from, in_sets, info.flags_type,
+                     terminal_width);
 }
 
 template <typename ElementType>
 static void DumpList(Stream &strm, const char *title,
                      const std::vector<ElementType> &list,
                      std::function<void(Stream &, ElementType)> emitter) {
   if (list.empty())
     return;
 
   strm.EOL();
   strm << title;
   bool first = true;
   for (ElementType elem : list) {
     if (!first)
       strm << ", ";
     first = false;
     emitter(strm, elem);
   }
 }
 
 void lldb_private::DoDumpRegisterInfo(
     Stream &strm, const char *name, const char *alt_name, uint32_t byte_size,
     const std::vector<const char *> &invalidates,
     const std::vector<const char *> &read_from,
-    const std::vector<SetInfo> &in_sets) {
+    const std::vector<SetInfo> &in_sets, const RegisterFlags *flags_type,
+    uint32_t terminal_width) {
   strm << "       Name: " << name;
   if (alt_name)
     strm << " (" << alt_name << ")";
   strm.EOL();
 
   // Size in bits may seem obvious for the usual 32 or 64 bit registers.
   // When we get to vector registers, then scalable vector registers, it is very
   // useful to know without the user doing extra work.
   strm.Printf("       Size: %d bytes (%d bits)", byte_size, byte_size * 8);
 
   std::function<void(Stream &, const char *)> emit_str =
       [](Stream &strm, const char *s) { strm << s; };
   DumpList(strm, "Invalidates: ", invalidates, emit_str);
   DumpList(strm, "  Read from: ", read_from, emit_str);
 
   std::function<void(Stream &, SetInfo)> emit_set = [](Stream &strm,
                                                        SetInfo info) {
     strm.Printf("%s (index %d)", info.first, info.second);
   };
   DumpList(strm, "    In sets: ", in_sets, emit_set);
+
+  if (flags_type)
+    strm.Printf("\n\n%s", flags_type->AsTable(terminal_width).c_str());
 }

lldb/test/API/commands/register/register/register_command/TestRegisters.py

def test_info_many_registers(self):
         # Only 1 register allowed at this time.
         self.expect("register info abc def", error=True,
                     substrs=["error: register info takes exactly 1 argument"])
 
     @skipIf(archs=no_match(["aarch64"]))
     def test_info_register(self):
         # The behaviour of this command is generic but the specific registers
         # are not, so this is written for AArch64 only.
-        # Text alignment and ordering are checked in the DumpRegisterInfo unit tests.
+        # Text alignment and ordering are checked in the DumpRegisterInfo and
+        # RegisterFlags unit tests.
         self.build()
         self.common_setup()
 
         # Standard register. Doesn't invalidate anything, doesn't have an alias.
         self.expect("register info x1", substrs=[
                    "Name: x1",
                    "Size: 8 bytes (64 bits)",
                    "In sets: General Purpose Registers"])

lldb/test/API/functionalities/gdb_remote_client/TestXMLRegisterFlags.py

def test_xml_includes_flags_redefined(self):
                 </feature>
             """
                 ),
             }
         )
 
         self.expect("register read x0", substrs=["(correct = 1)"])
         self.expect("register read x1", substrs=["(correct = 1)"])
+
+    @skipIfXmlSupportMissing
+    @skipIfRemote
+    def test_flags_in_register_info(self):
+        # See RegisterFlags for comprehensive formatting tests.
+        self.setup_flags_test(
+            '<field name="D" start="0" end="7"/>'
+            '<field name="C" start="8" end="15"/>'
+            '<field name="B" start="16" end="23"/>'
+            '<field name="A" start="24" end="31"/>'
+        )
+
+        # The table should split according to terminal width.
+        self.runCmd("settings set term-width 17")
+
+        self.expect("register info cpsr",
+            substrs=[
+                "       Name: cpsr\n"
+                "       Size: 4 bytes (32 bits)\n"
+                "    In sets: general (index 0)\n"
+                "\n"
+                "| 31-24 | 23-16 |\n"
+                "|-------|-------|\n"
+                "|   A   |   B   |\n"
+                "\n"
+                "| 15-8 | 7-0 |\n"
+                "|------|-----|\n"
+                "|  C   |  D  |"])
 No newline at end of file

lldb/unittests/Core/DumpRegisterInfoTest.cpp

 //===-- DumpRegisterInfoTest.cpp ------------------------------------------===//
 //
 // 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
 //
 //===----------------------------------------------------------------------===//
 
 #include "lldb/Core/DumpRegisterInfo.h"
+#include "lldb/Target/RegisterFlags.h"
 #include "lldb/Utility/StreamString.h"
 #include "gtest/gtest.h"
 
 using namespace lldb_private;
 
 TEST(DoDumpRegisterInfoTest, MinimumInfo) {
   StreamString strm;
-  DoDumpRegisterInfo(strm, "foo", nullptr, 4, {}, {}, {});
+  DoDumpRegisterInfo(strm, "foo", nullptr, 4, {}, {}, {}, nullptr, 0);
   ASSERT_EQ(strm.GetString(), "       Name: foo\n"
                               "       Size: 4 bytes (32 bits)");
 }
 
 TEST(DoDumpRegisterInfoTest, AltName) {
   StreamString strm;
-  DoDumpRegisterInfo(strm, "foo", "bar", 4, {}, {}, {});
+  DoDumpRegisterInfo(strm, "foo", "bar", 4, {}, {}, {}, nullptr, 0);
   ASSERT_EQ(strm.GetString(), "       Name: foo (bar)\n"
                               "       Size: 4 bytes (32 bits)");
 }
 
 TEST(DoDumpRegisterInfoTest, Invalidates) {
   StreamString strm;
-  DoDumpRegisterInfo(strm, "foo", nullptr, 4, {"foo2"}, {}, {});
+  DoDumpRegisterInfo(strm, "foo", nullptr, 4, {"foo2"}, {}, {}, nullptr, 0);
   ASSERT_EQ(strm.GetString(), "       Name: foo\n"
                               "       Size: 4 bytes (32 bits)\n"
                               "Invalidates: foo2");
 
   strm.Clear();
-  DoDumpRegisterInfo(strm, "foo", nullptr, 4, {"foo2", "foo3", "foo4"}, {}, {});
+  DoDumpRegisterInfo(strm, "foo", nullptr, 4, {"foo2", "foo3", "foo4"}, {}, {},
+                     nullptr, 0);
   ASSERT_EQ(strm.GetString(), "       Name: foo\n"
                               "       Size: 4 bytes (32 bits)\n"
                               "Invalidates: foo2, foo3, foo4");
 }
 
 TEST(DoDumpRegisterInfoTest, ReadFrom) {
   StreamString strm;
-  DoDumpRegisterInfo(strm, "foo", nullptr, 4, {}, {"foo1"}, {});
+  DoDumpRegisterInfo(strm, "foo", nullptr, 4, {}, {"foo1"}, {}, nullptr, 0);
   ASSERT_EQ(strm.GetString(), "       Name: foo\n"
                               "       Size: 4 bytes (32 bits)\n"
                               "  Read from: foo1");
 
   strm.Clear();
-  DoDumpRegisterInfo(strm, "foo", nullptr, 4, {}, {"foo1", "foo2", "foo3"}, {});
+  DoDumpRegisterInfo(strm, "foo", nullptr, 4, {}, {"foo1", "foo2", "foo3"}, {},
+                     nullptr, 0);
   ASSERT_EQ(strm.GetString(), "       Name: foo\n"
                               "       Size: 4 bytes (32 bits)\n"
                               "  Read from: foo1, foo2, foo3");
 }
 
 TEST(DoDumpRegisterInfoTest, InSets) {
   StreamString strm;
-  DoDumpRegisterInfo(strm, "foo", nullptr, 4, {}, {}, {{"set1", 101}});
+  DoDumpRegisterInfo(strm, "foo", nullptr, 4, {}, {}, {{"set1", 101}}, nullptr,
+                     0);
   ASSERT_EQ(strm.GetString(), "       Name: foo\n"
                               "       Size: 4 bytes (32 bits)\n"
                               "    In sets: set1 (index 101)");
 
   strm.Clear();
   DoDumpRegisterInfo(strm, "foo", nullptr, 4, {}, {},
-                     {{"set1", 0}, {"set2", 1}, {"set3", 2}});
+                     {{"set1", 0}, {"set2", 1}, {"set3", 2}}, nullptr, 0);
   ASSERT_EQ(strm.GetString(),
             "       Name: foo\n"
             "       Size: 4 bytes (32 bits)\n"
             "    In sets: set1 (index 0), set2 (index 1), set3 (index 2)");
 }
 
 TEST(DoDumpRegisterInfoTest, MaxInfo) {
   StreamString strm;
   DoDumpRegisterInfo(strm, "foo", nullptr, 4, {"foo2", "foo3"},
-                     {"foo3", "foo4"}, {{"set1", 1}, {"set2", 2}});
+                     {"foo3", "foo4"}, {{"set1", 1}, {"set2", 2}}, nullptr, 0);
   ASSERT_EQ(strm.GetString(), "       Name: foo\n"
                               "       Size: 4 bytes (32 bits)\n"
                               "Invalidates: foo2, foo3\n"
                               "  Read from: foo3, foo4\n"
                               "    In sets: set1 (index 1), set2 (index 2)");
 }
+
+TEST(DoDumpRegisterInfoTest, FieldsTable) {
+  // This is thoroughly tested in RegisterFlags itself, only checking the
+  // integration here.
+  StreamString strm;
+  RegisterFlags flags(
+      "", 4,
+      {RegisterFlags::Field("A", 24, 31), RegisterFlags::Field("B", 16, 23),
+       RegisterFlags::Field("C", 8, 15), RegisterFlags::Field("D", 0, 7)});
+
+  DoDumpRegisterInfo(strm, "foo", nullptr, 4, {}, {}, {}, &flags, 100);
+  ASSERT_EQ(strm.GetString(), "       Name: foo\n"
+                              "       Size: 4 bytes (32 bits)\n"
+                              "\n"
+                              "| 31-24 | 23-16 | 15-8 | 7-0 |\n"
+                              "|-------|-------|------|-----|\n"
+                              "|   A   |   B   |  C   |  D  |");
+}