RELEASE-NOTES.mkdn

Release Notes

Version x.y.z (in progress)

• Totally reworked the Mutex API to further improve robustness in the face of cancellation.

  • The basic locking operation lock (and its friend try_lock) now return a "permit" that can be used to do one synchronous thing to the guarded data. (This operation was named perform/try_perform in 0.3.)
  • If you need to access the guarded data on either side of an await point, the lock_assuming_cancel_safe operation becomes available if you opt-in. (This operation was named lock in all prior versions, but was renamed to make it harder to grab by accident and easier to spot in code review.)

• Removed operations that were marked as deprecated during the 0.3.0 series: spsc::Push::push.

• The handoff module is no longer available by default. If you want it, request it by enabling the the handoff Cargo feature. (It's incredibly useful, but has some gotchas, so I wanted to make it a little harder to reach.)

Version 0.3.6

• Fixed bug that meant mutex wouldn't build if you didn't also have handoff enabled. Applications relying on default features wouldn't hit this since they're both on by default.

• Added exec::with_deadline and exec::with_timeout, more convenient methods for time-limiting the execution of a future. Compared to the traditional method of using select_biased!, these functions are significantly less verbose, more obvious, and produce smaller code too. This also relieves applications from depending on the futures crate for timeouts if they don't want to.

Version 0.3.5

• Fix bug in handoff when built without debug_assertions -- I introduced this in 0.3.4 in my code size "improvements." This has demonstrated the need to build the examples in both release and debug modes for coverage.

Version 0.3.4

• Changed the lifetimes on the reserve operation on spsc::Push. The original definition allowed for an unlikely but easily reachable deadlock, where code could simultaneously wait for two permits from the same queue -- the second permit will never arrive. I consider this a bug fix, and it won't break code unless that code contains a deadlock, so I'm including this in a minor rev. Currently not planning on yanking 0.3.3.

• Further code size improvements.

Version 0.3.3

• Fixed a bug I introduced into yield_cpu in 0.3.1. Please move away from 0.3.1/0.3.2 at your convenience. No other changes in this release.

Version 0.3.2

• Added explicit cancel safety annotations to all async/future operations. Currently everything except handoff is either strict cancel-safe or deprecated! Yay.
• Made certain implementation details cheaper on ARMv6-M.
• Took a pass over all the rustdoc and tidied things up. There are now more examples and stuff.

Version 0.3.1

• Based on watching people learning async, I'm adding a new operation to lilos::spsc::Push: reserve. This is similar to the old push but resolves to a Permit that lets you do the push synchronously. This lets you avoid losing data if cancelled, which is critical for building higher-level cancel-safe abstractions. Because I'm increasingly convinced of its danger, I have deprecated lilos::spsc::Push::push. Please use reserve if you need to block: q.reserve().await.push(data);

• lilos no longer depends on futures, which may reduce your build times, and makes things easier to interpret in a debugger.

Version 0.3.0

lilos now supports the stable toolchain!

• Minimum supported Rust version now 1.69 for various fixes.

• Cortex-M0 CPUs are now fully supported, with a worked example for the RP2040 in examples/rp2040, and successful applications (not in this repo) on Nordic nRF52832 and STM32G0. (Note that lilos is not multi-CPU aware, so the second core on the RP2040 can run code but not lilos tasks. Because very few lilos types are Send, it should be hard to screw this up without effort.)

• All SysTick timer support is now behind a feature, systick, which is on by default. You can omit this if you're targeting a platform where the SysTick timer is stopped in the normal sleep/wait states, such as the Nordic nRF52832. Your application will need to use interrupts (including potentially interrupts from a replacement low-power timer) to handle all events. I'll post a worked example eventually.

• Upgraded to cortex-m-rt 0.7.1; earlier 0.6-series cortex-m-rt crates don't reliably preserve stack alignment on startup, and must be avoided. (It would be nice if Cargo had something louder than yank in this case.) This is a user-visible change because you're responsible for linking in the cortex-m-rt setup code into your main routine -- make sure you're not using 0.6.

Example app updates

• New STM32H7 UART echo example -- similar to the STM32F407 example, but on hardware you can buy! (Edit: ...aaaaand it's out of stock)

• Changes to ensure that RLS/rust-analyzer work in examples.

API changes

• OS APIs have given up on never_type ever stabilizing and switched to the awkwardly-named-but-stable core::convert::Infallible type. The main implication for programs: task futures should now have the type async fn my_task(arguments) -> Infallible instead of -> !. You can probably search-replace this.

• The Mutex API has changed to omit the lock operation by default. I've decided the traditional lock/MutexGuard approach in async code makes it too easy to accidentally write cancel-incorrect abstractions. You now have to opt into the guard-based operations on a Mutex-by-Mutex basis by replacing Mutex<T> with Mutex<CancelSafe<T>> -- but first try using the perform operation instead.

• APIs relying on core::time::Duration have been switched over to a new lilos::time::Millis type, with Duration optionally supported where it makes sense. It turns out that Duration is internally structured such that essentially all operations require 64-bit (or 128-bit!) multiplication and/or division/remainder. This became really obvious on M0, which lacks any sort of division insruction. Switching away from Duration cuts several kiB off the size of the OS (which, depending on which features you're using, can be as much as 50-60%).

• The OS timestamp type has been renamed from lilos::time::Ticks to lilos::time::TickTime because I kept feeling like "ticks" sounds like a measure of time duration, rather than a timestamp. With the introduction of Millis it started to seem really ambiguous, so, I changed it.

• Two significant API changes to PeriodicGate:

  • PeriodicGate is now created using from instead of new, which lets it take either a cheap Millis or an expensive Duration. (This is the main change required to port simple applications to 0.3 in my experience.)

  • Added PeriodicGate::new_shift for setting up periodic timers out of phase with respect to one another. This is useful for e.g. scheduling a display refresh at 60 Hz, and scheduling serial communication to happen at exactly the same frequency but shifted so they don't compete (which was the motivating use case).

• Notify::until is now more powerful and can wait for a bool condition (its original use case), or for an operation returning Option to return Some. In the latter case, it returns the contained value. As a result, the old until_some has been removed -- change any uses of it to use until.

• All public types in the OS now have Debug impls for your debug-printing pleasure.

• TickTime can now be converted to and from a u64.

• The internal atomic module, containing "polyfill" atomic operations for portability between bigger cores and Cortex-M0, is now pub so applications can use it if desired.

Bug fixes

• mutex macros now import Pin so you don't have to (whoops!).

Internal changes

• A bunch of code size optimizations for small processors.
• Switch to Rust 2021.
• Fix some uses of deprecated cortex-m API.
• More aggressive warning settings.
• Use unsafe_op_in_unsafe_fn, which should really be Rust's default.
• The repo is no longer a workspace, because builds in workspaces with .cargo/config files change behavior depending on which directory you're in, despite having all build targets available, and this keeps confusing me.
• Example programs and OS internals have switched to the newly stabilized core::pin::pin! macro instead of pin_utils. You don't have to do this in your own programs, but I recommend it!

Version 0.2.1

• Add handoff (rendezvous) type, which can be much cheaper than a full spsc queue if you don't mind having the sender and receiver synchronize.

• No longer require the inline-asm feature from cortex-m. This is a visible change since it may affect your feature unification, but should not be a breaking change.

Version 0.2.0

• It became apparent that the original queue had soundness issues. Replaced queue with spsc, a rewritten version that I'm more confident in. This has a very different API, so this is a breaking change. spsc (single-producer single-consumer) is intended to distinguish it from other kinds of queues in the future.

• Both spsc (formerly queue) and mutex are now behind features, so you can opt into the parts of the system you need.

Version 0.1.0

Initial public release of the "operating system" factored out of my LED controller project.

0.1.1 and 0.1.2 were only docs changes.