Skip to main content

hyperlight_common/
log_level.rs

1// SPDX-License-Identifier: Apache-2.0
2// Copyright 2025 The Hyperlight Authors.
3
4/// This type is a unified definition of log level filters between the guest and host.
5///
6/// This is needed because currently the guest uses both the `log` and `tracing` crates,
7/// and needs each type of `LevelFilter` from both crates.
8///
9/// To avoid as much as possible the amount of conversions between the two types, we define a
10/// single type that can be converted to both `log::LevelFilter` and `tracing_core::LevelFilter`.
11/// NOTE: This also takes care of the fact that the `tracing` and `log` enum types for the log
12/// levels are not guaranteed to have the same discriminants, so we can't just cast between them.
13#[derive(Debug, Clone, Copy, PartialEq, Eq)]
14pub enum GuestLogFilter {
15    Off,
16    Error,
17    Warn,
18    Info,
19    Debug,
20    Trace,
21}
22
23/// Marks a pending runtime guest log-level update in scratch memory.
24pub const GUEST_LOG_FILTER_UPDATE_PENDING: u64 = 1 << 63;
25
26impl From<GuestLogFilter> for tracing_core::LevelFilter {
27    fn from(filter: GuestLogFilter) -> Self {
28        match filter {
29            GuestLogFilter::Off => tracing_core::LevelFilter::OFF,
30            GuestLogFilter::Error => tracing_core::LevelFilter::ERROR,
31            GuestLogFilter::Warn => tracing_core::LevelFilter::WARN,
32            GuestLogFilter::Info => tracing_core::LevelFilter::INFO,
33            GuestLogFilter::Debug => tracing_core::LevelFilter::DEBUG,
34            GuestLogFilter::Trace => tracing_core::LevelFilter::TRACE,
35        }
36    }
37}
38
39impl From<GuestLogFilter> for log::LevelFilter {
40    fn from(filter: GuestLogFilter) -> Self {
41        match filter {
42            GuestLogFilter::Off => log::LevelFilter::Off,
43            GuestLogFilter::Error => log::LevelFilter::Error,
44            GuestLogFilter::Warn => log::LevelFilter::Warn,
45            GuestLogFilter::Info => log::LevelFilter::Info,
46            GuestLogFilter::Debug => log::LevelFilter::Debug,
47            GuestLogFilter::Trace => log::LevelFilter::Trace,
48        }
49    }
50}
51
52/// Used by the host to convert a [`tracing_core::LevelFilter`] to the intermediary [`GuestLogFilter`]
53/// filter that is later converted to `u64` and passed to the guest via the C API.
54impl From<tracing_core::LevelFilter> for GuestLogFilter {
55    fn from(value: tracing_core::LevelFilter) -> Self {
56        match value {
57            tracing_core::LevelFilter::OFF => Self::Off,
58            tracing_core::LevelFilter::ERROR => Self::Error,
59            tracing_core::LevelFilter::WARN => Self::Warn,
60            tracing_core::LevelFilter::INFO => Self::Info,
61            tracing_core::LevelFilter::DEBUG => Self::Debug,
62            tracing_core::LevelFilter::TRACE => Self::Trace,
63        }
64    }
65}
66
67/// Used by the guest to convert a `u64` value passed from the host via the C API to the
68/// intermediary [`GuestLogFilter`] filter that is later converted to both
69/// `tracing_core::LevelFilter` and `log::LevelFilter`.
70impl TryFrom<u64> for GuestLogFilter {
71    type Error = ();
72
73    fn try_from(value: u64) -> Result<Self, <GuestLogFilter as TryFrom<u64>>::Error> {
74        match value {
75            0 => Ok(Self::Off),
76            1 => Ok(Self::Error),
77            2 => Ok(Self::Warn),
78            3 => Ok(Self::Info),
79            4 => Ok(Self::Debug),
80            5 => Ok(Self::Trace),
81            _ => Err(()),
82        }
83    }
84}
85
86/// Used by the host to convert the [`GuestLogFilter`] to a `u64` that is passed to the guest via
87/// the C API.
88impl From<GuestLogFilter> for u64 {
89    fn from(value: GuestLogFilter) -> Self {
90        match value {
91            GuestLogFilter::Off => 0,
92            GuestLogFilter::Error => 1,
93            GuestLogFilter::Warn => 2,
94            GuestLogFilter::Info => 3,
95            GuestLogFilter::Debug => 4,
96            GuestLogFilter::Trace => 5,
97        }
98    }
99}
100
101#[cfg(test)]
102mod tests {
103    use super::GuestLogFilter;
104
105    #[test]
106    fn guest_log_filter_u64_roundtrip() {
107        let variants = [
108            GuestLogFilter::Off,
109            GuestLogFilter::Error,
110            GuestLogFilter::Warn,
111            GuestLogFilter::Info,
112            GuestLogFilter::Debug,
113            GuestLogFilter::Trace,
114        ];
115
116        for variant in variants {
117            let as_u64: u64 = variant.into();
118            let back =
119                GuestLogFilter::try_from(as_u64).expect("conversion from u64 should succeed");
120            assert_eq!(variant, back);
121        }
122    }
123
124    #[test]
125    fn guest_log_filter_tracing_roundtrip() {
126        let variants = [
127            GuestLogFilter::Off,
128            GuestLogFilter::Error,
129            GuestLogFilter::Warn,
130            GuestLogFilter::Info,
131            GuestLogFilter::Debug,
132            GuestLogFilter::Trace,
133        ];
134
135        for variant in variants {
136            let tracing_filter: tracing_core::LevelFilter = variant.into();
137            let back: GuestLogFilter = tracing_filter.into();
138            assert_eq!(variant, back);
139        }
140    }
141
142    #[test]
143    fn guest_log_filter_log_conversion() {
144        let variants = [
145            GuestLogFilter::Off,
146            GuestLogFilter::Error,
147            GuestLogFilter::Warn,
148            GuestLogFilter::Info,
149            GuestLogFilter::Debug,
150            GuestLogFilter::Trace,
151        ];
152
153        let log_variants = [
154            log::LevelFilter::Off,
155            log::LevelFilter::Error,
156            log::LevelFilter::Warn,
157            log::LevelFilter::Info,
158            log::LevelFilter::Debug,
159            log::LevelFilter::Trace,
160        ];
161
162        for (variant, log_variant) in variants.into_iter().zip(log_variants) {
163            let log_filter = log::LevelFilter::from(variant);
164            assert_eq!(log_filter, log_variant);
165        }
166    }
167
168    #[test]
169    fn guest_log_filter_try_from_u64_rejects_invalid() {
170        // Any value outside the defined range [0, 5] should be rejected.
171        assert!(GuestLogFilter::try_from(u64::MAX).is_err());
172        assert!(GuestLogFilter::try_from(6).is_err());
173    }
174}