[NFC][mlir][OpenMP] Added documentation for omp.atomic ops

[shraiysh]

Summary

This patch adds the documentation for the operations omp.atomic.read,
omp.atomic.write and omp.atomic.update.

[peixin]

LGTM with several nits.

mlir/include/mlir/Dialect/OpenMP/OpenMPOps.td

583

Please remove "according to the OpenMP Standard". All the materials in this file follow the OpenMP standard. No need to emphasize the point. Also for the following.

610

typo: read -> write.

668

exactly same -> exactly the same?

[shraiysh]

Addressed comments. Thanks for the review!

[NimishMishra]

@shraiysh Thanks for the patch. A few nits.

mlir/include/mlir/Dialect/OpenMP/OpenMPOps.td

593

Same here. Please check the following statement from OpenMP 5.0 specification

"If atomic-clause is read then memory-order-clause must not be acq_rel or release"

621

According to OpenMP 5.0 spec, I have noticed the following restriction

"If atomic-clause is write then memory-order-clause must not be acq_rel or acquire."

Can you please check this once?

[shraiysh]

As this has been merged already, I will change those specific points in a separate patch.

mlir/include/mlir/Dialect/OpenMP/OpenMPOps.td

 // In the OpenMP Specification, atomic construct has an `atomic-clause` which
 // can take the values `read`, `write`, `update` and `capture`. These four
 // kinds of atomic constructs are fundamentally independent and are handled
 // separately while lowering. Having four separate operations (one for each
 // value of the clause) here decomposes handling of this construct into a
 // two-step process.
 
 def AtomicReadOp : OpenMP_Op<"atomic.read"> {
+
+  let summary = "performs an atomic read";
+
+  let description = [{
+    This operation performs an atomic read.
+
+    The operand `address` is the address from where the value is atomically
+    read.
+
+    `hint` is the value of hint (as specified in the hint clause). It is a
+    compile time constant. As the name suggests, this is just a hint for
+    optimization.
+
+    `memory_order` indicates the memory ordering behavior of the construct. It
+    can be one of `seq_cst`, `acq_rel`, `release`, `acquire` or `relaxed`.
+  }];
+
   let arguments = (ins OpenMP_PointerLikeType:$address,
                        DefaultValuedAttr<I64Attr, "0">:$hint,
                        OptionalAttr<MemoryOrderKind>:$memory_order);
   let results = (outs AnyType);
   let parser = [{ return parseAtomicReadOp(parser, result); }];
   let printer = [{ return printAtomicReadOp(p, *this); }];
   let verifier = [{ return verifyAtomicReadOp(*this); }];
 }
 
 def AtomicWriteOp : OpenMP_Op<"atomic.write"> {
+
+  let summary = "performs an atomic write";
+
+  let description = [{
+    This operation performs an atomic write.
+
+    The operand `address` is the address to where the `value` is atomically
+    written w.r.t. multiple threads. The evaluation of `value` need not be
+    atomic w.r.t. the write to address. In general, the type(address) must
+    dereference to type(value).
+
+    `hint` is the value of hint (as specified in the hint clause). It is a
+    compile time constant. As the name suggests, this is just a hint for
+    optimization.
+
+    `memory_order` indicates the memory ordering behavior of the construct. It
+    can be one of `seq_cst`, `acq_rel`, `release`, `acquire` or `relaxed`.
+  }];
+
   let arguments = (ins OpenMP_PointerLikeType:$address,
                        AnyType:$value,
                        DefaultValuedAttr<I64Attr, "0">:$hint,
                        OptionalAttr<MemoryOrderKind>:$memory_order);
   let parser = [{ return parseAtomicWriteOp(parser, result); }];
   let printer = [{ return printAtomicWriteOp(p, *this); }];
   let verifier = [{ return verifyAtomicWriteOp(*this); }];
 }
def AtomicBinOpKindAttr : I64EnumAttr<
      ATOMIC_BINOP_KIND_SHIFT_LEFT, ATOMIC_BINOP_KIND_MAX,
      ATOMIC_BINOP_KIND_MIN, ATOMIC_BINOP_KIND_EQV, ATOMIC_BINOP_KIND_NEQV]> {
   let cppNamespace = "::mlir::omp";
   let stringToSymbolFnName = "AtomicBinOpKindToEnum";
   let symbolToStringFnName = "AtomicBinOpKindToString";
 }
 
 def AtomicUpdateOp : OpenMP_Op<"atomic.update"> {
+
+  let summary = "performs an atomic update";
+
+  let description = [{
+    This operation performs an atomic update.
+
+    The operands `x` and `expr` are exactly the same as the operands `x` and
+    `expr` in the OpenMP Standard. The operand `x` is the address of the
+    variable that is being updated. `x` is atomically read/written. The
+    evaluation of `expr` need not be atomic w.r.t the read or write of the
+    location designated by `x`. In general, type(x) must dereference to
+    type(expr).
+
+    The attribute `isXBinopExpr` is
+      - true when the expression is of the form `x binop expr` on RHS
+      - false when the expression is of the form `expr binop x` on RHS
+
+    The attribute `binop` is the binary operation being performed atomically.
+
+    `hint` is the value of hint (as used in the hint clause). It is a compile
+    time constant. As the name suggests, this is just a hint for optimization.
+
+    `memory_order` indicates the memory ordering behavior of the construct. It
+    can be one of `seq_cst`, `acq_rel`, `release`, `acquire` or `relaxed`.
+  }];
+
   let arguments = (ins OpenMP_PointerLikeType:$x,
                        AnyType:$expr,
                        UnitAttr:$isXBinopExpr,
                        AtomicBinOpKindAttr:$binop,
                        DefaultValuedAttr<I64Attr, "0">:$hint,
                        OptionalAttr<MemoryOrderKind>:$memory_order);
   let parser = [{ return parseAtomicUpdateOp(parser, result); }];
   let printer = [{ return printAtomicUpdateOp(p, *this); }];