Add serde support for various bindings

Add implementations of `serde::{Serialize, Deserialize}` for
kvm-bindings structures commonly used for live migration/snapshotting.
The selections of structures to add the derives to was determined by
finding the minimal set that allows both Firecracker and CloudHypervisor
to compile against this branch.

Serialization happens as opaque binary blobs via the `zerocopy` crate.
This is to support live migration across different versions of
kvm-bindings (which can potentially be using bindings generated from
different versions of the kernel headers). Since the kernel's ABI is
backward-compatible, the only changes that can happen are:

- "reserved" areas of structures acquire meaning. This is a change
  purely at the representational level, and has no impact on the
  underlying binary representation. Thus, our serialization is
  roboust to these changes (whereas simply deriving the serde traits
  would cause incompatibilities here).

- Adding new fields to the end of a structure. When deserializating, we
  compare the length of the deserialized data with the size of the
  struct, and pad with zeros/truncate as appropriate.

This allows seamless live update.

Signed-off-by: Patrick Roy <[email protected]>

Author: roypat

Cargo.toml

@@ -14,6 +14,12 @@ rustdoc-args = ["--cfg", "docsrs"]
 
 [features]
 fam-wrappers = ["vmm-sys-util"]
+# It is not needed to enable the `with-serde` feature of `vmm-sys-util` here, because due to how cargo merges features,
+# if a downstream crate enables vmm-sys-util in its Cargo.toml, it will get enabled globally.
+with-serde = ["dep:serde", "serde/derive", "dep:zerocopy"]
+
 
 [dependencies]
 vmm-sys-util = { version = "0.12.1", optional = true }
+serde = { version = "1.0.0", optional = true, features = ["derive"] }
+zerocopy = { version = "0.7.32", optional = true, features = ["derive"] }

README.md

@@ -5,7 +5,6 @@ Rust FFI bindings to KVM, generated using
 [bindgen](https://crates.io/crates/bindgen). It currently has support for the
 following target architectures:
 - x86_64
-- arm
 - arm64
 
 The bindings exported by this crate are statically generated using header files
@@ -17,7 +16,7 @@ kernel version they are using. For example, the `immediate_exit` field from the
 capability is available. Using invalid fields or features may lead to undefined
 behaviour.
 
-# Usage
+## Usage
 First, add the following to your `Cargo.toml`:
 ```toml
 kvm-bindings = "0.3"
@@ -35,7 +34,14 @@ this crate. Example:
 kvm-bindings = { version = "0.3", features = ["fam-wrappers"]}
 ```
 
-# Dependencies
+## Dependencies
 The crate has an `optional` dependency to
 [vmm-sys-util](https://crates.io/crates/vmm-sys-util) when enabling the
 `fam-wrappers` feature.
+
+It also has an optional dependency on [`serde`](serde.rs) when enabling the 
+`with-serde` feature, to allow serialization of bindings. Serialization of
+bindings happens as opaque binary blobs via [`zerocopy`](https://google.github.io/comprehensive-rust/bare-metal/useful-crates/zerocopy.html).
+Due to the kernel's ABI compatibility, this means that bindings serialized
+in version `x` of `kvm-bindings` can be deserialized in version `y` of the
+crate, even if the bindings have had been regenerated in the meantime.

src/arm64/bindings.rs

@@ -955,6 +955,10 @@ pub type __wsum = __u32;
 pub type __poll_t = ::std::os::raw::c_uint;
 #[repr(C)]
 #[derive(Debug, Default, Copy, Clone, PartialEq)]
+#[cfg_attr(
+    feature = "with-serde",
+    derive(zerocopy::AsBytes, zerocopy::FromBytes, zerocopy::FromZeroes)
+)]
 pub struct user_pt_regs {
     pub regs: [__u64; 31usize],
     pub sp: __u64,
@@ -1019,6 +1023,10 @@ fn bindgen_test_layout_user_pt_regs() {
 #[repr(C)]
 #[repr(align(16))]
 #[derive(Debug, Default, Copy, Clone, PartialEq)]
+#[cfg_attr(
+    feature = "with-serde",
+    derive(zerocopy::AsBytes, zerocopy::FromBytes, zerocopy::FromZeroes)
+)]
 pub struct user_fpsimd_state {
     pub vregs: [__uint128_t; 32usize],
     pub fpsr: __u32,
@@ -1499,6 +1507,10 @@ fn bindgen_test_layout_user_za_header() {
 #[repr(C)]
 #[repr(align(16))]
 #[derive(Debug, Default, Copy, Clone, PartialEq)]
+#[cfg_attr(
+    feature = "with-serde",
+    derive(zerocopy::AsBytes, zerocopy::FromBytes, zerocopy::FromZeroes)
+)]
 pub struct kvm_regs {
     pub regs: user_pt_regs,
     pub sp_el1: __u64,
@@ -1574,6 +1586,10 @@ fn bindgen_test_layout_kvm_regs() {
 }
 #[repr(C)]
 #[derive(Debug, Default, Copy, Clone, PartialEq)]
+#[cfg_attr(
+    feature = "with-serde",
+    derive(zerocopy::AsBytes, zerocopy::FromBytes, zerocopy::FromZeroes)
+)]
 pub struct kvm_vcpu_init {
     pub target: __u32,
     pub features: [__u32; 7usize],
@@ -6511,6 +6527,10 @@ fn bindgen_test_layout_kvm_vapic_addr() {
 }
 #[repr(C)]
 #[derive(Debug, Default, Copy, Clone, PartialEq)]
+#[cfg_attr(
+    feature = "with-serde",
+    derive(zerocopy::AsBytes, zerocopy::FromBytes, zerocopy::FromZeroes)
+)]
 pub struct kvm_mp_state {
     pub mp_state: __u32,
 }
