OpCAPITestGen.cpp

Go to the documentation of this file.

//===- OpCAPITestGen.cpp - C API test generator for operations ------------===//
//
// Part of the LLZK Project, under the Apache License v2.0.
// See LICENSE.txt for license information.
// Copyright 2025 Veridise Inc.
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
//
// OpCAPITestGen generates unit tests for the C API operations generated by
// OpCAPIGen. These are link-time tests that ensure all generated functions
// compile and link properly, using a pattern where the C API function is
// wrapped in a conditional that is always false but the compiler still ensures
// the function within will link correctly.
//
// Test Strategy:
// - Each test creates a dummy operation from a different dialect (arith.constant)
// - Tests then call the generated C API functions inside an if statement that
//   checks if the dummy op is of the target type (always false)
// - The compiler still verifies the function signatures and the linker ensures
//   the symbols are defined, even though the code never executes at runtime
//
// These tests will catch the following kinds of issues:
// - Functions declared but not defined (link errors)
// - Signature mismatches between header and implementation
// - Missing functions in the build system
// - ABI compatibility issues
// - Refactoring breaks
//
// However, the following issues will NOT be caught:
// - Generator logic bugs (if generator is wrong, tests will be wrong too)
// - Runtime behavior
// - Semantic correctness
//
//===----------------------------------------------------------------------===//
 
#include "CAPIGenRegistration.h"
#include "CommonCAPIGen.h"
#include "OpCAPIParamHelper.h"
 
#include <mlir/TableGen/GenInfo.h>
#include <mlir/TableGen/Operator.h>
 
#include <llvm/ADT/StringExtras.h>
#include <llvm/Support/CommandLine.h>
#include <llvm/Support/FormatVariadic.h>
#include <llvm/TableGen/Record.h>
#include <llvm/TableGen/TableGenBackend.h>
 
using namespace mlir;
using namespace mlir::tblgen;
 
namespace {

struct OpTestGenerator : public TestGenerator {
  OpTestGenerator(llvm::raw_ostream &outputStream) : TestGenerator("Operation", outputStream) {}

  std::string genCleanup() const override { return "mlirOperationDestroy"; };

