device-driver Toolkit

The device-driver toolkit is a Rust-based framework designed to automate the creation of safe, documented hardware device drivers. It solves two primary pain points in driver development:

1. Complex Data Structures: It provides battle-tested data structures for representing hardware interfaces.
2. Manual Definition Work: It uses code generation (via a macro DSL or YAML configuration) so developers only need to define the unique aspects of their hardware.

The toolkit focuses on correctness, ease of use, and high-quality documentation by providing a dense input language, support for various byte/bit orderings, and analysis steps to catch common mistakes.

The device-driver-lexer crate is part of the Device Driver Toolkit, designed to help developers write better device drivers more efficiently.

Warning: This is an internal crate and is not intended for public usage. It does not follow Semantic Versioning (SemVer). If you choose to use it in your project, you must pin the version to prevent breaking changes from unexpected updates.

The device-driver toolkit is designed to help developers write hardware drivers more efficiently. It uses a custom domain-specific language called DDSL (device driver specification language) as input to define hardware registers and fields.

Drivers generated with this toolkit are compatible with any no-std context and can be integrated with the embedded-hal crate or any custom hardware interfaces. It is particularly well-suited for peripherals communicating over buses like I2C, SPI, or parallel buses (e.g., accelerometers, radio transceivers, or displays).

register SYNT {
    address: 0x05,
    reset: 0x42162762,
    fields: fieldset _ {
        size-bytes: 4,
        byte-order: BE,
        
        field PLL_CP_ISEL 31:29 -> uint,
        field BS 28 -> bool,
        field SYNT 27:0 -> uint
    }
}

A Fieldset is a collection of fields that represent the data within a register, a command input, or a command output. It defines a specific type where individual fields are accessible via getter and setter methods named after the fields.

While users typically do not need to construct fieldsets manually, you can do so for special cases. Fieldsets also support bitwise operators (e.g., !, ^, &) which operate on all underlying bits, including those not explicitly part of a defined field. Additionally, fieldsets implement Into and From for byte arrays of the same size.

use device_driver::Fieldset;

let mut reg = MyFieldSet::ZERO;
reg.set_foo(1234);
let foo = reg.foo();

To make driver code more readable, you can map bit patterns to meaningful names using enums. This can be done inline within a field definition.

• Infallible conversion: Use -> _ as enum _ when the enum covers all possible bit patterns.
• Fallible conversion: Use -> _ as try enum _ when the enum might not cover all possible bit patterns.

Example of an inline enum conversion:

field tremolo_depth 7 -> _ as enum _ {
    Low: 0b0,
    High: 0b1,
}

field tremolo_depth 7 -> _ as enum _ {
    /// 1.0dB
    Low: 0b0,
    /// 4.8dB
    High: 0b1,
}

Devices and blocks are the primary containers for operations.

• Devices: The root block. It always has an address-offset of 0. You can construct a device using its generated new function with an owned interface value. To release the device and reclaim the interface, call the free function.
• Blocks: Nested structures within devices or other blocks.
• The Block Trait: Both devices and blocks implement the Block trait, providing raw interface access and the ability to start bulk operations.

Note on Bulk Operations: A bulk operation only has access to the specific device or block it was started on. If an operation requires access to the entire device hierarchy, ensure you start the bulk operation on the device itself.

The device-driver library uses a trait-based system to define what operations an interface can perform. Every type of hardware operation has a corresponding trait. If your interface implements these traits, the generated driver can perform those operations.

Core Trait Categories

• Register Interface: For reading and writing registers.
• Command Interface: For sending commands to the device.
• Buffer Interface: For buffer-based operations.

Async Support

For every synchronous trait, there is a corresponding Async version. When you implement the async trait, you can use the _async suffix on the driver's methods (e.g., .read_async().await).

A ref object allows you to create a copy of an existing object and provide overrides for specific attributes.

Syntax: ref <IDENTIFIER> = <OriginalObject>

// Assuming REG_A is defined elsewhere
register REG_B ref REG_A {
  const ADDRESS = 0x05;
}

In the Device Driver Specification Language (DDSSL), a command represents an operation. Commands are defined using an identifier followed by optional parameters in square brackets (like stride) and a body containing specific properties.

Commands belong to the Operation identifier namespace and support being repeated, but they do not support basetype, conversion type, or subnodes directly within the command definition itself.

/// doc comment line
command Example[8 stride 4] {
    address: 0,
    address-overlap: allow,
    fields-in: MyFieldset,
    fields-out: MyFieldset,
}