clarify atomic operation descriptions

Author: bashbaug

api/footnotes.asciidoc

@@ -61,7 +61,7 @@ To create an image object from another image object that share the data store be
 ]
 
 :fn-image-mem-fence: pass:n[ \
-This value for memory_scope can only be used with atomic_work_item_fence with flags set to `CLK_IMAGE_MEM_FENCE`. \
+This value for *memory_scope* can only be used with *atomic_work_item_fence* with flags set to `CLK_IMAGE_MEM_FENCE`. \
 ]
 
 :fn-int64-performance: pass:n[ \

api/opencl_architecture.asciidoc

@@ -1198,10 +1198,10 @@ The precise semantics of synchronization and the memory orders are formally
 defined in <<memory-ordering-rules, Memory Ordering Rules>>.
 Here, we give a high level description of how these memory orders apply to
 atomic operations on atomic objects shared between units of execution.
-OpenCL 2.x memory_order choices are based on those from the ISO C11 standard
+The OpenCL 2.x memory orders are based on those from the ISO C11 standard
 memory model.
 They are specified in certain OpenCL functions through the following
-enumeration constants:
+*memory_order* enumeration constants:
 
   * *memory_order_relaxed*: implies no order constraints.
     This memory order can be used safely to increment counters that are
@@ -1239,13 +1239,13 @@ detailed rules for when synchronisation must occur.
     loads and stores from different units of execution appear to be simply
     interleaved.
 
-Regardless of which memory_order is specified, resolving constraints on
+Regardless of which memory order is specified, resolving constraints on
 memory operations across a heterogeneous platform adds considerable overhead
 to the execution of a program.
 An OpenCL platform may be able to optimize certain operations that depend on
 the features of the memory consistency model by restricting the scope of the
 memory operations.
-Distinct memory scopes are defined by the values of the memory_scope
+Distinct memory scopes are defined by the values of the *memory_scope*
 enumeration constant:
 
   * *memory_scope_work_item*: memory-ordering constraints only apply within
@@ -1319,17 +1319,15 @@ operations_ and _fences_.
 Atomic operations are indivisible.
 They either occur completely or not at all.
 These operations are used to order memory operations between units of
-execution and hence they are parameterized with the memory_order and
-memory_scope parameters defined by the OpenCL memory consistency model.
+execution and hence they are parameterized with the memory order and
+memory scope parameters defined by the OpenCL memory consistency model.
 The atomic operations for OpenCL kernel languages are similar to the
 corresponding operations defined by the C11 standard.
 
 The OpenCL 2.x atomic operations apply to variables of an atomic type (a
-subset of those in the C11 standard) including atomic versions of the int,
-uint, long, ulong, float, double, half, intptr_t, uintptr_t, size_t, and
-ptrdiff_t types.
-However, support for some of these atomic types depends on support for the
-corresponding regular types.
+subset of those in the C11 standard).
+Support for some of the atomic types depends on support for the corresponding
+regular non-atomic types.
 
 An atomic operation on one or more memory locations is either an acquire
 operation, a release operation, or both an acquire and release operation.
@@ -1345,40 +1343,41 @@ The orders *memory_order_acquire* (used for reads), *memory_order_release*
 (used for writes), and *memory_order_acq_rel* (used for read-modify-write
 operations) are used for simple communication between units of execution
 using shared variables.
-Informally, executing a *memory_order_release* on an atomic object A makes
+Informally, executing a *memory_order_release* on an atomic object *A* makes
 all previous side effects visible to any unit of execution that later
-executes a *memory_order_acquire* on A.
+executes a *memory_order_acquire* on *A*.
 The orders *memory_order_acquire*, *memory_order_release*, and
 *memory_order_acq_rel* do not provide sequential consistency for race-free
 programs because they will not ensure that atomic stores followed by atomic
 loads become visible to other threads in that order.
 
 [[atomic-fence-orders]]
-The fence operation is atomic_work_item_fence, which includes a memory_order
-argument as well as the memory_scope and cl_mem_fence_flags arguments.
-Depending on the memory_order argument, this operation:
-
-  * has no effects, if *memory_order_relaxed*;
-  * is an acquire fence, if *memory_order_acquire*;
-  * is a release fence, if *memory_order_release*;
-  * is both an acquire fence and a release fence, if *memory_order_acq_rel*;
+The fence operation is *atomic_work_item_fence*, which includes a memory order
+argument as well as memory scope and memory flag arguments.
+Depending on the memory order argument, this operation:
+
+  * has no effects, if the memory order is *memory_order_relaxed*;
+  * is an acquire fence, if the memory order is *memory_order_acquire*;
+  * is a release fence, if the memory order is *memory_order_release*;
+  * is both an acquire fence and a release fence, if the memory order is
+  *memory_order_acq_rel*;
   * is a sequentially-consistent fence with both acquire and release
-    semantics, if *memory_order_seq_cst*.
+    semantics, if the memory order is *memory_order_seq_cst*.
 
 If specified, the cl_mem_fence_flags argument must be `CLK_IMAGE_MEM_FENCE`,
 `CLK_GLOBAL_MEM_FENCE`, `CLK_LOCAL_MEM_FENCE`, or `CLK_GLOBAL_MEM_FENCE |
 CLK_LOCAL_MEM_FENCE`.
 
-The `atomic_work_item_fence(CLK_IMAGE_MEM_FENCE, ...)` built-in function must be
-used to make sure that sampler-less writes are visible to later reads by the
-same work-item.
-Without use of the atomic_work_item_fence function, write-read coherence on
+The *atomic_work_item_fence* built-in function must be used with
+`CLK_IMAGE_MEM_FENCE` to make sure that sampler-less writes are visible to later
+reads by the same work-item.
+Without use of the *atomic_work_item_fence* function, write-read coherence on
 image objects is not guaranteed: if a work-item reads from an image to which
-it has previously written without an intervening atomic_work_item_fence, it
+it has previously written without an intervening *atomic_work_item_fence*, it
 is not guaranteed that those previous writes are visible to the work-item.
 
 The synchronization operations in OpenCL 2.x can be parameterized by a
-memory_scope.
+memory scope.
 Memory scopes control the extent that an atomic operation or fence is
 visible with respect to the memory model.
 These memory scopes may be used when performing atomic operations and fences
@@ -1595,10 +1594,10 @@ C code and the host program contribute to the local- and
 global-happens-before relations.
 This section discusses ordering rules for OpenCL 2.x atomic operations.
 
-<<device-side-enqueue, Device-side enqueue>> defines the enumerated type
-memory_order.
+The <<memory-consistency-model>> section defines the enumerated type
+*memory_order*.
 
-  * For *memory_order_relaxed*, no operation orders memory.
+  * For *memory_order_relaxed*, there is no memory ordering.
   * For *memory_order_release*, *memory_order_acq_rel*, and
     *memory_order_seq_cst*, a store operation performs a release operation
     on the affected memory location.
@@ -1752,7 +1751,7 @@ This section describes how the OpenCL 2.x fence operations contribute to the
 local- and global-happens-before relations.
 
 Earlier, we introduced synchronization primitives called fences.
-Fences can utilize the acquire memory_order, release memory_order, or both.
+Fences can utilize the acquire memory order, release memory order, or both.
 A fence with acquire semantics is called an acquire fence; a fence with
 release semantics is called a release fence.  The <<atomic-fence-orders,
 overview of atomic and fence operations>> section describes the memory orders