Trait devices::virtio::VirtioDevice

source · 
pub trait VirtioDevice: Send {

Show 30 methods    // Required methods
    fn keep_rds(&self) -> Vec<RawDescriptor>;
    fn device_type(&self) -> DeviceType;
    fn queue_max_sizes(&self) -> &[u16];
    fn activate(
        &mut self,
        mem: GuestMemory,
        interrupt: Interrupt,
        queues: BTreeMap<usize, Queue>
    ) -> Result<()>;

    // Provided methods
    fn debug_label(&self) -> String { ... }
    fn num_interrupts(&self) -> usize { ... }
    fn features(&self) -> u64 { ... }
    fn ack_features(&mut self, value: u64) { ... }
    fn read_config(&self, offset: u64, data: &mut [u8]) { ... }
    fn write_config(&mut self, offset: u64, data: &[u8]) { ... }
    fn reset(&mut self) -> Result<()> { ... }
    fn get_device_bars(
        &mut self,
        _address: PciAddress
    ) -> Vec<PciBarConfiguration> { ... }
    fn get_device_caps(&self) -> Vec<Box<dyn PciCapability>> { ... }
    fn on_device_sandboxed(&mut self) { ... }
    fn control_notify(&self, _behavior: MsixStatus) { ... }
    fn generate_acpi(
        &mut self,
        _pci_address: &Option<PciAddress>,
        sdts: Vec<SDT>
    ) -> Option<Vec<SDT>> { ... }
    fn read_bar(
        &mut self,
        _bar_index: PciBarIndex,
        _offset: u64,
        _data: &mut [u8]
    ) { ... }
    fn write_bar(&mut self, _bar_index: PciBarIndex, _offset: u64, _data: &[u8]) { ... }
    fn pci_address(&self) -> Option<PciAddress> { ... }
    fn transport_type(&self) -> VirtioTransportType { ... }
    fn get_shared_memory_region(&self) -> Option<SharedMemoryRegion> { ... }
    fn expose_shmem_descriptors_with_viommu(&self) -> bool { ... }
    fn set_shared_memory_mapper(&mut self, _mapper: Box<dyn SharedMemoryMapper>) { ... }
    fn set_shared_memory_region_base(&mut self, _addr: GuestAddress) { ... }
    fn get_shared_memory_prepare_type(&mut self) -> SharedMemoryPrepareType { ... }
    fn virtio_sleep(&mut self) -> Result<Option<BTreeMap<usize, Queue>>> { ... }
    fn virtio_wake(
        &mut self,
        _queues_state: Option<(GuestMemory, Interrupt, BTreeMap<usize, Queue>)>
    ) -> Result<()> { ... }
    fn virtio_snapshot(&mut self) -> Result<Value> { ... }
    fn virtio_restore(&mut self, _data: Value) -> Result<()> { ... }
    fn bootorder_fw_cfg(&self, _pci_address: u8) -> Option<(Vec<u8>, usize)> { ... }

}
Expand description

Trait for virtio devices to be driven by a virtio transport.

The lifecycle of a virtio device is to be moved to a virtio transport, which will then query the device. Once the guest driver has configured the device, VirtioDevice::activate will be called and all the events, memory, and queues for device operation will be moved into the device. Optionally, a virtio device can implement device reset in which it returns said resources and resets its internal.

Virtio device state machine

                          restore (inactive)
      ----------------------------------------------------
      |                                                  |
      |                                                  V
      |                       ------------         --------------
------------- restore(active) |  asleep  |         |   asleep   |   // States in this row
|asleep(new)|---------------> | (active) |         | (inactive) |   // can be snapshotted
-------------                 ------------         --------------
   ^       |                     ^    |              ^      |
   |       |                     |    |              |      |
 sleep    wake                sleep  wake         sleep   wake
   |       |                     |    |              |      |
   |       V                     |    V              |      V
 ------------     activate     ----------  reset   ------------
 |    new   | ---------------> | active | ------>  | inactive |
 ------------                  ---------- <------  ------------
                                          activate

Required Methods§

source

fn keep_rds(&self) -> Vec<RawDescriptor>

A vector of device-specific file descriptors that must be kept open after jailing. Must be called before the process is jailed.

source

fn device_type(&self) -> DeviceType

The virtio device type.

source

fn queue_max_sizes(&self) -> &[u16]

The maximum size of each queue that this device supports.

source

fn activate( &mut self, mem: GuestMemory, interrupt: Interrupt, queues: BTreeMap<usize, Queue> ) -> Result<()>

Activates this device for real usage.

Provided Methods§

source

