mlir/docs/Tutorials/CreatingADialect.md

   1 # Creating a Dialect
   2
   3 [TOC]
   4
   5 Public dialects are typically separated into at least 3 directories:
   6 * mlir/include/mlir/Dialect/Foo   (for public include files)
   7 * mlir/lib/Dialect/Foo            (for sources)
   8 * mlir/lib/Dialect/Foo/IR         (for operations)
   9 * mlir/lib/Dialect/Foo/Transforms (for transforms)
  10 * mlir/test/Dialect/Foo           (for tests)
  11
  12 Along with other public headers, the 'include' directory contains a
  13 TableGen file in the [ODS format](../DefiningDialects/Operations.md), describing the
  14 operations in the dialect.  This is used to generate operation
  15 declarations (FooOps.h.inc) and definitions (FooOps.cpp.inc) and
  16 operation interface declarations (FooOpsInterfaces.h.inc) and
  17 definitions (FooOpsInterfaces.cpp.inc).
  18
  19 The 'IR' directory typically contains implementations of functions for
  20 the dialect which are not automatically generated by ODS.  These are
  21 typically defined in FooDialect.cpp, which includes FooOps.cpp.inc and
  22 FooOpsInterfaces.h.inc.
  23
  24 The 'Transforms' directory contains rewrite rules for the dialect,
  25 typically described in TableGen file using the [DDR
  26 format](../DeclarativeRewrites.md).
  27
  28 Note that dialect names should not generally be suffixed with “Ops”,
  29 although some files pertaining only to the operations of a dialect (e.g.
  30 FooOps.cpp) might be.
  31
  32 ## CMake best practices
  33
  34 ### TableGen Targets
  35
  36 Operations in dialects are typically declared using the ODS format in
  37 tablegen in a file FooOps.td.  This file forms the core of a dialect and
  38 is declared using add_mlir_dialect().
  39
  40 ```cmake
  41 add_mlir_dialect(FooOps foo)
  42 add_mlir_doc(FooOps FooDialect Dialects/ -gen-dialect-doc)
  43 ```
  44
  45 This generates the correct rules to run mlir-tblgen, along with a
  46 'MLIRFooOpsIncGen' target which can be used to declare dependencies.
  47
  48 Dialect transformations are typically declared in a file FooTransforms.td.
  49 Targets for TableGen are described in typical llvm fashion.
  50
  51 ```cmake
  52 set(LLVM_TARGET_DEFINITIONS FooTransforms.td)
  53 mlir_tablegen(FooTransforms.h.inc -gen-rewriters)
  54 add_public_tablegen_target(MLIRFooTransformIncGen)
  55 ```
  56
  57 The result is another 'IncGen' target, which runs mlir-tblgen.
  58
  59 ### Library Targets
  60
  61 Dialects may have multiple libraries.  Each library is typically
  62 declared with add_mlir_dialect_library().  Dialect libraries often
  63 depend on the generation of header files from TableGen (specified
  64 using the DEPENDS keyword).  Dialect libraries may also depend on
  65 other dialect libraries.  Typically this dependence is declared using
  66 target_link_libraries() and the PUBLIC keyword.  For instance:
  67
  68 ```cmake
  69 add_mlir_dialect_library(MLIRFoo
  70   DEPENDS
  71   MLIRFooOpsIncGen
  72   MLIRFooTransformsIncGen
  73
  74   LINK_COMPONENTS
  75   Core
  76
  77   LINK_LIBS PUBLIC
  78   MLIRBar
  79   <some-other-library>
  80   )
  81 ```
  82
  83 add_mlir_dialect_library() is a thin wrapper around add_llvm_library()
  84 which collects a list of all the dialect libraries.  This list is
  85 often useful for linking tools (e.g. mlir-opt) which should have
  86 access to all dialects.  This list is also linked into libMLIR.so.
  87 The list can be retrieved from the MLIR_DIALECT_LIBS global property:
  88
  89 ```cmake
  90 get_property(dialect_libs GLOBAL PROPERTY MLIR_DIALECT_LIBS)
  91 ```
  92
  93 Note that although the Bar dialect also uses TableGen to declare its
  94 operations, it is not necessary to explicitly depend on the
  95 corresponding IncGen targets.  The PUBLIC link dependency is
  96 sufficient.  Also note that we avoid using add_dependencies
  97 explicitly, since the dependencies need to be available to the
  98 underlying add_llvm_library() call, allowing it to correctly create
  99 new targets with the same sources.  However, dialects that depend on
 100 LLVM IR may need to depend on the LLVM 'intrinsics_gen' target to
 101 ensure that tablegen'd LLVM header files have been generated.
 102
 103 In addition, linkage to MLIR libraries is specified using the
 104 LINK_LIBS descriptor and linkage to LLVM libraries is specified using
 105 the LINK_COMPONENTS descriptor.  This allows cmake infrastructure to
 106 generate new library targets with correct linkage, in particular, when
 107 BUILD_SHARED_LIBS=on or LLVM_LINK_LLVM_DYLIB=on are specified.
 108
 109
 110 # Dialect Conversions
 111
 112 Conversions from “X” to “Y” live in mlir/include/mlir/Conversion/XToY,
 113 mlir/lib/Conversion/XToY and mlir/test/Conversion/XToY, respectively.
 114
 115 Default file names for conversion should omit “Convert” from their
 116 name, e.g. lib/VectorToLLVM/VectorToLLVM.cpp.
 117
 118 Conversion passes should live separately from conversions themselves
 119 for convenience of users that only care about a pass and not about its
 120 implementation with patterns or other infrastructure. For example
 121 include/mlir/VectorToLLVM/VectorToLLVMPass.h.
 122
 123 Common conversion functionality from or to dialect “X” that does not
 124 belong to the dialect definition can be located in
 125 mlir/lib/Conversion/XCommon, for example
 126 mlir/lib/Conversion/GPUCommon.
 127
 128 ## CMake best practices
 129
 130 Each conversion typically exists in a separate library, declared with
 131 add_mlir_conversion_library().  Conversion libraries typically depend
 132 on their source and target dialects, but may also depend on other
 133 dialects (e.g. MLIRFunc).  Typically this dependence is specified
 134 using target_link_libraries() and the PUBLIC keyword.  For instance:
 135
 136 ```cmake
 137 add_mlir_conversion_library(MLIRBarToFoo
 138   BarToFoo.cpp
 139
 140   ADDITIONAL_HEADER_DIRS
 141   ${MLIR_MAIN_INCLUDE_DIR}/mlir/Conversion/BarToFoo
 142
 143   LINK_LIBS PUBLIC
 144   MLIRBar
 145   MLIRFoo
 146   )
 147 ```
 148
 149 add_mlir_conversion_library() is a thin wrapper around
 150 add_llvm_library() which collects a list of all the conversion
 151 libraries.  This list is often useful for linking tools
 152 (e.g. mlir-opt) which should have access to all dialects.  This list
 153 is also linked in libMLIR.so.  The list can be retrieved from the
 154 MLIR_CONVERSION_LIBS global property:
 155
 156 ```cmake
 157 get_property(dialect_libs GLOBAL PROPERTY MLIR_CONVERSION_LIBS)
 158 ```
 159
 160 Note that it is only necessary to specify a PUBLIC dependence against
 161 dialects to generate compile-time and link-time dependencies, and it
 162 is not necessary to explicitly depend on the dialects' IncGen targets.
 163 However, conversions that directly include LLVM IR header files may
 164 need to depend on the LLVM 'intrinsics_gen' target to ensure that
 165 tablegen'd LLVM header files have been generated.