Add support for KVM_GET_XSAVE2

Since Linux 5.17, the `kvm_xsave` struct has a flexiblre array member
(FAM) at the end, which can be retrieved using the `KVM_GET_XSAVE2`
ioctl [1]. What makes this FAM special is that the length is not stored
in itself, but has to be retrieved via
`KVM_CHECK_CAPABILITY(KVM_CAP_XSAVE2)` which returns the total size of
the `kvm_xsave` struct (e.g. the traditional 4096 byte region + extra
region with the size of the FAM). To support it in rust-vmm, `Xsave` has
been introduced as its `FamStructWrapper`.

The size required to hold the whole `kvm_xsave` structure can vary
depending on features that have been dynamically enabled by
`arch_prctl()` [2]. Any features must not be enabled after the size has
been confirmed; otherwise, `KVM_GET_XSAVE2` writes beyond the allocated
area for `Xsave`, potentially causing undefined behavior. It is unable
to put `KVM_CHECK_CAPABILITY` call for the size check and
`KVM_GET_XSAVE2` call together into `get_xsave2()`, because there is a
chance of race condition where another thread enables additional
features between them. That's why `get_xsave2()` is marked `unsafe`.

Although `KVM_SET_XSAVE` was extended and `KVM_SET_XSAVE2` was not added
to support the `kvm_xsave` with FAM, `set_xsave2()` is also implemented
to enable users to pass `Xsave` to it for convenience. That is also
marked `unsafe` for the same reason.

[1]: https://www.kernel.org/doc/html/latest/virt/kvm/api.html#kvm-get-xsave2
[2]: https://docs.kernel.org/arch/x86/xstate.html

Co-authored-by: Patrick Roy <[email protected]>
Signed-off-by: Takahiro Itazuri <[email protected]>

Author: 2 people

kvm-ioctls/CHANGELOG.md

@@ -2,11 +2,16 @@
 
 ## Upcoming Release
 
