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
01 The family pattern
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
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
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
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
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
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
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: 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
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 system | Slot declared by the gadget | |
|---|---|---|
| Members | accel, tpm, tee, fpga, gpio-control, can-bus, physical-memory-control and most others | bool-file, custom-device, dsp, gpio, gpio-chardev, i2c, iio, pwm, serial-port, spi, uio |
| Who provides the slot | snapd, on classic and on Ubuntu Core | the gadget snap, one slot per device (the base declaration also admits the system for most of them) |
| What the slot says | nothing | the device: path, number, source-chip and lines, devices and files |
| Policy | a fixed AppArmor rule and a fixed udev tag | rules generated from the slot attributes |
| Connection | by hand; accel auto-connects | by 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 connectby an administrator is the only gate.
Gotchas
- A connection can grant nothing.
dsp(slotflavor) andsd-control(plugflavor) accept any value and emit rules only forambarellaanddual-sd.gpioandpwmemit 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-fileresolves itspaththrough symlinks when the profile is generated, so a missing LED or GPIO makes the profile fail instead.gpioandgpio-chardevcannot be connected at the same time.gpio-chardevrefuses to connect on a kernel without gpio-aggregator configfs support.serial-portwithusb-vendorandusb-productgets a broad/dev/tty[A-Z]*[0-9] rwkAppArmor rule; the udev tag on that USB identity is what limits the app to one adapter.i2cwithsysfs-nameinstead ofpathgrants the sysfs directory only: no device node and no udev tag.- A new SoC tty prefix for
serial-portneeds a change in snapd, because the accepted device names are a fixed list. usb-gadgethas a plug installation rule that checks top-levelname,whereandpersistentattributes, while the real mounts are inffs-mounts. A plug withffs-mountsinstalls without a snap-declaration, which the commit that added the rule did not intend (findings/review/BUGS.md item 2).
Further reading
- Hardware interfaces: how the hardware interfaces relate to the gadget and to hotplug.
- Super-privileged interfaces: what needs a store declaration and how to ask for one.
- The custom-device interface: every attribute with examples.
- The gpio-chardev interface: slot and plug examples for the character-device GPIO interface.
- Gadget snap format: where a gadget declares its slots and its default connections.
- Connect interfaces:
snap connections,snap connectandsnap disconnect.
Roads from here
INTERFACES AND CONFINEMENT
- Interfaces — back to the interfaces overview
- How interfaces are implemented — how a slot attribute becomes profiles and udev rules
- Confinement — the device cgroup that snap-confine sets up
INTERFACE FAMILIES · every interface, grouped by what it touches
- "Interfaces: devices and storage" — the neighbouring family
UBUNTU CORE · install and recovery
- Model, gadget and kernel — where gadget-provided slots come from