Merge tock#131

131: Better subscribe API r=Woyten a=Woyten

This PR improves the usability of the `subscribe` API. The current API has the following problems:

- It is impossible to implement `SubscribableCallback` for different `FnMut` traits. This is the reason why the odd `WithCallback` helper objects were introduced.
- `SubscribableCallback` is crate private by accident. As a result, it is hard to reason what types actually implement `SubscribableCallback`

Besides that, the following APIs have been made more consistent:
- LEDs
- Buttons
- GPIO
- Temperature

Co-authored-by: Woyten <[email protected]>

Author: bors[bot]

.travis.yml

@@ -18,7 +18,7 @@ cache: cargo
 install:
   - rustup target add thumbv7em-none-eabi
   - rustup target add riscv32imc-unknown-none-elf
-  - rustup component add rustfmt-preview
+  - rustup component add rustfmt
   - rustup component add clippy
 
 script:

CHANGELOG.md

@@ -2,23 +2,41 @@
 
 ## 0.2.0 (WIP)
 
+### Comprehensive Changes
+
 - Many functions are asynchronous
-  - To make create an `async` main function you can use the attribute `#[libtock::main]`
+  - To create an `async` main function you can use the attribute `#[libtock::main]`
   - To retrieve the value of an asynchronous `value`, use `value.await`
   - This is only possible within an `async fn`, so either
     - Make the caller `fn` of `.await` an `async fn`
     - Not recommended: Use `core::executor::block_on(value)` to retrieve the `value`
+- Most API functions, including `main()`, return a `Result<T, TockError>`
+- All drivers can exclusively be retrieved by `retrieve_drivers` which returns a `Drivers` singleton. Drivers can be shared between different tasks only if it is safe to do so.
+
+### Changed APIs
+
+- The basic APIs have been made consistent. They are initialized via driver factories and no longer require a `WithCallback` object, s.t. the callback subscription is more intuitive. The affected APIs are:
+  - LEDs
+  - Buttons
+  - GPIO
+  - Temperature
+  - ADC (partially)
+- The timer API now supports concurrent sleep operations
+
+### Syscalls
+
+- `syscalls::subscribe` is actually usable
 - `syscalls::yieldk_for` is no longer available
   - Yielding manually is discouraged as it conflicts with Rust's safety guarantees. If you need to wait for a condition, use `futures::wait_until` and `.await`.
 - `syscalls::yieldk` has become `unsafe` for the same reason
-- Commands are no longer `unsafe`
+- `syscalls::command` is no longer `unsafe`
 - The low-level syscalls have been moved to `syscalls::raw`
   - `syscalls::subscribe_ptr` becomes `syscalls::raw::subscribe`
   - `syscalls::allow_ptr` becomes `syscalls::raw::allow`
+
+### Miscellaneous
+
 - Targets without support for atomics can be built
-- Most API functions, including `main()`, return a `Result<T, TockError>`
-- The library now supports parallel timers
-- all drivers can exclusively be retrieved by `retrieve_drivers` which returns a `Drivers`-singleton. Drivers can be shared between different tasks only if it is safe to do so.
 
 ## a8bb4fa9be504517d5533511fd8e607ea61f1750 (0.1.0)
 

examples/adc.rs

@@ -3,28 +3,24 @@
 use core::fmt::Write;
 use libtock::result::TockResult;
 use libtock::timer::Duration;
-use libtock::Drivers;
 
 #[libtock::main]
 async fn main() -> TockResult<()> {
-    let Drivers {
-        console_driver,
-        timer_context,
-        adc_driver,
-        ..
-    } = libtock::retrieve_drivers()?;
+    let mut drivers = libtock::retrieve_drivers()?;
 
-    let mut driver = timer_context.create_timer_driver();
-    let timer_driver = driver.activate()?;
-    let mut console = console_driver.create_console();
-    let mut with_callback = adc_driver.with_callback(|channel: usize, value: usize| {
+    let adc_driver = drivers.adc.init_driver()?;
+    let mut timer_driver = drivers.timer.create_timer_driver();
+    let timer_driver = timer_driver.activate()?;
+    let mut console = drivers.console.create_console();
+
+    let mut callback = |channel, value| {
         writeln!(console, "channel: {}, value: {}", channel, value).unwrap();
-    });
+    };
 
-    let adc = with_callback.init()?;
+    let _subscription = adc_driver.subscribe(&mut callback)?;
 
     loop {
-        adc.sample(0)?;
+        adc_driver.sample(0)?;
         timer_driver.sleep(Duration::from_ms(2000)).await?;
     }
 }

examples/adc_buffer.rs

@@ -4,31 +4,29 @@ use core::fmt::Write;
 use libtock::adc::AdcBuffer;
 use libtock::result::TockResult;
 use libtock::syscalls;
