[MLIR][LinAlg][Docs] Add missing example code and other small fixes.

[ergawy]

Summary

Fixes a few small issues in the docs. It seems one of the examples was missing
the expected MLIR output due to a copy-paste typo.

[ergawy]

Just updated the syntax to reflect the current situation and fixed a small copy-paste issue. Hopefully, nothing wrong was introduced :).

[nicolasvasilache]

Looks great, thanks!
Just a few args_in / args_out remaining to delete and this is good to go.

mlir/docs/Dialects/Linalg.md

98–99

Now that you mention it, args_in and args_out are obsolete and derived form ins and outs + operand_segment_sizes :)
Could you please delete those 2 lines and hunt the other places ?

309

ah you removed them from here already, thanks!

331–332

I think you can also delete this line, I think I just used it to generate the IR but ended up copying the wrong IR .. :p thanks for fixing

[ergawy]

Handle review comments.

mlir/docs/Dialects/Linalg.md

 1-offset layout.
 
 ```mlir
 // File name: example1.mlir
 #accesses = [
   affine_map<(m) -> (m)>,
   affine_map<(m) -> (m)>
 ]
+
 #attrs = {
-  args_in = 1,
-  args_out = 1,
   indexing_maps = #accesses,
   iterator_types = ["parallel"]
 }
+
 // memory layouts
 #identity = affine_map<(d0) -> (d0)>
 
 func @example(%A: memref<?xf32, #identity>,
               %B: memref<?xvector<4xf32>, offset: 1, strides: [2]>) {
-  linalg.generic #attrs %A, %B {
+  linalg.generic #attrs
+  ins(%A: memref<?xf32, #identity>)
+  outs(%B: memref<?xvector<4xf32>, offset: 1, strides: [2]>) {
   ^bb0(%a: f32, %b: vector<4xf32>):
     %c = "some_compute"(%a, %b): (f32, vector<4xf32>) -> (vector<4xf32>)
     linalg.yield %c: vector<4xf32>
-  } : memref<?xf32, #identity>, memref<?xvector<4xf32>, offset: 1, strides: [2]>
+  }
   return
 }
 ```
 
 The property "*Input and Output Operands Define The Iteration Space*" is
 materialized by a lowering into a form that will resemble:
 
 ```mlir

 
 A `linalg.generic` *defines* the mapping between the iteration space (i.e. the
 loops) and the data.
 
 Consider the following fully specified `linalg.generic` example. Here, the first
 `memref` is a 2-strided one on both of its dimensions, and the second `memref`
 uses an identity layout.
 
-```
+```mlir
 // File name: example2.mlir
 #indexing_maps = [
   affine_map<(i, j) -> (j, i)>,
   affine_map<(i, j) -> (j)>
 ]
+
 #attrs = {
-  args_in = 1,
-  args_out = 1,
   indexing_maps = #indexing_maps,
   iterator_types = ["parallel", "parallel"]
 }
 
 func @example(%A: memref<8x?xf32, offset: 0, strides: [2, 2]>,
               %B: memref<?xvector<4xf32>>) {
-  linalg.generic #attrs %A, %B {
+  linalg.generic #attrs
+  ins(%A: memref<8x?xf32, offset: 0, strides: [2, 2]>)
+  outs(%B: memref<?xvector<4xf32>>) {
   ^bb0(%a: f32, %b: vector<4xf32>):
     %c = "some_compute"(%a, %b): (f32, vector<4xf32>) -> (vector<4xf32>)
     linalg.yield %c: vector<4xf32>
-  }: memref<8x?xf32 , offset: 0, strides: [2, 2]>, memref<?xvector<4xf32>>
+  }
   return
 }
 ```
 
 The property "*Reversible Mappings Between Control and Data Structures*" is
 materialized by a lowering into a form that will resemble:
 
-```
+```mlir
 // Run: mlir-opt example2.mlir -allow-unregistered-dialect -convert-linalg-to-loops
 #map0 = affine_map<(d0, d1) -> (d0 * 2 + d1 * 2)>
 
 func @example(%arg0: memref<8x?xf32, #map0>, %arg1: memref<?xvector<4xf32>>) {
   %c8 = constant 8 : index
   %c0 = constant 0 : index
   %c1 = constant 1 : index
   %0 = dim %arg0, %c1 : memref<8x?xf32, #map0>

 inside the region: the region can capture buffers arbitrarily and write into
 them. If this conflicts with some parallel iterator requirement, this is
 undefined behavior.
 
 Previous examples already elaborate compute payloads with an unregistered
 function `"some_compute"`. The following code snippet shows what the result will
 be when using a concrete operation `addf`:
 
-```
+```mlir
 // File name: example3.mlir
-#indexing_maps = [
-  affine_map<(i, j) -> (i, j)>,
-  affine_map<(i, j) -> (i, j)>,
-  affine_map<(i, j) -> (i, j)>
-]
+#map = affine_map<(i, j) -> (i, j)>
+
 #attrs = {
-  args_in = 2,
-  args_out = 1,
-  indexing_maps = #indexing_maps,
+  indexing_maps = [#map, #map, #map],
   iterator_types = ["parallel", "parallel"]
 }
+
 func @example(%A: memref<?x?xf32>, %B: memref<?x?xf32>, %C: memref<?x?xf32>) {
-  linalg.generic #attrs %A, %B, %C {
+  linalg.generic #attrs
+  ins(%A, %B: memref<?x?xf32>, memref<?x?xf32>)
+  outs(%C: memref<?x?xf32>) {
     ^bb0(%a: f32, %b: f32, %c: f32):
       %d = addf %a, %b : f32
       linalg.yield %d : f32
-  }: memref<?x?xf32>, memref<?x?xf32>, memref<?x?xf32>
+  }
+
   return
 }
 ```
 
 This function basically element-wise adds up two matrices (`%A` and `%B`) and
 stores the result into another one (`%C`).
 
 The property "*The Compute Payload is Specified With a Region*" is materialized
 by a lowering into a form that will resemble:
 
-```
-// Run: mlir-opt example3.mlir -convert-linalg-to-loops
-#indexing_maps = [
-  affine_map<(i, j) -> (i, j)>,
-  affine_map<(i, j) -> (i, j)>,
-  affine_map<(i, j) -> (i, j)>
-]
-#attrs = {
-  args_in = 2,
-  args_out = 1,
-  indexing_maps = #indexing_maps,
-  iterator_types = ["parallel", "parallel"]
+```mlir
+func @example(%arg0: memref<?x?xf32>, %arg1: memref<?x?xf32>, %arg2: memref<?x?xf32>) {
+  %c0 = constant 0 : index
+  %c1 = constant 1 : index
+  %0 = dim %arg0, %c0 : memref<?x?xf32>
+  %1 = dim %arg0, %c1 : memref<?x?xf32>
+  scf.for %arg3 = %c0 to %0 step %c1 {
+    scf.for %arg4 = %c0 to %1 step %c1 {
+      %2 = load %arg0[%arg3, %arg4] : memref<?x?xf32>
+      %3 = load %arg1[%arg3, %arg4] : memref<?x?xf32>
+      %4 = addf %2, %3 : f32
+      store %4, %arg2[%arg3, %arg4] : memref<?x?xf32>
+    }
   }
-func @example(%A: memref<?x?xf32>, %B: memref<?x?xf32>, %C: memref<?x?xf32>) {
-  linalg.generic #attrs %A, %B, %C {
-  ^bb0(%a: f32, %b: f32, %c: f32):
-    %d = addf %a, %b : f32
-    linalg.yield %d : f32
-  }: memref<?x?xf32>, memref<?x?xf32>, memref<?x?xf32>
   return
 }
 ```
 
 In the process of lowering to loops and lower-level constructs, similar
 requirements are encountered, as are discussed in the
 [inlined call op proposal](https://llvm.discourse.group/t/introduce-std-inlined-call-op-proposal/282/2).
 We expect to be able to reuse the common lower-level infrastructure provided it

 integration at the ABI level. Regardless of whether one wants to use external
 library calls or a custom ISA, the problem for codegen is similar: preservation
 of a fixed granularity.
 
 Consider the following example that adds an additional attribute
 `library_call="pointwise_add"` that specifies the name of an external library
 call we intend to use:
 
-```
+```mlir
 // File name: example4.mlir
 #indexing_maps = [
   affine_map<(i, j) -> (i, j)>,
   affine_map<(i, j) -> (i, j)>,
   affine_map<(i, j) -> (i, j)>
 ]
+
 #attrs = {
-  args_in = 2,
-  args_out = 1,
   indexing_maps = #indexing_maps,
   iterator_types = ["parallel", "parallel"],
   library_call = "pointwise_add"
 }
+
 func @example(%A: memref<?x?xf32>, %B: memref<?x?xf32>, %C: memref<?x?xf32>) {
-  linalg.generic #attrs %A, %B, %C {
+  linalg.generic #attrs
+  ins(%A, %B: memref<?x?xf32>, memref<?x?xf32>)
+  outs(%C: memref<?x?xf32>) {
   ^bb0(%a: f32, %b: f32, %c: f32):
     %d = addf %a, %b : f32
     linalg.yield %d : f32
-  }: memref<?x?xf32>, memref<?x?xf32>, memref<?x?xf32>
+  }
   return
 }
 ```
 
 The property "*Map To an External Library Call*" is materialized by a lowering
 into a form that will resemble:
 
-```
+```mlir
 // Run: mlir-opt example4.mlir -convert-linalg-to-std
 // Note that we lower the Linalg dialect directly to the Standard dialect.
 // See this doc: https://mlir.llvm.org/docs/Dialects/Standard/
 
 #map0 = affine_map<(d0, d1)[s0, s1, s2] -> (d0 * s1 + s0 + d1 * s2)>
 
 func @example(%arg0: memref<?x?xf32>, %arg1: memref<?x?xf32>, %arg2: memref<?x?xf32>) {
   %0 = memref_cast %arg0 : memref<?x?xf32> to memref<?x?xf32, #map0>
   %1 = memref_cast %arg1 : memref<?x?xf32> to memref<?x?xf32, #map0>
   %2 = memref_cast %arg2 : memref<?x?xf32> to memref<?x?xf32, #map0>
   call @pointwise_add(%0, %1, %2) : (memref<?x?xf32, #map0>, memref<?x?xf32, #map0>, memref<?x?xf32, #map0>) -> ()
   return
 }
 func @pointwise_add(memref<?x?xf32, #map0>, memref<?x?xf32, #map0>, memref<?x?xf32, #map0>) attributes {llvm.emit_c_interface}
 ```
 
 Which, after lowering to LLVM resembles:
 
-```
+```mlir
 // Run: mlir-opt example4.mlir -convert-linalg-to-std | mlir-opt -convert-std-to-llvm
 // Some generated code are omitted here.
 func @example(%arg0: !llvm<"float*">, ...) {
   ...
   llvm.call @pointwise_add(...) : (!llvm<"float*">, ...) -> ()
   return
 }