[SandboxIR] Boilerplate code

This is the first patch in a series of patches for the Sandbox Vectorizer
project.
SandboxIR is not tightly coupled to the Sandbox Vectorizer and could be used
independently as a transactional layer on top of LLVM IR.

For a more detailed description of the project please refer to the RFC:
https://discourse.llvm.org/t/rfc-sandbox-vectorizer-an-experimental-modular-vectorizer/79059

This patch adds some basic boilerplate code for the SandboxIR which includes
parts of the SandboxIR `Value` class.

Author: vporpo

llvm/include/llvm/Transforms/SandboxIR/SandboxIR.h

@@ -0,0 +1,141 @@
+//===- SandboxIR.h ----------------------------------------------*- 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
+//
+//===----------------------------------------------------------------------===//
+//
+// Sandbox IR is a lightweight overlay transactional IR on top of LLVM IR.
+// Features:
+// - You can save/rollback the state of the IR at any time.
+// - Any changes made to Sandbox IR will automatically update the underlying
+//   LLVM IR so both IRs are always in sync.
+// - Feels like LLVM IR, similar API.
+//
+// SandboxIR forms a class hierarchy that resembles that of LLVM IR
+// but is in the `sandboxir` namespace:
+//
+//        +- Argument   +- Constant     +- OpaqueInst
+//        |             |               |
+// Value -+- User ------+- Instruction -+- InsertElementInst
+//        |                             |
+//        +- BasicBlock                 +- ExtractElementInst
+//        |                             |
+//        +- Function                   +- ShuffleVectorInst
+//                                      |
+//                                      +- StoreInst
+//                                      |
+//                                      +- LoadInst
+//                                      |
+//                                      +- CmpInst
+//                                      |
+//                                      +- CastInst
+//                                      |
+//                                      +- PHINode
+//                                      |
+//                                      +- SelectInst
+//                                      |
+//                                      +- BinaryOperator
+//                                      |
+//                                      +- UnaryOperator
+//
+// Use
+//
+#ifndef LLVM_TRANSFORMS_SANDBOXIR_SANDBOXIR_H
+#define LLVM_TRANSFORMS_SANDBOXIR_SANDBOXIR_H
+
+#include "llvm/IR/User.h"
+#include "llvm/IR/Value.h"
+#include "llvm/Support/raw_ostream.h"
+
+namespace llvm {
+
+namespace sandboxir {
+
+class Context;
+
+/// A SandboxIR Value has users. This is the base class.
+class Value {
+public:
+  enum class ClassID : unsigned {
+#define DEF_VALUE(ID, CLASS) ID,
+#define DEF_USER(ID, CLASS) ID,
+#define DEF_INSTR(ID, OPC, CLASS) ID,
+#include "llvm/Transforms/SandboxIR/SandboxIRValues.def"
+  };
+
+protected:
+  static const char *getSubclassIDStr(ClassID ID) {
+    switch (ID) {
+      // clang-format off
+#define DEF_VALUE(ID, CLASS) case ClassID::ID: return #ID;
+#define DEF_USER(ID,  CLASS) case ClassID::ID: return #ID;
+#define DEF_INSTR(ID, OPC, CLASS) case ClassID::ID: return #ID;
+      // clang-format on
+#include "llvm/Transforms/SandboxIR/SandboxIRValues.def"
+    }
+    llvm_unreachable("Unimplemented ID");
+  }
+
+  /// For isa/dyn_cast.
+  ClassID SubclassID;
+#ifndef NDEBUG
+  /// A unique ID used for forming the name (used for debugging).
+  unsigned UID;
+#endif
+  /// The LLVM Value that corresponds to this SandboxIR Value.
+  /// NOTE: Some SBInstructions, like Packs, may include more than one value.
+  llvm::Value *Val = nullptr;
+
+  /// All values point to the context.
+  Context &Ctxt;
+  // This is used by eraseFromParent().
+  void clearValue() { Val = nullptr; }
+  template <typename ItTy, typename SBTy> friend class LLVMOpUserItToSBTy;
+
+public:
+  Value(ClassID SubclassID, llvm::Value *Val, Context &Ctxt);
+  virtual ~Value() = default;
+  ClassID getSubclassID() const { return SubclassID; }
+
+  Type *getType() const { return Val->getType(); }
+
+  Context &getContext() const;
+#ifndef NDEBUG
+  /// Should crash if there is something wrong with the instruction.
+  virtual void verify() const = 0;
+  /// Returns the name in the form 'SB<number>.' like 'SB1.'
+  std::string getName() const;
+  virtual void dumpCommonHeader(raw_ostream &OS) const;
+  void dumpCommonFooter(raw_ostream &OS) const;
+  void dumpCommonPrefix(raw_ostream &OS) const;
+  void dumpCommonSuffix(raw_ostream &OS) const;
+  void printAsOperandCommon(raw_ostream &OS) const;
+#endif
+};
+
+class User : public Value {
+public:
+  User(ClassID ID, llvm::Value *V, Context &Ctxt) : Value(ID, V, Ctxt) {}
+  /// For isa/dyn_cast.
+  static bool classof(const Value *From);
+#ifndef NDEBUG
+  void verify() const override {
+    assert(isa<llvm::User>(Val) && "Expected User!");
+  }
+  void dumpCommonHeader(raw_ostream &OS) const final;
+#endif
+};
+
+class Context {
+protected:
+  LLVMContext &LLVMCtxt;
+
+public:
+  Context(LLVMContext &LLVMCtxt) : LLVMCtxt(LLVMCtxt) {}
+};
+} // namespace sandboxir
+} // namespace llvm
+
+#endif // LLVM_TRANSFORMS_SANDBOXIR_SANDBOXIR_H

