Implement debugger engine testing

This is an initial, rough version, but implements enough to perform single line stepping, and verifying location and local values.

See docs/debugger.md for details.

Author: ben-clayton

Android.mk

@@ -59,6 +59,7 @@ LOCAL_SRC_FILES:= \
     src/vulkan/descriptor.cc \
     src/vulkan/device.cc \
     src/vulkan/engine_vulkan.cc \
+    src/vulkan/engine_vulkan_debugger.cc \
     src/vulkan/frame_buffer.cc \
     src/vulkan/graphics_pipeline.cc \
     src/vulkan/image_descriptor.cc \

src/dawn/engine_dawn.h

@@ -18,6 +18,7 @@
 #include <cstdint>
 #include <string>
 #include <unordered_map>
+#include <utility>
 #include <vector>
 
 #include "dawn/dawncpp.h"
@@ -61,6 +62,10 @@ class EngineDawn : public Engine {
       const PatchParameterVerticesCommand* cmd) override;
   Result DoBuffer(const BufferCommand* cmd) override;
 
+  std::pair<Debugger*, Result> GetDebugger() override {
+    return {nullptr, Result("Dawn does not currently support a debugger")};
+  }
+
  private:
   // Returns the Dawn-specific render pipeline for the given command,
   // if it exists.  Returns nullptr otherwise.

src/engine.h

@@ -17,6 +17,7 @@
 
 #include <memory>
 #include <string>
+#include <utility>
 #include <vector>
 
 #include "amber/amber.h"
@@ -53,6 +54,14 @@ struct EngineData {
 ///  5. Engine destructor is called.
 class Engine {
  public:
+  /// Debugger is the interface to the engine's shader debugger.
+  class Debugger : public debug::Events {
+   public:
+    /// Flush waits for all the debugger commands issued to complete, and
+    /// returns a Result that includes any debugger test failure.
+    virtual Result Flush() = 0;
+  };
+
   /// Creates a new engine of the requested |type|.
   static std::unique_ptr<Engine> Create(EngineType type);
 
@@ -106,6 +115,11 @@ class Engine {
   /// This covers both Vulkan buffers and images.
   virtual Result DoBuffer(const BufferCommand* cmd) = 0;
 
+  /// GetDebugger returns the shader debugger from the engine.
+  /// If the engine does not support a shader debugger then the Result will be a
+  /// failure.
+  virtual std::pair<Debugger*, Result> GetDebugger() = 0;
+
   /// Sets the engine data to use.
   void SetEngineData(const EngineData& data) { engine_data_ = data; }
 

src/executor.cc

@@ -83,16 +83,40 @@ Result Executor::Execute(Engine* engine,
   if (options->execution_type == ExecutionType::kPipelineCreateOnly)
     return {};
 
+  Engine::Debugger* debugger = nullptr;
+
   // Process Commands
   for (const auto& cmd : script->GetCommands()) {
     if (options->delegate && options->delegate->LogExecuteCalls()) {
       options->delegate->Log(std::to_string(cmd->GetLine()) + ": " +
                              cmd->ToString());
     }
 
+    auto dbg_script = cmd->GetDebugScript();
+    if (dbg_script != nullptr) {
+      if (debugger == nullptr) {
+        // Lazilly obtain the debugger from the engine.
+        Result res;
+        std::tie(debugger, res) = engine->GetDebugger();
+        if (!res.IsSuccess()) {
+          return res;
+        }
+      }
+      // Run the debugger script on the debugger for this command.
+      // This will run concurrently with the command.
+      dbg_script->Run(debugger);
+    }
+
     Result r = ExecuteCommand(engine, cmd.get());
     if (!r.IsSuccess())
       return r;
+
+    if (debugger != nullptr) {
+      // Collect the debugger test results.
+      r = debugger->Flush();
+      if (!r.IsSuccess())
+        return r;
+    }
   }
   return {};
 }

src/executor_test.cc

@@ -159,6 +159,11 @@ class EngineStub : public Engine {
     return {};
   }
 
+  std::pair<Debugger*, Result> GetDebugger() override {
+    return {nullptr,
+            Result("EngineStub does not currently support a debugger")};
+  }
+
  private:
   bool fail_clear_command_ = false;
   bool fail_clear_color_command_ = false;

src/vulkan/CMakeLists.txt

@@ -21,6 +21,7 @@ set(VULKAN_ENGINE_SOURCES
     device.cc
     descriptor.cc
     engine_vulkan.cc
+    engine_vulkan_debugger.cc
     frame_buffer.cc
     graphics_pipeline.cc
     image_descriptor.cc

src/vulkan/engine_vulkan.h

@@ -19,6 +19,7 @@
 #include <memory>
 #include <string>
 #include <unordered_map>
+#include <utility>
 #include <vector>
 
 #include "amber/vulkan_header.h"
@@ -37,6 +38,8 @@ namespace vulkan {
 /// Engine implementation based on Vulkan.
 class EngineVulkan : public Engine {
  public:
+  class VkDebugger;
+
   EngineVulkan();
   ~EngineVulkan() override;
 
@@ -60,6 +63,8 @@ class EngineVulkan : public Engine {
       const PatchParameterVerticesCommand* cmd) override;
   Result DoBuffer(const BufferCommand* cmd) override;
 
+  std::pair<Debugger*, Result> GetDebugger() override;
+
  private:
   struct PipelineInfo {
     std::unique_ptr<Pipeline> vk_pipeline;
@@ -87,6 +92,8 @@ class EngineVulkan : public Engine {
   std::unique_ptr<CommandPool> pool_;
 
   std::map<amber::Pipeline*, PipelineInfo> pipeline_map_;
+
+  std::unique_ptr<Debugger> debugger_;
 };
 
 }  // namespace vulkan