Merge #344

344: Add a Subscribe API to `libtock_platform`. r=jrvanwhy a=jrvanwhy

This API is based on the design at #341.

Based on a request from Ti50, I added a configuration parameter to `subscribe`. Currently the only part of `subscribe` that is configurable is its behavior if the kernel returns a non-null upcall. By default I don't think `subscribe` should do anything special for that case (because it "shouldn't happen" and I want to keep code size small), but Ti50 wants to add a debug print to that branch.

I also provided default `Upcall` implementations for several basic types (`Cell<Bool>`, `Cell<Option<(u32, u32, u32)>>`, and similar) which simply store their arguments and a flag indicating they were called. I expect these `Upcall` implementations to be used repeatedly across multiple codebases.

Co-authored-by: Johnathan Van Why <[email protected]>

Author: bors[bot]

platform/src/default_config.rs

@@ -0,0 +1,5 @@
+/// A general purpose syscall configuration, which drivers should use as their
+/// default syscall config.
+pub struct DefaultConfig;
+
+impl crate::subscribe::Config for DefaultConfig {}

platform/src/exit_on_drop.rs

@@ -0,0 +1,27 @@
+/// Calls the Exit system call when dropped. Used to catch panic unwinding from
+/// a `#![no_std]` context. The caller should `core::mem::forget` the
+/// `ExitOnDrop` when it no longer needs to catch unwinding.
+///
+///
+/// # Example
+/// ```
+/// use libtock_platform::exit_on_drop::ExitOnDrop;
+/// fn function_that_must_not_unwind<S: libtock_platform::Syscalls>() {
+///     let exit_on_drop: ExitOnDrop::<S> = Default::default();
+///     /* Do something that might unwind here. */
+///     core::mem::forget(exit_on_drop);
+/// }
+/// ```
+pub struct ExitOnDrop<S: crate::Syscalls>(core::marker::PhantomData<S>);
+
+impl<S: crate::Syscalls> Default for ExitOnDrop<S> {
+    fn default() -> ExitOnDrop<S> {
+        ExitOnDrop(core::marker::PhantomData)
+    }
+}
+
+impl<S: crate::Syscalls> Drop for ExitOnDrop<S> {
+    fn drop(&mut self) {
+        S::exit_terminate(0);
+    }
+}

platform/src/lib.rs

@@ -4,10 +4,13 @@
 mod async_traits;
 mod command_return;
 mod constants;
+mod default_config;
 mod error_code;
+pub mod exit_on_drop;
 mod raw_syscalls;
 mod register;
 pub mod return_variant;
+pub mod subscribe;
 mod syscall_scope;
 mod syscalls;
 mod syscalls_impl;
@@ -17,10 +20,12 @@ mod yield_types;
 pub use async_traits::{CallbackContext, FreeCallback, Locator, MethodCallback};
 pub use command_return::CommandReturn;
 pub use constants::{exit_id, syscall_class, yield_id};
+pub use default_config::DefaultConfig;
 pub use error_code::ErrorCode;
 pub use raw_syscalls::RawSyscalls;
 pub use register::Register;
 pub use return_variant::ReturnVariant;
+pub use subscribe::{Subscribe, Upcall};
 pub use syscall_scope::syscall_scope;
 pub use syscalls::Syscalls;
 pub use termination::Termination;

platform/src/raw_syscalls.rs

@@ -59,7 +59,7 @@ use crate::Register;
 //
 // These system calls are refined further individually, which is documented on
 // a per-function basis.
