serial: add methods to retrieve the underlying output writer

Add three methods (writer(), writer_mut() and into_writer()) to Serial
in order to obtain the original output object back from the device.
This allows the device to gain ownership of the object and for the
caller to retrieve it back when needed.

Otherwise, if one wants the device to write output into an in-memory
structure (e.g. a Vec), which can later be accessed, one must give
out a mutable reference. This can be problematic if one stores the
buffer and the device within the same structure due to Rust's issues
with self-referential structures. This is also more ergonomic in
terms of saving and restoring the device's state, if one considers
the output part of the state.

Signed-off-by: Carlos López <[email protected]>

Author: 00xc

vm-superio/CHANGELOG.md

@@ -6,6 +6,7 @@
 
 - Added a `reset_evt` to the `I8042Device` type to retrieve the underlying
   reset event object.
+- Added three methods to `Serial` to retrieve the `Write` output object.
 
 # v0.7.0
 

vm-superio/src/serial.rs

@@ -401,6 +401,79 @@ impl<T: Trigger, EV: SerialEvents, W: Write> Serial<T, EV, W> {
         }
     }
 
+    /// Gets a reference to the output Write object
+    ///
+    /// ```rust
+    /// # use vm_superio::Trigger;
+    /// # use vm_superio::serial::Serial;
+    /// # struct DummyTrigger;
+    /// # impl Trigger for DummyTrigger {
+    /// #     type E = ();
+    /// #     fn trigger(&self) -> Result<(), ()> { Ok(()) }
+    /// # }
+    /// const DATA_OFFSET: u8 = 0;
+    ///
+    /// let output = Vec::new();
+    /// let mut serial = Serial::new(DummyTrigger, output);
+    /// serial.write(DATA_OFFSET, 0x66).unwrap();
+    /// assert_eq!(serial.writer().first().copied(), Some(0x66));
+    /// ```
+    pub fn writer(&self) -> &W {
+        &self.out
+    }
+
+    /// Gets a mutable reference to the output Write object
+    ///
+    /// ```rust
+    /// # use vm_superio::Trigger;
+    /// # use vm_superio::serial::Serial;
+    /// # struct DummyTrigger;
+    /// # impl Trigger for DummyTrigger {
+    /// #     type E = ();
+    /// #     fn trigger(&self) -> Result<(), ()> { Ok(()) }
+    /// # }
+    /// const DATA_OFFSET: u8 = 0;
+    ///
+    /// let output = Vec::new();
+    /// let mut serial = Serial::new(DummyTrigger, output);
+    /// serial.write(DATA_OFFSET, 0x66).unwrap();
+    /// serial.writer_mut().clear();
+    /// assert_eq!(serial.writer().first(), None);
+    /// ```
+    pub fn writer_mut(&mut self) -> &mut W {
+        &mut self.out
+    }
+
+    /// Consumes the device and retrieves the inner writer. This
+    /// can be useful when restoring a copy of the device.
+    ///
+    /// ```rust
+    /// # use vm_superio::Trigger;
+    /// # use vm_superio::serial::{NoEvents, Serial};
+    /// # struct DummyTrigger;
+    /// # impl Trigger for DummyTrigger {
+    /// #    type E = ();
+    /// #    fn trigger(&self) -> Result<(), ()> { Ok(()) }
+    /// # }
+    /// const DATA_OFFSET: u8 = 0;
+    ///
+    /// // Create a device with some state
+    /// let output = Vec::new();
+    /// let mut serial = Serial::new(DummyTrigger, output);
+    /// serial.write(DATA_OFFSET, 0x66).unwrap();
+    ///
+    /// // Save the state
+    /// let state = serial.state();
+    /// let output = serial.into_writer();
+    ///
+    /// // Restore the device
+    /// let restored_serial = Serial::from_state(&state, DummyTrigger, NoEvents, output).unwrap();
+    /// assert_eq!(restored_serial.writer().first().copied(), Some(0x66));
+    /// ```
+    pub fn into_writer(self) -> W {
+        self.out
+    }
+
     /// Provides a reference to the interrupt event object.
     pub fn interrupt_evt(&self) -> &T {
         &self.interrupt_evt