llvm/include/llvm/Transforms/SandboxIR/SandboxIRValues.def

@@ -0,0 +1,29 @@
+//===- SandboxIRValues.def --------------------------------------*- 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
+//
+//===----------------------------------------------------------------------===//
+
+// clang-format off
+
+//        ClassID,                        Class
+DEF_USER(User,                            sandboxir::User)
+
+// clang-format on
+#ifdef DEF_VALUE
+#undef DEF_VALUE
+#endif
+#ifdef DEF_USER
+#undef DEF_USER
+#endif
+#ifdef DEF_INSTR
+#undef DEF_INSTR
+#endif
+#ifdef OPCODES
+#undef OPCODES
+#endif
+#ifdef OP
+#undef OP
+#endif

llvm/lib/Transforms/CMakeLists.txt

@@ -10,3 +10,4 @@ add_subdirectory(ObjCARC)
 add_subdirectory(Coroutines)
 add_subdirectory(CFGuard)
 add_subdirectory(HipStdPar)
+add_subdirectory(SandboxIR)

llvm/lib/Transforms/SandboxIR/CMakeLists.txt

@@ -0,0 +1,11 @@
+add_llvm_component_library(LLVMSandboxIR
+  SandboxIR.cpp
+
+  ADDITIONAL_HEADER_DIRS
+  ${LLVM_MAIN_INCLUDE_DIR}/llvm/Transforms/SandboxIR
+
+  LINK_COMPONENTS
+  Core
+  Support
+  )
+

llvm/lib/Transforms/SandboxIR/SandboxIR.cpp

@@ -0,0 +1,66 @@
+//===- SandboxIR.cpp - A transactional overlay IR on top of LLVM IR -------===//
+//
+// 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 "llvm/Transforms/SandboxIR/SandboxIR.h"
+#include "llvm/Support/Debug.h"
+#include <sstream>
+
+using namespace llvm;
+using namespace sandboxir;
+
+sandboxir::Value::Value(ClassID SubclassID, llvm::Value *Val, Context &Ctxt)
+    : SubclassID(SubclassID), Val(Val), Ctxt(Ctxt) {
+#ifndef NDEBUG
+  UID = 0; // FIXME: Once SBContext is available.
+#endif
+}
+
+#ifndef NDEBUG
+std::string sandboxir::Value::getName() const {
+  std::stringstream SS;
+  SS << "SB" << UID << ".";
+  return SS.str();
+}
+
+void sandboxir::Value::dumpCommonHeader(raw_ostream &OS) const {
+  OS << getName() << " " << getSubclassIDStr(SubclassID) << " ";
+}
+
+void sandboxir::Value::dumpCommonFooter(raw_ostream &OS) const {
+  OS.indent(2) << "Val: ";
+  if (Val)
+    OS << *Val;
+  else
+    OS << "NULL";
+  OS << "\n";
+}
+
+void sandboxir::Value::dumpCommonPrefix(raw_ostream &OS) const {
+  if (Val)
+    OS << *Val;
+  else
+    OS << "NULL ";
+}
+
+void sandboxir::Value::dumpCommonSuffix(raw_ostream &OS) const {
+  OS << " ; " << getName() << " (" << getSubclassIDStr(SubclassID) << ") "
+     << this;
+}
+
+void sandboxir::Value::printAsOperandCommon(raw_ostream &OS) const {
+  if (Val)
+    Val->printAsOperand(OS);
+  else
+    OS << "NULL ";
+}
+
+void sandboxir::User::dumpCommonHeader(raw_ostream &OS) const {
+  Value::dumpCommonHeader(OS);
+  // TODO: This is incomplete
+}
+#endif // NDEBUG

