Update comments

taiki-e · Sep 19, 2024 · 563a4d4 · 563a4d4
1 parent 26d6f23
commit 563a4d4
Show file tree

Hide file tree

Showing 12 changed files with 55 additions and 39 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -83,20 +83,20 @@ jobs:
         # - LLVM 19 : stable 1.82 -     , nightly-2024-08-01 (1.82) -
         # (see also https://github.com/rust-lang/rust/commits/master/src/llvm-project)
         # Minimum external LLVM version table:
-        # - LLVM 3.5: stable 1.8  - 1.22, ?                        - ?
-        # - LLVM 3.9: stable 1.23 - 1.28, ?                        - ?
-        # - LLVM 5  : stable 1.29 - 1.32, ?                        - ?
-        # - LLVM 6  : stable 1.33 - 1.40, ?                        - ?
-        # - LLVM 7  : stable 1.41 - 1.43, ?                        - ?
-        # - LLVM 8  : stable 1.44 - 1.49, ?                        - ?
-        # - LLVM 9  : stable 1.50 - 1.52, ?                        - ?
-        # - LLVM 10 : stable 1.53 - 1.57, ?                        - ?
-        # - LLVM 12 : stable 1.58 - 1.64, ?                        - ?
-        # - LLVM 13 : stable 1.65 - 1.68, ?                        - ?
-        # - LLVM 14 : stable 1.69 - 1.72, ?                        - ?
-        # - LLVM 15 : stable 1.73 - 1.75, ?                        - ?
-        # - LLVM 16 : stable 1.76 - 1.78, ?                        - ?
-        # - LLVM 17 : stable 1.79 -     , ?                        -
+        # - LLVM 3.9: stable 1.23 - 1.28, https://github.com/rust-lang/rust/pull/45326
+        # - LLVM 5  : stable 1.29 - 1.32, https://github.com/rust-lang/rust/pull/51899
+        # - LLVM 6  : stable 1.33 - 1.40, https://github.com/rust-lang/rust/pull/56642
+        # - LLVM 7  : stable 1.41 - 1.43, https://github.com/rust-lang/rust/pull/66973
+        # - LLVM 8  : stable 1.44 - 1.49, https://github.com/rust-lang/rust/pull/71147
+        # - LLVM 9  : stable 1.50 - 1.52, https://github.com/rust-lang/rust/pull/78848
+        # - LLVM 10 : stable 1.53 - 1.57, https://github.com/rust-lang/rust/pull/83387
+        # - LLVM 12 : stable 1.58 - 1.64, https://github.com/rust-lang/rust/pull/90175
+        # - LLVM 13 : stable 1.65 - 1.68, https://github.com/rust-lang/rust/pull/100460
+        # - LLVM 14 : stable 1.69 - 1.72, https://github.com/rust-lang/rust/pull/107573
+        # - LLVM 15 : stable 1.73 - 1.75, https://github.com/rust-lang/rust/pull/114148
+        # - LLVM 16 : stable 1.76 - 1.78, https://github.com/rust-lang/rust/pull/117947
+        # - LLVM 17 : stable 1.79 - 1.82, https://github.com/rust-lang/rust/pull/122649
+        # - LLVM 18 : stable 1.83 -     , https://github.com/rust-lang/rust/pull/130487
         include:
           - rust: '1.56'
           - rust: nightly-2021-08-21 # Rust 1.56, LLVM 12