-pub unsafe trait RawSyscalls {
+pub unsafe trait RawSyscalls: Sized {
     // yield1 can only be used to call `yield-wait`, which does not have a
     // return value. To simplify the assembly implementation, we remove its
     // return value.

platform/src/subscribe.rs

@@ -0,0 +1,157 @@
+use crate::syscall_scope::ShareList;
+use crate::Syscalls;
+
+// -----------------------------------------------------------------------------
+// `Subscribe` struct
+// -----------------------------------------------------------------------------
+
+/// A `Subscribe` instance allows safe code to call Tock's Subscribe system
+/// call, by guaranteeing the upcall will be cleaned up before 'scope ends. It
+/// is generally used with the `syscall_scope` function, which offers a safe
+/// interface for constructing `Subscribe` instances.
+pub struct Subscribe<'scope, S: Syscalls, const DRIVER_NUM: u32, const SUBSCRIBE_NUM: u32> {
+    _syscalls: core::marker::PhantomData<S>,
+
+    // Make this struct invariant with respect to the 'scope lifetime.
+    //
+    // Covariance would be unsound, as that would allow code with a
+    // `Subscribe<'static, ...>` to register an upcall that lasts for a shorter
+    // lifetime, resulting in use-after-free if the upcall is invoked.
+    // Contravariance would be sound, but is not necessary and may be confusing.
+    //
+    // Additionally, we want to have at least one private member of this struct
+    // so that code outside this module cannot construct a `Subscribe` without
+    // calling `ShareList::new`.
+    _scope: core::marker::PhantomData<core::cell::Cell<&'scope ()>>,
+}
+
+impl<'scope, S: Syscalls, const DRIVER_NUM: u32, const SUBSCRIBE_NUM: u32> Drop
+    for Subscribe<'scope, S, DRIVER_NUM, SUBSCRIBE_NUM>
+{
+    fn drop(&mut self) {
+        S::unsubscribe(DRIVER_NUM, SUBSCRIBE_NUM);
+    }
+}
+
+impl<'scope, S: Syscalls, const DRIVER_NUM: u32, const SUBSCRIBE_NUM: u32> ShareList<'scope>
+    for Subscribe<'scope, S, DRIVER_NUM, SUBSCRIBE_NUM>
+{
+    // Safety: The safety invariant is inherited from the ShareList trait's
+    // definition. The caller must guarantee that Drop::drop is called on this
+    // Subscribe before the 'scope lifetime ends.
+    unsafe fn new() -> Subscribe<'scope, S, DRIVER_NUM, SUBSCRIBE_NUM> {
+        Subscribe {
+            _syscalls: core::marker::PhantomData,
+            _scope: core::marker::PhantomData,
+        }
+    }
+}
+
+// -----------------------------------------------------------------------------
+// `Upcall` trait
+// -----------------------------------------------------------------------------
+
+/// A Tock kernel upcall. Upcalls are registered using the Subscribe system
+/// call, and are invoked during Yield calls.
+///
+/// Each `Upcall` supports one or more subscribe IDs, which are indicated by the
+/// `SupportedIds` parameter. The types `AnySubscribeId` and `OneSubscribeId`
+/// are provided to use as `SupportedIds` parameters in `Upcall`
+/// implementations.
+pub trait Upcall<SupportedIds> {
+    fn upcall(&self, arg0: u32, arg1: u32, arg2: u32);
+}
+
+pub trait SupportsId<const DRIVER_NUM: u32, const SUBSCRIBE_NUM: u32> {}
+
+pub struct AnyId;
+impl<const DRIVER_NUM: u32, const SUBSCRIBE_NUM: u32> SupportsId<DRIVER_NUM, SUBSCRIBE_NUM>
+    for AnyId
+{
+}
+
+pub struct OneId<const DRIVER_NUM: u32, const SUBSCRIBE_NUM: u32>;
+impl<const DRIVER_NUM: u32, const SUBSCRIBE_NUM: u32> SupportsId<DRIVER_NUM, SUBSCRIBE_NUM>
+    for OneId<DRIVER_NUM, SUBSCRIBE_NUM>
+{
+}
+
+// -----------------------------------------------------------------------------
+// Upcall implementations that simply store their arguments
+// -----------------------------------------------------------------------------
+
+/// An implementation of `Upcall` that sets the contained boolean value to
+/// `true` when the upcall is invoked.
+impl Upcall<AnyId> for core::cell::Cell<bool> {
+    fn upcall(&self, _: u32, _: u32, _: u32) {
+        self.set(true);
+    }
+}
+
+/// Implemented for consistency with the other `Cell<Option<...>>` `Upcall`
+/// impls. Most users would prefer the `Cell<bool>` implementation over this
+/// impl, but this may be useful in a generic or macro context.
+impl Upcall<AnyId> for core::cell::Cell<Option<()>> {
+    fn upcall(&self, _: u32, _: u32, _: u32) {
+        self.set(Some(()));
+    }
+}
+
+/// An `Upcall` implementation that stores its first argument when called.
+impl Upcall<AnyId> for core::cell::Cell<Option<(u32,)>> {
+    fn upcall(&self, arg0: u32, _: u32, _: u32) {
+        self.set(Some((arg0,)));
+    }
+}
+
+/// An `Upcall` implementation that stores its first two arguments when called.
+impl Upcall<AnyId> for core::cell::Cell<Option<(u32, u32)>> {
+    fn upcall(&self, arg0: u32, arg1: u32, _: u32) {
+        self.set(Some((arg0, arg1)));
+    }
+}
+
+/// An `Upcall` implementation that stores its arguments when called.
+impl Upcall<AnyId> for core::cell::Cell<Option<(u32, u32, u32)>> {
+    fn upcall(&self, arg0: u32, arg1: u32, arg2: u32) {
+        self.set(Some((arg0, arg1, arg2)));
+    }
+}
+
+#[cfg(test)]
+#[test]
+fn upcall_impls() {
+    let cell_bool = core::cell::Cell::new(false);
+    cell_bool.upcall(1, 2, 3);
+    assert!(cell_bool.get());
+
+    let cell_empty = core::cell::Cell::new(None);
+    cell_empty.upcall(1, 2, 3);
+    assert_eq!(cell_empty.get(), Some(()));
+
+    let cell_one = core::cell::Cell::new(None);
+    cell_one.upcall(1, 2, 3);
+    assert_eq!(cell_one.get(), Some((1,)));
+
+    let cell_two = core::cell::Cell::new(None);
+    cell_two.upcall(1, 2, 3);
+    assert_eq!(cell_two.get(), Some((1, 2)));
+
+    let cell_three = core::cell::Cell::new(None);
+    cell_three.upcall(1, 2, 3);
+    assert_eq!(cell_three.get(), Some((1, 2, 3)));
+}
+
+// -----------------------------------------------------------------------------
+// `Config` trait
+// -----------------------------------------------------------------------------
+
+/// `Config` configures the behavior of the Subscribe system call. It should
+/// generally be passed through by drivers, to allow application code to
+/// configure error handling.
+pub trait Config {
+    /// Called if a Subscribe call succeeds and returns a non-null upcall. In
+    /// some applications, this may indicate unexpected reentrance. By default,
+    /// the non-null upcall is ignored.
+    fn returned_nonnull_upcall(_driver_num: u32, _subscribe_num: u32) {}
+}

