| # Device Abstraction | |
| Status: Draft | |
| The OpenPRoT Driver Development Kit (Device Development Kit) provides a set of | |
| generic Rust traits and types for interacting with I/O peripherals and | |
| cryptographic algorithm accelerators encountered in the class of devices that | |
| perform Root of Trust (RoT) functions. | |
| The DDK isolates the OpenPRoT developer from the underlying embedded processor | |
| and operating system. | |
| ## Scope | |
| This section provides a non-exhaustive list of peripherals that fall within the | |
| scope of the Device Driver Kit (DDK). | |
| ### I/O Peripherals | |
| | Device | Description | | |
| | :--------------------------- | :----------------------------------------- | | |
| | **SMBus/I2C Monitor/Filter** | | | |
| | **Delay** | Delay execution for specified durations in microseconds or milliseconds. | | |
| ### Cryptographic Functions | |
| Cryptographic Algorithm | Description | |
| :---------------------- | :---------------------------------- | |
| **AES** | Symmetric encryption and decryption | |
| **ECC** | ECDSA signature and verification | |
| **digest** | Cryptographic hash functions | |
| **RSA** | RSA signature and verification | |
| We will refer to the collection of I/O peripherals and cryptographic algorithm | |
| accelerators as peripherals from now on. | |
| ## Design Goals | |
| ### Platform Agnostic | |
| The goal of the DDK is to provide a consistent and flexible interface for | |
| applications to invoke peripheral functionality, regardless of whether the | |
| interaction with the underlying peripheral driver is through system calls to a | |
| kernel mode device driver, inter-task communication or direct access to | |
| memory-mapped peripheral registers. | |
| ### Execution Model Agnostic | |
| The DDK should be agnostic of the execution model and provide flexibility for | |
| its users. | |
| The collection of traits in the DDK is to be segregated in different crates | |
| according to the APIs it exposes. i.e. synchronous, asynchronous, and | |
| non-blocking APIs. | |
| These crates ensure that DDK can cater to various execution models, making it | |
| versatile for different application requirements. | |
| * Synchronous APIs: The main open-prot-ddk crate contains blocking traits | |
| where operations are performed synchronously before returning. | |
| * Asynchronous APIs: The open-prot-ddk-async crate provides traits for | |
| asynchronous operations using Rust's async/await model. | |
| * Non-blocking APIs: The open-prot-ddk-nb crate offers traits for non-blocking | |
| operations which allows for polling-based execution. | |
| ## Design Principles | |
| ### Minimalism | |
| The design of the DDK prioritizes simplicity, making it straightforward for | |
| developers to implement. By avoiding unnecessary complexity, it ensures that the | |
| core traits and functionalities remain clear and easy to understand. | |
| ### Zero Cost | |
| This principle ensures that using the DDK introduces no additional overhead. In | |
| other words, the abstraction layer should neither slow down the system nor | |
| consume more resources than direct hardware access. | |
| ### Composability | |
| The HAL shall be designed to be modular and flexible, allowing developers to | |
| easily combine different components. This composability means that various | |
| drivers and peripherals can work together seamlessly, making it easier to build | |
| complex systems from simple, reusable parts. | |
| ### Robust Error Handling | |
| Trait methods must be designed to handle potential failures, as hardware | |
| interactions can be unpredictable. This means **that methods invoking hardware | |
| should return a Result type to account for various failure scenarios,** | |
| including misconfiguration, power issues, or disabled hardware. | |
| ```rust | |
| pub trait SpiRead<W> { type Error; | |
| fn read(&mut self, words: &mut [W]) -> Result<(), Self::Error>; | |
| } | |
| ``` | |
| While the default approach should be to use fallible methods, HAL | |
| implementations can also provide infallible versions if the hardware guarantees | |
| no failure. This ensures that generic code can rely on robust error handling, | |
| while platform-specific code can avoid unnecessary boilerplate when appropriate. | |
| ```rust | |
| use core::convert::Infallible; | |
| pub struct MyInfallibleSpi; | |
| impl SpiRead<u8> for MyInfallibleSpi { | |
| type Error = Infallible; | |
| fn read(&mut self, words: &mut [u8]) -> Result<(), Self::Error> { | |
| // Perform the read operation | |
| Ok(()) | |
| } | |
| } | |
| ``` | |
| ### Separate Control and Data Path Operations {#separate-control-and-data-path-operations} | |
| * Clarity: By separating configuration (control path) from data transfer (data | |
| path), each part of the code has a clear responsibility. This makes the code | |
| easier to understand and maintain. | |
| * Modularity: It allows for more modular design, where control and data | |
| handling can be developed and tested independently. | |
| Example | |
| This example is extracted from Tock's TRD3 design document. Uart functionality | |
| is decomposed into fine grained traits defined for control path (Configure) and | |
| data path operations (Transmit and Receive). | |
| ```rust | |
| pub trait Configure { | |
| fn configure(&self, params: Parameters) -> ReturnCode; | |
| } | |
| pub trait Transmit<'a> { | |
| fn set_transmit_client(&self, client: &'a dyn TransmitClient); | |
| fn transmit_buffer( | |
| &self, | |
| tx_buffer: &'static mut [u8], | |
| tx_len: usize, | |
| ) -> (ReturnCode, Option<&'static mut [u8]>); | |
| fn transmit_word(&self, word: u32) -> ReturnCode; | |
| fn transmit_abort(&self) -> ReturnCode; | |
| } | |
| pub trait Receive<'a> { | |
| fn set_receive_client(&self, client: &'a dyn ReceiveClient); | |
| fn receive_buffer( | |
| &self, | |
| rx_buffer: &'static mut [u8], | |
| rx_len: usize, | |
| ) -> (ReturnCode, Option<&'static mut [u8]>); | |
| fn receive_word(&self) -> ReturnCode; | |
| fn receive_abort(&self) -> ReturnCode; | |
| } | |
| pub trait Uart<'a>: Configure + Transmit<'a> + Receive<'a> {} | |
| pub trait UartData<'a>: Transmit<'a> + Receive<'a> {} | |
| ``` | |
| #### Use Case : Device Sharing | |
| * **Peripheral Client Task**: This task is only exposed to data path | |
| operations, such as reading from or writing to the peripheral. It interacts | |
| with the peripheral server to perform these operations without having direct | |
| access to the configuration settings. | |
| * **Peripheral Server Task**: This task is responsible for managing and | |
| sharing the peripheral functionality across multiple client tasks. It has | |
| the exclusive role of configuring the peripheral for data transfer | |
| operations, ensuring that all configuration changes are centralized and | |
| controlled. This separation allows for robust access control and simplifies | |
| the management of peripheral settings. | |
| ## Methodology | |
| In order to accomplish this goal in an efficient fashion the DDK should not try | |
| to reinvent the wheel but leverage existing work in the Rust community such as | |
| the Embedded Rust Workgroup's embedded-hal or the RustCrypto projects. | |
| As much as possible, the OpenPRoT workgroup should evaluate, curate, and | |
| recommend existing abstractions that have already gained wide adoption. | |
| By leveraging well-established and widely accepted abstractions, the DDK can | |
| ensure compatibility, reliability, and ease of integration across various | |
| platforms and applications. This approach not only saves development time and | |
| resources but also promotes standardization and interoperability within the | |
| ecosystem. | |
| When abstractions need to be invented, as is the case for the I3C protocol, for | |
| instance the OpenPRot workgroup will design it according to the community | |
| guidelines for the project it is curating from and make contributions upstream. | |
| ## Use Cases | |
| This section illustrates the contexts where the DDK can be used. | |
| ### Low Level Driver | |
| A low level driver implements a peripheral (or a cryptographic algorithm) driver | |
| trait by accessing memory mapped registers directly and it is distributed as a | |
| `no_std` crate. | |
| A `no_std` crate like the one depicted below would be linked directly into a | |
| user mode task with exclusive peripheral ownership. This use case is encountered | |
| in microkernel-based embedded operating systems such as openprot's kernel, | |
| Pigweed's `pw_kernel`, where drivers run in unprivileged mode. | |
| <img src="figure1.png" alt="figure1" width="300"/> | |
| ### Proxy for a Kernel Mode Device Driver | |
| In this section, we explore how a trait from the Device Development Kit (DDK) | |
| can enhance portability by decoupling the application writer from the underlying | |
| embedded stack. | |
| The user of the peripheral is an application that is interacting with a kernel | |
| mode device driver via system calls, but is completely isolated from the | |
| underlying implementation. | |
| This is applicable to any O/S with device drivers living in the kernel, like the | |
| Tock O/S. | |
| <img src="figure2.png" alt="figure2" width="500"/> | |
| ### Proxy for a Peripheral Server Task | |
| In this section, we will explore once more how traits from the Device | |
| Development Kit (DDK) can enhance portability by decoupling the application | |
| writer from the underlying Operating System architecture. This scenario is | |
| applicable to any microkernel-based O/S | |
| The xyz-i2c-ipc-impl depicted below is distributed as a `no_std` driver crate | |
| and is linked to a I2C client task. The I2C client task is an application that | |
| is interacting with a user mode device driver, named the I2C server task via | |
| message passing. | |
| The I2C Server task owns the actual peripheral and is linked to a | |
| xyz-i2c-drv-imp driver crate, which is a low-level driver. . | |
| <img src="figure3.png" alt="figure3" width="600"/> | |
| The I2C client task sends requests to the I2C peripheral owned by the server | |
| task via message passing, completely oblivious to the underlying implementation. | |
| <img src="figure4.png" alt="figure4" width="600"/> |