[mlir] Add support for diagnostics in C API.

[ftynse]

Summary

Add basic support for registering diagnostic handlers with the context
(actually, the diagnostic engine contained in the context) and processing
diagnostic messages from the C API.

[ftynse]

Reorganize comments

[stellaraccident]

Thanks - this will be very helpful.

Nits and one question about API stability.

mlir/include/mlir-c/Support.h

61

How likely do you think it will be that this will change? At an API boundary like this with inline functions, even though insulated behind a function call, it would be quite a chaotic thing to change it (ie. Existing binaries interpreting true values as false). If this is a serious possibility to flip semantics, better to take the optimization hit and make the accessors opaque.

On the other hand, this seems like a totally fine thing for the C API to specify completely and disallow future change: if the underlying implementation changes semantics, the C API layer would translate to the compatible semantics.

74

Did you mean to lowercase the leasing "m"?

mlir/test/CAPI/ir.c

1017

Typo in "CHEKC"

[ftynse]

Review

[ftynse]

mlir/include/mlir-c/Support.h

61

I don't expect this to change, but also don't want users to inspect things directly. But it's C, so direct inspection is probably unavoidable, so we may just use an enum instead. WDYT?

[stellaraccident]

mlir/include/mlir-c/Support.h

61

It's C - the best you can do is provide a speed bump. I'm fine with how you have it, but I think you should remove the part of the comment about this changing: in fact we need a string guarantee that it doesn't change, and it is put together this way for legibility.

[ftynse]

Clarify comments

[ftynse]

mlir/include/mlir-c/Support.h

61

I removed that part of the comment. Just for completeness, here how the enum solution would look like - https://reviews.llvm.org/D88960. It would allow for if (someOperation())-style checks, which is what LogicalResult was expected to solve.

mlir/include/mlir-c/Diagnostics.h

+/*===-- mlir-c/Diagnostics.h - MLIR Diagnostic subsystem C API ----*- 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 header declares the C APIs accessing MLIR Diagnostics subsystem.      *|
+|*                                                                            *|
+\*===----------------------------------------------------------------------===*/
+
+#ifndef MLIR_C_DIAGNOSTICS_H
+#define MLIR_C_DIAGNOSTICS_H
+
+#include "mlir-c/IR.h"
+#include "mlir-c/Support.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** An opaque reference to a dignostic, always owned by the diagnostics engine
+ * (context). Must not be stored outside of the diagnostic handler. */
+struct MlirDiagnostic {
+  void *ptr;
+};
+typedef struct MlirDiagnostic MlirDiagnostic;
+
+/** Severity of a diagnostic. */
+enum MlirDiagnosticSeverity {
+  MlirDiagnosticError,
+  MlirDiagnosticWarning,
+  MlirDiagnosticNote,
+  MlirDiagnosticRemark
+};
+typedef enum MlirDiagnosticSeverity MlirDiagnosticSeverity;
+
+/** Opaque identifier of a diagnostic handler, useful to detach a handler. */
+typedef uint64_t MlirDiagnosticHandlerID;
+
+/** Diagnostic handler type. Acceps a reference to a diagnostic, which is only
+ * guaranteed to be live during the call. If the handler processed the
+ * diagnostic completely, it is expected to return success. Otherwise, it is
+ * expected to return failure to indicate that other handlers should attempt to
+ * process the diagnostic. */
+typedef MlirLogicalResult (*MlirDiagnosticHandler)(MlirDiagnostic);
+
+/** Prints a diagnostic using the provided callback. */
+void mlirDiagnosticPrint(MlirDiagnostic diagnostic, MlirStringCallback callback,
+                         void *userData);
+
+/** Returns the location at which the diagnostic is reported. */
+MlirLocation mlirDiagnosticGetLocation(MlirDiagnostic diagnostic);
+
+/** Returns the severity of the diagnostic. */
+MlirDiagnosticSeverity mlirDiagnosticGetSeverity(MlirDiagnostic diagnostic);
+
+/** Returns the number of notes attached to the diagnostic. */
+intptr_t mlirDiagnosticGetNumNotes(MlirDiagnostic diagnostic);
+
+/** Returns `pos`-th note attached to the diagnostic. Expects `pos` to be a
+ * valid zero-based index into the list of notes. */
+MlirDiagnostic mlirDiagnosticGetNote(MlirDiagnostic diagnostic, intptr_t pos);
+
+/** Attaches the diagnostic handler to the context. Handlers are invoked in the
+ * reverse order of attachment until one of them processes the diagnostic
+ * completely. Returns an identifier that can be used to detach the handler. */
+MlirDiagnosticHandlerID
+mlirContextAttachDiagnosticHandler(MlirContext context,
+                                   MlirDiagnosticHandler handler);
+
+/** Detaches an attached diagnostic handler from the context given its
+ * identifier. */
+void mlirContextDetachDiagnosticHandler(MlirContext context,
+                                        MlirDiagnosticHandlerID id);
+
+/** Emits an error at the given location through the diagnostics engine. Used
+ * for testing purposes. */
+void mlirEmitError(MlirLocation location, const char *message);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // MLIR_C_DIAGNOSTICS_H

