Add a GDB/LLDB interface for interactive debugging of MLIR Actions

This includes a small runtime acting as callback for the ExecutionEngine
and a C API that makes it possible to control from the debugger.

A python script for LLDB is included that hook a new `mlir` subcommand
and allows to set breakpoints and inspect the current action, the context
and the stack.

Differential Revision: https://reviews.llvm.org/D144817

Author: joker-eph

mlir/include/mlir/Debug/DebuggerExecutionContextHook.h

@@ -0,0 +1,96 @@
+//===- DebuggerExecutionContextHook.h - Debugger Support --------*- C++ -*-===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+//
+// This file contains a set of C API functions that are used by the debugger to
+// interact with the ExecutionContext.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef MLIR_SUPPORT_DEBUGGEREXECUTIONCONTEXTHOOK_H
+#define MLIR_SUPPORT_DEBUGGEREXECUTIONCONTEXTHOOK_H
+
+#include "mlir-c/IR.h"
+#include "mlir/Debug/ExecutionContext.h"
+#include "llvm/Support/Compiler.h"
+
+extern "C" {
+struct MLIRBreakpoint;
+struct MLIRIRunit;
+typedef struct MLIRBreakpoint *BreakpointHandle;
+typedef struct MLIRIRunit *irunitHandle;
+
+/// This is used by the debugger to control what to do after a breakpoint is
+/// hit. See tracing::ExecutionContext::Control for more information.
+void mlirDebuggerSetControl(int controlOption);
+
+/// Print the available context for the current Action.
+void mlirDebuggerPrintContext();
+
+/// Print the current action backtrace.
+void mlirDebuggerPrintActionBacktrace(bool withContext);
+
+//===----------------------------------------------------------------------===//
+// Cursor Management: The cursor is used to select an IRUnit from the context
+// and to navigate through the IRUnit hierarchy.
+//===----------------------------------------------------------------------===//
+
+/// Print the current IR unit cursor.
+void mlirDebuggerCursorPrint(bool withRegion);
+
+/// Select the IR unit from the current context by ID.
+void mlirDebuggerCursorSelectIRUnitFromContext(int index);
+
+/// Select the parent IR unit of the provided IR unit, or print an error if the
+/// IR unit has no parent.
+void mlirDebuggerCursorSelectParentIRUnit();
+
+/// Select the child IR unit at the provided index, print an error if the index
+/// is out of bound. For example if the irunit is an operation, the children IR
+/// units will be the operation's regions.
+void mlirDebuggerCursorSelectChildIRUnit(int index);
+
+/// Return the next IR unit logically in the IR. For example if the irunit is a
+/// Region the next IR unit will be the next region in the parent operation or
+/// nullptr if there is no next region.
+void mlirDebuggerCursorSelectPreviousIRUnit();
+
+/// Return the previous IR unit logically in the IR. For example if the irunit
+/// is a Region, the previous IR unit will be the previous region in the parent
+/// operation or nullptr if there is no previous region.
+void mlirDebuggerCursorSelectNextIRUnit();
+
+//===----------------------------------------------------------------------===//
+// Breakpoint Management
+//===----------------------------------------------------------------------===//
+
+/// Enable the provided breakpoint.
+void mlirDebuggerEnableBreakpoint(BreakpointHandle breakpoint);
+
+/// Disable the provided breakpoint.
+void mlirDebuggerDisableBreakpoint(BreakpointHandle breakpoint);
+
+/// Add a breakpoint matching exactly the provided tag.
+BreakpointHandle mlirDebuggerAddTagBreakpoint(const char *tag);
+
+/// Add a breakpoint matching a pattern by name.
+void mlirDebuggerAddRewritePatternBreakpoint(const char *patternNameInfo);
+
+/// Add a breakpoint matching a file, line and column.
+void mlirDebuggerAddFileLineColLocBreakpoint(const char *file, int line,
+                                             int col);
+
+} // extern "C"
+
+namespace mlir {
+// Setup the debugger hooks as a callback on the provided ExecutionContext.
+void setupDebuggerExecutionContextHook(
+    tracing::ExecutionContext &executionContext);
+
+} // namespace mlir
+
+#endif // MLIR_SUPPORT_DEBUGGEREXECUTIONCONTEXTHOOK_H

