From 59508d46a699675da1b50fa4e2ee34980ba01e6c Mon Sep 17 00:00:00 2001
From: Kevin Bracey <kevin.bracey@arm.com>
Date: Tue, 28 Nov 2017 14:02:28 +0200
Subject: [PATCH] Explicitly note that CAS is strong in docs

Add a note to each CAS making explicit that the functions are strong.

Minor wording change to expectedCurrentValue - use of "still updated"
about the failure case suggested that it might be written to on success.
For some uses it's critically important that expectedCurrentValue only
be written on failure, so change wording to "instead updated".
---
 platform/mbed_critical.h | 24 ++++++++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)

diff --git a/platform/mbed_critical.h b/platform/mbed_critical.h
index 0b7cb2a8b1..c1c5689889 100644
--- a/platform/mbed_critical.h
+++ b/platform/mbed_critical.h
@@ -121,7 +121,7 @@ void core_util_critical_section_exit(void);
  * }
  *
  * @note: In the failure case (where the destination isn't set), the value
- * pointed to by expectedCurrentValue is still updated with the current value.
+ * pointed to by expectedCurrentValue is instead updated with the current value.
  * This property helps writing concise code for the following incr:
  *
  * function incr(p : pointer to int, a : int) returns int {
@@ -132,6 +132,10 @@ void core_util_critical_section_exit(void);
  *     }
  *     return value + a
  * }
+ *
+ * @note: This corresponds to the C11 "atomic_compare_exchange_strong" - it
+ * always succeeds if the current value is expected, as per the pseudocode
+ * above; it will not spuriously fail as "atomic_compare_exchange_weak" may.
  */
 bool core_util_atomic_cas_u8(uint8_t *ptr, uint8_t *expectedCurrentValue, uint8_t desiredValue);
 
@@ -174,7 +178,7 @@ bool core_util_atomic_cas_u8(uint8_t *ptr, uint8_t *expectedCurrentValue, uint8_
  * }
  *
  * @note: In the failure case (where the destination isn't set), the value
- * pointed to by expectedCurrentValue is still updated with the current value.
+ * pointed to by expectedCurrentValue is instead updated with the current value.
  * This property helps writing concise code for the following incr:
  *
  * function incr(p : pointer to int, a : int) returns int {
@@ -185,6 +189,10 @@ bool core_util_atomic_cas_u8(uint8_t *ptr, uint8_t *expectedCurrentValue, uint8_
  *     }
  *     return value + a
  * }
+ *
+ * @note: This corresponds to the C11 "atomic_compare_exchange_strong" - it
+ * always succeeds if the current value is expected, as per the pseudocode
+ * above; it will not spuriously fail as "atomic_compare_exchange_weak" may.
  */
 bool core_util_atomic_cas_u16(uint16_t *ptr, uint16_t *expectedCurrentValue, uint16_t desiredValue);
 
@@ -227,7 +235,7 @@ bool core_util_atomic_cas_u16(uint16_t *ptr, uint16_t *expectedCurrentValue, uin
  * }
  *
  * @note: In the failure case (where the destination isn't set), the value
- * pointed to by expectedCurrentValue is still updated with the current value.
+ * pointed to by expectedCurrentValue is instead updated with the current value.
  * This property helps writing concise code for the following incr:
  *
  * function incr(p : pointer to int, a : int) returns int {
@@ -237,6 +245,10 @@ bool core_util_atomic_cas_u16(uint16_t *ptr, uint16_t *expectedCurrentValue, uin
  *         done = atomic_cas(p, &value, value + a) // *value gets updated automatically until success
  *     }
  *     return value + a
+ *
+ * @note: This corresponds to the C11 "atomic_compare_exchange_strong" - it
+ * always succeeds if the current value is expected, as per the pseudocode
+ * above; it will not spuriously fail as "atomic_compare_exchange_weak" may.
  * }
  */
 bool core_util_atomic_cas_u32(uint32_t *ptr, uint32_t *expectedCurrentValue, uint32_t desiredValue);
@@ -280,7 +292,7 @@ bool core_util_atomic_cas_u32(uint32_t *ptr, uint32_t *expectedCurrentValue, uin
  * }
  *
  * @note: In the failure case (where the destination isn't set), the value
- * pointed to by expectedCurrentValue is still updated with the current value.
+ * pointed to by expectedCurrentValue is instead updated with the current value.
  * This property helps writing concise code for the following incr:
  *
  * function incr(p : pointer to int, a : int) returns int {
@@ -291,6 +303,10 @@ bool core_util_atomic_cas_u32(uint32_t *ptr, uint32_t *expectedCurrentValue, uin
  *     }
  *     return value + a
  * }
+ *
+ * @note: This corresponds to the C11 "atomic_compare_exchange_strong" - it
+ * always succeeds if the current value is expected, as per the pseudocode
+ * above; it will not spuriously fail as "atomic_compare_exchange_weak" may.
  */
 bool core_util_atomic_cas_ptr(void **ptr, void **expectedCurrentValue, void *desiredValue);