uefi: time: add integration_common module

This module provides the foundational plumbing for future time-related
crate integrations. It introduces common error types, including a
unified opaque ConversionError to standardize conversion failures across
crates.

While integration with crates like time and jiff is planned in
subsequent commits, this module lays the groundwork, ensuring a
consistent and minimal API for handling errors once those integrations
are implemented.

Author: phip1611

uefi/src/runtime/time_defs/integration_common.rs

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! Provides common helpers for the integration and conversion with
+//! different time crates from the ecosystem.
+
+use crate::runtime::TimeError;
+use core::error::Error;
+use core::fmt;
+use core::fmt::{Display, Formatter};
+
+/// An opaque error type indicating a UEFI [`Time`] could not be converted.
+///
+/// [`Time`]: super::Time
+#[derive(Debug)]
+pub struct ConversionError(pub(super) ConversionErrorInner);
+
+impl Display for ConversionError {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        write!(f, "Time conversion error: {}", self.0)
+    }
+}
+
+impl Error for ConversionError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        // Don't expose the inner error, it is not useful to the user.
+        None
+    }
+}
+
+#[derive(Debug)]
+pub(super) enum ConversionErrorInner {
+    /// Invalid component.
+    InvalidComponent,
+    /// Invalid UEFI time: [`Time::is_valid`] reported an error.
+    InvalidUefiTime(TimeError),
+    /// A timezone was required for the conversion, but the UEFI time indicates
+    /// [`Time::UNSPECIFIED_TIMEZONE`].
+    ///
+    /// [`Time::UNSPECIFIED_TIMEZONE`]: super::Time::UNSPECIFIED_TIMEZONE
+    UnspecifiedTimezone,
+}
+
+impl Display for ConversionErrorInner {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::InvalidComponent => write!(f, "Invalid component"),
+            Self::InvalidUefiTime(e) => write!(f, "Invalid UEFI time: {e}"),
+            Self::UnspecifiedTimezone => write!(f, "Unspecified timezone"),
+        }
+    }
+}
+
+impl Error for ConversionErrorInner {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        match self {
+            Self::InvalidComponent => None,
+            Self::InvalidUefiTime(e) => Some(e),
+            Self::UnspecifiedTimezone => None,
+        }
+    }
+}

uefi/src/runtime/time_defs/mod.rs

@@ -7,6 +7,9 @@ use core::fmt;
 use core::fmt::{Debug, Display, Formatter};
 use uefi_raw::time::Daylight;
 
+#[allow(unused)]
+mod integration_common;
+
 /// Date and time representation.
 #[derive(Copy, Clone, Eq, PartialEq)]
 #[repr(transparent)]