@@ -8786,6 +8806,10 @@ fn bindgen_test_layout_kvm_reg_list() {
 }
 #[repr(C)]
 #[derive(Debug, Default, Copy, Clone, PartialEq)]
+#[cfg_attr(
+    feature = "with-serde",
+    derive(zerocopy::AsBytes, zerocopy::FromBytes, zerocopy::FromZeroes)
+)]
 pub struct kvm_one_reg {
     pub id: __u64,
     pub addr: __u64,

src/arm64/mod.rs

@@ -7,6 +7,9 @@ pub mod bindings;
 #[cfg(feature = "fam-wrappers")]
 pub mod fam_wrappers;
 
+#[cfg(feature = "with-serde")]
+mod serialize;
+
 pub use self::bindings::*;
 #[cfg(feature = "fam-wrappers")]
 pub use self::fam_wrappers::*;

src/arm64/serialize.rs

@@ -0,0 +1,53 @@
+use bindings::{
+    kvm_mp_state, kvm_one_reg, kvm_regs, kvm_vcpu_init, user_fpsimd_state, user_pt_regs,
+};
+use serde::{Deserialize, Deserializer, Serialize, Serializer};
+use zerocopy::{transmute, AsBytes};
+
+serde_impls! {
+    user_pt_regs,
+    user_fpsimd_state,
+    kvm_regs,
+    kvm_vcpu_init,
+    kvm_mp_state,
+    kvm_one_reg
+}
+
+#[cfg(test)]
+mod tests {
+    use bindings::*;
+    use serde::{Deserialize, Serialize};
+
+    fn is_serde<T: Serialize + for<'de> Deserialize<'de>>() {}
+
+    #[test]
+    fn static_assert_serde_implementations() {
+        // This test statically (= at compile-time) asserts that various bindgen generated
+        // structures implement serde's `Serialize` and `Deserialize` traits.
+        // This is to make sure that we do not accidentally remove those implementations
+        // when regenerating bindings. If this test fails to compile, please add
+        //
+        // #[cfg_attr(
+        //     feature = "with-serde",
+        //     derive(zerocopy::AsBytes, zerocopy::FromBytes, zerocopy::FromZeroes)
+        // )]
+        //
+        // to all structures causing compilation errors (we need the zerocopy traits, as the
+        // `Serialize` and `Deserialize` implementations are provided by the `serde_impls!` macro
+        // above, which implements serialization based on zerocopy's `FromBytes` and `AsBytes`
+        // traits that it expects to be derived).
+        //
+        // NOTE: This only include "top-level" items, and does not list out bindgen-anonymous types
+        // (e.g. types like `kvm_vcpu_events__bindgen_ty_5`). These types can change name across
+        // bindgen versions. If after re-adding the derives to all the below items you can compile
+        // errors about anonymous types not implementing `Serialize`/`Deserialize`, please also add
+        // the derives to all anonymous types references in the definitions of the below items.
+
+        is_serde::<user_pt_regs>();
+        is_serde::<user_fpsimd_state>();
+        is_serde::<kvm_regs>();
+        is_serde::<kvm_vcpu_init>();
+        is_serde::<kvm_mp_state>();
+        is_serde::<kvm_one_reg>();
+    }
+}

src/lib.rs

@@ -12,6 +12,16 @@
 #[cfg(feature = "fam-wrappers")]
 extern crate vmm_sys_util;
 
+#[cfg(feature = "with-serde")]
+extern crate serde;
+
+#[cfg(feature = "with-serde")]
+extern crate zerocopy;
+
+#[cfg(feature = "with-serde")]
+#[macro_use]
+mod serialize;
+
 #[cfg(target_arch = "x86_64")]
 mod x86_64;
 #[cfg(target_arch = "x86_64")]

src/serialize.rs

@@ -0,0 +1,43 @@
+// Copyright 2024 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+//! Module containing serialization utilities
+
+/// Macro that generates serde::Serialize and serde::Deserialize implementations for the given types.
+/// This macro assumes that the types implement zerocopy::FromBytes and zerocopy::AsBytes, and uses
+/// these implementations to serialize as opaque byte arrays. During deserialization, it will
+/// try to deserialize as a `Vec`. If this deserialized `Vec` has a length that equals `size_of::<T>`,
+/// it will transmute to `T` (using zerocopy), otherwise the `Vec` will either be zero-padded, or truncated.
+/// This will hopefully allow live update of bindings across kernel versions even if the kernel adds
+/// new fields to the end of some struct (we heavily rely on the kernel not making ABI breaking changes here).
+macro_rules! serde_impls {
+    ($($typ: ty),*) => {
+        $(
+            impl Serialize for $typ {
+                fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+                where
+                    S: Serializer
+                {
+                    let bytes = self.as_bytes();
+                    serializer.serialize_bytes(bytes)
+                }
+            }
+
+            impl<'de> Deserialize<'de> for $typ {
+                fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+                where
+                    D: Deserializer<'de>
+                {
+                    let bytes = Vec::<u8>::deserialize(deserializer)?;
+
+                    let mut backing = [0u8; std::mem::size_of::<$typ>()];
+
+                    let limit = bytes.len().min(backing.len());
+
+                    backing[..limit].copy_from_slice(&bytes[..limit]);
+
+                    Ok(transmute!(backing))
+                }
+            }
+        )*
+    }
+}