synchronous api + example

Author: CosminGGeorgescu

apis/rng/src/lib.rs

@@ -1,2 +1,45 @@
+#![no_std]
+
 #[cfg(test)]
 mod tests;
+
+use core::cell::Cell;
+use libtock_platform::{share, AllowRw, DefaultConfig, ErrorCode, Subscribe, Syscalls};
+
+const DRIVER_NUM: u32 = 0x40001;
+const EXISTS: u32 = 0;
+const GET_BYTES: u32 = 1;
+
+pub struct Rng<S: Syscalls>(S);
+
+impl<S: Syscalls> Rng<S> {
+    /// Check if the RNG kernel driver exists
+    pub fn exists() -> Result<(), ErrorCode> {
+        S::command(DRIVER_NUM, EXISTS, 0, 0).to_result()
+    }
+
+    /// Ask to fill the provided `buf` with `n` random bytes.
+    /// If `n > buf.len()`, it will simply fill the whole buffer.
+    pub fn get_bytes_sync(buf: &mut [u8], n: u32) -> Result<(), ErrorCode> {
+        let called = Cell::new(false);
+        share::scope::<(AllowRw<S, DRIVER_NUM, 0>, Subscribe<S, DRIVER_NUM, 0>), _, _>(|handle| {
+            let (allow_ro, subscribe) = handle.split();
+
+            // Share the provided buffer with the kernel
+            S::allow_rw::<DefaultConfig, DRIVER_NUM, 0>(allow_ro, buf)?;
+
+            // Subscribe for an upcall with the kernel
+            S::subscribe::<_, _, DefaultConfig, DRIVER_NUM, 0>(subscribe, &called)?;
+
+            // Send the command to the kernel driver to fill the allowed_readwrite buffer
+            S::command(DRIVER_NUM, GET_BYTES, n, 0).to_result()?;
+
+            // Wait for a callback to happen
+            while !called.get() {
+                S::yield_wait();
+            }
+
+            Ok(())
+        })
+    }
+}

examples/rng.rs

@@ -0,0 +1,49 @@
+#![no_main]
+#![no_std]
+
+use core::fmt::Write;
+use libtock::alarm::Alarm;
+use libtock::console::Console;
+use libtock::rng::Rng;
+use libtock::runtime::{set_main, stack_size};
+use libtock_alarm::Milliseconds;
+
+set_main! {main}
+stack_size! {0x300}
+
+struct Randomness<'a, const N: usize>(&'a [u8; N]);
+
+impl<'a, const N: usize> core::fmt::Display for Randomness<'a, N> {
+    fn fmt(&self, _f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        let mut console_writer = Console::writer();
+        let mut bytes = self.0.iter();
+        while let Some(&byte) = bytes.next() {
+            write!(console_writer, "{byte:02x}")?;
+        }
+        Ok(())
+    }
+}
+
+fn main() {
+    if let Err(e) = Rng::exists() {
+        writeln!(
+            Console::writer(),
+            "RNG DRIVER DOESN'T EXIST\nERROR: {e:?}\n"
+        )
+        .unwrap();
+        return;
+    }
+
+    let mut buffer: [u8; 32] = Default::default();
+    let n: u32 = 32;
+    let mut console_writer = Console::writer();
+    loop {
+        match Rng::get_bytes_sync(&mut buffer, n) {
+            Ok(()) => {
+                write!(console_writer, "Randomness: {}\n", Randomness(&buffer)).unwrap();
+            }
+            Err(e) => writeln!(console_writer, "Error while getting bytes {e:?}\n").unwrap(),
+        }
+        Alarm::sleep_for(Milliseconds(2000)).unwrap();
+    }
+}

src/lib.rs

@@ -69,6 +69,10 @@ pub mod proximity {
     use libtock_proximity as proximity;
     pub type Proximity = proximity::Proximity<super::runtime::TockSyscalls>;
 }
