Improve portable_atomic_unsafe_assume_single_core docs

- Clarify that this uses an approach that disables interrupts.
- Clarify that this uses privileged instructions to disable interrupts.

CHANGELOG.md

@@ -10,6 +10,8 @@ Note: In this file, do not use the hard wrap in the middle of a sentence for com
 
 ## [Unreleased]
 
+- Update safety requirements for unsafe cfg `portable_atomic_unsafe_assume_single_core` to mention use of privileged instructions to disable interrupts.
+
 ## [0.3.10] - 2022-08-03
 
 - Optimize AArch64 128-bit atomic load when the `lse` target feature is enabled at compile-time. ([#20](https://github.com/taiki-e/portable-atomic/pull/20))

README.md

@@ -67,9 +67,12 @@ See [this list](https://github.com/taiki-e/portable-atomic/issues/10#issuecommen
 
 - **`--cfg portable_atomic_unsafe_assume_single_core`**<br>
   Assume that the target is single-core.
-  When this cfg is enabled, this crate provides atomic CAS for targets where atomic CAS is not available in the standard library.
+  When this cfg is enabled, this crate provides atomic CAS for targets where atomic CAS is not available in the standard library by disabling interrupts.
 
-  Note: This cfg is `unsafe`, and enabling this cfg for multi-core systems is **unsound**.
+  This cfg is `unsafe`, and note the following safety requirements:
+  - Enabling this cfg for multi-core systems is always **unsound**.
+  - This uses privileged instructions to disable interrupts, so it usually doesn't work on unprivileged mode.
+    Enabling this cfg in an environment where privileged instructions are not available is also usually considered **unsound**, although the details are system-dependent.
 
   This is intentionally not an optional feature. (If this is an optional feature, dependencies can implicitly enable the feature, resulting in the use of unsound code without the end-user being aware of it.)
 

src/imp/interrupt/mod.rs

@@ -1,10 +1,23 @@
 // Critical section based fallback implementations
 //
-// Since critical session-based fallback is not sound on multi-core systems,
-// this module will only be enabled in one of the following cases:
+// Critical session (disabling interrupts) based fallback is not sound on multi-core systems.
+// Also, this uses privileged instructions to disable interrupts, so it usually
+// doesn't work on unprivileged mode. Using this fallback in an environment where privileged
+// instructions are not available is also usually considered **unsound**,
+// although the details are system-dependent.
 //
-// - If the user explicitly declares the target to be single-core using an unsafe cfg.
-// - If the target can be safely assumed to be single-core.
+// Therefore, this implementation will only be enabled in one of the following cases:
+//
+// - When the user explicitly declares that the system is single-core and that
+//   privileged instructions are available using an unsafe cfg.
+// - When we can safely assume that the system is single-core and that
+//   privileged instructions are available on the system.
+//
+// AVR, which is single core[^avr1] and LLVM also generates code that disables
+// interrupts [^avr2] in atomic ops by default, is considered the latter.
+//
+// [^avr1]: https://github.com/llvm/llvm-project/blob/llvmorg-15.0.0-rc1/llvm/lib/Target/AVR/AVRExpandPseudoInsts.cpp#L1008
+// [^avr2]: https://github.com/llvm/llvm-project/blob/llvmorg-15.0.0-rc1/llvm/test/CodeGen/AVR/atomics/load16.ll#L5
 
 // On some platforms, atomic load/store can be implemented in a more efficient
 // way than disabling interrupts.

src/lib.rs

@@ -59,9 +59,12 @@ See [this list](https://github.com/taiki-e/portable-atomic/issues/10#issuecommen
 
 - **`--cfg portable_atomic_unsafe_assume_single_core`**<br>
   Assume that the target is single-core.
-  When this cfg is enabled, this crate provides atomic CAS for targets where atomic CAS is not available in the standard library.
+  When this cfg is enabled, this crate provides atomic CAS for targets where atomic CAS is not available in the standard library by disabling interrupts.
 
-  Note: This cfg is `unsafe`, and enabling this cfg for multi-core systems is **unsound**.
+  This cfg is `unsafe`, and note the following safety requirements:
+  - Enabling this cfg for multi-core systems is always **unsound**.
+  - This uses privileged instructions to disable interrupts, so it usually doesn't work on unprivileged mode.
+    Enabling this cfg in an environment where privileged instructions are not available is also usually considered **unsound**, although the details are system-dependent.
 
   This is intentionally not an optional feature. (If this is an optional feature, dependencies can implicitly enable the feature, resulting in the use of unsound code without the end-user being aware of it.)