-use libtock::Drivers;
 
 #[libtock::main]
 /// Reads a 128 byte sample into a buffer and prints the first value to the console.
 async fn main() -> TockResult<()> {
-    let Drivers {
-        console_driver,
-        adc_driver,
-        ..
-    } = libtock::retrieve_drivers()?;
-    let mut console = console_driver.create_console();
+    let mut drivers = libtock::retrieve_drivers()?;
+
+    let adc_driver = drivers.adc.init_driver()?;
+    let mut console = drivers.console.create_console();
+
     let mut adc_buffer = AdcBuffer::default();
     let mut temp_buffer = [0; libtock::adc::BUFFER_SIZE];
 
-    let adc_buffer = libtock::adc::Adc::init_buffer(&mut adc_buffer)?;
+    let adc_buffer = adc_driver.init_buffer(&mut adc_buffer)?;
 
-    let mut with_callback = adc_driver.with_callback(|_, _| {
+    let mut callback = |_, _| {
         adc_buffer.read_bytes(&mut temp_buffer[..]);
         writeln!(console, "First sample in buffer: {}", temp_buffer[0]).unwrap();
-    });
+    };
 
-    let adc = with_callback.init()?;
+    let _subscription = adc_driver.subscribe(&mut callback)?;
 
     loop {
-        adc.sample_continuous_buffered(0, 128)?;
+        adc_driver.sample_continuous_buffered(0, 128)?;
         unsafe { syscalls::raw::yieldk() };
     }
 }

examples/alloc_error.rs

@@ -0,0 +1,16 @@
+// Triggers the out-of-memory handler. Should make all LEDs cycle.
+
+#![no_std]
+
+extern crate alloc;
+
+use alloc::vec::Vec;
+use libtock::result::TockResult;
+
+#[libtock::main]
+fn main() -> TockResult<()> {
+    let mut vec = Vec::new();
+    loop {
+        vec.push(0);
+    }
+}

examples/ble_scanning.rs

@@ -6,7 +6,6 @@ use libtock::result::TockResult;
 use libtock::simple_ble;
 use libtock::simple_ble::BleCallback;
 use libtock::simple_ble::BleScanningDriver;
-use libtock::Drivers;
 use serde::Deserialize;
 
 #[derive(Deserialize)]
