Pull Request Overview

This PR replaces both the existing DeferredCall implementation (which was only usable for chip peripherals) and the existing DynamicDeferredCall implementation (which was used by capsules, kernel components, and even some chip peripherals) with a single, new DeferredCall. The new DeferredCall has higher size/cycle overhead than the original DeferredCall, but can be used anywhere in Tock. The new DeferredCall has lower size overhead than DynamicDeferredCall , and a much less verbose interface.

TL;DR SUMMARY:

• Imix flash: -524 bytes
• Imix (.bss + .data): +108 bytes
• Total code diff: -1300 LOC (not counting lines added from duplicating the time TRD)

Pros of this change

• We no longer have two different mechanisms for deferred procedure calls, which was always a rough edge for newcomers to Tock
• The new interface is much less verbose than the (more commonly used) DynamicDeferredCall -- this change has a net delta of 1300 LOC removed!
• The new DeferredCall checks whether more DeferredCalls have been created than there is space for, and checks that exactly as many DeferredCalls have been registered as were created. This check happens at the beginning of the kernel loop, rather than as DeferredCalls are created. This has two major advantages: first, DeferredCall errors will not lead to hard-to-debug hangs (before, a common bug was for too many DynamicDeferredCalls to be created, but the panic message could not be printed because the check happened at creation, before the debug writer had been setup). Second, it is now much more difficult to forget to register a DeferredCall -- as a result, there is no longer a need for capsules to verify that a DeferredCall has been initialized and registered before using it.
• The new interface has lower code size overhead than DynamicDeferredCall, and only marginally higher overhead than our old DeferredCall. For Imix, this change reduces code size by 524 bytes.
• The new interface does not use atomics, and as such we no longer require the #[core_intrinsics] nightly feature (notably, I think we could have made this change to the old DeferredCall as well).
• The new approach is completely compatible with out-of-tree capsules and peripherals using deferred calls (unlike the old DeferredCall).

Cons of this change

• Higher flash/RAM use and more cycles used compared to old DeferredCall, so for a board with no use for DynamicDeferredCall and no need for out-of-tree peripherals, this change can have a negative impact. In practice, any real Tock system will use enough DynamicDeferredCall (the console requires it if you use MuxUart!) that this is unlikely to have a negative impact for any systems.
• Pay the RAM cost of all 32 DeferredCalls whether they are used or not (fixed 256 byte cost). Overall, Imix RAM use went up by 108 bytes (there were some RAM savings thanks to the new DeferredCall being smaller in size than the old DynamicDeferredCall, which show up directly in .bss thanks to many of these types being allocated as fields on global static objects via static_init).
• Maximum of 32 DeferredCalls supported. We could increase this limit to 64 or 128 at some reasonably small cost, but it seems unlikely that any Tock boards today will require that many. For example, Imix uses only 11 and is already near its code size limit.
• Less clear mapping of DeferredCalls to the kernel scheduler compared to the old DynamicDeferredCall, since the use of globals means there is a level of indirection that cannot be directly traced through a DeferredCallManager or similar.

Acknowledgements

This PR involved significant collaboration with @lschuermann , who helped port many of the boards and chips over, wrote the original DynamicDeferredCall implementation, and collaborated with me on a bunch of different designs before we arrived at this one.

@kupiakos authored the first draft of the neat DynDefCallRef type, which helped to limit the code size overhead of this approach relative to simply using trait objects, which carry a bunch of information in vtables that we do not need for this.

Testing Strategy

This pull request was tested by running blink and imix on Imix. We will probably need to test across a few more boards, as it is easy to miss spots where we need to call DeferredCallClient::register() in main.rs. Fortunately, any board where we have forgotten to do this will panic at the start of the kernel loop with a useful message.

TODO or Help Wanted

Help wanted: Soundness review of how this type uses a (non-public) static mut Cell<usize> instead of AtomicUsize.

Documentation Updated

• Updated the relevant files in /docs (I think, may not have gotten everything).

Formatting

• Ran make prepush.