This crate contains host-side helpers to write virtio-media devices and full devices implementations.

Both helpers and devices are VMM-independent and rely on a handful of traits being implemented to operate on a given VMM. This means that implementing a specific device, and adding support for all virtio-media devices on a given VMM, are two completely orthogonal tasks. Adding support for a VMM makes all the devices relying on this crate available. Conversely, writing a new device using this crate makes it available to all supported VMMs.

Traits to implement by the VMM

• Descriptor chains must implement Read and Write on their device-readable and device-writable parts, respectively. This allows devices to read commands and writes responses.
• The event queue must implement the VirtioMediaEventQueue trait to allow devices to send events to the guest.
• The guest memory must be made accessible through an implementation of VirtioMediaGuestMemoryMapper.
• Optionally, .... can be implemented if the host supports mapping MMAP buffers into the guest address space.

These traits allow any device that implements VirtioMediaDevice to run on any VMM that implements them.

Anatomy of a device

Devices implement VirtioMediaDevice to provide ways to create and close sessions, and to make MMAP buffers visible to the guest (if supported). They also typically implement VirtioMediaIoctlHandler and make use of virtio_media_dispatch_ioctl to handle ioctls simply.

The VMM then uses VirtioMediaDeviceRunner in order to ask it to process a command whenever one arrives on the command queue.

By following this pattern, devices never need to care about deserializing and validating the virtio-media protocol. Instead, their relevant methods are invoked when needed, on validated input, while protocol errors are handled upstream in a way that is consistent for all devices.

The devices currently in this crate are:

• A device that proxies any host V4L2 device into the guest, in the crate::v4l2_device_proxy module.