Merge tock#122

122: Create 'drivers' singleton r=torfmaster a=torfmaster

# Overview
The drivers as well as the hardware represented by the drivers is only available once. To prevent hacing multiple mutable references to this global mutable state we do the following:

 * collect all drivers in a `drivers` object which is a singleton
 * ~if a driver allows to create a mutable reference to a part (e.g. an led) mutably borrow the driver as whole~

# Progress
The following drivers have been migrated:

[x] Timer
[x] Led
[x] Console
[x] GPIO
[x] Temperature 
[x] Buttons
[x] ADC
[x] RNG
[x] BLE
[x] ninedof

# Help needed
As this PR concerns API design comments are welcome! 
Moreover, the initialization of the `Hardware` struct is very verbose. However, initialization using a
`Default` implementation is not desired as this would make the individual drivers constructible outside the trate which is unsafe. Any ideas are very welcome. 

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

Author: bors[bot]

.travis.yml

@@ -13,7 +13,7 @@ os:
   - linux
   - osx
 
-cache: rust
+cache: cargo
 
 install:
   - rustup target add thumbv7em-none-eabi
@@ -22,7 +22,4 @@ install:
   - rustup component add clippy
 
 script:
-  - cargo fmt --all -- --check
-  - cargo test --workspace
-  - cargo clippy --workspace --all-targets
-  - ./build_examples.sh
+  - ./run_all_checks.sh

CHANGELOG.md

@@ -17,7 +17,8 @@
   - `syscalls::allow_ptr` becomes `syscalls::raw::allow`
 - Targets without support for atomics can be built
 - Most API functions, including `main()`, return a `Result<T, TockError>`
-- The timer now supports to be used simultaneously. To make this safe, `TimerDriver` is now a singleton.
+- 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

@@ -1,20 +1,23 @@
 #![no_std]
 
 use core::fmt::Write;
-use libtock::adc;
-use libtock::console::Console;
 use libtock::result::TockResult;
-use libtock::timer;
 use libtock::timer::Duration;
