--- a/hotspot/src/share/vm/runtime/atomic.hpp	Wed Jul 09 22:37:48 2014 -0400
+++ b/hotspot/src/share/vm/runtime/atomic.hpp	Thu Jul 10 08:15:30 2014 -0700
@@ -35,6 +35,18 @@
   // can provide an alternative action if not - see supports_cx8() for
   // a means to test availability.
 
+  // The memory operations that are mentioned with each of the atomic
+  // function families come from src/share/vm/runtime/orderAccess.hpp,
+  // e.g., <fence> is described in that file and is implemented by the
+  // OrderAccess::fence() function. See that file for the gory details
+  // on the Memory Access Ordering Model.
+
+  // All of the atomic operations that imply a read-modify-write action
+  // guarantee a two-way memory barrier across that operation. Historically
+  // these semantics reflect the strength of atomic operations that are
+  // provided on SPARC/X86. We assume that strength is necessary unless
+  // we can prove that a weaker form is sufficiently safe.
+
   // Atomically store to a location
   inline static void store    (jbyte    store_value, jbyte*    dest);
   inline static void store    (jshort   store_value, jshort*   dest);
@@ -55,7 +67,8 @@
   // See comment above about using jlong atomics on 32-bit platforms
   inline static jlong load(volatile jlong* src);
 
-  // Atomically add to a location, return updated value
+  // Atomically add to a location. Returns updated value. add*() provide:
+  // <fence> add-value-to-dest <membar StoreLoad|StoreStore>
   inline static jint     add    (jint     add_value, volatile jint*     dest);
   inline static size_t   add    (size_t   add_value, volatile size_t*   dest);
   inline static intptr_t add_ptr(intptr_t add_value, volatile intptr_t* dest);
@@ -63,30 +76,35 @@
   // See comment above about using jlong atomics on 32-bit platforms
          static jlong    add    (jlong    add_value, volatile jlong*    dest);
 
-  // Atomically increment location
+  // Atomically increment location. inc*() provide:
+  // <fence> increment-dest <membar StoreLoad|StoreStore>
   inline static void inc    (volatile jint*     dest);
          static void inc    (volatile jshort*   dest);
   inline static void inc    (volatile size_t*   dest);
   inline static void inc_ptr(volatile intptr_t* dest);
   inline static void inc_ptr(volatile void*     dest);
 
-  // Atomically decrement a location
+  // Atomically decrement a location. dec*() provide:
+  // <fence> decrement-dest <membar StoreLoad|StoreStore>
   inline static void dec    (volatile jint*     dest);
          static void dec    (volatile jshort*    dest);
   inline static void dec    (volatile size_t*   dest);
   inline static void dec_ptr(volatile intptr_t* dest);
   inline static void dec_ptr(volatile void*     dest);
 
-  // Performs atomic exchange of *dest with exchange_value.  Returns old prior value of *dest.
+  // Performs atomic exchange of *dest with exchange_value. Returns old
+  // prior value of *dest. xchg*() provide:
+  // <fence> exchange-value-with-dest <membar StoreLoad|StoreStore>
   inline static jint         xchg(jint         exchange_value, volatile jint*         dest);
          static unsigned int xchg(unsigned int exchange_value, volatile unsigned int* dest);
 
   inline static intptr_t xchg_ptr(intptr_t exchange_value, volatile intptr_t* dest);
   inline static void*    xchg_ptr(void*    exchange_value, volatile void*   dest);
 
-  // Performs atomic compare of *dest and compare_value, and exchanges *dest with exchange_value
-  // if the comparison succeeded.  Returns prior value of *dest.  Guarantees a two-way memory
-  // barrier across the cmpxchg.  I.e., it's really a 'fence_cmpxchg_acquire'.
+  // Performs atomic compare of *dest and compare_value, and exchanges
+  // *dest with exchange_value if the comparison succeeded. Returns prior
+  // value of *dest. cmpxchg*() provide:
+  // <fence> compare-and-exchange <membar StoreLoad|StoreStore>
          static jbyte    cmpxchg    (jbyte    exchange_value, volatile jbyte*    dest, jbyte    compare_value);
   inline static jint     cmpxchg    (jint     exchange_value, volatile jint*     dest, jint     compare_value);
   // See comment above about using jlong atomics on 32-bit platforms