Merge pull request #33 from jfrimmel/portable-atomics-docu

Add explanation of supported hardware

Author: jfrimmel

README.md

@@ -68,6 +68,24 @@ A note to users on systems with advanced memory features like MMUs and MPUs:
   Use a proper memory allocator for that use case (one that supports paging, etc.).
   However, if you need dynamic memory before enabling the MMU, this crate certainly is an option.
 
+# Platform support
+
+This crate does not use any platform-specific features (e.g. an MMU or specific instructions), except for the requirement for a atomic compare-and-swap-instruction (CAS), which is widely available.
+Therefore this crate works out-of-the-box on most architectures.
+
+Some platforms however don't provide such an instruction (e.g. `thumbv6m-none-eabi` or the RISC-V OpenTitan) or totally lack atomic instructions (e.g. AVR) due to only a single-core nature.
+On those platforms, where the CAS instruction is not available, one can use the workaround, that [`spin`][spin-docs] use: you can enable the `portable_atomic`-feature in your `Cargo.toml`, like this:
+```toml
+[dependencies.emballoc]
+version = "*" # replace with current version from crates.io
+features = ["portable_atomic"]
+```
+This enables the use of the `portable_atomic` instead of the `core`-atomics.
+This is safe on any platform.
+
+To actually enable atomics support on platforms without hardware support, the `--cfg portable_atomic_unsafe_assume_single_core`-option needs to be explicitly enabled when compiling.
+For more details see the [documentation of `spin`][spin-docs].
+
 # Minimum supported Rust version
 
 This crate has a stability guarantee about the compiler version supported.
@@ -85,3 +103,4 @@ at your option.
 
 [docu-testing]: https://docs.rs/emballoc/latest/emballoc/#testing
 [gist_hosted-test]: https://gist.github.com/jfrimmel/61943f9879adfbe760a78efa17a0ecaa
+[spin-docs]: https://crates.io/crates/spin#Feature_flags