Struct DeviceFd

pub struct DeviceFd { /* private fields */ }

Wrapper over the file descriptor obtained when creating an emulated device in the kernel.

Implementations

impl DeviceFd

pub fn has_device_attr( &self, device_attr: &kvm_device_attr, ) -> Result<(), Error>

Tests whether a device supports a particular attribute.

See the documentation for KVM_HAS_DEVICE_ATTR.

Arguments

• device_attr - The device attribute to be tested. addr field is ignored.

pub fn set_device_attr( &self, device_attr: &kvm_device_attr, ) -> Result<(), Error>

Sets a specified piece of device configuration and/or state.

See the documentation for KVM_SET_DEVICE_ATTR.

Arguments

• device_attr - The device attribute to be set.

Example

Configuring a VFIO device using set_device_attr. Note that VFIO devices are not yet available on RISC-V The patch for QEMU: https://lore.kernel.org/all/20240903201633.93182-1-dbarboza@ventanamicro.com/ and patch for linux kernel https://github.com/ventanamicro/linux/tree/dev-upstream are both not upstreamed. Disabling VFIO device test for RISC-V at the time being.

let kvm = Kvm::new().unwrap();
let vm = kvm.create_vm().unwrap();

let mut device = kvm_bindings::kvm_create_device {
    type_: kvm_device_type_KVM_DEV_TYPE_VFIO,
    fd: 0,
    flags: KVM_CREATE_DEVICE_TEST,
};

let device_fd = vm
    .create_device(&mut device)
    .expect("Cannot create KVM device");

let dist_attr = kvm_bindings::kvm_device_attr {
    group: KVM_DEV_VFIO_GROUP,
    attr: u64::from(KVM_DEV_VFIO_GROUP_ADD),
    addr: 0x0,
    flags: 0,
};

if (device_fd.has_device_attr(&dist_attr).is_ok()) {
    device_fd.set_device_attr(&dist_attr).unwrap();
}

pub unsafe fn get_device_attr( &self, device_attr: &mut kvm_device_attr, ) -> Result<(), Error>

Gets a specified piece of device configuration and/or state.

See the documentation for KVM_GET_DEVICE_ATTR.

Arguments

• device_attr - The device attribute to be get. Note: This argument serves as both input and output. When calling this function, the user should explicitly provide valid values for the group and the attr field of the kvm_device_attr structure, and a valid userspace address (i.e. the addr field) to access the returned device attribute data.

Returns

• Returns the last occured errno wrapped in an Err.
• device_attr - The addr field of the device_attr structure will point to the device attribute data.

Safety

The caller is responsible for the validity of the device_attr argument, including that it is safe to write to the addr member.

Examples

Getting the number of IRQs for a GICv2 device on an aarch64 platform

let kvm = Kvm::new().unwrap();
let vm = kvm.create_vm().unwrap();

use kvm_bindings::{
    KVM_DEV_ARM_VGIC_GRP_NR_IRQS, kvm_device_type_KVM_DEV_TYPE_ARM_VGIC_V2,
    kvm_device_type_KVM_DEV_TYPE_ARM_VGIC_V3,
};

// Create a GIC device.
let mut gic_device = kvm_bindings::kvm_create_device {
    type_: kvm_device_type_KVM_DEV_TYPE_ARM_VGIC_V3,
    fd: 0,
    flags: 0,
};
let device_fd = match vm.create_device(&mut gic_device) {
    Ok(fd) => fd,
    Err(_) => {
        gic_device.type_ = kvm_device_type_KVM_DEV_TYPE_ARM_VGIC_V2;
        vm.create_device(&mut gic_device)
            .expect("Cannot create KVM vGIC device")
    }
};

let mut data: u32 = 0;
let mut gic_attr = kvm_bindings::kvm_device_attr::default();
gic_attr.group = KVM_DEV_ARM_VGIC_GRP_NR_IRQS;
gic_attr.addr = &mut data as *mut u32 as u64;

// SAFETY: gic_attr.addr is safe to write to.
unsafe { device_fd.get_device_attr(&mut gic_attr) }.unwrap();

Trait Implementations

impl AsRawFd for DeviceFd

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for DeviceFd

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromRawFd for DeviceFd

unsafe fn from_raw_fd(fd: RawFd) -> Self

Safety

This function is unsafe as the primitives currently returned have the contract that they are the sole owner of the file descriptor they are wrapping. Usage of this function could accidentally allow violating this contract which can cause memory unsafety in code that relies on it being true.