[mlir][tosa] Update the description of rescale and variable ops (llvm#134815)

Updates the description to align with the specification. Also includes
some small cleanup to `sigmoid`, to avoid confusion.

Signed-off-by: Luke Hutton <[email protected]>

Author: lhutton1

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

@@ -545,9 +545,7 @@ def Tosa_SigmoidOp : Tosa_ElementwiseUnaryOp<"sigmoid"> {
     For quantized integer data types, the TABLE operator should be used instead.
     Each implementation may choose an appropriate TABLE given the scale and zero
     point of the input data. Eight or sixteen bit precision tables may be used
-    based on the input tensor to the sigmoid function. The sigmoid table has 513
-    entries each of 16-bit precision and covering the input range -16.0 to +16.0
-    in steps of 1/16.
+    based on the input tensor to the sigmoid function.
   }];
 
   let arguments = (ins
@@ -757,10 +755,10 @@ def Tosa_IntDivOp : Tosa_ElementwiseOp<"int_div", [SameOperandsAndResultElementT
   let summary = "Integer divide operator.";
 
   let description = [{
-    Elementwise integer divide of input1 by input2. Axis of size 1 will be 
-    broadcast as necessary. Rank of input tensors must match. The result of the 
-    divide is truncated towards zero. Expected use is for operations on 
-    non-scaled integers. Floating point divide should use RECIPROCAL and MUL. 
+    Elementwise integer divide of input1 by input2. Axis of size 1 will be
+    broadcast as necessary. Rank of input tensors must match. The result of the
+    divide is truncated towards zero. Expected use is for operations on
+    non-scaled integers. Floating point divide should use RECIPROCAL and MUL.
     Quantized integer divide should use TABLE (for 1/x) and MUL.
   }];
 
@@ -2328,7 +2326,21 @@ def Tosa_RescaleOp : Tosa_InferShapedTypeOp<"rescale"> {
   let summary = "Tosa rescale operator.";
 
   let description = [{
-    Rescale quantized values into a new domain. Supported rescalings are:
+    RESCALE is defined using an integer multiply, add, and shift.
+
+    Rescale supports two precisions of multiplier: 16-bit and 32-bit. The 32-bit multiplier
+    version supports two rounding modes to enable simpler lowering of existing frameworks
+    that use two stage rounding. All arithmetic is designed so that it does not overflow a
+    64-bit accumulator and that the result fits in 32 bits. In particular, a 48-bit value
+    cannot be scaled with the 32-bit multiplier because the accumulator would need to have
+    80 bits.
+
+    The shift and value range are limited to allow a variety of implementations. The limit
+    of 62 on shift allows the shift to be decomposed as two right shifts of 31.
+
+    Supported rescalings:
+    * This table is showing the supported conversions from the TOSA Specification.
+    * The MLIR dialect here can be used to represent other conversions.
 
     | Mode                   | Input | Output | Unsigned input | Unsigned output |
     |------------------------|-------|--------|----------------|-----------------|

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

@@ -86,8 +86,8 @@ def Tosa_VariableOp : Tosa_Op<"variable", []> {
   let summary = "Defines a variable";
 
   let description = [{
-    Defines a new TOSA variable. This is a mutable value.
-    Modifications are expressed using read/write semantics.
+    Defines a new TOSA variable. This is a persistent mutable value across multiple
+    TOSA graph invocations. Modifications are expressed using read/write semantics.
   }];
 
   let arguments = (ins
@@ -115,7 +115,7 @@ def Tosa_VariableWriteOp : Tosa_Op<"variable.write", []> {
   let summary = "write_buffer operator";
 
   let description = [{
-    Assigns a value to pseudo-buffer resource holding a mutable tensor.
+    Assigns a value to the pseudo-buffer resource holding a persistent mutable tensor.
   }];
 
   let arguments = (ins
@@ -140,7 +140,7 @@ def Tosa_VariableReadOp : Tosa_Op<"variable.read", []> {
   let summary = "read_buffer operator";
 
   let description = [{
-    Reads the value from a pseudo-buffer resource holding a mutable tensor.
+    Reads the value from a pseudo-buffer resource holding a persistent mutable tensor.
   }];
 
   let arguments = (ins