feat(avm): interactive debugger (#11477)

Debugger plus some fixes. This has bb-pilcom changes so update and rebuild after it merges.

<div>
    <a href="https://www.loom.com/share/1ce400f55d4a4d888000cb54c7361a6f">
      <p>AVM interactive debugger - Watch Video</p>
    </a>
    <a href="https://www.loom.com/share/1ce400f55d4a4d888000cb54c7361a6f">
      <img style="max-width:300px;" src="https://cdn.loom.com/sessions/thumbnails/1ce400f55d4a4d888000cb54c7361a6f-68caa0ac8f8e7ebb-full-play.gif">
    </a>
  </div>

Note: it does not support history or arrow keys or tab/autocompletion. Mostly because this is terminal-dependent and I don't want to pull in a console dependency. I might attempt to do it from scratch when I have some free time.

barretenberg/cpp/src/barretenberg/vm/avm/generated/columns.hpp

@@ -27,10 +27,11 @@ enum class Column { AVM_UNSHIFTED_ENTITIES };
 // C++ doesn't allow enum extension, so we'll have to cast.
 enum class ColumnAndShifts {
     AVM_ALL_ENTITIES,
-    // Sentinel.
-    NUM_COLUMNS,
+    SENTINEL_DO_NOT_USE,
 };
 
+constexpr auto NUM_COLUMNS_WITH_SHIFTS = 813;
+constexpr auto NUM_COLUMNS_WITHOUT_SHIFTS = 764;
 constexpr auto TO_BE_SHIFTED_COLUMNS_ARRAY = []() { return std::array{ AVM_TO_BE_SHIFTED_COLUMNS }; }();
 constexpr auto SHIFTED_COLUMNS_ARRAY = []() { return std::array{ AVM_SHIFTED_COLUMNS }; }();
 static_assert(TO_BE_SHIFTED_COLUMNS_ARRAY.size() == SHIFTED_COLUMNS_ARRAY.size());

barretenberg/cpp/src/barretenberg/vm/avm/generated/full_row.hpp

@@ -20,13 +20,13 @@ template <typename FF_> struct AvmFullRow {
     // Risky but oh so efficient.
     FF& get_column(ColumnAndShifts col)
     {
-        static_assert(sizeof(*this) == sizeof(FF) * static_cast<size_t>(ColumnAndShifts::NUM_COLUMNS));
+        static_assert(sizeof(*this) == sizeof(FF) * static_cast<size_t>(ColumnAndShifts::SENTINEL_DO_NOT_USE));
         return reinterpret_cast<FF*>(this)[static_cast<size_t>(col)];
     }
 
     const FF& get_column(ColumnAndShifts col) const
     {
-        static_assert(sizeof(*this) == sizeof(FF) * static_cast<size_t>(ColumnAndShifts::NUM_COLUMNS));
+        static_assert(sizeof(*this) == sizeof(FF) * static_cast<size_t>(ColumnAndShifts::SENTINEL_DO_NOT_USE));
         return reinterpret_cast<const FF*>(this)[static_cast<size_t>(col)];
     }
 };

barretenberg/cpp/src/barretenberg/vm/avm/trace/execution.cpp

@@ -151,8 +151,8 @@ void show_trace_info(const auto& trace)
         size_t total_entries = 0;
         size_t fullness = 0; // 0 to 100.
     };