mlir/include/mlir-c/Support.h

inline MlirStringRef mlirStringRefCreate(const char *str, size_t length) {
   return result;
 }
 
 /** Constructs a string reference from a null-terminated C string. Prefer
  * mlirStringRefCreate if the length of the string is known.
  */
 MlirStringRef mlirStringRefCreateFromCString(const char *str);
 
+/*============================================================================*/
+/* MlirLogicalResult.                                                         */
+/*============================================================================*/
+
+/** A logical result value, essentially a boolean with named states. LLVM
+ * convention for using boolean values to designate success or failure of an
+ * operation is a moving target, so MLIR opted for an explicit class.
+ * Instances of MlirLogicalResult must only be inspected using the associated
+ * functions. */
+struct MlirLogicalResult {
+  int8_t value;
+};
+typedef struct MlirLogicalResult MlirLogicalResult;
+
+/** Checks if the given logical result represents a success. */
+inline int mlirLogicalResultIsSuccess(MlirLogicalResult res) {
+  return res.value != 0;
+}
+
+/** Checks if the given logical result represents a failure. */
+inline int mlirLogicalResultIsFailure(MlirLogicalResult res) {
+  return res.value == 0;
+}
+
+/** Creates a logical result representing a success. */
+inline static MlirLogicalResult mlirLogicalResultSuccess() {
+  MlirLogicalResult res = {1};
+  return res;
+}
+
+/** Creates a logical result representing a failure. */
+inline static MlirLogicalResult mlirLogicalResultFailure() {
+  MlirLogicalResult res = {0};
+  return res;
+}
+
 #ifdef __cplusplus
 }
 #endif
 
 #endif // MLIR_C_SUPPORT_H

mlir/include/mlir/CAPI/Diagnostics.h

+//===- IR.h - C API Utils for MLIR Diagnostics ------------------*- 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
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef MLIR_CAPI_DIAGNOSTICS_H
+#define MLIR_CAPI_DIAGNOSTICS_H
+
+#include "mlir-c/Diagnostics.h"
+#include <cassert>
+
+namespace mlir {
+class Diagnostic;
+} // namespace mlir
+
+inline mlir::Diagnostic &unwrap(MlirDiagnostic diagnostic) {
+  assert(diagnostic.ptr && "unexpected null diagnostic");
+  return *(static_cast<mlir::Diagnostic *>(diagnostic.ptr));
+}
+
+inline MlirDiagnostic wrap(mlir::Diagnostic &diagnostic) {
+  return {&diagnostic};
+}
+
+#endif // MLIR_CAPI_DIAGNOSTICS_H

mlir/include/mlir/CAPI/Support.h

 // C++ code other than C API implementation nor from C code.
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef MLIR_CAPI_SUPPORT_H
 #define MLIR_CAPI_SUPPORT_H
 
 #include "mlir-c/Support.h"
