Device

A device models the target of the driver (typically a chip you can reach over e.g. SPI). A manifest can contain multiple devices. A driver will typically contain at least one device.

A device is spiritually the same as a block, except it can set some configs and serves as the root of the blocks.

Example usage:

// Create a device by giving it ownership of a compatible interface
let mut device = MyDevice::new(DeviceInterface::new());

// Use the operations defined on the device
device.foo().read()?;

// When supported, start bulk operations on the device (or any block)
use device_driver::Block; // Must import trait
let (foo, bar) = device
    .bulk_read()
    .with(|d| d.foo().plan())
    .with(|d| d.bar().plan())
    .execute()?;

Example

/// doc comment line
device Example {
    default-byte-order: LE,
    register-address-type: i32,
    command-address-type: i32,
    buffer-address-type: i32,
    word-boundaries: "bD:0B:_",
    register-address-mode: mapped,
    default-access: RW,
    address-offset: 0,

    block node,
    register node,
    command node,
    buffer node,
    fieldset node,
    enum node,
    extern node,
}

Table

Long properties

These properties are specified in the node body.

default-byte-order

Sets the default byte order used by fieldsets in this device. This can be overridden per fieldset.

// byte order
default-byte-order: LE

Info

• required: no
• multiple allowed: no
• supports doc comments: no

register-address-type

Sets the type used to address the registers in this device.

// integer type
register-address-type: i32

Info

• required: no
• multiple allowed: no
• supports doc comments: no

command-address-type

Sets the type used to address the commands in this device.

// integer type
command-address-type: i32

Info

• required: no
• multiple allowed: no
• supports doc comments: no

buffer-address-type

Sets the type used to address the buffers in this device.

// integer type
buffer-address-type: i32

Info

• required: no
• multiple allowed: no
• supports doc comments: no

word-boundaries

Sets the word splitting rules for all objects defined in the device.

This option exists to aid in copying names from the datasheet. Those names are often not proper names for types and operations. So by setting the rules, the compiler can split identifiers into good proper words and then convert them to the required casing. The splitting is done with convert_case using their string representation for boundaries.

In short, place a colon (:) between every boundary. Then each boundary follows the expressed pattern. For example aB will split words when a lower case letter is followed by an upper case letter. Some symbols are also allowed as boundary, like - & _.

If not specified, this uses a reasonable default for splitting.

// string
word-boundaries: "bD:0B:_"

Info

• required: no
• multiple allowed: no
• supports doc comments: no

register-address-mode

Sets the address mode for registers in this device.

When specified, the registers are assumed to share an address space:

• With the mapped option, that address space is a memory-mapped space where if register A has address X and is Y bytes big, then register B (if it exists) will have the address X+Y.
• With the indexed option, that address space has one register per number where if object A has address X, then object B (if it exists) will have the address X+1.

If this value is specified, then it permits bulk register reads and writes.

// address mode
register-address-mode: mapped

Info

• required: no
• multiple allowed: no
• supports doc comments: no

default-access

When set, all subobjects use this value as their access value (unless overridden) and don’t require an access specifier anymore

// access specifier
default-access: RW

Info

• required: no
• multiple allowed: no
• supports doc comments: no

address-offset

Defines the global address offset of this device. All objects in the device are relative to this offset. If this is not specified, the address offset defaults to 0.

// number
address-offset: 0

Info

• required: no
• multiple allowed: no
• supports doc comments: no

Possible subnodes

Subnodes of the following types are allowed in the node body.

• block
• register
• command
• buffer
• fieldset
• enum
• extern