Struct devices::vfio::VfioDevice

pub struct VfioDevice {
    dev: File,
    name: String,
    container: Arc<Mutex<VfioContainer>>,
    dev_type: VfioDeviceType,
    group_descriptor: RawDescriptor,
    group_id: u32,
    regions: Vec<VfioRegion>,
    num_irqs: u32,
    iova_alloc: Arc<Mutex<AddressAllocator>>,
    dt_symbol: Option<String>,
    pviommu: Option<(Arc<Mutex<KvmVfioPviommu>>, Vec<u32>)>,
}

Vfio device for exposing regions which could be read/write to kernel vfio device.

Fields

dev: File

name: String

container: Arc<Mutex<VfioContainer>>

dev_type: VfioDeviceType

group_descriptor: RawDescriptor

group_id: u32

regions: Vec<VfioRegion>

num_irqs: u32

iova_alloc: Arc<Mutex<AddressAllocator>>

dt_symbol: Option<String>

pviommu: Option<(Arc<Mutex<KvmVfioPviommu>>, Vec<u32>)>

Implementations

impl VfioDevice

pub fn new_passthrough<P: AsRef<Path>>( sysfspath: &P, vm: &impl Vm, container: Arc<Mutex<VfioContainer>>, iommu_dev: IommuDevType, dt_symbol: Option<String> ) -> Result<Self, VfioError>

Create a new vfio device, then guest read/write on this device could be transfered into kernel vfio. sysfspath specify the vfio device path in sys file system.

pub fn new<P: AsRef<Path>>( sysfspath: &P, container: Arc<Mutex<VfioContainer>> ) -> Result<Self, VfioError>

pub fn dev_file(&self) -> &File

Returns the file for this device.

pub fn device_name(&self) -> &String

Returns PCI device name, formatted as BUS:DEVICE.FUNCTION string.

pub fn device_type(&self) -> VfioDeviceType

Returns the type of this VFIO device.

pub fn dt_symbol(&self) -> Option<&str>

Returns the DT symbol (node label) of this VFIO device.

pub fn iommu(&self) -> Option<(IommuDevType, Option<u32>, &[u32])>

Returns the type and indentifier (if applicable) of the IOMMU used by this VFIO device and its master IDs.

pub fn pm_low_power_enter(&self) -> Result<(), VfioError>

enter the device’s low power state

pub fn pm_low_power_enter_with_wakeup( &self, wakeup_evt: Event ) -> Result<(), VfioError>

enter the device’s low power state with wakeup notification

pub fn pm_low_power_exit(&self) -> Result<(), VfioError>

exit the device’s low power state

pub fn acpi_dsm(&self, args: &[u8]) -> Result<Vec<u8>, VfioError>

call _DSM from the device’s ACPI table

pub fn acpi_notification_evt_enable( &self, acpi_notification_eventfd: &Event, index: u32 ) -> Result<(), VfioError>

Enable vfio device’s ACPI notifications and associate EventFD with device.

pub fn acpi_notification_disable(&self, index: u32) -> Result<(), VfioError>

Disable vfio device’s ACPI notification and disconnect EventFd with device.

pub fn acpi_notification_test( &self, index: u32, val: u32 ) -> Result<(), VfioError>

Test vfio device’s ACPI notification by simulating hardware triggering. When the signaling mechanism is set, the VFIO_IRQ_SET_DATA_BOOL can be used with VFIO_IRQ_SET_ACTION_TRIGGER to perform kernel level interrupt loopback testing.

pub fn irq_enable( &self, descriptors: &[Option<&Event>], index: u32, subindex: u32 ) -> Result<(), VfioError>

Enable vfio device’s irq and associate Irqfd Event with device. When MSIx is enabled, multi vectors will be supported, and vectors starting from subindex to subindex + descriptors length will be assigned with irqfd in the descriptors array. when index = VFIO_PCI_REQ_IRQ_INDEX, kernel vfio will trigger this event when physical device is removed. If descriptor is None, -1 is assigned to the irq. A value of -1 is used to either de-assign interrupts if already assigned or skip un-assigned interrupts.

pub fn resample_virq_enable( &self, descriptor: &Event, index: u32 ) -> Result<(), VfioError>

When intx is enabled, irqfd is used to trigger a level interrupt into guest, resample irqfd is used to get guest EOI notification. When host hw generates interrupt, vfio irq handler in host kernel receive and handle it, this handler disable hw irq first, then trigger irqfd to inject interrupt into guest. When resample irqfd is triggered by guest EOI, vfio kernel could enable hw irq, so hw could generate another interrupts. This function enable resample irqfd and let vfio kernel could get EOI notification.