+#include "mlir/Support/LogicalResult.h"
 #include "llvm/ADT/StringRef.h"
 
 /// Converts a StringRef into its MLIR C API equivalent.
 inline MlirStringRef wrap(llvm::StringRef ref) {
   return mlirStringRefCreate(ref.data(), ref.size());
 }
 
 /// Creates a StringRef out of its MLIR C API equivalent.
 inline llvm::StringRef unwrap(MlirStringRef ref) {
   return llvm::StringRef(ref.data, ref.length);
 }
 
+inline MlirLogicalResult wrap(mlir::LogicalResult res) {
+  if (mlir::succeeded(res))
+    return mlirLogicalResultSuccess();
+  return mlirLogicalResultFailure();
+}
+
+inline mlir::LogicalResult unwrap(MlirLogicalResult res) {
+  return mlir::success(mlirLogicalResultIsSuccess(res));
+}
+
 #endif // MLIR_CAPI_SUPPORT_H

mlir/lib/CAPI/IR/CMakeLists.txt

 # Main API.
 add_mlir_library(MLIRCAPIIR
   AffineMap.cpp
+  Diagnostics.cpp
   IR.cpp
   StandardAttributes.cpp
   StandardTypes.cpp
   Support.cpp
 
   EXCLUDE_FROM_LIBMLIR
 
   ADDITIONAL_HEADER_DIRS
   ${MLIR_MAIN_INCLUDE_DIR}/mlir-c
 
   LINK_LIBS PUBLIC
   MLIRIR
   MLIRParser
   MLIRSupport
   )

mlir/lib/CAPI/IR/Diagnostics.cpp

+//===- Diagnostics.cpp - C Interface for MLIR Diagnostics -----------------===//
+//
+// 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 "mlir-c/Diagnostics.h"
+#include "mlir/CAPI/Diagnostics.h"
+#include "mlir/CAPI/IR.h"
+#include "mlir/CAPI/Support.h"
+#include "mlir/CAPI/Utils.h"
+#include "mlir/IR/Diagnostics.h"
+
+using namespace mlir;
+
+void mlirDiagnosticPrint(MlirDiagnostic diagnostic, MlirStringCallback callback,
+                         void *userData) {
+  detail::CallbackOstream stream(callback, userData);
+  unwrap(diagnostic).print(stream);
+  stream.flush();
+}
+
+MlirLocation mlirDiagnosticGetLocation(MlirDiagnostic diagnostic) {
+  return wrap(unwrap(diagnostic).getLocation());
+}
+
+MlirDiagnosticSeverity mlirDiagnosticGetSeverity(MlirDiagnostic diagnostic) {
+  switch (unwrap(diagnostic).getSeverity()) {
+  case mlir::DiagnosticSeverity::Error:
+    return MlirDiagnosticError;
+  case mlir::DiagnosticSeverity::Warning:
+    return MlirDiagnosticWarning;
+  case mlir::DiagnosticSeverity::Note:
+    return MlirDiagnosticNote;
+  case mlir::DiagnosticSeverity::Remark:
+    return MlirDiagnosticRemark;
+  }
+  llvm_unreachable("unhandled diagnostic severity");
+}
+
+// Notes are stored in a vector, so note iterator range is a pair of
+// random access iterators, for which it is cheap to compute the size.
+intptr_t mlirDiagnosticGetNumNotes(MlirDiagnostic diagnostic) {
+  return static_cast<intptr_t>(llvm::size(unwrap(diagnostic).getNotes()));
+}
+
+// Notes are stored in a vector, so the iterator is a random access iterator,
+// cheap to advance multiple steps at a time.
+MlirDiagnostic mlirDiagnosticGetNote(MlirDiagnostic diagnostic, intptr_t pos) {
+  return wrap(*std::next(unwrap(diagnostic).getNotes().begin(), pos));
+}
+
+MlirDiagnosticHandlerID
+mlirContextAttachDiagnosticHandler(MlirContext context,
+                                   MlirDiagnosticHandler handler) {
+  assert(handler && "unexpected null diagnostic handler");
+  DiagnosticEngine::HandlerID id =
+      unwrap(context)->getDiagEngine().registerHandler(
+          [handler](Diagnostic &diagnostic) {
+            return unwrap(handler(wrap(diagnostic)));
+          });
+  return static_cast<MlirDiagnosticHandlerID>(id);
+}
+
+void mlirContextDetachDiagnosticHandler(MlirContext context,
+                                        MlirDiagnosticHandlerID id) {
+  unwrap(context)->getDiagEngine().eraseHandler(
+      static_cast<DiagnosticEngine::HandlerID>(id));
+}
+
+void mlirEmitError(MlirLocation location, const char *message) {
+  emitError(unwrap(location)) << message;
+}

