[mlir] Revamp operation documentation generation

Summary: This revisions performs several cleanups to the generated dialect documentation: * Standardizes format of attributes/operands/results sections * Splits out operation/type/dialect documentation generation to allow for composing generated and hand-written documentation * Add section for declarative assembly syntax and successors * General cleanup Differential Revision: https://reviews.llvm.org/D76573
llvm · Mar 24, 2020 · 1a083f0 · 1a083f0
1 parent 597718a
commit 1a083f0
Show file tree

Hide file tree

Showing 18 changed files with 194 additions and 100 deletions.
diff --git a/mlir/cmake/modules/AddMLIR.cmake b/mlir/cmake/modules/AddMLIR.cmake
@@ -32,26 +32,28 @@ function(whole_archive_link target)
 endfunction(whole_archive_link)
 
 # Declare a dialect in the include directory
-function(add_mlir_dialect dialect dialect_namespace dialect_doc_filename)
+function(add_mlir_dialect dialect dialect_namespace)
   set(LLVM_TARGET_DEFINITIONS ${dialect}.td)
   mlir_tablegen(${dialect}.h.inc -gen-op-decls)
   mlir_tablegen(${dialect}.cpp.inc -gen-op-defs)
   mlir_tablegen(${dialect}Dialect.h.inc -gen-dialect-decls -dialect=${dialect_namespace})
   add_public_tablegen_target(MLIR${dialect}IncGen)
   add_dependencies(mlir-headers MLIR${dialect}IncGen)
+endfunction()
 
-  # Generate Dialect Documentation
-  set(LLVM_TARGET_DEFINITIONS ${dialect_doc_filename}.td)
-  tablegen(MLIR ${dialect_doc_filename}.md -gen-op-doc "-I${MLIR_MAIN_SRC_DIR}" "-I${MLIR_INCLUDE_DIR}")
-  set(GEN_DOC_FILE ${MLIR_BINARY_DIR}/docs/Dialects/${dialect_doc_filename}.md)
+# Generate Documentation
+function(add_mlir_doc doc_filename command output_file output_directory)
+  set(LLVM_TARGET_DEFINITIONS ${doc_filename}.td)
+  tablegen(MLIR ${output_file}.md ${command} "-I${MLIR_MAIN_SRC_DIR}" "-I${MLIR_INCLUDE_DIR}")
+  set(GEN_DOC_FILE ${MLIR_BINARY_DIR}/docs/${output_directory}${output_file}.md)
   add_custom_command(
           OUTPUT ${GEN_DOC_FILE}
           COMMAND ${CMAKE_COMMAND} -E copy
-                  ${CMAKE_CURRENT_BINARY_DIR}/${dialect_doc_filename}.md
+                  ${CMAKE_CURRENT_BINARY_DIR}/${output_file}.md
                   ${GEN_DOC_FILE}
-          DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${dialect_doc_filename}.md)
-  add_custom_target(${dialect_doc_filename}DocGen DEPENDS ${GEN_DOC_FILE})
-  add_dependencies(mlir-doc ${dialect_doc_filename}DocGen)
+          DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${output_file}.md)
+  add_custom_target(${output_file}DocGen DEPENDS ${GEN_DOC_FILE})
+  add_dependencies(mlir-doc ${output_file}DocGen)
 endfunction()
 
 # Declare a library which can be compiled in libMLIR.so

diff --git a/mlir/docs/CreatingADialect.md b/mlir/docs/CreatingADialect.md
@@ -39,7 +39,8 @@ is declared using add_mlir_dialect().
 
 ```cmake
 
-add_mlir_dialect(FooOps foo FooOps)
+add_mlir_dialect(FooOps foo)
+add_mlir_doc(FooOps -gen-dialect-doc FooDialect Dialects/)
 
 ```
 

diff --git a/mlir/docs/Dialects/Vector.md b/mlir/docs/Dialects/Vector.md
@@ -1,5 +1,7 @@
 # Vector Dialect
 
+[TOC]
+
 MLIR supports multi-dimensional `vector` types and custom operations on those
 types. A generic, retargetable, higher-order ``vector`` type (`n-D` with `n >
 1`) is a structured type, that carries semantic information useful for
@@ -488,6 +490,6 @@ low-level abstraction.
 The use of special intrinsics in a `1-D` LLVM world is still available thanks
 to an explicit `vector.cast` op.
 
