Merge pull request #1873 from rust-osdev/uefi-raw-serial-revision

uefi-raw & uefi: serial: add support for protocol revision 1.1

Author: phip1611

uefi-raw/CHANGELOG.md

@@ -9,9 +9,14 @@
 - Added `HiiStringProtocol`.
 - Added `HiiPopupProtocol`.
 - Added `FormBrowser2Protocol`.
+- Added new type `SerialIoProtocolRevision`
+- Added new type `SerialIoProtocol_1_1` as companion for `SerialIoProtocol`
+  that includes the  `device_type_guid` parameter
 
 ## Changed
 - Switched `*const Self` to `*mut Self` in `SerialIoProtocol::set_attributes()`
+- Switched field `revision` in `SerialIoProtocol` from `u32` to new type
+  `SerialIoProtocolRevision`
 
 
 # uefi-raw - v0.13.0 (2025-11-05)

uefi-raw/src/protocol/console/serial.rs

@@ -77,10 +77,22 @@ pub struct SerialIoMode {
     pub stop_bits: StopBits,
 }
 
+newtype_enum! {
+    /// The revision of the [`SerialIoProtocol`].
+    #[derive(Default)]
+    pub enum SerialIoProtocolRevision: u32  => {
+        /// Initial version 1.0.
+        REVISION_1_0 = 0x00010000,
+        /// Version 1.1.
+        REVISION_1_1 = 0x00010001,
+    }
+}
+
+/// Serial I/O protocol (revision 1.0).
 #[derive(Debug)]
 #[repr(C)]
 pub struct SerialIoProtocol {
-    pub revision: u32,
+    pub revision: SerialIoProtocolRevision,
     pub reset: unsafe extern "efiapi" fn(*mut Self) -> Status,
     pub set_attributes: unsafe extern "efiapi" fn(
         *mut Self,
@@ -100,8 +112,19 @@ pub struct SerialIoProtocol {
 
 impl SerialIoProtocol {
     pub const GUID: Guid = guid!("bb25cf6f-f1d4-11d2-9a0c-0090273fc1fd");
-    pub const REVISION: u32 = 0x00010000;
-    pub const REVISION1P1: u32 = 0x00010001;
+}
+
+/// Serial I/O protocol (revision 1.1).
+#[derive(Debug)]
+#[repr(C)]
+#[allow(non_camel_case_types)]
+pub struct SerialIoProtocol_1_1 {
+    pub base_protocol: SerialIoProtocol,
+    pub device_type_guid: *const Guid,
+}
+
+impl SerialIoProtocol_1_1 {
+    pub const GUID: Guid = SerialIoProtocol::GUID;
 }
 
 newtype_enum! {

uefi-test-runner/src/proto/console/serial.rs

@@ -52,8 +52,16 @@ pub unsafe fn test() {
     info!("Running serial protocol test");
     let handle = boot::get_handle_for_protocol::<Serial>().expect("missing Serial protocol");
 
+    // Note: After this line, until we reconnected the console driver with the
+    // serial device, we won't get logging output on the serial device.
+    // Log messages are still printed to the debugcon device.
     let mut serial =
         boot::open_protocol_exclusive::<Serial>(handle).expect("failed to open serial protocol");
+    debug!("Serial protocol revision: {:?}", serial.revision());
+    debug!(
+        "Serial protocol device_type_guid: {:?}",
+        serial.device_type_guid()
+    );
 
     // Send the request, but don't check the result yet so that first
     // we can reconnect the console output for the logger.

uefi/CHANGELOG.md

@@ -10,6 +10,7 @@
 - Added `proto::device_path::DevicePath::to_pool()`.
 - Added `proto::device_path::DevicePathUtilities::duplicate_path()`.
 - Added `proto::pci::enumeration::PciTree::device_path()`.
+- Added `revision()` and `device_type_guid()` to `Serial` protocol
 
 ## Changed
 - export all `text::{input, output}::*` types

uefi/src/proto/console/serial.rs

@@ -2,12 +2,13 @@
 
 //! Abstraction over byte stream devices, also known as serial I/O devices.
 
-#[cfg(doc)]
-use crate::Status;
 use crate::proto::unsafe_protocol;
-use crate::{Result, StatusExt};
+use crate::{Error, Result, Status, StatusExt};
 use core::fmt::Write;
-use uefi_raw::protocol::console::serial::SerialIoProtocol;
+use uefi_raw::protocol::console::serial::{
+    SerialIoProtocol, SerialIoProtocol_1_1, SerialIoProtocolRevision,
+};
+use uguid::Guid;
 
 pub use uefi_raw::protocol::console::serial::{
     ControlBits, Parity, SerialIoMode as IoMode, StopBits,
@@ -52,6 +53,12 @@ pub use uefi_raw::protocol::console::serial::{
 pub struct Serial(SerialIoProtocol);
 
 impl Serial {
+    /// Returns the revision of the protocol.
+    #[must_use]
+    pub const fn revision(&self) -> SerialIoProtocolRevision {
+        self.0.revision
+    }
+
     /// Reset the device.
     ///
     /// # Errors
@@ -149,6 +156,46 @@ impl Serial {
             |_| buffer_size,
         )
     }
+
+    /// Pointer to a GUID identifying the device connected to the serial port.
+    ///
+    /// This is either `Ok` if [`Self::revision`] is at least
+    /// [`SerialIoProtocolRevision::REVISION_1_1`] or `Err` with
+    /// [`Status::UNSUPPORTED`].
+    ///
+    /// This GUID is `None` when the protocol is installed by the serial port
+    /// driver and may be populated by a platform driver for a serial port with
+    /// a known device attached. The GUID will remain `None` if there is no
+    /// platform serial device identification information available.
+    ///
+    /// # Errors
+    ///
+    /// - [`Status::UNSUPPORTED`]: If the revision is older than
+    ///   [`SerialIoProtocolRevision::REVISION_1_1`].
+    pub fn device_type_guid(&self) -> Result<Option<&'_ Guid>> {
+        let proto = self.as_revision_1_1()?;
+        // SAFETY: spec guarantees the layout of the underlying type
+        let device_type_guid = unsafe { proto.device_type_guid.as_ref() };
+        Ok(device_type_guid)
+    }
+
+    /// Casts the underlying [`SerialIoProtocol`] to an
+    /// [`SerialIoProtocol_1_1`].
+    fn as_revision_1_1(&self) -> Result<&'_ SerialIoProtocol_1_1> {
+        if self.revision() < SerialIoProtocolRevision::REVISION_1_1 {
+            return Err(Error::from(Status::UNSUPPORTED));
+        }
+
+        let ptr = &raw const self.0;
+        // SAFETY: ptr is guaranteed to be not null and by checking the revision
+        // we know the underlying allocation has the correct size.
+        let protocol = unsafe {
+            ptr.cast::<SerialIoProtocol_1_1>()
+                .as_ref()
+                .unwrap_unchecked()
+        };
+        Ok(protocol)
+    }
 }
 
 impl Write for Serial {

xtask/src/check_raw.rs

@@ -43,6 +43,7 @@ impl From<&Item> for ItemKind {
 #[derive(Debug, Eq, PartialEq)]
 enum ErrorKind {
     ForbiddenAbi,
+    ForbiddenAllow,
     ForbiddenAttr,
     ForbiddenItemKind(ItemKind),
     ForbiddenRepr(Vec<Repr>),
@@ -60,6 +61,7 @@ impl Display for ErrorKind {
     fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
         match self {
             Self::ForbiddenAbi => write!(f, "forbidden ABI"),
+            Self::ForbiddenAllow => write!(f, "forbidden allow"),
             Self::ForbiddenAttr => write!(f, "forbidden attribute"),
             Self::ForbiddenItemKind(ItemKind::Enum) => write!(
                 f,
@@ -140,6 +142,12 @@ fn is_pub(vis: &Visibility) -> bool {
     matches!(vis, Visibility::Public(_))
 }
 
+/// Allowed `#[allow]` attributes.
+#[derive(Debug, Clone, Copy)]
+enum Allow {
+    NonCamelCaseTypes,
+}
+
 /// Type repr. A type may have more than one of these (e.g. both `C` and `packed`).
 #[derive(Debug, Clone, Copy, Eq, PartialEq, Ord, PartialOrd)]
 enum Repr {
@@ -154,6 +162,7 @@ enum Repr {
 /// expected in `uefi-raw`.
 #[derive(Debug, Clone, Copy)]
 enum ParsedAttr {
+    Allow(Allow),
     Derive,
     Doc,
     Repr(Repr),
@@ -195,6 +204,20 @@ fn parse_attrs(attrs: &[Attribute], src: &Path) -> Result<Vec<ParsedAttr>, Error
             if unknown_repr_found {
                 return Err(Error::new(ErrorKind::UnknownRepr, src, attr));
             }
+        } else if path.is_ident("allow") {
+            let mut unknown_allow_found = false;
+            attr.parse_nested_meta(|meta| {
+                if meta.path.is_ident("non_camel_case_types") {
+                    va.push(ParsedAttr::Allow(Allow::NonCamelCaseTypes));
+                } else {
+                    unknown_allow_found = true;
+                }
+                Ok(())
+            })
+            .map_err(|_| Error::new(ErrorKind::MalformedAttrs, src, attr))?;
+            if unknown_allow_found {
+                return Err(Error::new(ErrorKind::ForbiddenAllow, src, attr));
+            }
         } else {
             return Err(Error::new(ErrorKind::ForbiddenAttr, src, attr));
         }