mlir/include/mlir/Debug/ExecutionContext.h

@@ -28,8 +28,16 @@ struct ActionActiveStack {
   const ActionActiveStack *getParent() const { return parent; }
   const Action &getAction() const { return action; }
   int getDepth() const { return depth; }
+  void print(raw_ostream &os, bool withContext) const;
+  void dump() const {
+    print(llvm::errs(), /*withContext=*/true);
+    llvm::errs() << "\n";
+  }
+  Breakpoint *getBreakpoint() const { return breakpoint; }
+  void setBreakpoint(Breakpoint *breakpoint) { this->breakpoint = breakpoint; }
 
 private:
+  Breakpoint *breakpoint = nullptr;
   const ActionActiveStack *parent;
   const Action &action;
   int depth;
@@ -69,7 +77,9 @@ class ExecutionContext {
   ExecutionContext() = default;
 
   /// Set the callback that is used to control the execution.
-  void setCallback(CallbackTy callback);
+  void setCallback(CallbackTy callback) {
+    onBreakpointControlExecutionCallback = callback;
+  }
 
   /// This abstract class defines the interface used to observe an Action
   /// execution. It allows to be notified before and after the callback is

mlir/include/mlir/IR/OperationSupport.h

@@ -835,7 +835,7 @@ class OpPrintingFlags {
   OpPrintingFlags &printGenericOpForm();
 
   /// Skip printing regions.
-  OpPrintingFlags &skipRegions();
+  OpPrintingFlags &skipRegions(bool skip = true);
 
   /// Do not verify the operation when using custom operation printers.
   OpPrintingFlags &assumeVerified();

mlir/include/mlir/Rewrite/PatternApplicator.h

@@ -37,8 +37,7 @@ class ApplyPatternAction : public tracing::ActionImpl<ApplyPatternAction> {
       "Encapsulate the application of rewrite patterns";
 
   void print(raw_ostream &os) const override {
-    os << "`" << tag << "`\n"
-       << " pattern: " << pattern.getDebugName() << '\n';
+    os << "`" << tag << " pattern: " << pattern.getDebugName();
   }
 
 private:

mlir/include/mlir/Tools/mlir-opt/MlirOptMain.h

@@ -78,6 +78,17 @@ class MlirOptMainConfig {
   }
   bool shouldEmitBytecode() const { return emitBytecodeFlag; }
 
+  /// Enable the debugger action hook: it makes the debugger able to intercept
+  /// MLIR Actions.
+  void enableDebuggerActionHook(bool enabled = true) {
+    enableDebuggerActionHookFlag = enabled;
+  }
+
+  /// Return true if the Debugger action hook is enabled.
+  bool isDebuggerActionHookEnabled() const {
+    return enableDebuggerActionHookFlag;
+  }
+
   /// Set the IRDL file to load before processing the input.
   MlirOptMainConfig &setIrdlFile(StringRef file) {
     irdlFileFlag = file;
@@ -180,6 +191,9 @@ class MlirOptMainConfig {
   /// Emit bytecode instead of textual assembly when generating output.
   bool emitBytecodeFlag = false;
 
+  /// Enable the Debugger action hook: Debugger can intercept MLIR Actions.
+  bool enableDebuggerActionHookFlag = false;
+
   /// IRDL file to register before processing the input.
   std::string irdlFileFlag = "";
 

mlir/lib/Debug/CMakeLists.txt

@@ -4,6 +4,7 @@ add_mlir_library(MLIRDebug
   DebugCounter.cpp
   ExecutionContext.cpp
   BreakpointManagers/FileLineColLocBreakpointManager.cpp
+  DebuggerExecutionContextHook.cpp
 
   ADDITIONAL_HEADER_DIRS
   ${MLIR_MAIN_INCLUDE_DIR}/mlir/Debug