Skip to content

Commit 813b84b

Browse files
aidintaidint
committed
add documentation for dialect interface ods support
1 parent e3d4a43 commit 813b84b

File tree

1 file changed

+173
-119
lines changed

1 file changed

+173
-119
lines changed

‎mlir/docs/Interfaces.md‎

Lines changed: 173 additions & 119 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,63 @@ if (DialectInlinerInterface *interface = dyn_cast<DialectInlinerInterface>(diale
8585
}
8686
```
8787

88+
#### Utilizing the ODS framework
89+
90+
Note: Before reading this section, the reader should have some familiarity with
91+
the concepts described in the
92+
[`Operation Definition Specification`](DefiningDialects/Operations.md) documentation.
93+
94+
MLIR also supports defining dialect interfaces directly in **TableGen**.
95+
This reduces boilerplate and allows authors to specify high-level interface
96+
structure declaratively.
97+
98+
For example, the above interface can be defined using ODS as follows:
99+
```tablegen
100+
def DialectInlinerInterface : DialectInterface<"DialectInlinerInterface"> {
101+
let description = [{
102+
Define a base inlining interface class to allow for dialects to opt-in to
103+
the inliner.
104+
}];
105+
106+
let methods = [
107+
InterfaceMethod<
108+
/*desc=*/ [{
109+
Returns true if the given region 'src' can be inlined into the region
110+
'dest' that is attached to an operation registered to the current dialect.
111+
'valueMapping' contains any remapped values from within the 'src' region.
112+
This can be used to examine what values will replace entry arguments into
113+
the 'src' region, for example.
114+
}],
115+
/*returnType=*/ "bool",
116+
/*methodName=*/ "isLegalToInline",
117+
/*args=*/ (ins "Region *":$dest, "Region *":$src,
118+
"IRMapping &":$valueMapping),
119+
/*methodBody=*/ [{
120+
return false;
121+
}]
122+
>
123+
];
124+
}
125+
```
126+
127+
`DialectInterfaces` class make use of the following components:
128+
129+
- C++ Class Name (Provided via template parameter)
130+
- The name of the C++ interface class.
131+
- Description (`description`)
132+
- A string description of the interface, its invariants, example usages,
133+
etc.
134+
- C++ Namespace (`cppNamespace`)
135+
- The C++ namespace that the interface class should be generated in.
136+
- Methods (`methods`)
137+
- The list of interface hook methods that are defined by the IR object.
138+
- The structure of these methods is defined [here](#interface-methods).
139+
140+
The header file can be generated via the following command:
141+
```bash
142+
mlir-tblgen gen-dialect-interface-decls DialectInterface.td
143+
144+
```
88145
#### DialectInterfaceCollection
89146

90147
An additional utility is provided via `DialectInterfaceCollection`. This class
@@ -364,10 +421,6 @@ void *TestDialect::getRegisteredInterfaceForOp(TypeID typeID,
364421
365422
#### Utilizing the ODS Framework
366423
367-
Note: Before reading this section, the reader should have some familiarity with
368-
the concepts described in the
369-
[`Operation Definition Specification`](DefiningDialects/Operations.md) documentation.
370-
371424
As detailed above, [Interfaces](#attributeoperationtype-interfaces) allow for
372425
attributes, operations, and types to expose method calls without requiring that
373426
the caller know the specific derived type. The downside to this infrastructure,
@@ -401,50 +454,50 @@ Providing a definition of the `AttrInterface`, `OpInterface`, or `TypeInterface`
401454
class will auto-generate the C++ classes for the interface. Interfaces are
402455
comprised of the following components:
403456

404-
* C++ Class Name (Provided via template parameter)
405-
- The name of the C++ interface class.
406-
* Interface Base Classes
407-
- A set of interfaces that the interface class should derived from. See
408-
[Interface Inheritance](#interface-inheritance) below for more details.
409-
* Description (`description`)
410-
- A string description of the interface, its invariants, example usages,
411-
etc.
412-
* C++ Namespace (`cppNamespace`)
413-
- The C++ namespace that the interface class should be generated in.
414-
* Methods (`methods`)
415-
- The list of interface hook methods that are defined by the IR object.
416-
- The structure of these methods is defined below.
417-
* Extra Class Declarations (Optional: `extraClassDeclaration`)
418-
- Additional C++ code that is generated in the declaration of the
419-
interface class. This allows for defining methods and more on the user
420-
facing interface class, that do not need to hook into the IR entity.
421-
These declarations are _not_ implicitly visible in default
422-
implementations of interface methods, but static declarations may be
423-
accessed with full name qualification.
424-
* Extra Shared Class Declarations (Optional: `extraSharedClassDeclaration`)
425-
- Additional C++ code that is injected into the declarations of both the
426-
interface and the trait class. This allows for defining methods and more
427-
that are exposed on both the interface and the trait class, e.g. to inject
428-
utilities on both the interface and the derived entity implementing the
429-
interface (e.g. attribute, operation, etc.).
430-
- In non-static methods, `$_attr`/`$_op`/`$_type`
431-
(depending on the type of interface) may be used to refer to an
432-
instance of the IR entity. In the interface declaration, the type of
433-
the instance is the interface class. In the trait declaration, the
434-
type of the instance is the concrete entity class
435-
(e.g. `IntegerAttr`, `FuncOp`, etc.).
436-
* Extra Trait Class Declarations (Optional: `extraTraitClassDeclaration`)
437-
- Additional C++ code that is injected into the interface trait
438-
declaration.
439-
- Allows the same replacements as extra shared class declarations.
457+
- C++ Class Name (Provided via template parameter)
458+
- The name of the C++ interface class.
459+
- Interface Base Classes
460+
- A set of interfaces that the interface class should derived from. See
461+
[Interface Inheritance](#interface-inheritance) below for more details.
462+
- Description (`description`)
463+
- A string description of the interface, its invariants, example usages,
464+
etc.
465+
- C++ Namespace (`cppNamespace`)
466+
- The C++ namespace that the interface class should be generated in.
467+
- Methods (`methods`)
468+
- The list of interface hook methods that are defined by the IR object.
469+
- The structure of these methods is defined below.
470+
- Extra Class Declarations (Optional: `extraClassDeclaration`)
471+
- Additional C++ code that is generated in the declaration of the
472+
interface class. This allows for defining methods and more on the user
473+
facing interface class, that do not need to hook into the IR entity.
474+
These declarations are _not_ implicitly visible in default
475+
implementations of interface methods, but static declarations may be
476+
accessed with full name qualification.
477+
- Extra Shared Class Declarations (Optional: `extraSharedClassDeclaration`)
478+
- Additional C++ code that is injected into the declarations of both the
479+
interface and the trait class. This allows for defining methods and more
480+
that are exposed on both the interface and the trait class, e.g. to inject
481+
utilities on both the interface and the derived entity implementing the
482+
interface (e.g. attribute, operation, etc.).
483+
- In non-static methods, `$_attr`/`$_op`/`$_type`
484+
(depending on the type of interface) may be used to refer to an
485+
instance of the IR entity. In the interface declaration, the type of
486+
the instance is the interface class. In the trait declaration, the
487+
type of the instance is the concrete entity class
488+
(e.g. `IntegerAttr`, `FuncOp`, etc.).
489+
- Extra Trait Class Declarations (Optional: `extraTraitClassDeclaration`)
490+
- Additional C++ code that is injected into the interface trait
491+
declaration.
492+
- Allows the same replacements as extra shared class declarations.
440493

441494
`OpInterface` classes may additionally contain the following:
442495

443-
* Verifier (`verify`)
444-
- A C++ code block containing additional verification applied to the
445-
operation that the interface is attached to.
446-
- The structure of this code block corresponds 1-1 with the structure of a
447-
[`Trait::verifyTrait`](Traits) method.
496+
- Verifier (`verify`)
497+
- A C++ code block containing additional verification applied to the
498+
operation that the interface is attached to.
499+
- The structure of this code block corresponds 1-1 with the structure of a
500+
[`Trait::verifyTrait`](Traits) method.
448501

449502
##### Interface Methods
450503

@@ -455,46 +508,46 @@ static method on the derived IR object.
455508

456509
Interface methods are comprised of the following components:
457510

458-
* Description
459-
- A string description of this method, its invariants, example usages,
460-
etc.
461-
* ReturnType
462-
- A string corresponding to the C++ return type of the method.
463-
* MethodName
464-
- A string corresponding to the C++ name of the method.
465-
* Arguments (Optional)
466-
- A dag of strings that correspond to a C++ type and variable name
467-
respectively.
468-
* MethodBody (Optional)
469-
- An optional explicit implementation of the interface method.
470-
- This implementation is placed within the method defined on the `Model`
471-
traits class, and is not defined by the `Trait` class that is attached
472-
to the IR entity. More concretely, this body is only visible by the
473-
interface class and does not affect the derived IR entity.
474-
- `ConcreteAttr`/`ConcreteOp`/`ConcreteType` is an implicitly defined
475-
`typename` that can be used to refer to the type of the derived IR
476-
entity currently being operated on.
477-
- In non-static methods, `$_op` and `$_self` may be used to refer to an
478-
instance of the derived IR entity.
479-
* DefaultImplementation (Optional)
480-
- An optional explicit default implementation of the interface method.
481-
- This implementation is placed within the `Trait` class that is attached
482-
to the IR entity, and does not directly affect any of the interface
483-
classes. As such, this method has the same characteristics as any other
484-
[`Trait`](Traits) method.
485-
- `ConcreteAttr`/`ConcreteOp`/`ConcreteType` is an implicitly defined
486-
`typename` that can be used to refer to the type of the derived IR
487-
entity currently being operated on.
488-
- This may refer to static fields of the interface class using the
489-
qualified name, e.g., `TestOpInterface::staticMethod()`.
511+
- Description
512+
- A string description of this method, its invariants, example usages,
513+
etc.
514+
- ReturnType
515+
- A string corresponding to the C++ return type of the method.
516+
- MethodName
517+
- A string corresponding to the C++ name of the method.
518+
- Arguments (Optional)
519+
- A dag of strings that correspond to a C++ type and variable name
520+
respectively.
521+
- MethodBody (Optional)
522+
- An optional explicit implementation of the interface method.
523+
- This implementation is placed within the method defined on the `Model`
524+
traits class, and is not defined by the `Trait` class that is attached
525+
to the IR entity. More concretely, this body is only visible by the
526+
interface class and does not affect the derived IR entity.
527+
- `ConcreteAttr`/`ConcreteOp`/`ConcreteType` is an implicitly defined
528+
`typename` that can be used to refer to the type of the derived IR
529+
entity currently being operated on.
530+
- In non-static methods, `$_op` and `$_self` may be used to refer to an
531+
instance of the derived IR entity.
532+
- DefaultImplementation (Optional)
533+
- An optional explicit default implementation of the interface method.
534+
- This implementation is placed within the `Trait` class that is attached
535+
to the IR entity, and does not directly affect any of the interface
536+
classes. As such, this method has the same characteristics as any other
537+
[`Trait`](Traits) method.
538+
- `ConcreteAttr`/`ConcreteOp`/`ConcreteType` is an implicitly defined
539+
`typename` that can be used to refer to the type of the derived IR
540+
entity currently being operated on.
541+
- This may refer to static fields of the interface class using the
542+
qualified name, e.g., `TestOpInterface::staticMethod()`.
490543

491544
ODS also allows for generating declarations for the `InterfaceMethod`s of an
492545
operation if the operation specifies the interface with
493546
`DeclareOpInterfaceMethods` (see an example below).
494547

495548
Examples:
496549

497-
```tablegen
550+
````tablegen
498551
def MyInterface : OpInterface<"MyInterface"> {
499552
let description = [{
500553
This is the description of the interface. It provides concrete information
@@ -665,7 +718,7 @@ def OpWithInferTypeInterfaceOp : Op<...
665718
// the generation of a declaration for those methods.
666719
def OpWithOverrideInferTypeInterfaceOp : Op<...
667720
[DeclareOpInterfaceMethods<MyInterface, ["getNumWithDefault"]>]> { ... }
668-
```
721+
````
669722

670723
##### Interface Inheritance
671724

@@ -725,7 +778,7 @@ def MyInterface : OpInterface<"MyInterface", [MyBaseInterface, MyOtherBaseInterf
725778

726779
An operation with `MyInterface` attached, would have the following interfaces added:
727780

728-
* MyBaseInterface, MyOtherBaseInterface, MyInterface
781+
- MyBaseInterface, MyOtherBaseInterface, MyInterface
729782

730783
The methods from `MyBaseInterface` in both `MyInterface` and `MyOtherBaseInterface` would
731784
forward to a single unique implementation for the operation.
@@ -749,51 +802,52 @@ common across many different operations. Below is a list of some key interfaces
749802
that may be used directly by any dialect. The format of the header for each
750803
interface section goes as follows:
751804

752-
* `Interface class name`
753-
- (`C++ class` -- `ODS class`(if applicable))
805+
- `Interface class name`
806+
- (`C++ class` -- `ODS class`(if applicable))
754807

755808
##### CallInterfaces
756-
* `CallOpInterface` - Used to represent operations like 'call'
757-
- `CallInterfaceCallable getCallableForCallee()`
758-
- `void setCalleeFromCallable(CallInterfaceCallable)`
759-
- `ArrayAttr getArgAttrsAttr()`
760-
- `ArrayAttr getResAttrsAttr()`
761-
- `void setArgAttrsAttr(ArrayAttr)`
762-
- `void setResAttrsAttr(ArrayAttr)`
763-
- `Attribute removeArgAttrsAttr()`
764-
- `Attribute removeResAttrsAttr()`
765-
* `CallableOpInterface` - Used to represent the target callee of call.
766-
- `Region * getCallableRegion()`
767-
- `ArrayRef<Type> getArgumentTypes()`
768-
- `ArrayRef<Type> getResultTypes()`
769-
- `ArrayAttr getArgAttrsAttr()`
770-
- `ArrayAttr getResAttrsAttr()`
771-
- `void setArgAttrsAttr(ArrayAttr)`
772-
- `void setResAttrsAttr(ArrayAttr)`
773-
- `Attribute removeArgAttrsAttr()`
774-
- `Attribute removeResAttrsAttr()`
809+
810+
- `CallOpInterface` - Used to represent operations like 'call'
811+
- `CallInterfaceCallable getCallableForCallee()`
812+
- `void setCalleeFromCallable(CallInterfaceCallable)`
813+
- `ArrayAttr getArgAttrsAttr()`
814+
- `ArrayAttr getResAttrsAttr()`
815+
- `void setArgAttrsAttr(ArrayAttr)`
816+
- `void setResAttrsAttr(ArrayAttr)`
817+
- `Attribute removeArgAttrsAttr()`
818+
- `Attribute removeResAttrsAttr()`
819+
- `CallableOpInterface` - Used to represent the target callee of call.
820+
- `Region * getCallableRegion()`
821+
- `ArrayRef<Type> getArgumentTypes()`
822+
- `ArrayRef<Type> getResultTypes()`
823+
- `ArrayAttr getArgAttrsAttr()`
824+
- `ArrayAttr getResAttrsAttr()`
825+
- `void setArgAttrsAttr(ArrayAttr)`
826+
- `void setResAttrsAttr(ArrayAttr)`
827+
- `Attribute removeArgAttrsAttr()`
828+
- `Attribute removeResAttrsAttr()`
775829

776830
##### RegionKindInterfaces
777831

778-
* `RegionKindInterface` - Used to describe the abstract semantics of regions.
779-
- `RegionKind getRegionKind(unsigned index)` - Return the kind of the
780-
region with the given index inside this operation.
781-
- RegionKind::Graph - represents a graph region without control flow
782-
semantics
783-
- RegionKind::SSACFG - represents an
784-
[SSA-style control flow](LangRef.md/#control-flow-and-ssacfg-regions) region
785-
with basic blocks and reachability
786-
- `hasSSADominance(unsigned index)` - Return true if the region with the
787-
given index inside this operation requires dominance.
832+
- `RegionKindInterface` - Used to describe the abstract semantics of regions.
833+
- `RegionKind getRegionKind(unsigned index)` - Return the kind of the
834+
region with the given index inside this operation.
835+
- RegionKind::Graph - represents a graph region without control flow
836+
semantics
837+
- RegionKind::SSACFG - represents an
838+
[SSA-style control flow](LangRef.md/#control-flow-and-ssacfg-regions) region
839+
with basic blocks and reachability
840+
- `hasSSADominance(unsigned index)` - Return true if the region with the
841+
given index inside this operation requires dominance.
788842

789843
##### SymbolInterfaces
790844

791-
* `SymbolOpInterface` - Used to represent
792-
[`Symbol`](SymbolsAndSymbolTables.md/#symbol) operations which reside
793-
immediately within a region that defines a
794-
[`SymbolTable`](SymbolsAndSymbolTables.md/#symbol-table).
845+
- `SymbolOpInterface` - Used to represent
846+
[`Symbol`](SymbolsAndSymbolTables.md/#symbol) operations which reside
847+
immediately within a region that defines a
848+
[`SymbolTable`](SymbolsAndSymbolTables.md/#symbol-table).
795849

796-
* `SymbolUserOpInterface` - Used to represent operations that reference
797-
[`Symbol`](SymbolsAndSymbolTables.md/#symbol) operations. This provides the
798-
ability to perform safe and efficient verification of symbol uses, as well
799-
as additional functionality.
850+
- `SymbolUserOpInterface` - Used to represent operations that reference
851+
[`Symbol`](SymbolsAndSymbolTables.md/#symbol) operations. This provides the
852+
ability to perform safe and efficient verification of symbol uses, as well
853+
as additional functionality.

0 commit comments

Comments
 (0)