Trait VirtioDevice 

pub trait VirtioDevice: InspectMut + Send {
    // Required methods
    fn traits(&self) -> DeviceTraits;
    fn read_registers_u32(
        &mut self,
        offset: u16,
    ) -> impl Future<Output = u32> + Send;
    fn write_registers_u32(
        &mut self,
        offset: u16,
        val: u32,
    ) -> impl Future<Output = ()> + Send;
    fn start_queue(
        &mut self,
        idx: u16,
        resources: QueueResources,
        features: &VirtioDeviceFeatures,
        initial_state: Option<QueueState>,
    ) -> impl Future<Output = Result<()>> + Send;
    fn stop_queue(
        &mut self,
        idx: u16,
    ) -> impl Future<Output = Option<QueueState>> + Send;

    // Provided methods
    fn queue_size(&self, _queue_index: u16) -> u16 { ... }
    fn set_shared_memory_region(
        &mut self,
        _region: &Arc<dyn MappedMemoryRegion>,
    ) -> Result<()> { ... }
    fn reset(&mut self) -> impl Future<Output = ()> + Send { ... }
    fn supports_save_restore(&self) -> bool { ... }
}

Per-queue virtio device trait. Ergonomic async fn — not object-safe.

Devices implement this trait. The blanket impl converts any VirtioDevice into a DynVirtioDevice for use behind Box<dyn>.

Required Methods

fn traits(&self) -> DeviceTraits

Device identity and capabilities.

fn read_registers_u32( &mut self, offset: u16, ) -> impl Future<Output = u32> + Send

Read device-specific config registers.

fn write_registers_u32( &mut self, offset: u16, val: u32, ) -> impl Future<Output = ()> + Send

Write device-specific config registers.

fn start_queue( &mut self, idx: u16, resources: QueueResources, features: &VirtioDeviceFeatures, initial_state: Option<QueueState>, ) -> impl Future<Output = Result<()>> + Send

Start a single queue.

Called when a queue becomes active — either because the guest set DRIVER_OK (transport starts all enabled queues), or a vhost-user frontend activated a specific queue.

idx is in 0..DeviceTraits::max_queues. The caller will never pass an index outside that range.

initial_state provides restored queue indices for save/restore or vhost-user SET_VRING_BASE. If None, the queue starts fresh (indices at 0).

fn stop_queue( &mut self, idx: u16, ) -> impl Future<Output = Option<QueueState>> + Send

Stop a single queue and return its state.

idx is in 0..DeviceTraits::max_queues. The caller will never pass an index outside that range.

Returns the queue’s QueueState on completion, or None if the queue was not active.

This must be idempotent: calling it on a queue that was never started (or has already been stopped) must return None immediately. Transports rely on this during reset/disable by iterating all queue indices, not just active ones.

Provided Methods

fn queue_size(&self, _queue_index: u16) -> u16

The queue size for the given queue index.

This is the initial value the transport advertises to the guest (e.g. via QUEUE_NUM_MAX on MMIO, or QUEUE_SIZE on PCI). The transport does not enforce this as a per-device cap; the only hard limit is crate::MAX_QUEUE_SIZE.

Must be a power of two, >0, and ≤ crate::MAX_QUEUE_SIZE. The transport validates these invariants at construction time.

queue_index must be less than traits().max_queues. The caller is responsible for bounds checking; implementations may panic on out-of-range indices.

Override to provide per-device or per-queue sizes. The default returns DEFAULT_QUEUE_SIZE (256).

fn set_shared_memory_region( &mut self, _region: &Arc<dyn MappedMemoryRegion>, ) -> Result<()>

Provide the shared memory region to the device.

Called before start_queue when the device advertises a shared memory region (e.g., virtio-pmem, virtio-fs with DAX). Corresponds to VHOST_USER_GET_SHARED_MEMORY_REGIONS in the vhost-user protocol.

Default: no-op.

fn reset(&mut self) -> impl Future<Output = ()> + Send

Reset device-internal state to initial values.

Called after all queues have been stopped on guest-initiated reset. Default: no-op.

fn supports_save_restore(&self) -> bool

Whether the device supports save/restore.

Devices that return false will cause the transport’s save() to fail with SaveError::NotSupported. Devices with host-side session state that cannot be serialized (e.g., virtio-9p, virtiofs) should leave this as false.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors