Driver SDK reference

The Mota Driver SDK is for user-space drivers on Linux. A driver is an ordinary process that reaches its device through a standard kernel interface (hidraw, usbfs, VFIO or UIO) and hands what it produces to Mota through a standard sink:

 device ──(hidraw · usbfs · VFIO/UIO)──▶ driver process ──▶ sink ──▶ Mota
                                         (SDK runtime)      uinput  → keyboards, mice, pads
                                                            D-Bus   → org.motaos.Sensors
                                                            TAP     → a network interface
                                                            ublk    → /dev/ublkbN

mota-driverd (in mota-services) runs drivers: it watches for devices, starts the matching driver as a sandboxed systemd unit, restarts it if it crashes, and stops it when the device goes away.

To write your first driver, start with Your first Mota driver. This page is the reference. The API docs proper are the crate's rustdoc (cargo doc -p mota-driver-sdk --open in the Mota source tree).

Compatibility. Semver on the crate API and on the manifest schema. Drivers rebuild against a new major version; there is no binary ABI.

1. A driver

A driver is two files, installed under /usr/lib/mota/drivers/<name>/:

• mota-driver.toml: the manifest: what it is, which devices it takes, its settings;
• the executable (named after the driver unless driver.exec says otherwise).

use mota_driver::prelude::*;

struct MyDriver { /* devices, sinks */ }

impl Driver for MyDriver {
    async fn probe(ctx: &mut Context) -> Result<Self> {
        // Open ctx.require_device()?, create the sink. Err(Unsupported) declines.
        todo!()
    }
    async fn run(&mut self, ctx: &mut Context) -> Result<()> {
        // Do the work until the device goes away.
        todo!()
    }
}

fn main() -> std::process::ExitCode {
    mota_driver::run::<MyDriver>()
}

mota-driver new generates this for each class (see §7).

2. Manifest

mota-driver.toml, schema 1:

schema = 1

[driver]
name = "hid-remap"          # 1-48 of a-z, 0-9, '-'; also the package and directory name
version = "1.0.0"
class = "input"             # input | sensor | network | block
description = "Remaps keys on a HID keyboard"
# exec = "hid-remap"        # executable, default = name

[[match]]                   # one or more; each sets exactly one of:
hid = { vendor = 0x1209, product = 0x0001 }
# usb = { vendor = 0x046d, product = 0xc52b, interface_class = 0x03 }  # interface_class optional
# pci = { vendor = 0x1234, device = 0x11e8 }
# virtual = true            # no hardware: started once when installed / at boot

[config]                    # free-form; the driver reads it with ctx.config()
remap = { KEY_CAPSLOCK = "KEY_LEFTCTRL" }

Unknown keys are errors, so typos fail at load time. The class decides what the driver may reach (§6.3), not just what it's called.

3. Runtime

3.1 Driver and run

3.2 Context

3.3 Arguments and environment

mota-driverd starts a driver as <exec> --manifest <path> [--device <path>]. For testing by hand the same values can come from the environment:

3.4 Exit codes

3.5 Errors and logging

mota_driver::Error: Io, Manifest, Unsupported, NoDevice, Usb, Other. Which one you return decides the exit code above.

Logging goes to stderr and so to the journal (mota-driver logs <name>). The SDK re-exports the crate it sets up: mota_driver::tracing::info!(...).

4. Hardware access (mota_driver::hw)

4.1 hw::hid: HID devices through hidraw

mota_driver::keys has the Linux KEY_* codes, from_name / name, HID usage → key code mapping, and BootKeyboard, a decoder for boot-protocol keyboard reports.

4.2 hw::usb: USB devices through usbfs

4.3 hw::pci: PCI devices through VFIO or UIO

mota-driverd binds the device to a user-space back end before starting the driver (§6.2) and passes its sysfs path; PciDevice::open takes that or a bare address (0000:00:04.0).

A DMA to an address the driver didn't map is blocked by the IOMMU and reported by the kernel (DMAR: … fault addr …); the test suite checks this.

5. Sinks (mota_driver::sink)

5.1 sink::input: a virtual input device (uinput)

let mut kb = VirtualInput::builder("My pad")
    .keys(&[keys::KEY_A, keys::KEY_B])       // and/or .rel_axes(..), .abs_axis(..)
    .id(input::BUS_USB, 0x1209, 0x0001, 1)   // optional
    .build()?;
kb.key(keys::KEY_A, true)?; kb.sync()?;      // or kb.tap(KEY_A)

Events go through evdev → libinput → the compositor like any keyboard or mouse. Only declared keys/axes can be sent. Dropping it removes the device.

5.2 sink::sensor: readings on org.motaos.Sensors

