Interfaces: buses and boards

interface family for app developers for Ubuntu Core developers for snapd developers for users for administrators

Hardware interfaces for GPIO, I2C, SPI, serial ports, TPM, TEE and accelerators: a slot on the system or declared by the gadget, a device rule plus a udev tag, and a connection made by hand except for accel.

On the map: interfaces district, family row

▶ Watch this deck — 9 scenes, ~7 min

01 The family pattern

BUSES AND BOARDS acme-agent on the gateway: an I2C sensor, a USB serial meter slot on the systemteetpmaccela fixed device rule and a udev tagthe device joins the app's device cgroupa fixed rule for the TPM device, plus a udev tag slot declared by the gadgetgpioi2cspiserial-portno system slot: the gadget snap declares itone slot per device, named by a slot attributea rule for the one I2C device named, plus a udev tag $ snap connect acme-agent:i2c pc:i2c-1both shapes: by hand, or by a store rule the exception: accel auto-connects on classic and on Ubuntu Corequalcomm-ipc-router auto-connects only between one publisher's snaps
acme-agent needs an I2C sensor and a USB serial meter; two shapes of hardware interface: a slot on the system with a device rule and a udev tag into the device cgroup, and a slot declared by the gadget whose attribute names one device; all connected by hand except accel

Two shapes: a system slot with a fixed device rule and a udev tag into the device cgroup, or a gadget slot whose attribute names one device. Every member except accel (and qualcomm-ipc-router between snaps of one publisher) denies auto-connection, so a connection is made by hand or granted by the store.

Your acme-agent on the gateway has to read a temperature sensor on an I2C bus and talk to a meter through a USB serial adapter. That's the kind of hardware this family covers: GPIO pins, I2C and SPI buses, serial-ports, the TPM, accelerators. The interfaces come in two shapes. Some have their slot on the system, with a fixed device rule and a udev tag that puts the device into the app's device-cgroup. Others have no system slot at all: the gadget snap declares one slot per device and names the device in an attribute. Either way, you connect them yourself. The exception is accel.

02 One pin, three interfaces

