Add more detail about locations in Chapter 2 of tutorial.
Resolves issue 241 (https://github.com/tensorflow/mlir/issues/241).
PiperOrigin-RevId: 281867192
Change-Id: I59dea8430eeb95f11b8a00c0a5dd46405e8e05e6
diff --git a/third_party/mlir/g3doc/Tutorials/Toy/Ch-2.md b/third_party/mlir/g3doc/Tutorials/Toy/Ch-2.md
index 6786ee0..34f25ab 100755
--- a/third_party/mlir/g3doc/Tutorials/Toy/Ch-2.md
+++ b/third_party/mlir/g3doc/Tutorials/Toy/Ch-2.md
@@ -41,7 +41,7 @@
Here is the MLIR assembly for the Toy `transpose` operations:
```mlir
-%t_tensor = "toy.transpose"(%tensor) {inplace = true} : (tensor<2x3xf64>) -> tensor<3x2xf64>
+%t_tensor = "toy.transpose"(%tensor) {inplace = true} : (tensor<2x3xf64>) -> tensor<3x2xf64> loc("example/file/path":12:1)
```
Let's break down the anatomy of this MLIR operation:
@@ -74,9 +74,14 @@
- `(tensor<2x3xf64) -> tensor<3x2xf64>`
- * This trailing portion refers to the type of the operation in a
- functional form, spelling the types of the arguments in parentheses and
- the type of the return values afterward.
+ * This refers to the type of the operation in a functional form, spelling
+ the types of the arguments in parentheses and the type of the return
+ values afterward.
+
+- loc("example/file/path":12:1)
+
+ * This is the location in the source code from which this operation
+ originated.
Shown here is the general form of an operation. As described above, the set of
operations in MLIR is extensible. This means that the infrastructure must be
@@ -84,10 +89,11 @@
boiling down the composition of an operation into discrete pieces:
- A name for the operation.
-- A source location for debugging purposes.
- A list of SSA operand values.
-- A list of [types](../../LangRef.md#type-system) for result values.
- A list of [attributes](../../LangRef.md#attributes).
+- A list of [types](../../LangRef.md#type-system) for result values.
+- A [source location](../../Diagnostics.md#source-locations) for debugging
+ purposes.
- A list of successors [blocks](../../LangRef.md#blocks) (for branches,
mostly).
- A list of [regions](../../LangRef.md#regions) (for structural operations
@@ -98,6 +104,15 @@
MLIR, the location is a core requirement, and APIs depend on and manipulate it.
Dropping a location is thus an explicit choice which cannot happen by mistake.
+To provide an illustration: If a transformation replaces an operation by
+another, that new operation must still have a location attached. This makes it
+possible to track where that operation came from.
+
+It's worth noting that the mlir-opt tool - a tool for testing
+compiler passes - does not include locations in the output by default. The
+`-mlir-print-debuginfo` flag specifies to include locations. (Run `mlir-opt
+--help` for more options.)
+
### Opaque API
MLIR is designed to be a completely extensible system, and as such, the