+## Operations
 
-### Operations
-
+[include "Dialects/VectorOps.md"]
diff --git a/mlir/docs/OpDefinitions.md b/mlir/docs/OpDefinitions.md
@@ -1222,7 +1222,7 @@ mlir-tblgen --gen-op-decls -I /path/to/mlir/include /path/to/input/td/file
 # To see op C++ class definition
 mlir-tblgen --gen-op-defs -I /path/to/mlir/include /path/to/input/td/file
 # To see op documentation
-mlir-tblgen --gen-op-doc -I /path/to/mlir/include /path/to/input/td/file
+mlir-tblgen --gen-dialect-doc -I /path/to/mlir/include /path/to/input/td/file
 
 # To see op interface C++ class declaration
 mlir-tblgen --gen-op-interface-decls -I /path/to/mlir/include /path/to/input/td/file
@@ -1232,7 +1232,6 @@ mlir-tblgen --gen-op-interface-defs -I /path/to/mlir/include /path/to/input/td/f
 mlir-tblgen --gen-op-interface-doc -I /path/to/mlir/include /path/to/input/td/file
 ```
 
-
 ## Appendix
 
 ### Requirements and existing mechanisms analysis

diff --git a/mlir/include/mlir/Dialect/Affine/IR/CMakeLists.txt b/mlir/include/mlir/Dialect/Affine/IR/CMakeLists.txt
@@ -1 +1,2 @@
-add_mlir_dialect(AffineOps affine AffineOps)
+add_mlir_dialect(AffineOps affine)
+add_mlir_doc(AffineOps -gen-dialect-doc AffineDialect Dialects/)
diff --git a/mlir/include/mlir/Dialect/FxpMathOps/CMakeLists.txt b/mlir/include/mlir/Dialect/FxpMathOps/CMakeLists.txt
@@ -1 +1,2 @@
-add_mlir_dialect(FxpMathOps fxpmath FxpMathOps)
+add_mlir_dialect(FxpMathOps fxpmath)
+add_mlir_doc(FxpMathOps -gen-dialect-doc FxpMathDialect Dialects/)
diff --git a/mlir/include/mlir/Dialect/GPU/CMakeLists.txt b/mlir/include/mlir/Dialect/GPU/CMakeLists.txt
@@ -1 +1,2 @@
-add_mlir_dialect(GPUOps gpu GPUOps)
+add_mlir_dialect(GPUOps gpu)
+add_mlir_doc(GPUOps -gen-dialect-doc GPUDialect Dialects/)
diff --git a/mlir/include/mlir/Dialect/LLVMIR/CMakeLists.txt b/mlir/include/mlir/Dialect/LLVMIR/CMakeLists.txt
@@ -6,8 +6,10 @@ mlir_tablegen(LLVMOpsEnums.h.inc -gen-enum-decls)
 mlir_tablegen(LLVMOpsEnums.cpp.inc -gen-enum-defs)
 add_public_tablegen_target(MLIRLLVMOpsIncGen)
 
-add_mlir_dialect(NVVMOps nvvm NVVMOps)
-add_mlir_dialect(ROCDLOps rocdl ROCDLOps)
+add_mlir_dialect(NVVMOps nvvm)
+add_mlir_doc(NVVMOps -gen-dialect-doc NVVMDialect Dialects/)
+add_mlir_dialect(ROCDLOps rocdl)
+add_mlir_doc(ROCDLOps -gen-dialect-doc ROCDLDialect Dialects/)
 
 set(LLVM_TARGET_DEFINITIONS LLVMOps.td)
 mlir_tablegen(LLVMConversions.inc -gen-llvmir-conversions)

diff --git a/mlir/include/mlir/Dialect/Linalg/IR/CMakeLists.txt b/mlir/include/mlir/Dialect/Linalg/IR/CMakeLists.txt
@@ -1,4 +1,5 @@
-add_mlir_dialect(LinalgOps linalg LinalgDoc)
+add_mlir_dialect(LinalgOps linalg)
+add_mlir_doc(LinalgDoc -gen-dialect-doc LinalgDialect Dialects/)
 set(LLVM_TARGET_DEFINITIONS LinalgStructuredOps.td)
 mlir_tablegen(LinalgStructuredOps.h.inc -gen-op-decls)
 mlir_tablegen(LinalgStructuredOps.cpp.inc -gen-op-defs)

diff --git a/mlir/include/mlir/Dialect/LoopOps/CMakeLists.txt b/mlir/include/mlir/Dialect/LoopOps/CMakeLists.txt
@@ -1 +1,2 @@
-add_mlir_dialect(LoopOps loop LoopOps)
+add_mlir_dialect(LoopOps loop)
+add_mlir_doc(LoopOps -gen-dialect-doc LoopDialect Dialects/)
diff --git a/mlir/include/mlir/Dialect/OpenMP/CMakeLists.txt b/mlir/include/mlir/Dialect/OpenMP/CMakeLists.txt
@@ -1 +1,2 @@
-add_mlir_dialect(OpenMPOps omp OpenMPOps)
+add_mlir_dialect(OpenMPOps omp)
+add_mlir_doc(OpenMPOps -gen-dialect-doc OpenMPDialect Dialects/)
diff --git a/mlir/include/mlir/Dialect/Quant/CMakeLists.txt b/mlir/include/mlir/Dialect/Quant/CMakeLists.txt
@@ -1 +1,2 @@
-add_mlir_dialect(QuantOps quant QuantOps)
+add_mlir_dialect(QuantOps quant)
+add_mlir_doc(QuantOps -gen-dialect-doc QuantDialect Dialects/)
diff --git a/mlir/include/mlir/Dialect/SPIRV/CMakeLists.txt b/mlir/include/mlir/Dialect/SPIRV/CMakeLists.txt
@@ -1,4 +1,5 @@
-add_mlir_dialect(SPIRVOps spv SPIRVOps)
+add_mlir_dialect(SPIRVOps spv)
+add_mlir_doc(SPIRVOps -gen-dialect-doc SPIRVDialect Dialects/)
 
 set(LLVM_TARGET_DEFINITIONS SPIRVBase.td)
 mlir_tablegen(SPIRVEnums.h.inc -gen-enum-decls)

diff --git a/mlir/include/mlir/Dialect/Vector/CMakeLists.txt b/mlir/include/mlir/Dialect/Vector/CMakeLists.txt
@@ -1,4 +1,5 @@
-add_mlir_dialect(VectorOps vector VectorOps)
+add_mlir_dialect(VectorOps vector)
+add_mlir_doc(VectorOps -gen-op-doc VectorOps Dialects/)
 
 set(LLVM_TARGET_DEFINITIONS VectorTransformPatterns.td)
 mlir_tablegen(VectorTransformPatterns.h.inc -gen-rewriters)

diff --git a/mlir/include/mlir/TableGen/Operator.h b/mlir/include/mlir/TableGen/Operator.h
@@ -198,6 +198,10 @@ class Operator {
   bool hasSummary() const;
   StringRef getSummary() const;
 
+  // Query functions for the assembly format of the operator.
+  bool hasAssemblyFormat() const;
+  StringRef getAssemblyFormat() const;
+
   // Returns this op's extra class declaration code.
   StringRef getExtraClassDeclaration() const;
 

diff --git a/mlir/lib/TableGen/Operator.cpp b/mlir/lib/TableGen/Operator.cpp
@@ -11,6 +11,7 @@
 //===----------------------------------------------------------------------===//
 
 #include "mlir/TableGen/Operator.h"
+#include "mlir/ADT/TypeSwitch.h"
 #include "mlir/TableGen/OpTrait.h"
 #include "mlir/TableGen/Predicate.h"
 #include "mlir/TableGen/Type.h"
@@ -411,6 +412,17 @@ StringRef tblgen::Operator::getSummary() const {
   return def.getValueAsString("summary");
 }
 
+bool tblgen::Operator::hasAssemblyFormat() const {
+  auto *valueInit = def.getValueInit("assemblyFormat");
+  return isa<llvm::CodeInit>(valueInit) || isa<llvm::StringInit>(valueInit);
+}
+
+StringRef tblgen::Operator::getAssemblyFormat() const {
+  return TypeSwitch<llvm::Init *, StringRef>(def.getValueInit("assemblyFormat"))
+      .Case<llvm::StringInit, llvm::CodeInit>(
+          [&](auto *init) { return init->getValue(); });
+}
+
 void tblgen::Operator::print(llvm::raw_ostream &os) const {
   os << "op '" << getOperationName() << "'\n";
   for (Argument arg : arguments) {