descriptor: should be resample IrqFd.

pub fn irq_disable(&self, index: u32) -> Result<(), VfioError>

disable vfio device’s irq and disconnect Irqfd Event with device

pub fn irq_unmask(&self, index: u32) -> Result<(), VfioError>

Unmask vfio device irq

pub fn irq_mask(&self, index: u32) -> Result<(), VfioError>

Mask vfio device irq

fn get_device_info( device_file: &File ) -> Result<(vfio_device_info, VfioDeviceType), VfioError>

Get and validate VFIO device information.

pub fn get_irqs(&self) -> Result<Vec<VfioIrq>, VfioError>

Query interrupt information return: Vector of interrupts information, each of which contains flags and index

fn get_regions( dev: &File, num_regions: u32 ) -> Result<Vec<VfioRegion>, VfioError>

pub fn get_region_flags(&self, index: usize) -> u32

get a region’s flag the return’s value may conatin: VFIO_REGION_INFO_FLAG_READ: region supports read VFIO_REGION_INFO_FLAG_WRITE: region supports write VFIO_REGION_INFO_FLAG_MMAP: region supports mmap VFIO_REGION_INFO_FLAG_CAPS: region’s info supports caps

pub fn get_region_offset(&self, index: usize) -> u64

get a region’s offset return: Region offset from the start of vfio device descriptor

pub fn get_region_size(&self, index: usize) -> u64

get a region’s size return: Region size from the start of vfio device descriptor

pub fn get_region_count(&self) -> usize

get a number of regions return: Number of regions of vfio device descriptor

pub fn get_region_mmap(&self, index: usize) -> Vec<vfio_region_sparse_mmap_area>

get a region’s mmap info vector

pub fn get_cap_type_info(&self, type_: u32, sub_type: u32) -> Option<(u32, u64)>

find the specified cap type in device regions Input: type_: cap type sub_type: cap sub_type Output: None: device doesn’t have the specified cap type Some((bar_index, region_size)): device has the specified cap type, return region’s index and size

pub fn get_offset_for_addr( &self, addr: &VfioRegionAddr ) -> Result<u64, VfioError>

Returns file offset corresponding to the given VfioRegionAddr. The offset can be used when reading/writing the VFIO device’s FD directly.

pub fn region_read(&self, index: usize, buf: &mut [u8], addr: u64)

Read region’s data from VFIO device into buf index: region num buf: data destination and buf length is read size addr: offset in the region

pub fn region_read_from_addr<T: FromBytes>( &self, addr: &VfioRegionAddr, offset: u64 ) -> T

Reads a value from the specified VfioRegionAddr.addr + offset.

pub fn region_write(&self, index: usize, buf: &[u8], addr: u64)

write the data from buf into a vfio device region index: region num buf: data src and buf length is write size addr: offset in the region

pub fn region_write_to_addr<T: AsBytes>( &self, val: &T, addr: &VfioRegionAddr, offset: u64 )

Writes data into the specified VfioRegionAddr.addr + offset.

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

get vfio device’s descriptors which are passed into minijail process

pub unsafe fn vfio_dma_map( &self, iova: u64, size: u64, user_addr: u64, write_en: bool ) -> Result<(), VfioError>

Add (iova, user_addr) map into vfio container iommu table

Safety

The caller is responsible for determining the safety of the VFIO_IOMMU_MAP_DMA ioctl.

pub fn vfio_dma_unmap(&self, iova: u64, size: u64) -> Result<(), VfioError>

Remove (iova, user_addr) map from vfio container iommu table

pub fn vfio_get_iommu_page_size_mask(&self) -> Result<u64, VfioError>

pub fn alloc_iova( &self, size: u64, align_size: u64, alloc: Alloc ) -> Result<u64, VfioError>

pub fn get_iova(&self, alloc: &Alloc) -> Option<AddressRange>

pub fn release_iova(&self, alloc: Alloc) -> Result<AddressRange, VfioError>

pub fn get_max_addr(&self) -> u64

pub fn device_file(&self) -> &File

Gets the vfio device backing File.

pub fn close(&self)

close vfio device

Trait Implementations

impl AsRawDescriptor for VfioDevice

fn as_raw_descriptor(&self) -> RawDescriptor

Returns the underlying raw descriptor.