+pub mod rng {
+    use libtock_rng as rng;
+    pub type Rng = rng::Rng<super::runtime::TockSyscalls>;
+}
 pub mod sound_pressure {
     use libtock_sound_pressure as sound_pressure;
     pub type SoundPressure = sound_pressure::SoundPressure<super::runtime::TockSyscalls>;

unittest/src/fake/mod.rs

@@ -22,6 +22,7 @@ mod leds;
 mod low_level_debug;
 mod ninedof;
 mod proximity;
+mod rng;
 mod sound_pressure;
 mod syscall_driver;
 mod syscalls;
@@ -40,6 +41,7 @@ pub use leds::Leds;
 pub use low_level_debug::{LowLevelDebug, Message};
 pub use ninedof::{NineDof, NineDofData};
 pub use proximity::Proximity;
+pub use rng::Rng;
 pub use sound_pressure::SoundPressure;
 pub use syscall_driver::SyscallDriver;
 pub use syscalls::Syscalls;

unittest/src/fake/rng/mod.rs

@@ -0,0 +1,83 @@
+use libtock_platform::ErrorCode;
+
+use crate::{DriverInfo, DriverShareRef, RwAllowBuffer};
+use std::cell::{Cell, RefCell};
+use std::ops::DerefMut;
+
+pub struct Rng {
+    busy: Cell<bool>,
+    share_ref: DriverShareRef,
+    buffer: RefCell<RwAllowBuffer>,
+    bytes: Cell<Vec<u8>>,
+}
+
+impl Rng {
+    pub fn new() -> std::rc::Rc<Rng> {
+        std::rc::Rc::new(Rng {
+            busy: Cell::new(false),
+            share_ref: Default::default(),
+            buffer: Default::default(),
+            bytes: Default::default(),
+        })
+    }
+
+    pub fn is_busy(&self) -> bool {
+        self.busy.get()
+    }
+}
+
+impl crate::fake::SyscallDriver for Rng {
+    fn info(&self) -> crate::DriverInfo {
+        DriverInfo::new(DRIVER_NUM).upcall_count(1)
+    }
+
+    fn register(&self, share_ref: DriverShareRef) {
+        self.share_ref.replace(share_ref);
+    }
+
+    fn command(&self, command_id: u32, argument0: u32, _: u32) -> libtock_platform::CommandReturn {
+        match command_id {
+            EXISTS => crate::command_return::success(),
+            GET_BYTES => {
+                if self.busy.get() {
+                    return crate::command_return::failure(ErrorCode::Busy);
+                }
+                self.busy.set(true);
+                // Mutably borrows RwAllowBuffer from the RefCell as to not take the buffer out
+                let mut allow_rw_buffer = self.buffer.borrow_mut();
+                let inner_buffer = (*allow_rw_buffer).deref_mut();
+                inner_buffer.copy_from_slice(
+                    &self.bytes.take()[0..core::cmp::min(inner_buffer.len(), argument0 as usize)],
+                );
+                crate::command_return::success()
+            }
+            _ => crate::command_return::failure(ErrorCode::NoSupport),
+        }
+    }
+
+    fn allow_readwrite(
+        &self,
+        buffer_num: u32,
+        buffer: crate::RwAllowBuffer,
+    ) -> Result<crate::RwAllowBuffer, (crate::RwAllowBuffer, libtock_platform::ErrorCode)> {
+        if buffer_num == 0 {
+            Ok(self.buffer.replace(buffer))
+        } else {
+            Err((buffer, ErrorCode::Invalid))
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests;
+
+// -----------------
+// RNG DRIVER NUMBER
+// -----------------
+const DRIVER_NUM: u32 = 0x40001;
+
+// -------------------
+// RNG COMMAND NUMBERS
+// -------------------
+const EXISTS: u32 = 0;
+const GET_BYTES: u32 = 1;

unittest/src/fake/rng/tests.rs

@@ -0,0 +1,52 @@
+use libtock_platform::{share, DefaultConfig};
+
+use crate::{fake, RwAllowBuffer};
+
+// Tests the command implementation.
+#[test]
+fn command() {
+    use fake::SyscallDriver;
+
+    let rng = fake::Rng::new();
+
+    // Test driver response to an existence check request
+    assert!(rng.command(fake::rng::EXISTS, 0, 0).is_success());
+
+    // Test driver response for sharing a buffer
+    // to a valid and invalid buffer index, respectively
+    assert!(rng.allow_readwrite(0, RwAllowBuffer::default()).is_ok());
+    assert!(rng.allow_readwrite(1, RwAllowBuffer::default()).is_err());
+}
+
+// Integration test that verifies Console works with fake::Kernel and
+// libtock_platform::Syscalls.
+#[test]
+fn kernel_integration() {
+    use libtock_platform::Syscalls;
+
+    let kernel = fake::Kernel::new();
+    let rng = fake::Rng::new();
+    // Predetermined sample of RNG data "read" from the RNG low-level driver
+    // that will be put into the shared buffer
+    let bytes = [0_u8, 1_u8, 2_u8, 3_u8, 4_u8];
+    rng.bytes.set(bytes.to_vec());
+    kernel.add_driver(&rng);
+
+    // Test driver response to an existence check request
+    assert!(fake::Syscalls::command(fake::rng::DRIVER_NUM, 0, 0, 0).is_success());
+
+    // Buffer to be shared with the kernel and filled with random bytes
+    let mut buffer: [u8; 5] = [0; 5];
+    share::scope(|allow_rw| {
+        // Register the provided buffer
+        fake::Syscalls::allow_rw::<DefaultConfig, { fake::rng::DRIVER_NUM }, 0>(
+            allow_rw,
+            &mut buffer,
+        )
+        .unwrap();
+        // Test driver response to buffer fill requests
+        assert!(fake::Syscalls::command(fake::rng::DRIVER_NUM, 1, 5, 0).is_success());
+    });
+    // Additionally check that the buffer has been correctly filled
+    assert_eq!(buffer.cmp(&bytes), core::cmp::Ordering::Equal);
+}