diff --git a/src/imp/atomic128/aarch64.rs b/src/imp/atomic128/aarch64.rs
@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
 /*
-Atomic{I,U}128 implementation on AArch64.
+128-bit atomic implementation on AArch64.
 
 There are a few ways to implement 128-bit atomic operations in AArch64.
 
@@ -1607,10 +1607,7 @@ unsafe fn _atomic_swap_swpp(dst: *mut u128, val: u128, order: Ordering) -> u128
         macro_rules! swap {
             ($order:tt, $fence:tt) => {
                 asm!(
-                    // 4: 19218002     	swpp	x2, x1, [x0]
-                    // 4: 19a18002     	swppa	x2, x1, [x0]
-                    // 4: 19618002     	swppl	x2, x1, [x0]
-                    // 4: 19e18002     	swppal	x2, x1, [x0]
+                    // 4: 19{2,a,6,e}18002     	swpp{,a,l,al}	x2, x1, [x0]
                     concat!(".inst 0x19", $order, "18002"),
                     $fence,
                     in("x0") ptr_reg!(dst),
@@ -2031,10 +2028,7 @@ unsafe fn atomic_and(dst: *mut u128, val: u128, order: Ordering) -> u128 {
         macro_rules! clear {
             ($order:tt, $fence:tt) => {
                 asm!(
-                    // 8: 19211008     	ldclrp	x8, x1, [x0]
-                    // 8: 19a11008     	ldclrpa	x8, x1, [x0]
-                    // 8: 19611008     	ldclrpl	x8, x1, [x0]
-                    // 8: 19e11008     	ldclrpal	x8, x1, [x0]
+                    // 8: 19{2,a,6,e}11008     	ldclrp{,a,l,al}	x8, x1, [x0]
                     concat!(".inst 0x19", $order, "11008"),
                     $fence,
                     in("x0") ptr_reg!(dst),
@@ -2112,10 +2106,7 @@ unsafe fn atomic_or(dst: *mut u128, val: u128, order: Ordering) -> u128 {
         macro_rules! or {
             ($order:tt, $fence:tt) => {
                 asm!(
-                    // 4: 19213002     	ldsetp	x2, x1, [x0]
-                    // 4: 19a13002     	ldsetpa	x2, x1, [x0]
-                    // 4: 19613002     	ldsetpl	x2, x1, [x0]
-                    // 4: 19e13002     	ldsetpal	x2, x1, [x0]
+                    // 4: 19{2,a,6,e}13002     	ldsetp{,a,l,al}	x2, x1, [x0]
                     concat!(".inst 0x19", $order, "13002"),
                     $fence,
                     in("x0") ptr_reg!(dst),

diff --git a/src/imp/atomic128/intrinsics.rs b/src/imp/atomic128/intrinsics.rs
@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
 /*
-Atomic{I,U}128 implementation without inline assembly.
+128-bit atomic implementation without inline assembly.
 
 Adapted from https://github.com/rust-lang/rust/blob/1.80.0/library/core/src/sync/atomic.rs.
 

diff --git a/src/imp/atomic128/powerpc64.rs b/src/imp/atomic128/powerpc64.rs
@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
 /*
-Atomic{I,U}128 implementation on PowerPC64.
+128-bit atomic implementation on PowerPC64.
 
 powerpc64 on pwr8+ support 128-bit atomics (load/store/LL/SC):
 https://github.com/llvm/llvm-project/commit/549e118e93c666914a1045fde38a2cac33e1e445

diff --git a/src/imp/atomic128/riscv64.rs b/src/imp/atomic128/riscv64.rs
@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
 /*
-Atomic{I,U}128 implementation on riscv64 using amocas.q (DWCAS).
+128-bit atomic implementation on riscv64 using amocas.q (DWCAS).
 
 Note: On Miri and ThreadSanitizer which do not support inline assembly, we don't use
 this module and use intrinsics.rs instead.

diff --git a/src/imp/atomic128/s390x.rs b/src/imp/atomic128/s390x.rs
@@ -1,13 +1,15 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
 /*
-Atomic{I,U}128 implementation on s390x.
+128-bit atomic implementation on s390x.
 
 s390x has 128-bit atomic load/store/CAS instructions and other operations are emulated by CAS loop.
 https://github.com/llvm/llvm-project/commit/a11f63a952664f700f076fd754476a2b9eb158cc
 https://github.com/llvm/llvm-project/commit/c568927f3e2e7d9804ea74ecbf11c16c014ddcbc
 
-LLVM's minimal supported architecture level is z10:
+128-bit atomic instructions (lpq,stpq,cdsg) has been present since
+[the First Edition of the Principles of Operation](https://publibfp.dhe.ibm.com/epubs/pdf/dz9zr000.pdf).
+LLVM's minimal supported architecture level is z10 (the Eighth Edition of the PoP):
 https://github.com/llvm/llvm-project/blob/llvmorg-19.1.0/llvm/lib/Target/SystemZ/SystemZProcessors.td#L16-L17
 This does not appear to have changed since the current s390x backend was added in LLVM 3.3:
 https://github.com/llvm/llvm-project/commit/5f613dfd1f7edb0ae95d521b7107b582d9df5103#diff-cbaef692b3958312e80fd5507a7e2aff071f1acb086f10e8a96bc06a7bb289db

diff --git a/src/imp/atomic128/x86_64.rs b/src/imp/atomic128/x86_64.rs
@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
 /*
-Atomic{I,U}128 implementation on x86_64 using CMPXCHG16B (DWCAS).
+128-bit atomic implementation on x86_64 using CMPXCHG16B (DWCAS).
 
 Note: On Miri and ThreadSanitizer which do not support inline assembly, we don't use
 this module and use intrinsics.rs instead.

diff --git a/src/imp/atomic64/arm_linux.rs b/src/imp/atomic64/arm_linux.rs
@@ -39,8 +39,9 @@ fn __kuser_helper_version() -> i32 {
     if v != 0 {
         return v;
     }
-    // SAFETY: core assumes that at least __kuser_memory_barrier (__kuser_helper_version >= 3) is
-    // available on this platform. __kuser_helper_version is always available on such a platform.
+    // SAFETY: core assumes that at least __kuser_memory_barrier (__kuser_helper_version >= 3,
+    // kernel version 2.6.15+) is available on this platform. __kuser_helper_version
+    // is always available on such a platform.
     v = unsafe { (KUSER_HELPER_VERSION as *const i32).read() };
     CACHE.store(v, Ordering::Relaxed);
     v

diff --git a/src/imp/atomic64/riscv32.rs b/src/imp/atomic64/riscv32.rs
@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
 /*
-Atomic{I,U}64 implementation on riscv32 using amocas.d (DWCAS).
+64-bit atomic implementation on riscv32 using amocas.d (DWCAS).
 
 Note: On Miri and ThreadSanitizer which do not support inline assembly, we don't use
 this module and use fallback implementation instead.

diff --git a/src/imp/detect/aarch64_fuchsia.rs b/src/imp/detect/aarch64_fuchsia.rs
@@ -7,7 +7,7 @@ As of nightly-2024-09-07, is_aarch64_feature_detected doesn't support run-time d
 https://github.com/rust-lang/stdarch/blob/d9466edb4c53cece8686ee6e17b028436ddf4151/crates/std_detect/src/detect/mod.rs
 
 Refs:
-- https://fuchsia.dev/fuchsia-src/reference/syscalls/system_get_features
+- https://fuchsia.dev/reference/syscalls/system_get_features
 - https://github.com/llvm/llvm-project/commit/4e731abc55681751b5d736b613f7720e50eb1ad4
 */
 
