qubes.devices – Devices

API for various types of devices.

Main concept is that some domain may expose (potentially multiple) devices, which can be attached to other domains. Devices can be of different buses (like ‘pci’, ‘usb’, etc). Each device bus is implemented by an extension.

Devices are identified by pair of (backend domain, ident), where ident is str and can contain only characters from [a-zA-Z0-9._-] set.

Such extension should:

• provide qubes.devices endpoint - a class descendant from qubes.devices.DeviceInfo, designed to hold device description (including bus-specific properties)

• handle device-attach:bus and device-detach:bus events for performing the attach/detach action; events are fired even when domain isn’t running and extension should be prepared for this; handlers for those events can be coroutines

• handle device-list:bus event - list devices exposed by particular domain; it should return a list of appropriate DeviceInfo objects

• handle device-get:bus event - get one device object exposed by this domain of given identifier

• handle device-list-attached:class event - list devices currently attached to this domain

• fire device-list-change:class event when a device list change is detected (new/removed device)

Note that device-listing event handlers cannot be asynchronous. This for example means you cannot call qrexec service there. This is intentional to keep device listing operation cheap. You need to design the extension to take this into account (for example by using QubesDB).

Extension may use QubesDB watch API (QubesVM.watch_qdb_path(path), then handle domain-qdb-change:path) to detect changes and fire device-list-change:class event.

exception qubes.devices.DeviceAlreadyAttached

Bases: QubesException, KeyError

Trying to attach already attached device

exception qubes.devices.DeviceNotAttached

Bases: QubesException, KeyError

Trying to detach not attached device

class qubes.devices.DeviceAssignment(backend_domain, ident, options=None, persistent=False, bus=None)

Bases: object

Maps a device to a frontend_domain.

clone()

Clone object instance

property device

Get DeviceInfo object corresponding to this DeviceAssignment

class qubes.devices.DeviceCollection(vm, bus)

Bases: object

Bag for devices.

Used as default value for DeviceManager.__missing__() factory.

Parameters:

• vm – VM for which we manage devices

• bus – device bus

This class emits following events on VM object:

device-attach:<class>(device, options)

Fired when device is attached to a VM.

Handler for this event may be asynchronous.

Parameters:

• device – DeviceInfo object to be attached

• options – dict of attachment options

device-pre-attach:<class>(device)

Fired before device is attached to a VM

Handler for this event may be asynchronous.

Parameters:

device – DeviceInfo object to be attached

device-detach:<class>(device)

Fired when device is detached from a VM.

Handler for this event can be asynchronous (a coroutine).

Parameters:

device – DeviceInfo object to be attached

device-pre-detach:<class>(device)

Fired before device is detached from a VM

Handler for this event can be asynchronous (a coroutine).

Parameters:

device – DeviceInfo object to be attached

device-list:<class>

Fired to get list of devices exposed by a VM. Handlers of this event should return a list of py:class:DeviceInfo objects (or appropriate class specific descendant)

device-get:<class>(ident)

Fired to get a single device, given by the ident parameter. Handlers of this event should either return appropriate object of DeviceInfo, or None. Especially should not raise exceptions.KeyError.

device-list-attached:<class>(persistent)

Fired to get list of currently attached devices to a VM. Handlers of this event should return list of devices actually attached to a domain, regardless of its settings.

assignments(persistent: bool | None = None)

List assignments for devices which are (or may be) attached to the

vm.

Devices may be attached persistently (so they are included in qubes.xml) or not. Device can also be in qubes.xml, but be temporarily detached.

Parameters:

persistent (Optional[bool]) – only include devices which are or are

not attached persistently.

async attach(device_assignment: DeviceAssignment)

Attach (add) device to domain.

Parameters:

device (DeviceInfo) – device object

attached()

List devices which are (or may be) attached to this vm

available()

List devices exposed by this vm

async detach(device_assignment: DeviceAssignment)

Detach (remove) device from domain.

Parameters:

device (DeviceInfo) – device object

load_persistent(device_assignment: DeviceAssignment)

Load DeviceAssignment retrieved from qubes.xml

This can be used only for loading qubes.xml, when VM events are not enabled yet.

persistent()

Devices persistently attached and safe to access before libvirt bootstrap.

update_persistent(device: DeviceInfo, persistent: bool)

Update persistent flag of already attached device.

class qubes.devices.DeviceInfo(backend_domain, ident, description=None, frontend_domain=None)

Bases: object

Holds all information about a device

backend_domain

domain providing this device

description

human readable description/name of the device

frontend_domain

(running) domain to which device is currently attached

ident

device identifier (unique for given domain and device type)

class qubes.devices.DeviceManager(vm)

Bases: dict

Device manager that hold all devices by their classes.

Parameters:

vm – VM for which we manage devices

class qubes.devices.PersistentCollection

Bases: object

Helper object managing persistent `DeviceAssignment`s.

add(assignment: DeviceAssignment)

Add assignment to collection

discard(assignment)

Discard assignment from collection

get(device: DeviceInfo) → DeviceAssignment

Returns the corresponding qubes.devices.DeviceAssignment for the device.

class qubes.devices.UnknownDevice(backend_domain, ident, description=None, frontend_domain=None)

Bases: DeviceInfo

Unknown device - for example exposed by domain not running currently