Update comments/docs

DEVELOPMENT.md

@@ -14,14 +14,15 @@ portable-atomic/
 ├── version.rs                    -- rustc version detection code used by build script
 ├── portable-atomic-util/         -- crate that defines synchronization primitives built with portable-atomic
 ├── src/
+│   ├── cfgs.rs                   -- definitions of cfg_{has,no}_* macros
 │   ├── imp/
 │   │   ├── atomic128/            -- 128-bit atomic implementations on 64-bit architectures (mainly by asm)
 │   │   ├── atomic64/             -- 64-bit atomic implementations on 32-bit architectures (mainly by asm)
 │   │   ├── core_atomic.rs        -- wrapper for core::sync::atomic types
 │   │   ├── detect/               -- Run-time CPU feature detection implementations used for outline-atomics
 │   │   ├── fallback/             -- fallback implementation based on global locks
 │   │   ├── float.rs              -- atomic float implementation based on atomic integer
-│   │   ├── interrupt/            -- fallback implementation based on disabling interrupts (for no-std)
+│   │   ├── interrupt/            -- fallback implementation based on disabling interrupts or critical-section (for no-std)
 │   │   ├── msp430.rs             -- atomic implementation for MSP430 (by asm)
 │   │   ├── riscv.rs              -- atomic implementation for RISC-V without A-extension (by asm)
 │   │   └── x86.rs                -- atomic implementation for x86/x86_64 (by asm)
@@ -31,8 +32,11 @@ portable-atomic/
 ├── target-specs/                 -- specs of custom targets used for tests
 ├── tests/
 │   ├── api-test/                 -- API check