+### Added
+
+- [[#310](https://github.com/rust-vmm/kvm/pull/310)]: Added support for
+  `KVM_CAP_XSAVE2` and the `KVM_GET_XSAVE2` ioctl.
+
 ## v0.20.0
 
-### Added 
+### Added
 
-- [[#288](https://github.com/rust-vmm/kvm-ioctls/pull/288)]: Introduce `Cap::GuestMemfd`, `Cap::MemoryAttributes` and 
+- [[#288](https://github.com/rust-vmm/kvm-ioctls/pull/288)]: Introduce `Cap::GuestMemfd`, `Cap::MemoryAttributes` and
    `Cap::UserMemory2` capabilities enum variants for use with `VmFd::check_extension`.
 - [[#288](https://github.com/rust-vmm/kvm-ioctls/pull/288)]: Introduce `VmFd::check_extension_raw` and `VmFd::check_extension_int` to allow `KVM_CHECK_EXTENSION` to return integer.
 

kvm-ioctls/src/cap.rs

@@ -82,6 +82,8 @@ pub enum Cap {
     #[cfg(target_arch = "x86_64")]
     Xsave = KVM_CAP_XSAVE,
     #[cfg(target_arch = "x86_64")]
+    Xsave2 = KVM_CAP_XSAVE2,
+    #[cfg(target_arch = "x86_64")]
     Xcrs = KVM_CAP_XCRS,
     PpcGetPvinfo = KVM_CAP_PPC_GET_PVINFO,
     PpcIrqLevel = KVM_CAP_PPC_IRQ_LEVEL,

kvm-ioctls/src/ioctls/vcpu.rs

@@ -861,6 +861,61 @@ impl VcpuFd {
         Ok(xsave)
     }
 
+    /// X86 specific call that gets the current vcpu's "xsave struct" via `KVM_GET_XSAVE2`.
+    ///
+    /// See the documentation for `KVM_GET_XSAVE2` in the
+    /// [KVM API doc](https://www.kernel.org/doc/Documentation/virtual/kvm/api.txt).
+    ///
+    /// # Arguments
+    ///
+    /// * `xsave` - A mutable reference to an [`Xsave`] instance that will be populated with the
+    ///             current vcpu's "xsave struct".
+    ///
+    /// # Safety
+    ///
+    /// This function is unsafe because there is no guarantee `xsave` is allocated with enough space
+    /// to hold the entire xsave state.
+    ///
+    /// The required size can be retrieved via `KVM_CHECK_EXTENSION(KVM_CAP_XSAVE2)` and can vary
+    /// depending on features that have been dynamically enabled by `arch_prctl()`. Thus, any
+    /// features must not be enabled dynamically after the required size has been confirmed.
+    ///
+    /// If `xsave` is not large enough, `KVM_GET_XSAVE2` copies data beyond the allocated area,
+    /// possibly causing undefined behavior.
+    ///
+    /// See the documentation for dynamically enabled XSTATE features in the
+    /// [kernel doc](https://docs.kernel.org/arch/x86/xstate.html).
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # extern crate kvm_ioctls;
+    /// # extern crate kvm_bindings;
+    /// # use kvm_ioctls::{Kvm, Cap};
+    /// # use kvm_bindings::{Xsave, kvm_xsave};
+    /// let kvm = Kvm::new().unwrap();
+    /// let vm = kvm.create_vm().unwrap();
+    /// let vcpu = vm.create_vcpu(0).unwrap();
+    /// let xsave_size = vm.check_extension_int(Cap::Xsave2);
+    /// if xsave_size > 0 {
+    ///     let fam_size = xsave_size as usize - std::mem::size_of::<kvm_xsave>();
+    ///     let mut xsave = Xsave::new(fam_size).unwrap();
+    ///     unsafe { vcpu.get_xsave2(&mut xsave).unwrap() };
+    /// }
+    /// ```
+    #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
+    pub unsafe fn get_xsave2(&self, xsave: &mut Xsave) -> Result<()> {
+        // SAFETY: Safe as long as `xsave` is allocated with enough space to hold the entire "xsave
+        // struct". That's why this function is unsafe.
+        let ret = unsafe {
+            ioctl_with_mut_ref(self, KVM_GET_XSAVE2(), &mut xsave.as_mut_fam_struct().xsave)
+        };
+        if ret != 0 {
+            return Err(errno::Error::last());
+        }
+        Ok(())
+    }
+
     /// X86 specific call that sets the vcpu's current "xsave struct".
     ///
     /// See the documentation for `KVM_SET_XSAVE` in the
@@ -892,6 +947,51 @@ impl VcpuFd {
         Ok(())
     }
 
+    /// Convenience function for doing `KVM_SET_XSAVE` with the FAM-enabled [`Xsave`]
+    /// instead of the pre-5.17 plain [`kvm_xsave`].
+    ///
+    /// # Arguments
+    ///
+    /// * `xsave` - A reference to an [`Xsave`] instance to be set.
+    ///
+    /// # Safety
+    ///
+    /// This function is unsafe because there is no guarantee `xsave` is properly allocated with
+    /// the size that KVM assumes.
+    ///
+    /// The required size can be retrieved via `KVM_CHECK_EXTENSION(KVM_CAP_XSAVE2)` and can vary
+    /// depending on features that have been dynamically enabled by `arch_prctl()`. Thus, any
+    /// features must not be enabled after the required size has been confirmed.
+    ///
+    /// If `xsave` is not large enough, `KVM_SET_XSAVE` copies data beyond the allocated area to
+    /// the kernel, possibly causing undefined behavior.
+    ///
+    /// See the documentation for dynamically enabled XSTATE features in the
+    /// [kernel doc](https://docs.kernel.org/arch/x86/xstate.html).
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # extern crate kvm_ioctls;
+    /// # extern crate kvm_bindings;
+    /// # use kvm_ioctls::{Kvm, Cap};
+    /// # use kvm_bindings::{Xsave, kvm_xsave};
+    /// let kvm = Kvm::new().unwrap();
+    /// let vm = kvm.create_vm().unwrap();
+    /// let vcpu = vm.create_vcpu(0).unwrap();
+    /// let xsave_size = vm.check_extension_int(Cap::Xsave2);
+    /// if xsave_size > 0 {
+    ///     let fam_size = xsave_size as usize - std::mem::size_of::<kvm_xsave>();
+    ///     let xsave = Xsave::new(fam_size).unwrap();
+    ///     // Your `xsave` manipulation here.
+    ///     unsafe { vcpu.set_xsave2(&xsave).unwrap() };
+    /// }
+    /// ```
+    #[cfg(target_arch = "x86_64")]
+    pub unsafe fn set_xsave2(&self, xsave: &Xsave) -> Result<()> {
+        self.set_xsave(&xsave.as_fam_struct_ref().xsave)
+    }
+
     /// X86 specific call that returns the vcpu's current "xcrs".
     ///
     /// See the documentation for `KVM_GET_XCRS` in the
@@ -2228,6 +2328,21 @@ mod tests {
         vcpu.set_xsave(&xsave).unwrap();
         let other_xsave = vcpu.get_xsave().unwrap();
         assert_eq!(&xsave.region[..], &other_xsave.region[..]);
+
+        let xsave_size = vm.check_extension_int(Cap::Xsave2);
+        // only if KVM_CAP_XSAVE2 is supported
+        if xsave_size > 0 {
+            let fam_size = xsave_size as usize - std::mem::size_of::<kvm_xsave>();
+            let mut xsave2 = Xsave::new(fam_size).unwrap();
+            // SAFETY: Safe because `xsave2` is allocated with enough space.
+            unsafe { vcpu.get_xsave2(&mut xsave2).unwrap() };
+            assert_eq!(
+                &xsave.region[..],
+                &xsave2.as_fam_struct_ref().xsave.region[..]
+            );
+            // SAFETY: Safe because `xsave2` is allocated with enough space.
+            unsafe { vcpu.set_xsave2(&xsave2).unwrap() };
+        }
     }
 
     #[cfg(target_arch = "x86_64")]

kvm-ioctls/src/kvm_ioctls.rs

@@ -198,6 +198,9 @@ ioctl_iow_nr!(KVM_SET_DEBUGREGS, KVMIO, 0xa2, kvm_debugregs);
 /* Available with KVM_CAP_XSAVE */
 #[cfg(target_arch = "x86_64")]
 ioctl_ior_nr!(KVM_GET_XSAVE, KVMIO, 0xa4, kvm_xsave);
+/* Available with KVM_CAP_XSAVE2 */
+#[cfg(target_arch = "x86_64")]
+ioctl_ior_nr!(KVM_GET_XSAVE2, KVMIO, 0xcf, kvm_xsave);
 /* Available with KVM_CAP_XSAVE */
 #[cfg(target_arch = "x86_64")]
 ioctl_iow_nr!(KVM_SET_XSAVE, KVMIO, 0xa5, kvm_xsave);