Skip to content

Commit

Permalink
Update comments/docs
Browse files Browse the repository at this point in the history
  • Loading branch information
taiki-e committed Oct 19, 2024
1 parent f647cca commit 33b6cb5
Show file tree
Hide file tree
Showing 6 changed files with 15 additions and 8 deletions.
10 changes: 7 additions & 3 deletions DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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
```

Expand Down
2 changes: 1 addition & 1 deletion portable-atomic-util/src/arc.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion src/imp/atomic128/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |

Expand Down
2 changes: 1 addition & 1 deletion src/imp/atomic64/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
6 changes: 4 additions & 2 deletions src/imp/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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)),
Expand Down Expand Up @@ -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),
Expand Down
1 change: 1 addition & 0 deletions src/imp/riscv.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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") => {
Expand Down

0 comments on commit 33b6cb5

Please sign in to comment.