-│   ├── {avr,gba,no-std-qemu}/    -- tests for no-std targets
-│   └── helper/                   -- test helpers
+│   ├── avr/                      -- tests for no-std AVR targets
+│   ├── gba/                      -- tests for no-std Armv4T targets
+│   ├── msp430/                   -- tests for no-std MSP430 targets
+│   ├── no-std-qemu/              -- tests for no-std Cortex-M/Armv5TE/RISC-V targets
+│   └── xtensa/                   -- tests for no-std Xtensa targets
 └── tools/                        -- tools for CI and/or development
 ```
 

portable-atomic-util/src/arc.rs

@@ -2233,7 +2233,7 @@ impl<T> Default for Arc<[T]> {
     /// This may or may not share an allocation with other Arcs.
     #[inline]
     fn default() -> Self {
-        // TODO: we cannot use non-allocation optimization (https://github.com/rust-lang/rust/blob/893f95f1f7c663c67c884120003b3bf21b0af61a/library/alloc/src/sync.rs#L3452-L3463)
+        // TODO: we cannot use non-allocation optimization (https://github.com/rust-lang/rust/blob/1.80.0/library/alloc/src/sync.rs#L3449)
         // for now due to casting Arc<[T; N]> -> Arc<[T]> requires unstable CoerceUnsized.
         let arr: [T; 0] = [];
         Arc::from(arr)

src/imp/atomic128/README.md

@@ -10,7 +10,7 @@ Here is the table of targets that support 128-bit atomics and the instructions u
 | ----------- | ---- | ----- | --- | --- | ---- |
 | x86_64 | cmpxchg16b or vmovdqa | cmpxchg16b or vmovdqa | cmpxchg16b | cmpxchg16b | cmpxchg16b target feature required. vmovdqa requires Intel, AMD, or Zhaoxin CPU with AVX. <br> Both compile-time and run-time detection are supported for cmpxchg16b. vmovdqa is currently run-time detection only. <br> Requires rustc 1.59+ |
 | aarch64/arm64ec | ldxp/stxp or casp or ldp/ldiapp | ldxp/stxp or casp or stp/stilp/swpp | ldxp/stxp or casp | ldxp/stxp or casp/swpp/ldclrp/ldsetp | casp requires lse target feature, ldp/stp requires lse2 target feature, ldiapp/stilp requires lse2 and rcpc3 target features, swpp/ldclrp/ldsetp requires lse128 target feature. <br> Both compile-time and run-time detection are supported. <br> Requires rustc 1.59+ (aarch64) / nightly (arm64ec) |
-| riscv64 | amocas.q | amocas.q | amocas.q | amocas.q | Experimental because LLVM marking the corresponding target feature as experimental. Requires experimental-zacas target feature. Both compile-time and run-time detection are supported (run-time detection is currently disabled by default). <br> Requires 1.82+ (LLVM 19+) |
+| riscv64 | amocas.q | amocas.q | amocas.q | amocas.q | Experimental because LLVM marking the corresponding target feature as experimental. Requires experimental-zacas target feature. Both compile-time and run-time detection are supported (run-time detection is currently disabled by default). <br> Requires rustc 1.82+ (LLVM 19+) |
 | powerpc64 | lq | stq | lqarx/stqcx. | lqarx/stqcx. | Requires target-cpu pwr8+ (powerpc64le is pwr8 by default). Both compile-time and run-time detection are supported (run-time detection is currently disabled by default). <br> Requires nightly |
 | s390x | lpq | stpq | cdsg | cdsg | Requires nightly |
 

src/imp/atomic64/README.md

@@ -10,7 +10,7 @@ Here is the table of targets that support 64-bit atomics and the instructions us
 | ----------- | ---- | ----- | --- | --- | ---- |
 | x86 | cmpxchg8b or fild or movlps or movq | cmpxchg8b or fistp or movlps | cmpxchg8b | cmpxchg8b | provided by `core::sync::atomic` |
 | arm | ldrexd | ldrexd/strexd | ldrexd/strexd | ldrexd/strexd | provided by `core::sync::atomic` for Armv6+, otherwise provided by us for Linux/Android using kuser_cmpxchg64 (see [arm_linux.rs](arm_linux.rs) for more) |
-| riscv32 | amocas.d | amocas.d | amocas.d | amocas.d | Experimental because LLVM marking the corresponding target feature as experimental. Requires experimental-zacas target feature. Both compile-time and run-time detection are supported (run-time detection is currently disabled by default). <br> Requires 1.82+ (LLVM 19+) |
+| riscv32 | amocas.d | amocas.d | amocas.d | amocas.d | Experimental because LLVM marking the corresponding target feature as experimental. Requires experimental-zacas target feature. Both compile-time and run-time detection are supported (run-time detection is currently disabled by default). <br> Requires rustc 1.82+ (LLVM 19+) |
 
 If `core::sync::atomic` provides 64-bit atomics, we use them.
 On compiler versions or platforms where these are not supported, the fallback implementation is used.

src/imp/mod.rs

@@ -163,6 +163,7 @@ pub(crate) mod float;
 
 // -----------------------------------------------------------------------------
 
+// has CAS | (has core atomic & !(avr | msp430 | critical section)) => core atomic
 #[cfg(not(any(
     portable_atomic_no_atomic_load_store,
     target_arch = "avr",
@@ -213,7 +214,7 @@ items! {
     )]
     pub(crate) use self::core_atomic::{AtomicI64, AtomicU64};
 }
-// bpf
+// bpf & !(critical section) => core atomic
 #[cfg(all(
     target_arch = "bpf",
     portable_atomic_no_atomic_load_store,
@@ -381,6 +382,7 @@ items! {
 #[cfg_attr(portable_atomic_no_cfg_target_has_atomic, cfg(portable_atomic_no_atomic_64))]
 #[cfg_attr(not(portable_atomic_no_cfg_target_has_atomic), cfg(not(target_has_atomic = "64")))]
 pub(crate) use self::atomic64::arm_linux::{AtomicI64, AtomicU64};
+// riscv32 & (zacas | outline-atomics)
 #[cfg(all(
     target_arch = "riscv32",
     not(any(miri, portable_atomic_sanitize_thread)),
@@ -422,7 +424,7 @@ pub(crate) use self::atomic128::aarch64::{AtomicI128, AtomicU128};
     ),
 ))]
 pub(crate) use self::atomic128::x86_64::{AtomicI128, AtomicU128};
-// riscv64 & zacas
+// riscv64 & (zacas | outline-atomics)
 #[cfg(all(
     target_arch = "riscv64",
     not(portable_atomic_no_asm),

src/imp/riscv.rs

@@ -67,6 +67,7 @@ macro_rules! w {
 ))]
 macro_rules! atomic_rmw_amo_ext {
     ("w") => {
+        // Use +a also for zaamo because `option arch +zaamo` requires LLVM 19 https://github.com/llvm/llvm-project/commit/8be079cdddfd628d356d9ddb5ab397ea95fb1030
         "+a"
     };
     ("d") => {