-    std::vector<ColumnStats> column_stats(static_cast<size_t>(avm::ColumnAndShifts::NUM_COLUMNS));
-    bb::parallel_for(static_cast<size_t>(avm::ColumnAndShifts::NUM_COLUMNS), [&](size_t col) {
+    std::vector<ColumnStats> column_stats(avm::NUM_COLUMNS_WITH_SHIFTS);
+    bb::parallel_for(avm::NUM_COLUMNS_WITH_SHIFTS, [&](size_t col) {
         size_t non_zero_entries = 0;
         ssize_t last_non_zero_row = -1;
         for (uint32_t row_n = 0; row_n < trace.size(); row_n++) {

barretenberg/cpp/src/barretenberg/vm2/debugger.cpp

@@ -0,0 +1,225 @@
+#include "barretenberg/vm2/debugger.hpp"
+
+#include <iostream>
+#include <optional>
+#include <regex>
+#include <string>
+#include <vector>
+
+#include "barretenberg/numeric/uint256/uint256.hpp"
+#include "barretenberg/vm2/common/field.hpp"
+#include "barretenberg/vm2/generated/columns.hpp"
+#include "barretenberg/vm2/generated/flavor.hpp"
+#include "barretenberg/vm2/generated/full_row.hpp"
+#include "barretenberg/vm2/tracegen/lib/trace_conversion.hpp"
+
+namespace bb::avm2 {
+namespace {
+
+template <typename FF> std::string field_to_string(const FF& ff)
+{
+    std::ostringstream os;
+    os << ff;
+    std::string raw = os.str();
+    auto first_not_zero = raw.find_first_not_of('0', 2);
+    std::string result = "0x" + (first_not_zero != std::string::npos ? raw.substr(first_not_zero) : "0");
+    return result;
+}
+
+std::vector<std::string> get_command()
+{
+    std::string line;
+    std::getline(std::cin, line);
+    // Split the line into words.
+    return bb::detail::split_and_trim(line, ' ');
+}
+
+std::string str_replace(const std::string& s, const std::string& search, const std::string& replace)
+{
+    size_t pos = 0;
+    std::string res = s;
+    while ((pos = res.find(search, pos)) != std::string::npos) {
+        res.replace(pos, search.length(), replace);
+        pos += replace.length();
+    }
+    return res;
+}
+
+std::string to_binary(uint64_t n, bool leading_zeroes = true)
+{
+    std::string result;
+    for (int i = 0; i < 64; ++i) {
+        result = ((n & 1) ? "1" : "0") + result;
+        n >>= 1;
+    }
+    if (!leading_zeroes) {
+        size_t first_one = result.find('1');
+        if (first_one != std::string::npos) {
+            result = result.substr(first_one);
+        } else {
+            result = "0";
+        }
+    }
+    return result;
+}
+
+void help()
+{
+    std::cout << "Commands:" << std::endl;
+    std::cout << "  ' - increment row" << std::endl;
+    std::cout << "  , - decrement row" << std::endl;
+    std::cout << "  @<row> - jump to row" << std::endl;
+    std::cout << "  .<column_regex> [...column_regex] - print column values" << std::endl;
+    std::cout << "  /set <column> <value> - set column" << std::endl;
+    std::cout << "  /prefix <column_prefix> - set column prefix" << std::endl;
+    std::cout << "  /noprefix - clear column prefix" << std::endl;
+    std::cout << "  /testrelation <relation_name> [subrelation_name_or_number] - test relation" << std::endl;
+    std::cout << "  exit, e, q - exit" << std::endl;
+}
+
+} // namespace
+
+void InteractiveDebugger::run(uint32_t starting_row)
+{
+    row = starting_row;
+    std::cout << "Entering interactive debugging mode at row " << row << "..." << std::endl;
+    while (true) {
+        // Print prompt with current row.
+        std::cout << this->row << "> ";
+        auto command = get_command();
+        if (command.empty()) {
+            continue;
+        }
+        if (command[0] == "'") {
+            row++;
+        } else if (command[0] == ",") {
+            if (row > 0) {
+                row--;
+            } else {
+                std::cout << "Cannot decrement row below 0." << std::endl;
+            }
+        } else if (command[0].starts_with("@")) {
+            row = static_cast<uint32_t>(std::stoi(command[0].substr(1)));
+        } else if (command[0] == "exit" || command[0] == "e" || command[0] == "q") {
+            break;
+        } else if (command[0] == "/set" || command[0] == "/s") {
+            if (command.size() != 3) {
+                std::cout << "Usage: /set <column> <value>" << std::endl;
+            } else {
+                set_column(command[1], command[2]);
+            }
+        } else if (command[0] == "/prefix" || command[0] == "/p") {
+            if (command.size() != 2) {
+                std::cout << "Usage: /prefix <column_prefix>" << std::endl;
+            } else {
+                prefix = command[1];
+            }
+        } else if (command[0] == "/noprefix" || command[0] == "/np") {
+            prefix = "";
+        } else if (command[0] == "/testrelation" || command[0] == "/tr") {
+            if (command.size() != 2 && command.size() != 3) {
+                std::cout << "Usage: /testrelation <relation_name> [subrelation_name_or_number]" << std::endl;
+            } else {
+                test_relation(command[1], command.size() == 3 ? std::make_optional(command[2]) : std::nullopt);
+            }
+        } else if (command[0].starts_with(".")) {
+            // Remove dot from first column name.
+            command[0].erase(0, 1);
+            // Print columns.
+            print_columns(command);
+        } else {
+            help();
+        }
+    }
+}
+
+void InteractiveDebugger::print_columns(const std::vector<std::string>& regexes)
+{
+    bool found = false;
+    std::string joined_regex;
+    for (const auto& str : regexes) {
+        joined_regex += prefix + str_replace(str, "'", "_shift") + "|";
+    }
+    joined_regex.pop_back(); // Remove trailing '|'.
+    std::regex re;
+    try {
+        re.assign(joined_regex);
+    } catch (std::regex_error& e) {
+        std::cout << "Invalid regex: " << e.what() << std::endl;
+        return;
+    }
+    // We use the full row to have the shifts as well.
+    const auto full_row = tracegen::get_full_row(trace, row);
+    for (size_t i = 0; i < COLUMN_NAMES.size(); ++i) {
+        if (std::regex_match(COLUMN_NAMES[i], re)) {
+            auto val = full_row.get_column(static_cast<ColumnAndShifts>(i));
+            std::cout << COLUMN_NAMES[i] << ": " << field_to_string(val);
+            // If the value is small enough, print it as decimal and binary.
+            if (val == FF(static_cast<uint64_t>(val))) {
+                uint64_t n = static_cast<uint64_t>(val);
+                std::cout << " (" << n << ", " << to_binary(n, /*leading_zeroes=*/false) << "b)";
+            }
+            std::cout << std::endl;
+            found = true;
+        }
+    }
+    if (!found) {
+        std::cout << "No columns matched: " << joined_regex << std::endl;
+    }
+}
+
+void InteractiveDebugger::set_column(const std::string& column_name, const std::string& value)
+{
+    std::string final_name = prefix + column_name;
+    for (size_t i = 0; i < COLUMN_NAMES.size(); ++i) {
+        // We match both names, for copy-pasting ease.
+        if (COLUMN_NAMES[i] == final_name || COLUMN_NAMES[i] == column_name) {
+            trace.set(static_cast<Column>(i), row, std::stoi(value));
+            std::cout << "Column " << COLUMN_NAMES[i] << " set to value " << value << std::endl;
+            return;
+        }
+    }
+    std::cout << "Column " << column_name << " not found." << std::endl;
+}
+
+void InteractiveDebugger::test_relation(const std::string& relation_name, std::optional<std::string> subrelation_name)
+{
+    bool found = false;
+    bool failed = false;
+
+    bb::constexpr_for<0, std::tuple_size_v<typename AvmFlavor::MainRelations>, 1>([&]<size_t i>() {
+        using Relation = std::tuple_element_t<i, typename AvmFlavor::MainRelations>;
+
+        if (Relation::NAME != relation_name) {
+            return;
+        }
+        found = true;
+
+        typename Relation::SumcheckArrayOfValuesOverSubrelations result{};
+        Relation::accumulate(result, tracegen::get_full_row(trace, row), {}, 1);
+        for (size_t j = 0; j < result.size(); ++j) {
+            if (!result[j].is_zero() &&
+                (!subrelation_name || Relation::get_subrelation_label(j) == *subrelation_name)) {
+                std::cout << format("Relation ",
+                                    Relation::NAME,
+                                    ", subrelation ",
+                                    Relation::get_subrelation_label(j),
+                                    " failed at row ",
+                                    row)
+                          << std::endl;
+                failed = true;
+                return;
+            }
+        }
+    });
+
+    if (!found) {
+        std::cout << "Relation " << relation_name << " not found." << std::endl;
+    } else if (!failed) {
+        std::cout << "Relation " << relation_name << " ("
+                  << (subrelation_name.has_value() ? *subrelation_name : "all subrelations") << ")"
+                  << " passed!" << std::endl;
+    }
+}
+
+} // namespace bb::avm2

barretenberg/cpp/src/barretenberg/vm2/debugger.hpp

@@ -0,0 +1,39 @@
+#pragma once
+
+#include <string>
+#include <vector>
+
+#include "barretenberg/vm2/tracegen/trace_container.hpp"
+
+namespace bb::avm2 {
+
+/**
+ * An interactive debugger for the AVM2.
+ *
+ * (1) To use it in tests add the following after you construct the trace:
+ *
+ * auto container = TestTraceContainer::from_rows(trace);
+ * InteractiveDebugger debugger(container);
+ * debugger.run();
+ *
+ * (2) To use it to debug `avm2_check_circuit` failures just set the `AVM_DEBUG` environment variable.
+ */
+class InteractiveDebugger {
+  public:
+    InteractiveDebugger(tracegen::TraceContainer& trace)
+        : trace(trace)
+    {}
+
+    void run(uint32_t starting_row = 0);
+
+  private:
+    tracegen::TraceContainer& trace;
+    uint32_t row = 0;
+    std::string prefix;
+
+    void print_columns(const std::vector<std::string>& regex);
+    void set_column(const std::string& column_name, const std::string& value);
+    void test_relation(const std::string& relation_name, std::optional<std::string> subrelation_name);
+};
+
+} // namespace bb::avm2

barretenberg/cpp/src/barretenberg/vm2/generated/columns.hpp

@@ -27,10 +27,11 @@ enum class Column { AVM2_UNSHIFTED_ENTITIES };
 // C++ doesn't allow enum extension, so we'll have to cast.
 enum class ColumnAndShifts {
     AVM2_ALL_ENTITIES,
-    // Sentinel.
-    NUM_COLUMNS,
+    SENTINEL_DO_NOT_USE,
 };
 
+constexpr auto NUM_COLUMNS_WITH_SHIFTS = 50;
+constexpr auto NUM_COLUMNS_WITHOUT_SHIFTS = 49;
 constexpr auto TO_BE_SHIFTED_COLUMNS_ARRAY = []() { return std::array{ AVM2_TO_BE_SHIFTED_COLUMNS }; }();
 constexpr auto SHIFTED_COLUMNS_ARRAY = []() { return std::array{ AVM2_SHIFTED_COLUMNS }; }();
 static_assert(TO_BE_SHIFTED_COLUMNS_ARRAY.size() == SHIFTED_COLUMNS_ARRAY.size());

barretenberg/cpp/src/barretenberg/vm2/generated/full_row.hpp

@@ -20,13 +20,13 @@ template <typename FF_> struct AvmFullRow {
     // Risky but oh so efficient.
     FF& get_column(ColumnAndShifts col)
     {
-        static_assert(sizeof(*this) == sizeof(FF) * static_cast<size_t>(ColumnAndShifts::NUM_COLUMNS));
+        static_assert(sizeof(*this) == sizeof(FF) * static_cast<size_t>(ColumnAndShifts::SENTINEL_DO_NOT_USE));
         return reinterpret_cast<FF*>(this)[static_cast<size_t>(col)];
     }
 
     const FF& get_column(ColumnAndShifts col) const
     {
-        static_assert(sizeof(*this) == sizeof(FF) * static_cast<size_t>(ColumnAndShifts::NUM_COLUMNS));
+        static_assert(sizeof(*this) == sizeof(FF) * static_cast<size_t>(ColumnAndShifts::SENTINEL_DO_NOT_USE));
         return reinterpret_cast<const FF*>(this)[static_cast<size_t>(col)];
     }
 };

barretenberg/cpp/src/barretenberg/vm2/proving_helper.cpp

@@ -1,13 +1,16 @@
 #include "barretenberg/vm2/proving_helper.hpp"
 
+#include <cstdlib>
 #include <memory>
+#include <stdexcept>
 
 #include "barretenberg/common/serialize.hpp"
 #include "barretenberg/common/thread.hpp"
 #include "barretenberg/numeric/bitop/get_msb.hpp"
 #include "barretenberg/vm/stats.hpp"
 #include "barretenberg/vm2/common/constants.hpp"
 #include "barretenberg/vm2/constraining/check_circuit.hpp"
+#include "barretenberg/vm2/debugger.hpp"
 #include "barretenberg/vm2/generated/prover.hpp"
 #include "barretenberg/vm2/generated/verifier.hpp"
 
@@ -137,12 +140,20 @@ bool AvmProvingHelper::check_circuit(tracegen::TraceContainer&& trace)
     const size_t num_rows = trace.get_num_rows_without_clk() + 1;
     info("Running check circuit over ", num_rows, " rows.");
 
+    // Go into interactive debug mode if requested.
+    if (getenv("AVM_DEBUG") != nullptr) {
+        InteractiveDebugger debugger(trace);
+        debugger.run();
+    }
+
+    // Warning: this destroys the trace.
     auto polynomials = AVM_TRACK_TIME_V("proving/prove:compute_polynomials", compute_polynomials(trace));
     try {
         AVM_TRACK_TIME("proving/check_circuit", constraining::run_check_circuit(polynomials, num_rows));
-    } catch (const std::exception& e) {
+    } catch (std::runtime_error& e) {
+        // FIXME: This exception is never caught because it's thrown in a different thread.
+        // Execution never gets here!
         info("Circuit check failed: ", e.what());
-        return false;
     }
 
     return true;