let bus = SensorBus::connect().await?;
let s = bus.register("cpu", "CPU package", Kind::Temperature).await?;  // id unique within the driver
s.publish(54.5).await?;

Each kind has one fixed unit, so readers never convert:

Sensor ids are <driver>/<id>. Only a running sensor-class driver started by mota-driverd may register or publish, and only for its own sensors; they disappear when the driver stops.

5.3 sink::net: a network interface (TAP)

let tap = Tap::builder().name("mnet%d").mtu(1500).build()?;   // .mac([..]) optional
tap.set_carrier(true)?;                       // link up/down as NetworkManager sees it
let n = tap.recv(&mut buf).await?;            // a frame the system sent
tap.send(&frame).await?;                      // a frame "received from the wire"

The interface is an ordinary Ethernet link: NetworkManager lists it and the kernel routes through it. set_ipv4(addr, prefix) is for tunnel-style drivers that own their addressing; a driver for a real NIC leaves addressing to NetworkManager. frame_size() is the buffer size recv needs. Dropping the Tap removes the interface.

5.4 sink::block: a disk (ublk)

struct Disk { /* your device */ }
impl BlockHandler for Disk {
    fn read(&mut self, offset: u64, buf: &mut [u8]) -> io::Result<()> { .. }
    fn write(&mut self, offset: u64, buf: &[u8]) -> io::Result<()> { .. }
    fn flush(&mut self) -> io::Result<()> { Ok(()) }   // optional
}
let disk = BlockDevice::builder().size(64 << 20)   // .block_size(4096) .queue_depth(..) .read_only(..)
    .build(Disk { .. })?;                          // /dev/ublkbN
disk.wait().await                                  // in run(): until stopped from outside

The handler runs on its own thread, one request at a time, so it may block (it can use Irq::wait_blocking). Offsets and lengths are bytes and always fall inside the disk. Dropping the BlockDevice drains in-flight I/O and removes the disk. If a driver dies without that, the kernel keeps a dead ublk device; the next build() deletes dead devices whose server is gone, so a restarted driver gets its old /dev/ublkbN back.

6. mota-driverd

6.1 Binding

driverd scans sysfs at start and then follows kernel uevents. A device is bound to the first enabled driver whose [[match]] accepts it:

Unplugging stops the unit. Driver units are independent of driverd: they keep running across a driverd restart and are adopted again.

6.2 PCI devices

driverd takes a PCI function only if no kernel driver owns it (or it is already on vfio-pci / uio_pci_generic). It never unbinds a kernel driver; to give a kernel-driven device to a Mota driver, blacklist the kernel driver. A matching but kernel-owned device is logged once and left alone.

With an IOMMU group it binds the device to vfio-pci, otherwise to uio_pci_generic. When the driver stops (disabled, uninstalled), the device is unbound and left with no driver, as it was found.

6.3 Sandbox

Every driver runs as a transient unit with: NoNewPrivileges, ProtectSystem=strict, ProtectHome, PrivateTmp, kernel tunables / modules / logs / control groups / clock / hostname protected, MemoryDenyWriteExecute, RestrictNamespaces, native syscalls only, DevicePolicy=closed, and per class:

A PCI driver additionally gets /dev/vfio/vfio + /dev/vfio/<group> and a 256 MiB LimitMEMLOCK (VFIO), or /dev/uioN and its device's sysfs directory writable (UIO). Nothing else from /dev.

6.4 Restarts and states

A crash restarts the driver after 500 ms. Exit codes 3 and 4 never restart. After 4 starts in 5 minutes systemd stops restarting; driverd shows the binding as disabled and notifies the user. mota-driver enable (or replugging) clears it.

Binding states: starting, running, stopped, unsupported (probe declined), disabled (crash loop), failed (couldn't start).

6.5 D-Bus: org.motaos.Drivers

System bus, object /org/motaos/Drivers.

6.6 D-Bus: org.motaos.Sensors

System bus, object /org/motaos/Sensors.

7. mota-driver CLI

Packages

mota-driver package installs the executable and manifest to /usr/lib/mota/drivers/<name>/, depends on mota-services, and calls Reload from postinst / postrm, so installing a driver binds matching devices at once and removing it stops them.

8. Testing

The scripts run as root inside a Mota VM (see their headers).

9. Examples (sdk/drivers/)

10. Limits in 1.2

• Classes are input, sensor, network and block. There is no display or audio class (those stay with the compositor and PipeWire).
• Block devices have one queue and a synchronous handler.
• Without an IOMMU, PCI drivers have no DMA.
• A device a kernel driver owns is never taken automatically.
• No binary compatibility between SDK major versions; rebuild.