embassy-rs / atomic-polyfill Goto Github PK

⚠️ DEPRECATED ⚠️ -- use `portable-atomic` instead.

License: Apache License 2.0

Rust 96.46% Shell 3.54%

atomic-polyfill's Introduction

⚠️ THIS CRATE IS DEPRECATED ⚠️

Use portable-atomic instead. It supports many more architectures and more efficient ways of emulating atomics.

portable-atomic with the critical-section feature is a drop-in replacement. It uses the critical-section crate to ensure locking, just like atomic-polyfill.

However, if your chip is single-core, you might want to enable the unsafe-assume-single-core feature instead. It makes portable-atomic emulate atomics by disabling interrupts. It is faster than using a critical-section implementation that disables interrupts, because it allows disabling them only on CAS operations, not in load/store operations.

If you're writing a library, add a dependency on portable-atomic but do NOT enable any feature on it. Let the end user of your library enable the right features for their target. If you enable features, you're taking their choice away.

atomic-polyfill

This crate polyfills atomics on targets where they're not available, using critical sections. It is intended to be a drop-in replacement for core::sync::atomic.

There are two "levels" of polyfilling:

Native: No polyfilling is performed, the native core::sync::atomic::AtomicXX is reexported.
Full: Both load/store and compare-and-set operations are polyfilled.

Polyfilling requires a critical-section implementation for the current target. Check the critical-section README for details.

Target support

The right polyfill level is automatically picked based on the target and the atomic width:

Target	Level	Level for u64/i64
thumbv4t	Full	Full
thumbv6m	Full	Full
thumbv7, thumbv8	Native	Full
riscv32imc	Full	Full
riscv32imac	Native	Full
xtensa-*-espidf	Native	Native
xtensa-esp32-*	Native	Full
xtensa-esp32s2-*	Full	Full
xtensa-esp32s3-*	Native	Full
xtensa-esp8266-*	Full	Full
AVR	Full	Full

For targets not listed above, atomic-polyfill assumes nothing and reexports core::sync::atomic::*. No polyfilling is done. PRs for polyfilling more targets are welcome :)

Minimum Supported Rust Version (MSRV)

MSRV is currently Rust 1.54. MSRV may be upgraded at any new patch release as long as latest stable Rust is supported.

License

This work is licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

atomic-polyfill's People

Contributors

Stargazers

Watchers

Forkers

icodein korken89 bgamari mabezdev mutantbob danbev misterzirillo stskeeps spaghetto vadixidav romancardenas kamirr junelife

atomic-polyfill's Issues

Missing compiler_fence in polyfilled mode

Support for target msp430-none-elf

I am currently working on a project on an MSP430 and embassy-executor appears to require an implementation of atomic-polyfill for this target. I can cook up a patched version on a fork and submit a PR. Creating this issue to track.

Does not compile for AVR

I was unable to compile the latest release or latest master using nightly. In order to get it to compile successfully, I had to bring in the master version of critical-section instead of 0.2.7.

jeremy@jeremy-desktop:~/apechem/atomic-polyfill$ cargo +nightly  build --target avr-unknown-gnu-atmega328 -Z build-std=core --release
   Compiling critical-section v0.2.7
   Compiling atomic-polyfill v0.1.8 (/home/jeremy/apechem/atomic-polyfill)
error: cannot find macro `llvm_asm` in this scope
   --> /home/jeremy/.cargo/registry/src/github.com-1ecc6299db9ec823/critical-section-0.2.7/src/lib.rs:127:13
    |
127 |             llvm_asm!(
    |             ^^^^^^^^

error: cannot find macro `llvm_asm` in this scope
   --> /home/jeremy/.cargo/registry/src/github.com-1ecc6299db9ec823/critical-section-0.2.7/src/lib.rs:139:17
    |
139 |                 llvm_asm!("sei" :::: "volatile");
    |                 ^^^^^^^^

error[E0635]: unknown feature `llvm_asm`
 --> /home/jeremy/.cargo/registry/src/github.com-1ecc6299db9ec823/critical-section-0.2.7/src/lib.rs:3:42
  |
3 | #![cfg_attr(target_arch = "avr", feature(llvm_asm))]
  |                                          ^^^^^^^^

For more information about this error, try `rustc --explain E0635`.

Won't build for 32bit systems, e.g. ESP32

This crate is required because shared-bus 0.2.3 now depends on it.

at 09:24:22 ❯ cargo build                                                                                      
   Compiling atomic-polyfill v0.1.6
   Compiling robotica-remote-rust v0.22.8 (/home/brian/tree/personal/robotica-remote-rust)
error[E0432]: unresolved import `core::sync::atomic::AtomicU64`
   --> /home/brian/.cargo/registry/src/github.com-1ecc6299db9ec823/atomic-polyfill-0.1.6/src/lib.rs:8:17
    |
8   |         pub use core::sync::atomic::$atomic_type;
    |                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ no `AtomicU64` in `sync::atomic`
...
195 | atomic_int!(u64, AtomicU64, u64_native, u64_cas, u64_full);
    | ----------------------------------------------------------
    | |                |
    | |                help: a similar name exists in the module: `AtomicU8`
    | in this macro invocation
    |
    = note: this error originates in the macro `atomic_int` (in Nightly builds, run with -Z macro-backtrace for more info)

error[E0432]: unresolved import `core::sync::atomic::AtomicI64`
   --> /home/brian/.cargo/registry/src/github.com-1ecc6299db9ec823/atomic-polyfill-0.1.6/src/lib.rs:8:17
    |
8   |         pub use core::sync::atomic::$atomic_type;
    |                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ no `AtomicI64` in `sync::atomic`
...
200 | atomic_int!(i64, AtomicI64, i64_native, i64_cas, i64_full);
    | ----------------------------------------------------------
    | |                |
    | |                help: a similar name exists in the module: `AtomicI8`
    | in this macro invocation
    |
    = note: this error originates in the macro `atomic_int` (in Nightly builds, run with -Z macro-backtrace for more info)

For more information about this error, try `rustc --explain E0432`.
error: could not compile `atomic-polyfill` due to 2 previous errors

Should deprecated stuff be available?

Currently this crate doesn't make available deprecated items in polyfilled mode. This includes:

The compare_and_swap method on all atomic types
The ATOMIC_XX_INIT consts
The spin_loop_hint function

To me this doesn't seem a big deal because if you're migrating some code from core::sync::atomic to atomic_polyfill you're already doing modifications,

OTOH it might be annoying to have code that compiles in non-polyfilled mode and fails in polyfilled mode. If we aim to be a complete drop-in replacement maybe deprecated items should be available too...

Thoughts?

Implement Arc and Weak using items from this crate

I'd like to use this in a crate that also uses Arc. Theoretically, it should be possible to also re-export/re-implement the Arc and Weak types using this crate. Maybe lock it behind an alloc feature for targets without an allocator available.

I can implement this PR myself.

Debug impl for AtomicPtr and AtomicBool

AtomicPtr and AtomicBool don't implement Debug, contrary to their std equivalent.

Minimum Safe Rust Version

Does this crate have an MSRV policy? I doubt that it's any recent version of Rust (since it just re-exports core primitives or redefines them using relatively low-level types), but it would be nice to know for when users want to include it in their projects.

Revisit Build-Script Polyfill Level Granularity

The compile-time features in the crate are fairly granular, but in build.rs they are more coarse.
In practice, this means that platforms such as AVR can't express that they natively support some
atomic operations on small-width integer types, but need polyfills on larger ones to the build process.

Would you be open to a patch that makes the built-in tuning in build.rs a bit more granular?