llvm/unittests/Transforms/CMakeLists.txt

@@ -4,3 +4,4 @@ add_subdirectory(IPO)
 add_subdirectory(Scalar)
 add_subdirectory(Utils)
 add_subdirectory(Vectorize)
+add_subdirectory(SandboxIR)

llvm/unittests/Transforms/SandboxIR/CMakeLists.txt

@@ -0,0 +1,10 @@
+set(LLVM_LINK_COMPONENTS
+  AsmParser
+  SandboxIR
+  )
+
+add_llvm_unittest(SandboxIRTests
+  SandboxIRTest.cpp
+  )
+
+set_property(TARGET SandboxIRTests PROPERTY FOLDER "Tests/UnitTests/TransformsTests")

llvm/unittests/Transforms/SandboxIR/SandboxIRTest.cpp

@@ -0,0 +1,43 @@
+//===- SandboxIRTest.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 "llvm/Transforms/SandboxIR/SandboxIR.h"
+#include "llvm/AsmParser/Parser.h"
+#include "llvm/IR/BasicBlock.h"
+#include "llvm/IR/Function.h"
+#include "llvm/IR/Instruction.h"
+#include "llvm/IR/Module.h"
+#include "llvm/Support/SourceMgr.h"
+#include "gtest/gtest.h"
+
+using namespace llvm;
+
+struct SandboxIRTest : public testing::Test {
+  LLVMContext C;
+  std::unique_ptr<Module> M;
+
+  void parseIR(LLVMContext &C, const char *IR) {
+    SMDiagnostic Err;
+    M = parseAssemblyString(IR, Err, C);
+    if (!M)
+      Err.print("SandboxIRTest", errs());
+  }
+};
+
+TEST_F(SandboxIRTest, UserInstantiation) {
+  parseIR(C, R"IR(
+define void @foo(i32 %v1) {
+  ret void
+}
+)IR");
+  Function &F = *M->getFunction("foo");
+  auto *Ret = F.begin()->getTerminator();
+  sandboxir::Context Ctxt(C);
+  sandboxir::User U(sandboxir::Value::ClassID::User, Ret, Ctxt);
+  (void)U;
+}

llvm/utils/gn/secondary/llvm/lib/Transforms/SandboxIR/BUILD.gn

@@ -0,0 +1,10 @@
+static_library("SandboxIR") {
+  output_name = "LLVMSandboxIR"
+  deps = [
+    "//llvm/lib/IR",
+    "//llvm/lib/Support",
+  ]
+  sources = [
+    "SandboxIR.cpp",
+  ]
+}

utils/bazel/llvm-project-overlay/llvm/BUILD.bazel

@@ -1467,6 +1467,23 @@ cc_library(
     ],
 )
 
+cc_library(
+    name = "SandboxIR",
+    srcs = glob([
+        "lib/Transforms/SandboxIR/*.cpp",
+    ]),
+    hdrs = glob([
+        "include/llvm/Transforms/SandboxIR/*.h",
+        "include/llvm/Transforms/SandboxIR/*.def",
+    ]),
+    copts = llvm_copts,
+    deps = [
+        ":Core",
+        ":Support",
+        ":config",
+    ],
+)
+
 cc_library(
     name = "Vectorize",
     srcs = glob([
@@ -1826,6 +1843,7 @@ cc_library(
         ":InstCombine",
         ":Instrumentation",
         ":ObjCARC",
+        ":SandboxIR",
         ":Scalar",
         ":Vectorize",
     ],
@@ -2658,6 +2676,7 @@ cc_library(
         ":Instrumentation",
         ":MC",
         ":ObjCARC",
+        ":SandboxIR",
         ":Scalar",
         ":Support",
         ":Target",