mlir/test/CAPI/ir.c

 /*===- ir.c - Simple test of C APIs ---------------------------------------===*\
 |*                                                                            *|
 |* 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                    *|
 |*                                                                            *|
 \*===----------------------------------------------------------------------===*/
 
 /* RUN: mlir-capi-ir-test 2>&1 | FileCheck %s
  */
 
-#include "mlir-c/IR.h"
 #include "mlir-c/AffineMap.h"
+#include "mlir-c/Diagnostics.h"
+#include "mlir-c/IR.h"
 #include "mlir-c/Registration.h"
 #include "mlir-c/StandardAttributes.h"
 #include "mlir-c/StandardDialect.h"
 #include "mlir-c/StandardTypes.h"
 
 #include <assert.h>
 #include <math.h>
 #include <stdio.h>
int registerOnlyStd() {
   MlirStringRef alsoStdNs = mlirStandardDialectGetNamespace();
   if (stdNs.length != alsoStdNs.length ||
       strncmp(stdNs.data, alsoStdNs.data, stdNs.length))
     return 8;
 
   return 0;
 }
 
+// Wraps a diagnostic into additional text we can match against.
+MlirLogicalResult errorHandler(MlirDiagnostic diagnostic) {
+  fprintf(stderr, "processing diagnostic <<\n");
+  mlirDiagnosticPrint(diagnostic, printToStderr, NULL);
+  fprintf(stderr, "\n");
+  MlirLocation loc = mlirDiagnosticGetLocation(diagnostic);
+  mlirLocationPrint(loc, printToStderr, NULL);
+  assert(mlirDiagnosticGetNumNotes(diagnostic) == 0);
+  fprintf(stderr, ">> end of diagnostic\n");
+  return mlirLogicalResultSuccess();
+}
+
+void testDiagnostics() {
+  MlirContext ctx = mlirContextCreate();
+  MlirDiagnosticHandlerID id =
+      mlirContextAttachDiagnosticHandler(ctx, errorHandler);
+  MlirLocation loc = mlirLocationUnknownGet(ctx);
+  mlirEmitError(loc, "test diagnostics");
+  mlirContextDetachDiagnosticHandler(ctx, id);
+  mlirEmitError(loc, "more test diagnostics");
+}
+
 int main() {
   MlirContext ctx = mlirContextCreate();
   mlirRegisterAllDialects(ctx);
   MlirLocation location = mlirLocationUnknownGet(ctx);
 
   MlirModule moduleOp = makeAdd(ctx, location);
   MlirOperation module = mlirModuleGetOperation(moduleOp);
   mlirOperationDump(module);
int main() {
   fprintf(stderr, "%d\n", errcode);
   // clang-format off
   // CHECK-LABEL: @registration
   // CHECK: 0
   // clang-format on
 
   mlirContextDestroy(ctx);
 
+  fprintf(stderr, "@test_diagnostics\n");
+  testDiagnostics();
+  // clang-format off
+  // CHECK-LABEL: @test_diagnostics
+  // CHECK: processing diagnostic <<
+  // CHECK:   test diagnostics
+  // CHECK:   loc(unknown)
+  // CHECK: >> end of diagnostic
+  // CHECK-NOT: processing diagnostic
+  // CHECK:     more test diagnostics
+
   return 0;
 }