@@ -17,31 +16,28 @@ struct LedCommand {
 
 #[libtock::main]
 async fn main() -> TockResult<()> {
-    let Drivers {
-        led_driver_factory,
-        mut ble_scanning_driver,
-        ..
-    } = libtock::retrieve_drivers()?;
+    let mut drivers = libtock::retrieve_drivers()?;
 
-    let led_driver = led_driver_factory.create_driver()?;
+    let leds_driver = drivers.leds.init_driver()?;
 
     let mut shared_buffer = BleScanningDriver::create_scan_buffer();
     let mut my_buffer = BleScanningDriver::create_scan_buffer();
-    let shared_memory = ble_scanning_driver.share_memory(&mut shared_buffer)?;
+    let shared_memory = drivers.ble_scanning.share_memory(&mut shared_buffer)?;
 
     let mut callback = BleCallback::new(|_: usize, _: usize| {
         shared_memory.read_bytes(&mut my_buffer[..]);
         ble_parser::find(&my_buffer, simple_ble::gap_data::SERVICE_DATA as u8)
             .and_then(|service_data| ble_parser::extract_for_service([91, 79], service_data))
             .and_then(|payload| corepack::from_bytes::<LedCommand>(&payload).ok())
             .and_then(|msg| {
-                led_driver
+                leds_driver
                     .get(msg.nr as usize)
-                    .map(|led| led.set_state(msg.st))
+                    .map(|led| led.set(msg.st))
+                    .into()
             });
     });
 
-    let _subscription = ble_scanning_driver.start(&mut callback)?;
+    let _subscription = drivers.ble_scanning.start(&mut callback)?;
 
     future::pending().await
 }

examples/blink.rs

@@ -2,26 +2,21 @@
 
 use libtock::result::TockResult;
 use libtock::timer::Duration;
-use libtock::Drivers;
 
 #[libtock::main]
 async fn main() -> TockResult<()> {
-    let Drivers {
-        led_driver_factory,
-        timer_context,
-        ..
-    } = libtock::retrieve_drivers()?;
+    let mut drivers = libtock::retrieve_drivers()?;
 
-    let mut driver = timer_context.create_timer_driver();
-    let timer_driver = driver.activate()?;
-    let led_driver = led_driver_factory.create_driver()?;
+    let leds_driver = drivers.leds.init_driver()?;
+    let mut timer_driver = drivers.timer.create_timer_driver();
+    let timer_driver = timer_driver.activate()?;
 
     // Blink the LEDs in a binary count pattern and scale
     // to the number of LEDs on the board.
     let mut count: usize = 0;
     loop {
-        for led in led_driver.all() {
-            let i = led.number();
+        for led in leds_driver.leds() {
+            let i = led.led_num();
             if count & (1 << i) == (1 << i) {
                 led.on()?;
             } else {

examples/blink_random.rs

@@ -1,45 +1,37 @@
 #![no_std]
 
-use libtock::led::LedDriver;
+use libtock::leds::LedsDriver;
 use libtock::result::TockResult;
 use libtock::timer::Duration;
-use libtock::Drivers;
 
 #[libtock::main]
 async fn main() -> TockResult<()> {
-    let Drivers {
-        timer_context,
-        mut rng_driver,
-        led_driver_factory,
-        ..
-    } = libtock::retrieve_drivers()?;
+    let mut drivers = libtock::retrieve_drivers()?;
 
-    let led_driver = led_driver_factory.create_driver()?;
+    let leds_driver = drivers.leds.init_driver()?;
+    let mut timer_driver = drivers.timer.create_timer_driver();
+    let timer_driver = timer_driver.activate()?;
 
-    let mut driver = timer_context.create_timer_driver();
-    let timer_driver = driver.activate()?;
-
-    let num_leds = led_driver.count()?;
     // blink_nibble assumes 4 leds.
-    assert_eq!(num_leds, 4);
+    assert_eq!(leds_driver.num_leds(), 4);
 
     let mut buf = [0; 64];
     loop {
-        rng_driver.fill_buffer(&mut buf).await?;
+        drivers.rng.fill_buffer(&mut buf).await?;
 
         for &x in buf.iter() {
-            blink_nibble(x, &led_driver)?;
+            blink_nibble(&leds_driver, x)?;
             timer_driver.sleep(Duration::from_ms(100)).await?;
-            blink_nibble(x >> 4, &led_driver)?;
+            blink_nibble(&leds_driver, x >> 4)?;
             timer_driver.sleep(Duration::from_ms(100)).await?;
         }
     }
 }
 
 // Takes the 4 least-significant bits of x, and turn the 4 leds on/off accordingly.
-fn blink_nibble(x: u8, led_driver: &LedDriver) -> TockResult<()> {
+fn blink_nibble(leds_driver: &LedsDriver, x: u8) -> TockResult<()> {
     for i in 0..4 {
-        let led = led_driver.get(i).unwrap();
+        let led = leds_driver.get(i)?;
         if (x >> i) & 1 != 0 {
             led.on()?;
         } else {

examples/button_leds.rs

@@ -3,29 +3,23 @@
 use futures::future;
 use libtock::buttons::ButtonState;
 use libtock::result::TockResult;
-use libtock::Drivers;
 
 #[libtock::main]
 async fn main() -> TockResult<()> {
-    let Drivers {
-        led_driver_factory,
-        button_driver,
-        ..
-    } = libtock::retrieve_drivers()?;
+    let mut drivers = libtock::retrieve_drivers()?;
 
-    let led_driver = led_driver_factory.create_driver()?;
+    let buttons_driver = drivers.buttons.init_driver()?;
+    let leds_driver = drivers.leds.init_driver()?;
 
-    let mut with_callback = button_driver.with_callback(|button_num: usize, state| {
-        match state {
-            ButtonState::Pressed => led_driver.get(button_num).unwrap().toggle().ok().unwrap(),
-            ButtonState::Released => (),
-        };
-    });
+    let mut callback = |button_num, state| {
+        if let (ButtonState::Pressed, Ok(led)) = (state, leds_driver.get(button_num)) {
+            led.toggle().ok().unwrap();
+        }
+    };
 
-    let mut buttons = with_callback.init()?;
-
-    for mut button in &mut buttons {
-        button.enable()?;
+    let _subscription = buttons_driver.subscribe(&mut callback)?;
+    for button in buttons_driver.buttons() {
+        button.enable_interrupt()?;
     }
 
     future::pending().await

examples/button_read.rs

@@ -1,34 +1,27 @@
 #![no_std]
 
 use core::fmt::Write;
-use libtock::buttons::ButtonState;
 use libtock::result::TockResult;
 use libtock::timer::Duration;
-use libtock::Drivers;
 
 #[libtock::main]
 async fn main() -> TockResult<()> {
-    let Drivers {
-        console_driver,
-        timer_context,
-        button_driver,
-        ..
-    } = libtock::retrieve_drivers()?;
-    let mut console = console_driver.create_console();
-    let mut with_callback = button_driver.with_callback(|_, _| {});
-    let mut buttons = with_callback.init()?;
-    let mut button = buttons.iter_mut().next().unwrap();
-    let button = button.enable()?;
+    let mut drivers = libtock::retrieve_drivers()?;
 
-    let mut driver = timer_context.create_timer_driver();
-    let timer_driver = driver.activate()?;
+    let buttons_driver = drivers.buttons.init_driver()?;
+    let mut timer_driver = drivers.timer.create_timer_driver();
+    let timer_driver = timer_driver.activate()?;
+    let mut console = drivers.console.create_console();
 
     loop {
-        match button.read()? {
-            ButtonState::Pressed => writeln!(console, "pressed"),
-            ButtonState::Released => writeln!(console, "released"),
-        }?;
-
+        for button in buttons_driver.buttons() {
+            writeln!(
+                console,
+                "button {}: {:?}",
+                button.button_num(),
+                button.read()?
+            )?;
+        }
         timer_driver.sleep(Duration::from_ms(500)).await?;
     }
 }