libtock-rs

If you prefer a synchronous programming model over the default asynchronous callback model, use SyncAdapter from the libtock_sync crate.

SyncAdapter wraps a Syscalls implementation and uses a MethodCallback to capture asynchronous responses. You can then call .wait() to block (via yieldk) until the response is available.

// Example usage pattern
let mut sync_adapter = SyncAdapter::new(syscalls);
// ... trigger async operation ...
let response = sync_adapter.wait();

If you want to minimize your dependency tree and avoid pulling in optional dependencies, use libtock_core instead of the full libtock crate.

libtock_core can be found in the core/ directory of the repository.

Integration tests in libtock-rs are actual Tock process binaries. Unlike unit tests, these are designed to run on either an emulated Tock system or a real Tock hardware system.

Integration tests are located in the tests/ directory of the libtock crate.

To avoid name collisions on crates.io, most crates in this repository use the libtock prefix (e.g., libtock_gpio).

• Public/Driver Crates: Use the libtock_ prefix.
• Internal Crates: Crates intended only for internal use (such as syscall_tests) do not use the prefix.
• Directory Names: The actual directory names within the repository do not include the libtock_ prefix.

To avoid circular dependencies and Rust lifetime/drop-check issues between fake::Kernel and fake::SyscallDriver, the design uses a DriverShareRef pattern.

Instead of drivers holding a direct reference to the fake::Kernel, they receive a DriverShareRef. This handle provides access to ShareData (which contains common data like the upcall queue) without requiring lifetime parameters. This allows the unit test case to own both the kernel and the drivers directly.

DriverShareRef is provided to drivers via a registration method on the SyscallDriver trait.

struct DriverShareRef {
    driver_num: u32,
    share_data: Rc<ShareData>,
}

trait SyscallDriver {
    /* ... */

    fn register(&self, share_ref: DriverShareRef);
}

To run libtock-rs code on a development machine or in CI, the library uses a platform abstraction layer. Most crates in the repository are designed to be platform-independent to facilitate this.

To enable testing, you must provide an implementation of the libtock_platform::Syscalls trait. There are two primary ways to do this:

1. For Unit Tests: Use the libtock_unittest crate. This provides a 'fake kernel' implementation of the Syscalls trait and relies on the Rust std library for the runtime.
2. For Real Tock Processes: Use the libtock_runtime crate. This provides the actual syscall interface to the Tock kernel and includes the necessary linker scripts and Rust runtime to start a Tock process binary.

The libtock_platform crate provides core abstractions used by drivers in libtock_core. Its primary purpose is to offer lightweight asynchronous APIs that are more efficient in terms of code size and RAM usage than standard Rust futures.

Key features include:

• Asynchronous Abstractions: Provides traits like FreeCallback to handle asynchronous responses without the overhead of full Rust futures.
• Platform Agnostic Traits: Defines generic traits (e.g., FreeCallback<AsyncResponse>) that allow drivers to be implemented once and used across different environments, including unit tests running on host machines (like Linux) rather than on Tock hardware.

When using ufmt, be aware of its design priorities, which influence how the generated code behaves:

1. Optimization: Prioritizes binary size and execution speed over compilation time.
2. No Dynamic Dispatch: The generated code avoids dynamic dispatch to remain efficient.
3. Panic-Free: When optimized, the generated code contains no panicking branches.
4. Minimal Recursion: The implementation avoids recursion wherever possible to save stack space.