ONE PIN · THE RELAY gpioone pin per slotexported by a systemd unit/sys/class/gpio/gpio17/*sysfs ABI, deprecated gpio-chardevgadget slot: source chip and linessnap-gpio-helper buildsa virtual chip at boot/dev/snap/gpio-chardev/<slot-snap>/<slot>gadget-only slot gpio and gpio-chardev cannot be connected at the same time gpio-controlevery pin on every chip/dev/gpiochip[0-9]* rw,plus the whole sysfs gpio treesuper-privileged:a store declaration to install
Three GPIO interfaces for the gateway's relay pin: gpio for one pin over sysfs, gpio-chardev for chosen lines through a virtual chip, gpio-control for every pin; gpio and gpio-chardev cannot be connected together

gpio grants one pin through the deprecated sysfs ABI; gpio-chardev grants chosen lines of a chip through a virtual chip built at boot, and cannot be connected together with gpio; gpio-control grants every pin and is super-privileged.

The gateway also switches a relay from one GPIO pin. Which interface should acme-agent ask for? gpio grants that one pin. The gadget slot carries the pin number, a systemd unit exports the pin through sysfs, and the app gets that pin's directory. That sysfs interface is deprecated, and gpio-chardev replaces it. Its slot names a source chip and a range of lines, snap-gpio-helper builds a virtual chip from them at boot, and the app opens it under /dev/snap/gpio-chardev. You can't have both connected at once. gpio-control is the far end: every pin on every chip. That's why it's super-privileged.

03 Connecting by hand general version

GADGET SLOTS · FOR USERS $ snap connect acme-agent:i2c pc:i2c-1the plug is on acme-agent; the slot is on the gadget snap, pc $ snap connections pcInterface Plug Slot Notesi2c acme-agent:i2c pc:i2c-1 manualserial-port - pc:meter - nothing here connects by itself unless the store's rules for the device say so acme-agentprofile allows the sensordevice cgroup: what the app may openthe I2C sensor ✓ connected an SPI device ✗ not granted: open fails
The command that connects acme-agent to the gadget's i2c-1 slot by hand, the list of the gadget's connections, and the device cgroup letting the app open only the granted device

The slot is on the gadget snap, so snap connect names both ends; snap connections shows what the gadget offers. Nothing connects by itself without a store rule. A connected device is allowed by the profile and added to the app's device cgroup; before that it cannot be opened.

You've installed acme-agent on the gateway, and it can't read the sensor yet. On a device like this, the I2C slot usually belongs to the gadget snap rather than the system, so snap connect names both ends: acme-agent's plug, then the gadget's slot. snap connections, given the gadget's name, lists what it offers and what's connected. Nothing in this family connects by itself unless the store's rules for the device say so. Once you connect, two things change. The app's profile allows the device node, and the node joins the app's device-cgroup. Before that, opening it fails, right path or not.

04 What the gadget declares, the app gets for app developers for Ubuntu Core developers for snapd developers in place of the general version

WHAT THE GADGET DECLARES gadget snap.yaml (pc)slots:generated: AppArmor and udev meter:interface: serial-portusb-vendor: 0xabcdusb-product: 0x1234path: /dev/serial-port-meterATTRS{idVendor}=="abcd",ATTRS{idProduct}=="1234",SYMLINK+="serial-port-meter" /dev/tty[A-Z]*[0-9] rwk,the cgroup narrows it i2c-1:interface: i2cpath: /dev/i2c-1/dev/i2c-1 rw,KERNEL=="i2c-1" spi0:interface: spipath: /dev/spidev0.0/dev/spidev0.0 rw,KERNEL=="spidev0.0"
The gateway gadget's snap.yaml with serial-port, i2c and spi slots beside the AppArmor and udev rules generated from each attribute

Each gadget slot attribute becomes policy: usb-vendor and usb-product give serial-port a stable /dev/serial-port-<name> symlink, with the device cgroup narrowing a broad tty rule to that adapter; an i2c or spi path becomes a device rule and a KERNEL== tag.

Here's the gadget's side of that connection, in its snap.yaml. Each slot attribute turns into policy. The serial-port slot gives the meter adapter's usb-vendor and usb-product, and a path for a stable name. snapd writes a udev rule that matches that USB identity and creates the symlink, so acme-agent doesn't care which ttyUSB number the adapter got this morning. AppArmor allows a broad tty pattern; the device-cgroup narrows it to that one adapter. The i2c slot's path becomes a rule for that node and a udev tag on its kernel name, and the spi slot does the same for its spidev node.

05 Super-privileged versus merely manual for app developers for Ubuntu Core developers for snapd developers for administrators

TWO RULE KEYS tee/dev/tee[0-9]* /dev/teepriv[0-9]* rw, base declaration, plug side:allow-installation: falsedeny-auto-connection: trueinstall: refused without a snap-declarationconnect: by handsuper-privileged physical-memory-control/dev/mem rw, capability sys_rawio, base declaration, slot side only:deny-auto-connection: trueno plug rule: installation allowedinstall: allowed, although root-equivalentconnect: by hand is the only gatemerely manual super-privileged is about installation; manual is about connection read only? physical-memory-observe: /dev/mem r, and no capability
tee with a plug-side allow-installation false beside physical-memory-control with only deny-auto-connection true; installation versus connection

tee has a plug-side allow-installation: false, so a store snap cannot install without a store rule. physical-memory-control is root-equivalent yet carries only deny-auto-connection: true: it installs freely and snap connect is the only gate. physical-memory-observe is the read-only pick.

Two rule keys in the base declaration do different jobs. Take tee, for trusted execution devices. It grants the client nodes and the privileged teepriv node, and its plug rule says allow-installation: false. A store snap that plugs tee won't install without a rule in its own snap-declaration. That's what super-privileged means. Now physical-memory-control: /dev/mem, read and write, plus the sys_rawio capability. That's as good as root, yet its only rule is deny-auto-connection true. It installs freely, and your snap connect is the only gate. If acme-agent only needs to read, physical-memory-observe is the safer pick.

06 custom-device, policy written in YAML for app developers for Ubuntu Core developers for snapd developers

CUSTOM-DEVICE gadget snap.yamlslots:hwdev:interface: custom-devicecustom-device: acme-iogenerated: AppArmor and udev devices:- /dev/input/event[0-9]read-devices:- /dev/js*files:read: [/dev/input/by-id/*]"/dev/input/event[0-9]" rwk,"/dev/js*" r,"/dev/input/by-id/*" r, udev-tagging:- kernel: event[0-9]subsystem: inputKERNEL=="event[0-9]", SUBSYSTEM=="input"KERNEL=="js*" (the default rule) base declaration, slot side:allow-connection: custom-device: $SLOT(custom-device)the label defaults to the plug or slot name allow-installation: false
A custom-device slot in a gadget snap.yaml beside the AppArmor and udev rules it generates, and the base-declaration rule requiring matching labels and a declaration to install

The slot attributes are the policy: devices become rwk, read-devices and files.read become r, files.write becomes rw, and udev-tagging replaces the default KERNEL== rule. Connection needs matching custom-device labels; the slot is super-privileged.

Suppose the gateway has a device that no interface covers. With custom-device, the gadget writes the policy itself, in its snap.yaml. Each path under devices becomes a read, write and lock rule; each under read-devices, a read only rule. Files read and write cover other paths. Every device gets a udev rule on its kernel name, unless a udev-tagging entry replaces it with matches on subsystem, attributes or environment. To connect, acme-agent's plug must carry the same custom-device label as the slot, and the label defaults to the plug or slot name. The slot is super-privileged: the gadget needs a declaration to install.

07 The silent no-op for app developers for Ubuntu Core developers for snapd developers for administrators

CONNECTED, NOT GRANTED dspslot attribute, in the gadget:flavor: ambarela # misspelt accepted: no BeforePrepareSlot checkpolicy: emptyonly flavor: ambarella emits rulessnap connections: connectedthe app: no access gpio (and pwm)sysfs node missing when the profile is generated/sys/class/gpio/gpio17 absentcannot export not existing gpiono rule emitted, no errorfailing here would block snapd updatesLP: 1866424 granted once the profiles are regenerated connected does not mean granted
Two connections that succeed and grant nothing: dsp with a misspelt flavor producing empty policy, and gpio with a missing sysfs node logging a notice and emitting no rule

dsp accepts any flavor and emits rules only for ambarella; gpio and pwm log "cannot export not existing gpio" and emit nothing when the sysfs node is missing, so snapd updates are not blocked (LP: 1866424). Either way the connection shows as connected and grants nothing.

Here's a trap worth knowing about: a connection can succeed and grant nothing. dsp takes a flavor attribute on the gadget slot, and only ambarella is implemented. Nothing checks the value, so a misspelt flavor is accepted and produces an empty policy. snap connections says connected; the app has no access. gpio and pwm do something similar on purpose. If the pin's sysfs node is missing when the profile is generated, snapd logs cannot export not existing gpio and emits no rule, because failing there would block snapd updates. acme-agent gets that pin only when the profiles are regenerated, by a refresh or a reconnect.

08 Where to go next

ROADS a slot on the system or on the gadget · a device rule plus a udev tag · connected by hand gatehousethe interfaces overview gatekeepers' hallattributes become profiles and rules devices and storagethe neighbouring family model, gadget and kernelwhere the gadget's slots come from confinementthe device cgroup being set up
The five roads out of this topic: interfaces overview, implementation, devices and storage, model and gadget, confinement

Roads: the interfaces overview, the implementation, the neighbouring devices-and-storage family, the model deck for gadget-provided slots, and confinement for the device cgroup.

That's the family: a slot on the system or on the gadget, a device rule plus a udev tag, and nearly always a connection you make by hand. Here's where to go next. The gatehouse is the interfaces overview. The gatekeepers' hall shows how a slot attribute turns into profiles and udev rules. Devices and storage is the neighbouring family. The model deck shows where the gateway's gadget, and so its slots, come from. And the walls show the device-cgroup that snap-confine sets up when acme-agent starts.

09 All 35 interfaces at a glance

ALL 35 INTERFACES AT A GLANCE accel qualcomm-ipc-router allegro-vcu bool-file broadcom-asic-control can-bus custom-device * dcdbas-control dsp fpga gpio gpio-chardev gpio-control * gpio-memory-control i2c iio intel-mei intel-qat io-ports-control ion-memory-control * kernel-crypto-api mediatek-accel physical-memory-control physical-memory-observe pwm remoteproc * sd-control * serial-port spi tee * tpm uio usb-gadget vcio xilinx-dma * auto-connectsconditionalby handstore rule to connect* store rule to install · italic: Ubuntu Touch era
Every interface in the buses and boards family, sorted and coloured by how it gets connected: auto-connect, conditional, by hand, or store rule needed

Every interface in the family by connection class: 1 auto-connect, 1 conditionally, 33 by hand, 0 need a store rule to connect; 7 are super-privileged.

All 35 interfaces of the buses and boards family at a glance, sorted by how they get connected. 1 auto-connect on every system: accel. 1 auto-connect under conditions: qualcomm-ipc-router. 33 connect by hand with snap connect, which is most of the family. 7, marked with a star, are super-privileged and need a store rule to install. Every one of them is in the catalogue below this deck, with what it grants and its rule.

Read more

The two shapes

Slot on the systemSlot declared by the gadget
Membersaccel, tpm, tee, fpga, gpio-control, can-bus, physical-memory-control and most othersbool-file, custom-device, dsp, gpio, gpio-chardev, i2c, iio, pwm, serial-port, spi, uio
Who provides the slotsnapd, on classic and on Ubuntu Corethe gadget snap, one slot per device (the base declaration also admits the system for most of them)
What the slot saysnothingthe device: path, number, source-chip and lines, devices and files
Policya fixed AppArmor rule and a fixed udev tagrules generated from the slot attributes
Connectionby hand; accel auto-connectsby hand, unless the gadget's snap-declaration grants auto-connection

qualcomm-ipc-router fits neither: an app snap may provide its slot, and it auto-connects only between snaps of the same publisher with matching qcipc values.

Installation and connection are separate gates

  • Super-privileged means a plug-side allow-installation: false: a store snap with the plug does not install without a snap-declaration rule. In this family: gpio-control, ion-memory-control, remoteproc, sd-control, tee and xilinx-dma. custom-device is restricted on the slot side instead, so the gadget needs the declaration.
  • Several broad interfaces only deny auto-connection: physical-memory-control and io-ports-control (both as strong as root), gpio-memory-control, intel-qat (every VFIO group) and tpm (the raw node as well as the resource manager). For them snap connect by an administrator is the only gate.

Gotchas

  • A connection can grant nothing. dsp (slot flavor) and sd-control (plug flavor) accept any value and emit rules only for ambarella and dual-sd. gpio and pwm emit no rule when the sysfs node is missing at profile generation (LP: 1866424); the access appears after the next regeneration, such as a refresh or a reconnect.
  • bool-file resolves its path through symlinks when the profile is generated, so a missing LED or GPIO makes the profile fail instead.
  • gpio and gpio-chardev cannot be connected at the same time. gpio-chardev refuses to connect on a kernel without gpio-aggregator configfs support.
  • serial-port with usb-vendor and usb-product gets a broad /dev/tty[A-Z]*[0-9] rwk AppArmor rule; the udev tag on that USB identity is what limits the app to one adapter.
  • i2c with sysfs-name instead of path grants the sysfs directory only: no device node and no udev tag.
  • A new SoC tty prefix for serial-port needs a change in snapd, because the accepted device names are a fixed list.
  • usb-gadget has a plug installation rule that checks top-level name, where and persistent attributes, while the real mounts are in ffs-mounts. A plug with ffs-mounts installs without a snap-declaration, which the commit that added the rule did not intend (findings/review/BUGS.md item 2).

Further reading

Roads from here

INTERFACES AND CONFINEMENT

INTERFACE FAMILIES · every interface, grouped by what it touches

UBUNTU CORE · install and recovery