fn debug_label(&self) -> String

Returns a label suitable for debug output.

source

fn num_interrupts(&self) -> usize

The number of interrupts used by this device.

source

fn features(&self) -> u64

The set of feature bits that this device supports in addition to the base features.

source

fn ack_features(&mut self, value: u64)

Acknowledges that this set of features should be enabled.

source

fn read_config(&self, offset: u64, data: &mut [u8])

Reads this device configuration space at offset.

source

fn write_config(&mut self, offset: u64, data: &[u8])

Writes to this device configuration space at offset.

source

fn reset(&mut self) -> Result<()>

Optionally deactivates this device. If the reset method is not able to reset the virtio device, or the virtio device model doesn’t implement the reset method, an Err value is returned to indicate the reset is not successful. Otherwise Ok(()) should be returned.

source

fn get_device_bars(&mut self, _address: PciAddress) -> Vec<PciBarConfiguration>

Returns any additional BAR configuration required by the device.

source

fn get_device_caps(&self) -> Vec<Box<dyn PciCapability>>

Returns any additional capabiltiies required by the device.

source

fn on_device_sandboxed(&mut self)

Invoked when the device is sandboxed.

source

fn control_notify(&self, _behavior: MsixStatus)

source

fn generate_acpi( &mut self, _pci_address: &Option<PciAddress>, sdts: Vec<SDT> ) -> Option<Vec<SDT>>

source

fn read_bar(&mut self, _bar_index: PciBarIndex, _offset: u64, _data: &mut [u8])

Reads from a BAR region mapped in to the device.

  • addr - The guest address inside the BAR.
  • data - Filled with the data from addr.
source

fn write_bar(&mut self, _bar_index: PciBarIndex, _offset: u64, _data: &[u8])

Writes to a BAR region mapped in to the device.

  • addr - The guest address inside the BAR.
  • data - The data to write.
source

fn pci_address(&self) -> Option<PciAddress>

Returns the PCI address where the device will be allocated. Returns None if any address is good for the device.

source

fn transport_type(&self) -> VirtioTransportType

Returns the Virtio transport type: PCI (default for crosvm) or MMIO.

source

fn get_shared_memory_region(&self) -> Option<SharedMemoryRegion>

Returns the device’s shared memory region if present.

source

fn expose_shmem_descriptors_with_viommu(&self) -> bool

If true, VFIO passthrough devices can access descriptors mapped into this region by mapping the corresponding addresses from this device’s PCI bar into their IO address space with virtio-iommu.

NOTE: Not all vm_control::VmMemorySource types are supported. NOTE: Not yet compatible with PrepareSharedMemoryRegion (aka fixed mapping).

source

fn set_shared_memory_mapper(&mut self, _mapper: Box<dyn SharedMemoryMapper>)

Provides the trait object used to map files into the device’s shared memory region.

If get_shared_memory_region returns Some, then this will be called before activate.

source

fn set_shared_memory_region_base(&mut self, _addr: GuestAddress)

Provides the base address of the shared memory region, if one is present. Will be called before activate.

NOTE: Mappings in shared memory regions should be accessed via offset, rather than via raw guest physical address. This function is only provided so devices can remain backwards compatible with older drivers.

source

fn get_shared_memory_prepare_type(&mut self) -> SharedMemoryPrepareType

Queries the implementation whether a single prepared hypervisor memory mapping with explicit caching type should be setup lazily on first mapping request, or whether to dynamically setup a hypervisor mapping with every request’s caching type.

source

fn virtio_sleep(&mut self) -> Result<Option<BTreeMap<usize, Queue>>>

Pause all processing.

Gives up the queues so that a higher layer can potentially snapshot them. The implementations should also drop the Interrupt and queues Events that were given along with the queues originally.

Unlike Suspendable::sleep, this is not idempotent. Attempting to sleep while already asleep is an error.

source

fn virtio_wake( &mut self, _queues_state: Option<(GuestMemory, Interrupt, BTreeMap<usize, Queue>)> ) -> Result<()>

Resume all processing.

If the device’s queues are active, then the queues and associated data will is included.

Unlike Suspendable::wake, this is not idempotent. Attempting to wake while already awake is an error.

source

fn virtio_snapshot(&mut self) -> Result<Value>

Snapshot current state. Device must be asleep.

source

fn virtio_restore(&mut self, _data: Value) -> Result<()>

Restore device state from a snapshot. TODO(b/280607404): Vhost user will need fds passed to the device process.

source

fn bootorder_fw_cfg(&self, _pci_address: u8) -> Option<(Vec<u8>, usize)>

Implementors§