mlir/tosa: supply better documentation for tosa.pad

[artagnon]

Summary

This patch modifies the description in TosaOps.td, taking into account
all the arguments, and supplying examples.

Signed-off-by: Ramkumar Ramachandra <[e-mail]>

[artagnon]

Wrap overly long line.

[rsuderman]

Proxying to @eric-k256 as he is in charge of TOSA operation specifics and should validate the description.

[artagnon]

Ping.

[eric-k256]

Thanks for the ping, this got lost in my todo list.

I like the updated description of the op, along with the arguments. I have concerns about including the examples with potential lowerings. It would be another area that would fall out of sync with what the real lowerings are. There is nothing that would break the build or otherwise notify someone changing a lowering that this documentation would also need to be updated. It feels safer to leave the definition of the lowering to the conversion documentation as the source of truth for that conversion. We could still leave an example without the lowering as a usage model.

[artagnon]

Address review comments: remove lowering example.

[eric-k256]

Thanks! LGTM now. Let me know if you need help landing this.

mlir/include/mlir/Dialect/Tosa/IR/TosaOps.td

 //===----------------------------------------------------------------------===//
 def Tosa_PadOp : Tosa_Op<"pad", [
     DeclareOpInterfaceMethods<InferShapedTypeOpInterface,
                               ["inferReturnTypeComponents"]>,
     Pure]> {
   let summary = "Pads a tensor with value specified.";
 
   let description = [{
-    Pads a tensor along borders of each dimension with pad_value.
+    The `tosa.pad` operation pads a tensor along borders of each dimension with `pad_const` (defaults to zero), given a padding configuration `padding` specifying low and high values along the dimensions.
+
+    Example:
+
+    ```mlir
+    %0 = arith.constant dense<[[1, 2], [3, 4]]> : tensor<2x2xi32>
+    "tosa.pad"(%arg0, %0)  : (tensor<1x2xf32>, tensor<2x2xi32>)  -> (tensor<4x9xf32>)
+    ```
+
+    This may lower to IR resembling:
+
+    ```mlir
+    tensor.pad %arg0 low[1, 3] high[2, 4] {
+    ^bb0(%arg1: index, %arg2: index):
+      tensor.yield %cst_0 : f32
+    } : tensor<1x2xf32> to tensor<4x9xf32>
+    ```
+
+    Example 2:
+
+    ```mlir
+    %0 = arith.constant dense<[[-1, 2], [3, 4]]> : tensor<2x2xi32>
+    "tosa.pad"(%arg0, %0)  : (tensor<1x2xf32>, tensor<2x2xi32>)  -> (tensor<?x9xf32>)
+    ```
+
+    This may lower to IR resembling:
+
+    ```mlir
+    %padded = tensor.pad %arg0 low[-1, 3] high[2, 4] {
+    ^bb0(%arg1: index, %arg2: index):
+      tensor.yield %cst_0 : f32
+    } : tensor<1x2xf32> to tensor<?x9xf32>
+    ```
   }];
 
   let arguments = (ins
     Tosa_RankedTensor:$input1,
     Tosa_Int32Or64Tensor:$padding,
     Optional<Tosa_ScalarTensor>:$pad_const,
     OptionalAttr<Tosa_PadOpQuantizationAttr>:$quantization_info
   );