  void genBuildOpTests(const Operator &op) const {
    static constexpr char fmt[] = R"(
TEST_F({1}OperationLinkTests, {0}_{2}_Build) {{
  // Returns an `arith.constant` op, which will never match the {2} dialect check.
  auto testOp = createIndexOperation();
 
  // This condition is always false, so the function is never actually called.
  // We only verify it compiles and links correctly.
  if ({0}OperationIsA_{1}_{2}(testOp)) {{
    MlirOpBuilder builder = mlirOpBuilderCreate(context);
    MlirLocation location = mlirLocationUnknownGet(context);
{3}
    (void){0}{1}_{2}Build(builder, location{4});
    // No need to destroy builder or op since this code never runs.
  }
 
  mlirOperationDestroy(testOp);
}
 
struct {2}BuildFuncHelper : public TestAnyBuildFuncHelper<CAPITest> {
  virtual bool callIsA(MlirOperation op) override { return {0}OperationIsA_{1}_{2}(op); }
  static std::unique_ptr<{2}BuildFuncHelper> get();
 
protected:
  {2}BuildFuncHelper() = default;
};
TEST_F(CAPITest, {1}_{2}_build_pass) { {2}BuildFuncHelper::get()->run(*this); }
)";
 
    assert(!className.empty() && "className must be set");
    os << llvm::formatv(
        fmt,
        getFunctionPrefix(),          // {0}
        dialectNameCapitalized,       // {1}
        className,                    // {2}
        generateBuildDummyParams(op), // {3}
        generateBuildParamList(op)    // {4}
    );
  }

  void genOperandTests(const Operator &op) const {
    static constexpr char OperandGetterTest[] = R"(
TEST_F({1}OperationLinkTests, {0}_{2}_Get{3}) {{
  auto testOp = createIndexOperation();
 
  if ({0}OperationIsA_{1}_{2}(testOp)) {{
    (void){0}{1}_{2}Get{3}(testOp);
  }
 
  mlirOperationDestroy(testOp);
}
)";
 
    static constexpr char OperandSetterTest[] = R"(
TEST_F({1}OperationLinkTests, {0}_{2}_Set{3}) {{
  auto testOp = createIndexOperation();
 
  if ({0}OperationIsA_{1}_{2}(testOp)) {{
    auto dummyValue = mlirOperationGetResult(testOp, 0);
    {0}{1}_{2}Set{3}(testOp, dummyValue);
  }
 
  mlirOperationDestroy(testOp);
}
)";
 
    static constexpr char VariadicOperandGetterTest[] = R"(
TEST_F({1}OperationLinkTests, {0}_{2}_Get{3}Count) {{
  auto testOp = createIndexOperation();
 
  if ({0}OperationIsA_{1}_{2}(testOp)) {{
    (void){0}{1}_{2}Get{3}Count(testOp);
  }
 
  mlirOperationDestroy(testOp);
}
 
TEST_F({1}OperationLinkTests, {0}_{2}_Get{3}At) {{
  auto testOp = createIndexOperation();
 
  if ({0}OperationIsA_{1}_{2}(testOp)) {{
    (void){0}{1}_{2}Get{3}At(testOp, 0);
  }
 
  mlirOperationDestroy(testOp);
}
)";
 
    static constexpr char VariadicOperandSetterTest[] = R"(
TEST_F({1}OperationLinkTests, {0}_{2}_Set{3}_Variadic) {{
  auto testOp = createIndexOperation();
 
  if ({0}OperationIsA_{1}_{2}(testOp)) {{
    auto dummyValue = mlirOperationGetResult(testOp, 0);
    MlirValue values[] = {{dummyValue};
    {0}{1}_{2}Set{3}(testOp, 1, values);
  }
 
  mlirOperationDestroy(testOp);
}
)";
 
    static constexpr char VariadicOfVariadicOperandSetterTest[] = R"(
TEST_F({1}OperationLinkTests, {0}_{2}_Set{3}_VariadicOfVariadic) {{
  auto testOp = createIndexOperation();
 
  if ({0}OperationIsA_{1}_{2}(testOp)) {{
    auto dummyValue = mlirOperationGetResult(testOp, 0);
    MlirValueRange groups[1];
    groups[0].values = &dummyValue;
    groups[0].size = 1;
    {0}{1}_{2}Set{3}(testOp, 1, groups);
  }
 
  mlirOperationDestroy(testOp);
}
)";
    assert(!className.empty() && "className must be set");
 
    for (int i = 0, e = op.getNumOperands(); i < e; ++i) {
      const auto &operand = op.getOperand(i);
      std::string capName = toPascalCase(operand.name);
      if (operand.isVariadic()) {
        if (getGenOpOperandGetters()) {
          os << llvm::formatv(
              VariadicOperandGetterTest,
              getFunctionPrefix(),    // {0}
              dialectNameCapitalized, // {1}
              className,              // {2}
              capName                 // {3}
          );
        }
        if (getGenOpOperandSetters()) {
          os << llvm::formatv(
              operand.isVariadicOfVariadic() ? VariadicOfVariadicOperandSetterTest
                                             : VariadicOperandSetterTest,
              getFunctionPrefix(),    // {0}
              dialectNameCapitalized, // {1}
              className,              // {2}
              capName                 // {3}
          );
        }
      } else {
        if (getGenOpOperandGetters()) {
          os << llvm::formatv(
              OperandGetterTest,
              getFunctionPrefix(),    // {0}
              dialectNameCapitalized, // {1}
              className,              // {2}
              capName                 // {3}
          );
        }
        if (getGenOpOperandSetters()) {
          os << llvm::formatv(
              OperandSetterTest,
              getFunctionPrefix(),    // {0}
              dialectNameCapitalized, // {1}
              className,              // {2}
              capName                 // {3}
          );
        }
      }
    }
  }

  void genAttributeTests(const Operator &op) const {
    static constexpr char AttributeGetterTest[] = R"(
TEST_F({1}OperationLinkTests, {0}_{2}_Get{3}Attr) {{
  auto testOp = createIndexOperation();
 
  if ({0}OperationIsA_{1}_{2}(testOp)) {{
    (void){0}{1}_{2}Get{3}(testOp);
  }
 
  mlirOperationDestroy(testOp);
}
)";
 
    static constexpr char AttributeSetterTest[] = R"(
TEST_F({1}OperationLinkTests, {0}_{2}_Set{3}Attr) {{
  auto testOp = createIndexOperation();
 
  if ({0}OperationIsA_{1}_{2}(testOp)) {{
    {0}{1}_{2}Set{3}(testOp, createIndexAttribute());
  }
 
  mlirOperationDestroy(testOp);
}
)";
    assert(!className.empty() && "className must be set");
 
    for (const auto &namedAttr : op.getAttributes()) {
      std::string capName = toPascalCase(namedAttr.name);
      if (getGenOpAttributeGetters()) {
        os << llvm::formatv(
            AttributeGetterTest,
            getFunctionPrefix(),    // {0}
            dialectNameCapitalized, // {1}
            className,              // {2}
            capName                 // {3}
        );
      }
      if (getGenOpAttributeSetters()) {
        os << llvm::formatv(
            AttributeSetterTest,
            getFunctionPrefix(),    // {0}
            dialectNameCapitalized, // {1}
            className,              // {2}
            capName                 // {3}
        );
      }
    }
  }

  void genResultTests(const Operator &op) const {
    static constexpr char ResultGetterTest[] = R"(
TEST_F({1}OperationLinkTests, {0}_{2}_Get{3}) {{
  auto testOp = createIndexOperation();
 
  if ({0}OperationIsA_{1}_{2}(testOp)) {{
    (void){0}{1}_{2}Get{3}(testOp);
  }
 
  mlirOperationDestroy(testOp);
}
)";
 
    static constexpr char VariadicResultGetterTest[] = R"(
TEST_F({1}OperationLinkTests, {0}_{2}_Get{3}Count) {{
  auto testOp = createIndexOperation();
 
  if ({0}OperationIsA_{1}_{2}(testOp)) {{
    (void){0}{1}_{2}Get{3}Count(testOp);
  }
 
  mlirOperationDestroy(testOp);
}
 
TEST_F({1}OperationLinkTests, {0}_{2}_Get{3}At) {{
  auto testOp = createIndexOperation();
 
  if ({0}OperationIsA_{1}_{2}(testOp)) {{
    (void){0}{1}_{2}Get{3}At(testOp, 0);
  }
 
  mlirOperationDestroy(testOp);
}
)";
    assert(!className.empty() && "className must be set");
 
    for (int i = 0, e = op.getNumResults(); i < e; ++i) {
      const auto &result = op.getResult(i);
      llvm::StringRef name = result.name;
      std::string capName = name.empty() ? llvm::formatv("Result{0}", i).str() : toPascalCase(name);
 
      if (result.isVariadic()) {
        os << llvm::formatv(
            VariadicResultGetterTest,
            getFunctionPrefix(),    // {0}
            dialectNameCapitalized, // {1}
            className,              // {2}
            capName                 // {3}
        );
      } else {
        os << llvm::formatv(
            ResultGetterTest,
            getFunctionPrefix(),    // {0}
            dialectNameCapitalized, // {1}
            className,              // {2}
            capName                 // {3}
        );
      }
    }
  }

  void genRegionTests(const Operator &op) const {
    static constexpr char RegionGetterTest[] = R"(
TEST_F({1}OperationLinkTests, {0}_{2}_Get{3}Region) {{
  auto testOp = createIndexOperation();
 
  if ({0}OperationIsA_{1}_{2}(testOp)) {{
    (void){0}{1}_{2}Get{3}(testOp);
  }
 
  mlirOperationDestroy(testOp);
}
)";
 
    static constexpr char VariadicRegionGetterTest[] = R"(
TEST_F({1}OperationLinkTests, {0}_{2}_Get{3}Count) {{
  auto testOp = createIndexOperation();
 
  if ({0}OperationIsA_{1}_{2}(testOp)) {{
    (void){0}{1}_{2}Get{3}Count(testOp);
  }
 
  mlirOperationDestroy(testOp);
}
 
TEST_F({1}OperationLinkTests, {0}_{2}_Get{3}At) {{
  auto testOp = createIndexOperation();
 
  if ({0}OperationIsA_{1}_{2}(testOp)) {{
    (void){0}{1}_{2}Get{3}At(testOp, 0);
  }
 
  mlirOperationDestroy(testOp);
}
)";
    assert(!className.empty() && "className must be set");
 
    for (unsigned int i = 0, e = op.getNumRegions(); i < e; ++i) {
      const auto &region = op.getRegion(i);
      llvm::StringRef name = region.name;
      std::string capName = name.empty() ? llvm::formatv("Region{0}", i).str() : toPascalCase(name);
 
      if (region.isVariadic()) {
        os << llvm::formatv(
            VariadicRegionGetterTest,
            getFunctionPrefix(),    // {0}
            dialectNameCapitalized, // {1}
            className,              // {2}
            capName                 // {3}
        );
      } else {
        os << llvm::formatv(
            RegionGetterTest,
            getFunctionPrefix(),    // {0}
            dialectNameCapitalized, // {1}
            className,              // {2}
            capName                 // {3}
        );
      }
    }
  }

  void genCompleteRecord(const Operator &op) {
    const Dialect &defDialect = op.getDialect();
 
    // Generate for the selected dialect only
    if (defDialect.getName() != getDialectName()) {
      return;
    }
 
    this->setNamespaceAndClassName(defDialect, op.getCppClassName());
 
    if (getGenIsA()) {
      this->genIsATest();
    }
    if (getGenOpBuild() && !op.skipDefaultBuilders()) {
      this->genBuildOpTests(op);
    }
    if (getGenOpOperandGetters() || getGenOpOperandSetters()) {
      this->genOperandTests(op);
    }
    if (getGenOpAttributeGetters() || getGenOpAttributeSetters()) {
      this->genAttributeTests(op);
    }
    if (getGenOpRegionGetters()) {
      this->genRegionTests(op);
    }
    if (getGenOpResultGetters()) {
      this->genResultTests(op);
    }
    if (getGenExtraClassMethods()) {
      for (const ExtraMethod &method : getCAPIExposedOpMethods(op)) {
        this->genExtraMethod(method);
      }
    }
  }
 
private:
  static std::string generateBuildDummyParams(const Operator &op) {
    struct : GenStringFromOpPieces {
      void genHeader(llvm::raw_ostream &os) override {
        // Declare dummyValue first
        os << "    auto dummyValue = mlirOperationGetResult(testOp, 0);\n";
      }
      void genResult(
          llvm::raw_ostream &os, const NamedTypeConstraint &result, const std::string &resultName
      ) override {
        if (result.isVariadic()) {
          os << llvm::formatv(
              "    auto {0}TypeArray = createIndexType();\n"
              "    MlirType {0}Types[] = {{{0}TypeArray};\n"
              "    intptr_t {0}Size = 0;\n",
              resultName
          );
        } else {
          os << llvm::formatv("    auto {0}Type = createIndexType();\n", resultName);
        }
      }
      void genOperand(llvm::raw_ostream &os, const NamedTypeConstraint &operand) override {
        // per `generateParamList()` only need to create something additional in case
        // of variadic operand, otherwise `dummyValue` is used directly.
        if (operand.isVariadic()) {
          os << llvm::formatv(
              "    MlirValue {0}Values[] = {{dummyValue};\n"
              "    intptr_t {0}Size = 0;\n",
              operand.name
          );
        }
      }
      void genAttribute(llvm::raw_ostream &os, const NamedAttribute &attr) override {
        std::string rhs;
        std::optional<std::string> attrType = tryCppTypeToCapiType(attr.attr.getStorageType());
        if (attrType.has_value() && attrType.value() == "MlirIdentifier") {
          rhs = "mlirOperationGetName(testOp)";
        } else {
          rhs = "createIndexAttribute()";
        }
        os << llvm::formatv("    auto {0}Attr = {1};\n", attr.name, rhs);
      }
      void genRegion(llvm::raw_ostream &os, const mlir::tblgen::NamedRegion &region) override {
        if (region.isVariadic()) {
          os << llvm::formatv("    unsigned {0}Count = 0;\n", region.name);
        }
      }
    } paramsStringGenerator;
    return paramsStringGenerator.gen(op);
  }

  static std::string generateBuildParamList(const Operator &op) {
    struct : GenStringFromOpPieces {
      void genResult(
          llvm::raw_ostream &os, const NamedTypeConstraint &result, const std::string &resultName
      ) override {
        if (result.isVariadic()) {
          os << llvm::formatv(", {0}Size, {0}Types", resultName);
        } else {
          os << llvm::formatv(", {0}Type", resultName);
        }
      }
      void genOperand(llvm::raw_ostream &os, const NamedTypeConstraint &operand) override {
        if (operand.isVariadic()) {
          os << llvm::formatv(", {0}Size, {0}Values", operand.name);
        } else {
          os << ", dummyValue";
        }
      }
      void genAttribute(llvm::raw_ostream &os, const NamedAttribute &attr) override {
        os << llvm::formatv(", {0}Attr", attr.name);
      }
      void genRegion(llvm::raw_ostream &os, const mlir::tblgen::NamedRegion &region) override {
        if (region.isVariadic()) {
          os << llvm::formatv(", {0}Count", region.name);
        }
      }
    } paramsStringGenerator;
    return paramsStringGenerator.gen(op);
  }
};
 
} // namespace

static bool emitOpCAPITests(const llvm::RecordKeeper &records, raw_ostream &os) {
  // Generate file header
  emitSourceFileHeader("Op C API Tests", os, records);
 
  // Create generator
  OpTestGenerator generator(os);
 
  // Generate test class prologue
  generator.genTestClassPrologue();
 
  // Generate tests for each operation
  for (const auto *def : records.getAllDerivedDefinitions("Op")) {
    Operator op(def);
    generator.genCompleteRecord(op);
  }
 
  return false;
}
 
void llzk::registerOpCAPITestGenerator() {
  static mlir::GenRegistration genOpCAPITests(
      "gen-op-capi-tests", "Generate operation C API unit tests", &emitOpCAPITests
  );
}