add QueueStateSer

This provides serialization capabilities to QueueState,
and is defined in the virtio-queue-ser crate.
QueueStateSer mirrors the state structure from virtio-queue, and
derives the required (de)serialization/versioning traits
(i.e. Serialize, Deserialize, Versionize).

Signed-off-by: Laura Loghin <[email protected]>

Author: lauralt

Cargo.toml

@@ -1,6 +1,7 @@
 [workspace]
 members = [
     "crates/virtio-queue",
+    "crates/virtio-queue-ser",
     "crates/virtio-device",
     "crates/devices/*",
 ]

crates/virtio-queue-ser/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "virtio-queue-ser"
+version = "0.1.0"
+authors = ["rust-vmm AWS maintainers <[email protected]>"]
+description = "Serialization for virtio queue state"
+repository = "https://github.com/rust-vmm/vm-virtio"
+keywords = ["queue", "serialization", "versioning"]
+readme = "README.md"
+license = "Apache-2.0 OR BSD-3-Clause"
+edition = "2018"
+
+[dependencies]
+serde = { version = ">=1.0.27", features = ["derive"] }
+versionize = ">=0.1.6"
+versionize_derive = ">=0.1.3"
+virtio-queue = { path = "../../crates/virtio-queue" }
+vm-memory = "0.7.0"

crates/virtio-queue-ser/src/lib.rs

@@ -0,0 +1,14 @@
+// Copyright 2022 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0 OR BSD-3-Clause
+
+//! Adds serialization capabilities to the state objects from `virtio-queue`.
+//!
+//! Provides wrappers over the state objects from `virtio-queue` crate that
+//! implement the `Serialize`, `Deserialize` and `Versionize` traits.
+
+#![deny(missing_docs)]
+
+mod state;
+
+pub use state::QueueStateSer;

crates/virtio-queue-ser/src/state.rs

@@ -0,0 +1,116 @@
+// Copyright 2022 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0 OR BSD-3-Clause
+
+use std::num::Wrapping;
+
+use serde::{Deserialize, Serialize};
+use versionize::{VersionMap, Versionize, VersionizeResult};
+use versionize_derive::Versionize;
+use virtio_queue::QueueState;
+use vm_memory::GuestAddress;
+
+/// /// Wrapper over a `QueueState` that has serialization capabilities.
+#[derive(Clone, Debug, Deserialize, PartialEq, Serialize, Versionize)]
+pub struct QueueStateSer {
+    /// The maximum size in elements offered by the device.
+    pub max_size: u16,
+    /// Tail position of the available ring.
+    pub next_avail: Wrapping<u16>,
+    /// Head position of the used ring.
+    pub next_used: Wrapping<u16>,
+    /// VIRTIO_F_RING_EVENT_IDX negotiated.
+    pub event_idx_enabled: bool,
+    /// The last used value when using VIRTIO_F_EVENT_IDX.
+    pub signalled_used: Option<Wrapping<u16>>,
+    /// The queue size in elements the driver selected.
+    pub size: u16,
+    /// Indicates if the queue finished with the configuration.
+    pub ready: bool,
+    /// Guest physical address of the descriptor table.
+    pub desc_table: u64,
+    /// Guest physical address of the available ring.
+    pub avail_ring: u64,
+    /// Guest physical address of the used ring.
+    pub used_ring: u64,
+}
+
+// The following `From` implementations can be used to convert from a `QueueStateSer` to the
+// `QueueState` from the base crate and vice versa.
+impl From<&QueueStateSer> for QueueState {
+    fn from(state: &QueueStateSer) -> Self {
+        QueueState {
+            max_size: state.max_size,
+            next_avail: state.next_avail,
+            next_used: state.next_used,
+            event_idx_enabled: state.event_idx_enabled,
+            signalled_used: state.signalled_used,
+            size: state.size,
+            ready: state.ready,
+            desc_table: GuestAddress(state.desc_table),
+            avail_ring: GuestAddress(state.avail_ring),
+            used_ring: GuestAddress(state.used_ring),
+        }
+    }
+}
+
+impl From<&QueueState> for QueueStateSer {
+    fn from(state: &QueueState) -> Self {
+        QueueStateSer {
+            max_size: state.max_size,
+            next_avail: state.next_avail,
+            next_used: state.next_used,
+            event_idx_enabled: state.event_idx_enabled,
+            signalled_used: state.signalled_used,
+            size: state.size,
+            ready: state.ready,
+            desc_table: state.desc_table.0,
+            avail_ring: state.avail_ring.0,
+            used_ring: state.used_ring.0,
+        }
+    }
+}
+
+impl Default for QueueStateSer {
+    fn default() -> Self {
+        QueueStateSer::from(&QueueState::default())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_state_ser() {
+        const SOME_VALUE: u16 = 16;
+
+        let state = QueueState {
+            max_size: SOME_VALUE * 2,
+            next_avail: Wrapping(SOME_VALUE - 1),
+            next_used: Wrapping(SOME_VALUE + 1),
+            event_idx_enabled: false,
+            signalled_used: None,
+            size: SOME_VALUE,
+            ready: false,
+            desc_table: GuestAddress(SOME_VALUE as u64),
+            avail_ring: GuestAddress(SOME_VALUE as u64),
+            used_ring: GuestAddress(SOME_VALUE as u64),
+        };
+
+        let ser_state = QueueStateSer::from(&state);
+
+        let state_after_restore = QueueState::from(&ser_state);
+
+        // Check that the old and the new state are identical when using the intermediate
+        // `QueueStateSer` object as well.
+        assert_eq!(state, state_after_restore);
+
+        // Test the `Default` implementation of `QueueStateSer`.
+        let default_queue_state_ser = QueueStateSer::default();
+        assert_eq!(
+            QueueState::from(&default_queue_state_ser),
+            QueueState::default()
+        );
+    }
+}

crates/virtio-queue/src/state.rs

@@ -22,7 +22,7 @@ use crate::defs::{
 use crate::{error, AvailIter, Descriptor, Error, QueueStateGuard, QueueStateT, VirtqUsedElem};
 
 /// Struct to maintain information and manipulate state of a virtio queue.
-#[derive(Clone, Debug)]
+#[derive(Clone, Debug, Default, PartialEq)]
 pub struct QueueState {
     /// The maximum size in elements offered by the device.
     pub max_size: u16,