+use libtock::Drivers;
 
 #[libtock::main]
 async fn main() -> TockResult<()> {
-    let context = timer::DriverContext::create()?;
-    let mut driver = context.create_timer_driver()?;
-    let timer_driver = driver.activate()?;
+    let Drivers {
+        console_driver,
+        timer_context,
+        adc_driver,
+        ..
+    } = libtock::retrieve_drivers()?;
 
-    let mut console = Console::default();
-    let mut with_callback = adc::with_callback(|channel: usize, value: usize| {
+    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| {
         writeln!(console, "channel: {}, value: {}", channel, value).unwrap();
     });
 

examples/adc_buffer.rs

@@ -1,22 +1,26 @@
 #![no_std]
 
 use core::fmt::Write;
-use libtock::adc;
 use libtock::adc::AdcBuffer;
-use libtock::console::Console;
 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 mut console = Console::default();
+    let Drivers {
+        console_driver,
+        adc_driver,
+        ..
+    } = libtock::retrieve_drivers()?;
+    let mut console = console_driver.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 mut with_callback = adc::with_callback(|_, _| {
+    let mut with_callback = adc_driver.with_callback(|_, _| {
         adc_buffer.read_bytes(&mut temp_buffer[..]);
         writeln!(console, "First sample in buffer: {}", temp_buffer[0]).unwrap();
     });

examples/ble_scanning.rs

@@ -2,11 +2,11 @@
 
 use futures::future;
 use libtock::ble_parser;
-use libtock::led;
 use libtock::result::TockResult;
 use libtock::simple_ble;
 use libtock::simple_ble::BleCallback;
-use libtock::simple_ble::BleDriver;
+use libtock::simple_ble::BleScanningDriver;
+use libtock::Drivers;
 use serde::Deserialize;
 
 #[derive(Deserialize)]
@@ -17,19 +17,31 @@ struct LedCommand {
 
 #[libtock::main]
 async fn main() -> TockResult<()> {
-    let mut shared_buffer = BleDriver::create_scan_buffer();
-    let mut my_buffer = BleDriver::create_scan_buffer();
-    let shared_memory = BleDriver::share_memory(&mut shared_buffer)?;
+    let Drivers {
+        led_driver_factory,
+        mut ble_scanning_driver,
+        ..
+    } = libtock::retrieve_drivers()?;
+
+    let led_driver = led_driver_factory.create_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 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::get(msg.nr as usize).map(|led| led.set_state(msg.st)));
+            .and_then(|msg| {
+                led_driver
+                    .get(msg.nr as usize)
+                    .map(|led| led.set_state(msg.st))
+            });
     });
 
-    let _subscription = BleDriver::start(&mut callback)?;
+    let _subscription = ble_scanning_driver.start(&mut callback)?;
 
     future::pending().await
 }

examples/blink.rs

@@ -1,26 +1,31 @@
 #![no_std]
 
-use libtock::led;
 use libtock::result::TockResult;
-use libtock::timer;
 use libtock::timer::Duration;
+use libtock::Drivers;
 
 #[libtock::main]
 async fn main() -> TockResult<()> {
-    let num_leds = led::count()?;
-    let context = timer::DriverContext::create()?;
-    let mut driver = context.create_timer_driver()?;
+    let Drivers {
+        led_driver_factory,
+        timer_context,
+        ..
+    } = libtock::retrieve_drivers()?;
+
+    let mut driver = timer_context.create_timer_driver();
     let timer_driver = driver.activate()?;
+    let led_driver = led_driver_factory.create_driver()?;
 
     // 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 i in 0..num_leds {
+        for led in led_driver.all() {
+            let i = led.number();
             if count & (1 << i) == (1 << i) {
-                led::get(i).unwrap().on()?;
+                led.on()?;
             } else {
-                led::get(i).unwrap().off()?;
+                led.off()?;
             }
         }
         count = count.wrapping_add(1);

examples/blink_random.rs

@@ -1,38 +1,45 @@
 #![no_std]
 
-use libtock::led;
+use libtock::led::LedDriver;
 use libtock::result::TockResult;
-use libtock::rng;
-use libtock::timer;
 use libtock::timer::Duration;
+use libtock::Drivers;
 
 #[libtock::main]
 async fn main() -> TockResult<()> {
-    let context = timer::DriverContext::create()?;
-    let mut driver = context.create_timer_driver()?;
+    let Drivers {
+        timer_context,
+        mut rng_driver,
+        led_driver_factory,
+        ..
+    } = libtock::retrieve_drivers()?;
+
+    let led_driver = led_driver_factory.create_driver()?;
+
+    let mut driver = timer_context.create_timer_driver();
     let timer_driver = driver.activate()?;
 
-    let num_leds = led::count()?;
+    let num_leds = led_driver.count()?;
     // blink_nibble assumes 4 leds.
     assert_eq!(num_leds, 4);
 
     let mut buf = [0; 64];
     loop {
-        rng::fill_buffer(&mut buf).await?;
+        rng_driver.fill_buffer(&mut buf).await?;
 
         for &x in buf.iter() {
-            blink_nibble(x)?;
+            blink_nibble(x, &led_driver)?;
             timer_driver.sleep(Duration::from_ms(100)).await?;
-            blink_nibble(x >> 4)?;
+            blink_nibble(x >> 4, &led_driver)?;
             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) -> TockResult<()> {
+fn blink_nibble(x: u8, led_driver: &LedDriver) -> TockResult<()> {
     for i in 0..4 {
-        let led = led::get(i).unwrap();
+        let led = led_driver.get(i).unwrap();
         if (x >> i) & 1 != 0 {
             led.on()?;
         } else {

examples/button_leds.rs

@@ -1,16 +1,23 @@
 #![no_std]
 
 use futures::future;
-use libtock::buttons;
 use libtock::buttons::ButtonState;
-use libtock::led;
 use libtock::result::TockResult;
+use libtock::Drivers;
 
 #[libtock::main]
 async fn main() -> TockResult<()> {
-    let mut with_callback = buttons::with_callback(|button_num: usize, state| {
+    let Drivers {
+        led_driver_factory,
+        button_driver,
+        ..
+    } = libtock::retrieve_drivers()?;
+
+    let led_driver = led_driver_factory.create_driver()?;
+
+    let mut with_callback = button_driver.with_callback(|button_num: usize, state| {
         match state {
-            ButtonState::Pressed => led::get(button_num).unwrap().toggle().ok().unwrap(),
+            ButtonState::Pressed => led_driver.get(button_num).unwrap().toggle().ok().unwrap(),
             ButtonState::Released => (),
         };
     });

examples/button_read.rs

@@ -1,23 +1,26 @@
 #![no_std]
 
 use core::fmt::Write;
-use libtock::buttons;
 use libtock::buttons::ButtonState;
-use libtock::console::Console;
 use libtock::result::TockResult;
-use libtock::timer;
 use libtock::timer::Duration;
+use libtock::Drivers;
 
 #[libtock::main]
 async fn main() -> TockResult<()> {
-    let mut console = Console::default();
-    let mut with_callback = buttons::with_callback(|_, _| {});
+    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 context = timer::DriverContext::create()?;
-    let mut driver = context.create_timer_driver()?;
+    let mut driver = timer_context.create_timer_driver();
     let timer_driver = driver.activate()?;
 
     loop {

examples/button_subscribe.rs

@@ -2,17 +2,20 @@
 
 use core::fmt::Write;
 use futures::future;
-use libtock::buttons;
 use libtock::buttons::ButtonState;
-use libtock::console::Console;
 use libtock::result::TockResult;
+use libtock::Drivers;
 
 // FIXME: Hangs up when buttons are pressed rapidly. Yielding in callback leads to stack overflow.
 #[libtock::main]
 async fn main() -> TockResult<()> {
-    let mut console = Console::default();
-
-    let mut with_callback = buttons::with_callback(|button_num: usize, state| {
+    let Drivers {
+        console_driver,
+        button_driver,
+        ..
+    } = libtock::retrieve_drivers()?;
+    let mut console = console_driver.create_console();
+    let mut with_callback = button_driver.with_callback(|button_num: usize, state| {
         writeln!(
             console,
             "Button: {} - State: {}",

examples/gpio.rs

@@ -1,17 +1,20 @@
 #![no_std]
 
-use libtock::gpio::GpioPinUnitialized;
 use libtock::result::TockResult;
-use libtock::timer;
 use libtock::timer::Duration;
+use libtock::Drivers;
 
 // Example works on P0.03
 #[libtock::main]
 async fn main() -> TockResult<()> {
-    let pin = GpioPinUnitialized::new(0);
+    let Drivers {
+        timer_context,
+        gpio_driver,
+        ..
+    } = libtock::retrieve_drivers()?;
+    let pin = gpio_driver.pin(0)?;
     let pin = pin.open_for_write()?;
-    let context = timer::DriverContext::create()?;
-    let mut driver = context.create_timer_driver()?;
+    let mut driver = timer_context.create_timer_driver();
     let timer_driver = driver.activate()?;
 
     loop {

examples/gpio_read.rs

@@ -1,21 +1,24 @@
 #![no_std]
 
 use core::fmt::Write;
-use libtock::console::Console;
-use libtock::gpio::GpioPinUnitialized;
 use libtock::gpio::InputMode;
 use libtock::result::TockResult;
-use libtock::timer;
 use libtock::timer::Duration;
+use libtock::Drivers;
 
 // example works on p0.03
 #[libtock::main]
 async fn main() -> TockResult<()> {
-    let mut console = Console::default();
-    let pin = GpioPinUnitialized::new(0);
+    let Drivers {
+        console_driver,
+        timer_context,
+        gpio_driver,
+        ..
+    } = libtock::retrieve_drivers()?;
+    let mut console = console_driver.create_console();
+    let pin = gpio_driver.pin(0)?;
     let pin = pin.open_for_read(None, InputMode::PullDown)?;
-    let context = timer::DriverContext::create()?;
-    let mut driver = context.create_timer_driver()?;
+    let mut driver = timer_context.create_timer_driver();
     let timer_driver = driver.activate()?;
 
     loop {