platform/src/syscalls.rs

@@ -1,9 +1,11 @@
-use crate::{CommandReturn, YieldNoWaitReturn};
+use crate::{
+    subscribe, CommandReturn, ErrorCode, RawSyscalls, Subscribe, Upcall, YieldNoWaitReturn,
+};
 
 /// `Syscalls` provides safe abstractions over Tock's system calls. It is
 /// implemented for `libtock_runtime::TockSyscalls` and
 /// `libtock_unittest::fake::Kernel` (by way of `RawSyscalls`).
-pub trait Syscalls {
+pub trait Syscalls: RawSyscalls + Sized {
     // -------------------------------------------------------------------------
     // Yield
     // -------------------------------------------------------------------------
@@ -17,7 +19,26 @@ pub trait Syscalls {
     /// callback, then returns.
     fn yield_wait();
 
-    // TODO: Add a subscribe interface.
+    // -------------------------------------------------------------------------
+    // Subscribe
+    // -------------------------------------------------------------------------
+
+    /// Registers an upcall with the kernel.
+    fn subscribe<
+        'scope,
+        IDS: subscribe::SupportsId<DRIVER_NUM, SUBSCRIBE_NUM>,
+        U: Upcall<IDS>,
+        CONFIG: subscribe::Config,
+        const DRIVER_NUM: u32,
+        const SUBSCRIBE_NUM: u32,
+    >(
+        subscribe: &Subscribe<'scope, Self, DRIVER_NUM, SUBSCRIBE_NUM>,
+        upcall: &'scope U,
+    ) -> Result<(), ErrorCode>;
+
+    /// Unregisters the upcall with the given ID. If no upcall is registered
+    /// with the given ID, `unsubscribe` does nothing.
+    fn unsubscribe(driver_num: u32, subscribe_num: u32);
 
     // -------------------------------------------------------------------------
     // Command
@@ -31,6 +52,10 @@ pub trait Syscalls {
 
     // TODO: Add memop() methods.
 
+    // -------------------------------------------------------------------------
+    // Exit
+    // -------------------------------------------------------------------------
+
     fn exit_terminate(exit_code: u32) -> !;
 
     fn exit_restart(exit_code: u32) -> !;