Crate virtio_media

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.

Re-exports

pub use v4l2r;

Modules

devices

Virtio-media host devices.

io

Traits and implementations for reading virtio-media commands from and writing responses to virtio descriptors.

ioctl

memfd

Provides a simple memory allocator using memfd. The MemFd crate provides the same functionality, but also pulls some unwanted dependencies in, so we use this simple implementation instead.

mmap

poll

protocol

Structs

VirtioMediaDeviceRunner

Wrapping structure for a VirtioMediaDevice managing its sessions and providing methods for processing its commands.

Traits

GuestMemoryRange

Trait for representing a range of guest memory that has been mapped linearly into the host’s address space.

VirtioMediaDevice

Trait for implementing virtio-media devices.

VirtioMediaDeviceSession

VirtioMediaEventQueue

Trait for sending V4L2 events to the driver.

VirtioMediaGuestMemoryMapper

Trait enabling guest memory linear access for the device.

VirtioMediaHostMemoryMapper

Trait for mapping host buffers into the guest physical address space.