Struct devices::pci::msix::MsixConfig

pub struct MsixConfig {
    table_entries: Vec<MsixTableEntry>,
    pba_entries: Vec<u64>,
    irq_vec: Vec<Option<IrqfdGsi>>,
    masked: bool,
    enabled: bool,
    msi_device_socket: Tube,
    msix_num: u16,
    pci_id: u32,
    device_name: String,
}

Wrapper over MSI-X Capability Structure and MSI-X Tables

Fields

table_entries: Vec<MsixTableEntry>

pba_entries: Vec<u64>

irq_vec: Vec<Option<IrqfdGsi>>

masked: bool

enabled: bool

msi_device_socket: Tube

msix_num: u16

pci_id: u32

device_name: String

Implementations

impl MsixConfig

pub fn new( msix_vectors: u16, vm_socket: Tube, pci_id: u32, device_name: String ) -> Self

pub fn num_vectors(&self) -> u16

Get the number of MSI-X vectors in this configuration.

pub fn masked(&self) -> bool

Check whether the Function Mask bit in Message Control word in set or not. if 1, all of the vectors associated with the function are masked, regardless of their per-vector Mask bit states. If 0, each vector’s Mask bit determines whether the vector is masked or not.

pub fn table_masked(&self, index: usize) -> bool

Check whether the Function Mask bit in MSIX table Message Control word in set or not. If true, the vector is masked. If false, the vector is unmasked.

pub fn enabled(&self) -> bool

Check whether the MSI-X Enable bit in Message Control word in set or not. if 1, the function is permitted to use MSI-X to request service.

pub fn read_msix_capability(&self, data: u32) -> u32

Read the MSI-X Capability Structure. The top 2 bits in Message Control word are emulated and all other bits are read only.

pub fn write_msix_capability(&mut self, offset: u64, data: &[u8]) -> MsixStatus

Write to the MSI-X Capability Structure. Only the top 2 bits in Message Control Word are writable.

pub fn snapshot(&mut self) -> Result<Value>

Create a snapshot of the current MsixConfig struct for use in snapshotting.

pub fn restore(&mut self, snapshot: Value) -> Result<(), MsixError>

Restore a MsixConfig struct based on a snapshot. In short, this will restore all data exposed via MMIO, and recreate all MSI-X vectors (they will be re-wired to the irq chip).

fn msix_restore_one(&mut self, index: usize, gsi: u32) -> Result<(), MsixError>

Restore the specified MSI-X vector.

Note: we skip the checks from MsixConfig::msix_enable_one because for an interrupt to be present in MsixConfigSnapshot::irq_gsi_vec, it must have passed those checks.

fn msix_release_all(&mut self) -> Result<(), MsixError>

On warm restore, there could already be MSIs registered. We need to release them in case the routing has changed (e.g. different data <-> GSI).

fn add_msi_route(&mut self, index: u16, gsi: u32) -> Result<(), MsixError>

fn msix_enable_all(&mut self) -> Result<(), MsixError>

fn msix_enable_one(&mut self, index: usize) -> Result<(), MsixError>

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

Read MSI-X table

Arguments

• ‘offset’ - the offset within the MSI-X Table
• ‘data’ - used to store the read results

For all accesses to MSI-X Table and MSI-X PBA fields, software must use aligned full DWORD or aligned full QWORD transactions; otherwise, the result is undefined.

location: DWORD3 DWORD2 DWORD1 DWORD0 entry 0: Vector Control Msg Data Msg Upper Addr Msg Addr entry 1: Vector Control Msg Data Msg Upper Addr Msg Addr entry 2: Vector Control Msg Data Msg Upper Addr Msg Addr …

pub fn write_msix_table(&mut self, offset: u64, data: &[u8]) -> MsixStatus

Write to MSI-X table

Message Address: the contents of this field specifies the address for the memory write transaction; different MSI-X vectors have different Message Address values Message Data: the contents of this field specifies the data driven on AD[31::00] during the memory write transaction’s data phase. Vector Control: only bit 0 (Mask Bit) is not reserved: when this bit is set, the function is prohibited from sending a message using this MSI-X Table entry.

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

Read PBA Entries

Arguments

• ‘offset’ - the offset within the PBA entries
• ‘data’ - used to store the read results

Pending Bits[63::00]: For each Pending Bit that is set, the function has a pending message for the associated MSI-X Table entry.

pub fn write_pba_entries(&mut self, _offset: u64, _data: &[u8])

Write to PBA Entries

Software should never write, and should only read Pending Bits. If software writes to Pending Bits, the result is undefined.

fn set_pba_bit(&mut self, vector: u16, set: bool)

fn get_pba_bit(&self, vector: u16) -> u8

fn inject_msix_and_clear_pba(&mut self, vector: usize)

pub fn trigger(&mut self, vector: u16)

Inject virtual interrupt to the guest

Arguments

• ‘vector’ - the index to the MSI-X Table entry

PCI Spec 3.0 6.8.3.5: while a vector is masked, the function is prohibited from sending the associated message, and the function must set the associated Pending bit whenever the function would otherwise send the message. When software unmasks a vector whose associated Pending bit is set, the function must schedule sending the associated message, and clear the Pending bit as soon as the message has been sent.

If the vector is unmasked, writing to irqfd which wakes up KVM to inject virtual interrupt to the guest.

pub fn get_msi_socket(&self) -> RawDescriptor

Return the raw descriptor of the MSI device socket

pub fn get_irqfd(&self, vector: usize) -> Option<&Event>

Return irqfd of MSI-X Table entry

Arguments

• ‘vector’ - the index to the MSI-X table entry

pub fn destroy(&mut self)

Trait Implementations

impl AsRawDescriptor for MsixConfig

fn as_raw_descriptor(&self) -> RawDescriptor

Returns the underlying raw descriptor.

impl PciCapConfig for MsixConfig

fn read_mask(&self) -> &'static [u32]

Returns the read mask used by read_reg.

fn read_reg(&self, reg_idx: usize) -> u32

Reads a 32bit register from the capability. Only the bits set in the read mask will be used, while the rest of the bits will be taken from the PciConfiguration’s register data. reg_idx - index into the capability

fn write_reg( &mut self, reg_idx: usize, offset: u64, data: &[u8] ) -> Option<Box<dyn PciCapConfigWriteResult>>

Writes data to the capability. reg_idx - index into PciConfiguration.registers. offset - PciConfiguration.registers is in unit of DWord, offset define byte offset in the DWord. data - The data to write.

fn set_cap_mapping(&mut self, _mapping: PciCapMapping)

Used to pass the mmio region for the capability to the implementation. If any external events update the capability’s registers, then PciCapMapping.set_reg must be called to make the changes visible to the guest.

fn num_regs(&self) -> usize