Atomic Operation Library

Memory Model

Like the standard library, XWOS atomic operations are divided into 6 memory ordering models:

xwaop_mo_relaxed

Relaxed ordering, no memory barrier operations.

xwaop_mo_consume

Consume ordering, adds a Data dependency barrier between read operations. This barrier is uncommon; for common x86/ARM architectures, Data dependency barrier is handled automatically. To the author’s knowledge, currently only Alpha architecture CPUs require programmer attention to Data dependency barrier. The Rust language does not even provide this memory ordering.

xwaop_mo_acquire

Acquire ordering, often used in conjunction with reads to form load-acquire.

xwaop_mo_release

Release ordering, often used in conjunction with writes to form store-release.

xwaop_mo_acq_rel

Acquire-release ordering: acquire on load and release on store. Typically used for read-modify-write atomic operations.

xwaop_mo_seq_cst

Sequentially consistent ordering, indicating that the CPU’s access order to memory strictly follows the order of the program code (after compilation). This is referred to in journal literature as Sequential Consistency.

Atomic Operations

XWOS provides an atomic operation template library. Various basic types defined in Basic Types can use atomic operations. XWOS’s atomic operation library can be mixed with atomic operations from the standard library <stdatomic.h>.

Atomic operation function templates include:

• Read
  • xwaop_load(): Load
    • Can specify one of 6 memory orderings
  • xwaop_read(): Read
    • Memory order: xwaop_mo_acquire
• Write
  • xwaop_store(): Store
    • Can specify one of 6 memory orderings
  • xwaop_write(): Write
    • Memory order: xwaop_mo_release
• Read-Modify-Write
  • Basic arithmetic
    • xwaop_add(): Add
    • xwaop_sub(): Subtract
    • xwaop_rsb(): Reverse subtract
    • Memory order: xwaop_mo_acq_rel
  • Bitwise operations
    • xwaop_and(): AND
    • xwaop_or(): OR
    • xwaop_xor(): XOR
    • Memory order: xwaop_mo_acq_rel
  • Bit operations
    • xwaop_s1m(): Set all bits in the data mask portion to 1
    • xwaop_c0m(): Clear all bits in the data mask portion to 0
    • xwaop_x1m(): Toggle all bits in the data mask portion
    • Memory order: xwaop_mo_acq_rel
• Read-Test-Modify-Write
  • All functions whose names match the regular expression xwaop_t.+_then_.+
    • Divided into two cases
      • Test succeeds, continue with “modify-write” operation, memory order is xwaop_mo_acq_rel at this point
      • Test fails, equivalent to a read operation, memory order is xwaop_mo_consume at this point

The first parameter of all atomic operation functions is the Basic Type, and the second parameter is the pointer to the atomic data, for example:

xwer_t rc;
xwsq_a refcnt = v;
xwsq_t nv, ov;

/*
 * Test whether refcnt is 0:
 * + true: refcnt increases by 1, nv returns the new value after increment, ov returns the old value before increment,
 *         memory order: acq_rel, rc is the return value XWOK;
 * + false: both nv and ov return the value of refcnt, memory order: consume, rc is the return value -EACCES;
 */
rc = xwaop_teq_then_add(xwsq_t, &refcnt, 0, 1, &nv, &ov);

Bitmap Atomic Operations

Bitmaps (xwbmp_t arrays) can undergo atomic operations. XWOS provides a basic function library:

• Declaration
  • xwbmpaop_define(): Declare an atomic bitmap
• Read
  • xwbmpaop_t1i(): Test whether a certain bit in the bitmap is set to 1
  • Memory order: consume
• Write
  • xwbmpaop_s1all(): Set all bits in the bitmap to 1
  • xwbmpaop_c0all(): Clear all bits in the bitmap to 0
  • Memory order: acq_rel
• Read-Modify-Write
  • xwbmpaop_s1i(): Set a certain bit in the bitmap to 1
  • xwbmpaop_c1i(): Clear a certain bit in the bitmap to 0
  • xwbmpaop_x1i(): Toggle a certain bit in the bitmap
  • Memory order: acq_rel
• Read-Test-Modify-Write
  • All functions whose names match the regular expression xwbmpaop_.+_then_.+
    • xwbmpaop_t0i_then_s1i(): Test whether a certain bit in the bitmap is 0, and if so, set it to 1
    • xwbmpaop_t1i_then_c0i(): Test whether a certain bit in the bitmap is 1, and if so, clear it to 0
    • xwbmpaop_fls_then_c0i(): Find the first bit set to 1 from the most significant bit and clear it to 0
    • xwbmpaop_flz_then_s1i(): Find the first bit set to 0 from the most significant bit and set it to 1
    • xwbmpaop_ffs_then_c0i(): Find the first bit set to 1 from the least significant bit and clear it to 0
    • xwbmpaop_ffz_then_s1i(): Find the first bit set to 0 from the least significant bit and set it to 1
    • Divided into two cases
      • Test succeeds, continue with “modify-write” operation, memory order is xwaop_mo_acq_rel at this point
      • Test fails, equivalent to a read operation, memory order is xwaop_mo_consume at this point

API Reference

• Atomic Operations

  • Header file <xwos/lib/xwaop.h>

• Bitmap Atomic Operations

  • Header file <xwos/lib/xwbmpaop.h>