Device driver toolkit

A toolkit to write better device drivers, faster.

Head over to the website to learn about how to use the project to build your own device drivers.
There you'll find the book which contains the reference and a tutorial.

Use a simple specification language to define your driver:

device Ym3812 {
    register-address-type: u8,

    register operator_settings1 {
        address: 0x40,
        access: WO,

        fields: fieldset _ {
            size-bytes: 1,
            /// Causes output levels to decrease as the frequency rises
            field level_key_scaling 7:6 RW -> _ as enum ScalingLevel {
                NoChange: 0b00,
                DB3PerOctave: 0b01,
                DB1_5PerOctave: 0b10,
                DB6PerOctave: 0b11,
            },
            /// Attenuates the operator output level
            field output_level 5:0 RW,
        },
    },
}

Generate a rich svd2rust/chiptool-like driver API in Rust:

// Create device instance
let mut device = MyDevice::new(DeviceInterface::new());

// Write a register
device.foo().write(|reg| reg.set_value_1(MyEnum::B))?;

// Anything can be used async
device.foo().read_async().await?;

// Dispatch commands
device.simple_command().dispatch()?;

// Operate on registers in bulk
let (foo, bar) = device
    .bulk_read()
    .with(|d| d.foo().plan())
    .with(|d| d.bar().plan())
    .execute()?;

// Write and read buffers
device.wo_buf().write(&[0, 1, 2, 3])?;
let len = device.ro_buf().read(&mut buffer)?;

• v2: https://github.com/diondokter/device-driver
• v1: https://github.com/diondokter/device-driver/tree/v1

This toolkit consists of these parts:

• device-driver: The main crate you as the writer of a driver should include in your project. It is the runtime used by the generated code and offers an optional macro to easily compile DDSL code in your Rust project.
• compiler: The set of crates that form the compiler.
  • device-driver-cli: The source for the ddc binary, the traditional compiler executable for DDSL.
  • device-driver-macros: The compiler in Rust macro form.
  • device-driver-wasm: The compiler in wasm-bindgen form.
  • The rest are crates that make up parts of the compiler, split up to improve compile times.
• website: The source of the device-driver.com website.
• tests: A suite of tests that presents input files and compares the known output with the generated output.
• book: The mdbook with docs hosted on the website.

Of these, only the device-driver and device-driver-cli crates are considered public.

Anything that can reasonably break user code will warrant a breaking semver bump. This only holds if the user is only consuming 'public' device-driver code.

Increasing the MSRV is not considered a breaking change. Assume you need the latest stable version. The MSRV is encoded in the rust-version field of the Cargo.toml file.

Code licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

All non-code work, unless indicated otherwise, is licensed under CC BY 4.0, to be attributed to Dion Dokter & device-driver contributors.

All trademarks are owned by Dion Dokter.

Unless you explicitly state otherwise, any code contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Similarly, any non-code contribution shall be licenced under CC BY 4.0 and any trademark ownership shall be transferred to Dion Dokter.

Contributions must be in accordance with the notices in CONTRIBUTING.md.