@@ -27,7 +27,7 @@ mod ffi {
 
     #[link(name = "zircon")]
     extern "C" {
-        // https://fuchsia.dev/fuchsia-src/reference/syscalls/system_get_features
+        // https://fuchsia.dev/reference/syscalls/system_get_features
         pub(crate) fn zx_system_get_features(kind: u32, features: *mut u32) -> zx_status_t;
     }
 }

diff --git a/src/imp/detect/auxv.rs b/src/imp/detect/auxv.rs
@@ -6,19 +6,38 @@ Run-time CPU feature detection on AArch64/PowerPC64 Linux/Android/FreeBSD/OpenBS
 Supported platforms:
 - Linux 6.4+ (through prctl)
   https://github.com/torvalds/linux/commit/ddc65971bb677aa9f6a4c21f76d3133e106f88eb
+  prctl returns an unsupported error if operation is not supported,
+  so we can safely use this on older versions.
 - glibc 2.16+ (through getauxval)
   https://github.com/bminor/glibc/commit/c7683a6d02f3ed59f5cd119b3e8547f45a15912f
+  Always available on:
+  - aarch64 (glibc 2.17+ https://github.com/bminor/glibc/blob/glibc-2.17/NEWS#L35)
+  Not always available on:
+  - powerpc64 (glibc 2.3+ https://github.com/bminor/glibc/blob/glibc-2.3/NEWS#L55)
+  Since Rust 1.64, std requires glibc 2.17+ https://blog.rust-lang.org/2022/08/01/Increasing-glibc-kernel-requirements.html
 - musl 1.1.0+ (through getauxval)
   https://github.com/bminor/musl/commit/21ada94c4b8c01589367cea300916d7db8461ae7
+  Always available on:
+  - aarch64 (musl 1.1.7+ https://github.com/bminor/musl/blob/v1.1.7/WHATSNEW#L1422)
+  - powerpc64 (musl 1.1.15+ https://github.com/bminor/musl/blob/v1.1.15/WHATSNEW#L1702)
+  Since Rust 1.31, std requires musl 1.1.20+ https://github.com/rust-lang/rust/pull/54430
+  Since Rust 1.37, std requires musl 1.1.22+ https://github.com/rust-lang/rust/pull/61252
+  Since Rust 1.46, std requires musl 1.1.24+ https://github.com/rust-lang/rust/pull/73089
+  Since Rust 1.71, std requires musl 1.2.3+ https://blog.rust-lang.org/2023/05/09/Updating-musl-targets.html
 - uClibc-ng 1.0.43+ (through getauxval)
   https://github.com/wbx-github/uclibc-ng/commit/d869bb1600942c01a77539128f9ba5b5b55ad647
 - Picolibc 1.4.6+ (through getauxval)
   https://github.com/picolibc/picolibc/commit/19bfe51d62ad7e32533c7f664b5bca8e26286e31
 - Android 4.3+ (API level 18+) (through getauxval)
   https://github.com/aosp-mirror/platform_bionic/blob/d3ebc2f7c49a9893b114124d4a6b315f3a328764/libc/include/sys/auxv.h#L49
+  Always available on 64-bit architectures, which is supported on Android 5.0+ (API level 21+) https://android-developers.googleblog.com/2014/10/whats-new-in-android-50-lollipop.html
 - FreeBSD 12.0+ and 11.4+ (through elf_aux_info)
   https://github.com/freebsd/freebsd-src/commit/0b08ae2120cdd08c20a2b806e2fcef4d0a36c470
   https://github.com/freebsd/freebsd-src/blob/release/11.4.0/sys/sys/auxv.h
+  Not always available on:
+  - aarch64 (FreeBSD 11.0+ https://www.freebsd.org/releases/11.0R/announce)
+  - powerpc64 (FreeBSD 9.0+ https://www.freebsd.org/releases/9.0R/announce)
+  Since Rust 1.75, std requires FreeBSD 12+ https://github.com/rust-lang/rust/pull/114521
 - OpenBSD 7.6+ (through elf_aux_info)
   https://github.com/openbsd/src/commit/ef873df06dac50249b2dd380dc6100eee3b0d23d
 

diff --git a/src/imp/riscv.rs b/src/imp/riscv.rs
@@ -99,7 +99,10 @@ macro_rules! atomic_rmw_amo {
                 asm!(
                     ".option push",
                     // https://github.com/riscv-non-isa/riscv-asm-manual/blob/ad0de8c004e29c9a7ac33cfd054f4d4f9392f2fb/src/asm-manual.adoc#arch
-                    // Note that .insn <value> requires LLVM 19 https://github.com/llvm/llvm-project/commit/2a086dce691e3cc34a2fc27f4fb255bb2cbbfac9
+                    // LLVM supports `.option arch` directive on LLVM 17+, so use .insn directive on old LLVM.
+                    // https://github.com/llvm/llvm-project/commit/9e8ed3403c191ab9c4903e8eeb8f732ff8a43cb4
+                    // Note that `.insn <value>` directive requires LLVM 19.
+                    // https://github.com/llvm/llvm-project/commit/2a086dce691e3cc34a2fc27f4fb255bb2cbbfac9
                     concat!(".option arch, ", atomic_rmw_amo_ext!($asm_suffix)),
                     concat!("amo", stringify!($op), ".", $asm_suffix, $asm_order, " {out}, {val}, 0({dst})"),
                     ".option pop",