Skip to main content

etw_wrapper/
types.rs

1//! Crate-owned Windows ABI types.
2
3use core::hash::{Hash, Hasher};
4
5pub(crate) use crate::bindings::EVENT_DATA_DESCRIPTOR;
6
7/// Describes an ETW event's identity and filtering metadata.
8#[repr(C)]
9#[derive(Clone, Copy, Default)]
10pub struct EventDescriptor {
11    /// The event identifier.
12    pub id: u16,
13    /// The event definition version.
14    pub version: u8,
15    /// The event channel.
16    pub channel: u8,
17    /// The event severity level.
18    pub level: u8,
19    /// The operation performed by the event.
20    pub opcode: u8,
21    /// The event task.
22    pub task: u16,
23    /// The event category bitmask.
24    pub keyword: u64,
25}
26
27/// A Windows file time represented as 100-nanosecond intervals since January 1, 1601 UTC.
28#[repr(C)]
29#[derive(Clone, Copy, Default)]
30pub struct FileTime {
31    /// The low-order 32 bits of the file time.
32    pub low_date_time: u32,
33    /// The high-order 32 bits of the file time.
34    pub high_date_time: u32,
35}
36
37/// A Windows globally unique identifier.
38#[repr(C)]
39#[derive(Clone, Copy)]
40pub struct Guid {
41    /// The first 32 bits of the GUID.
42    pub data1: u32,
43    /// The next 16 bits of the GUID.
44    pub data2: u16,
45    /// The next 16 bits of the GUID.
46    pub data3: u16,
47    /// The final 64 bits of the GUID.
48    pub data4: [u8; 8],
49}
50
51/// A Windows date and time with millisecond precision.
52#[repr(C)]
53#[derive(Clone, Copy, Default)]
54pub struct SystemTime {
55    /// The year.
56    pub year: u16,
57    /// The month.
58    pub month: u16,
59    /// The day of the week.
60    pub day_of_week: u16,
61    /// The day of the month.
62    pub day: u16,
63    /// The hour.
64    pub hour: u16,
65    /// The minute.
66    pub minute: u16,
67    /// The second.
68    pub second: u16,
69    /// The millisecond.
70    pub milliseconds: u16,
71}
72
73impl Default for Guid {
74    fn default() -> Self {
75        Self::from_u128(0)
76    }
77}
78
79impl PartialEq for Guid {
80    fn eq(&self, other: &Self) -> bool {
81        self.data1 == other.data1
82            && self.data2 == other.data2
83            && self.data3 == other.data3
84            && self.data4 == other.data4
85    }
86}
87
88impl Eq for Guid {}
89
90impl Hash for Guid {
91    fn hash<H: Hasher>(&self, state: &mut H) {
92        self.data1.hash(state);
93        self.data2.hash(state);
94        self.data3.hash(state);
95        self.data4.hash(state);
96    }
97}
98
99impl Guid {
100    /// Creates a `Guid` from its canonical `u128` value.
101    #[must_use]
102    pub const fn from_u128(uuid: u128) -> Self {
103        Self {
104            data1: (uuid >> 96) as u32,
105            data2: (uuid >> 80 & 0xffff) as u16,
106            data3: (uuid >> 64 & 0xffff) as u16,
107            data4: (uuid as u64).to_be_bytes(),
108        }
109    }
110
111    /// Converts a `Guid` back to its canonical `u128` value.
112    #[must_use]
113    pub const fn to_u128(&self) -> u128 {
114        ((self.data1 as u128) << 96)
115            + ((self.data2 as u128) << 80)
116            + ((self.data3 as u128) << 64)
117            + u64::from_be_bytes(self.data4) as u128
118    }
119
120    /// Creates a `Guid` from its individual fields.
121    #[must_use]
122    pub const fn from_values(data1: u32, data2: u16, data3: u16, data4: [u8; 8]) -> Self {
123        Self {
124            data1,
125            data2,
126            data3,
127            data4,
128        }
129    }
130}
131
132impl core::fmt::Debug for Guid {
133    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
134        write!(
135            f,
136            "{:08X?}-{:04X?}-{:04X?}-{:02X?}{:02X?}-{:02X?}{:02X?}{:02X?}{:02X?}{:02X?}{:02X?}",
137            self.data1,
138            self.data2,
139            self.data3,
140            self.data4[0],
141            self.data4[1],
142            self.data4[2],
143            self.data4[3],
144            self.data4[4],
145            self.data4[5],
146            self.data4[6],
147            self.data4[7]
148        )
149    }
150}
151
152impl From<u128> for Guid {
153    fn from(value: u128) -> Self {
154        Self::from_u128(value)
155    }
156}
157
158impl From<Guid> for u128 {
159    fn from(value: Guid) -> Self {
160        value.to_u128()
161    }
162}
163
164macro_rules! impl_value_traits {
165    ($type:ty { $($field:ident),+ $(,)? }) => {
166        impl core::fmt::Debug for $type {
167            fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
168                let mut value = f.debug_struct(stringify!($type));
169                $(value.field(stringify!($field), &self.$field);)+
170                value.finish()
171            }
172        }
173
174        impl PartialEq for $type {
175            fn eq(&self, other: &Self) -> bool {
176                true $(&& self.$field == other.$field)+
177            }
178        }
179
180        impl Eq for $type {}
181
182        impl Hash for $type {
183            fn hash<H: Hasher>(&self, state: &mut H) {
184                $(self.$field.hash(state);)+
185            }
186        }
187    };
188}
189
190impl_value_traits!(FileTime {
191    low_date_time,
192    high_date_time,
193});
194impl_value_traits!(SystemTime {
195    year,
196    month,
197    day_of_week,
198    day,
199    hour,
200    minute,
201    second,
202    milliseconds,
203});
204impl_value_traits!(EventDescriptor {
205    id,
206    version,
207    channel,
208    level,
209    opcode,
210    task,
211    keyword,
212});
213
214// `windows-bindgen` cannot derive these through the descriptor's trailing union. Comparing and
215// hashing the union as its `Reserved` word covers every possible bit pattern and matches its ABI.
216impl core::fmt::Debug for EVENT_DATA_DESCRIPTOR {
217    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
218        f.debug_struct("EVENT_DATA_DESCRIPTOR")
219            .field("Ptr", &self.Ptr)
220            .field("Size", &self.Size)
221            .field("Reserved", unsafe { &self.Anonymous.Reserved })
222            .finish()
223    }
224}
225
226impl PartialEq for EVENT_DATA_DESCRIPTOR {
227    fn eq(&self, other: &Self) -> bool {
228        self.Ptr == other.Ptr
229            && self.Size == other.Size
230            && unsafe { self.Anonymous.Reserved == other.Anonymous.Reserved }
231    }
232}
233
234impl Eq for EVENT_DATA_DESCRIPTOR {}
235
236impl Hash for EVENT_DATA_DESCRIPTOR {
237    fn hash<H: Hasher>(&self, state: &mut H) {
238        self.Ptr.hash(state);
239        self.Size.hash(state);
240        unsafe { self.Anonymous.Reserved.hash(state) };
241    }
242}
243
244#[cfg(test)]
245mod tests {
246    use super::*;
247    use std::mem::offset_of;
248
249    // 6ba7b810-9dad-11d1-80b4-00c04fd430c8, the RFC 4122 DNS namespace UUID. Every field differs,
250    // so a byte-order mistake in `from_u128` cannot go unnoticed.
251    const SAMPLE: u128 = 0x6ba7b810_9dad_11d1_80b4_00c04fd430c8;
252
253    #[test]
254    fn public_types_preserve_the_win32_abi_layout() {
255        assert_eq!(size_of::<Guid>(), size_of::<crate::bindings::GUID>());
256        assert_eq!(align_of::<Guid>(), align_of::<crate::bindings::GUID>());
257        assert_eq!(offset_of!(Guid, data1), 0);
258        assert_eq!(offset_of!(Guid, data2), 4);
259        assert_eq!(offset_of!(Guid, data3), 6);
260        assert_eq!(offset_of!(Guid, data4), 8);
261
262        assert_eq!(size_of::<EventDescriptor>(), 16);
263        assert_eq!(align_of::<EventDescriptor>(), 8);
264        assert_eq!(offset_of!(EventDescriptor, id), 0);
265        assert_eq!(offset_of!(EventDescriptor, version), 2);
266        assert_eq!(offset_of!(EventDescriptor, channel), 3);
267        assert_eq!(offset_of!(EventDescriptor, level), 4);
268        assert_eq!(offset_of!(EventDescriptor, opcode), 5);
269        assert_eq!(offset_of!(EventDescriptor, task), 6);
270        assert_eq!(offset_of!(EventDescriptor, keyword), 8);
271
272        assert_eq!(size_of::<FileTime>(), 8);
273        assert_eq!(align_of::<FileTime>(), 4);
274        assert_eq!(offset_of!(FileTime, low_date_time), 0);
275        assert_eq!(offset_of!(FileTime, high_date_time), 4);
276
277        assert_eq!(size_of::<SystemTime>(), 16);
278        assert_eq!(align_of::<SystemTime>(), 2);
279        assert_eq!(offset_of!(SystemTime, year), 0);
280        assert_eq!(offset_of!(SystemTime, month), 2);
281        assert_eq!(offset_of!(SystemTime, day_of_week), 4);
282        assert_eq!(offset_of!(SystemTime, day), 6);
283        assert_eq!(offset_of!(SystemTime, hour), 8);
284        assert_eq!(offset_of!(SystemTime, minute), 10);
285        assert_eq!(offset_of!(SystemTime, second), 12);
286        assert_eq!(offset_of!(SystemTime, milliseconds), 14);
287    }
288
289    #[test]
290    fn guid_round_trips_through_u128() {
291        for value in [0, u128::MAX, SAMPLE, 1, 1 << 64] {
292            assert_eq!(Guid::from_u128(value).to_u128(), value);
293        }
294    }
295
296    #[test]
297    fn guid_debug_uses_the_canonical_text_form() {
298        assert_eq!(
299            format!("{:?}", Guid::from_u128(SAMPLE)),
300            "6BA7B810-9DAD-11D1-80B4-00C04FD430C8"
301        );
302    }
303
304    #[test]
305    fn guid_from_values_matches_from_u128() {
306        let expected = Guid::from_u128(SAMPLE);
307        let actual = Guid::from_values(
308            0x6ba7b810,
309            0x9dad,
310            0x11d1,
311            [0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8],
312        );
313        assert_eq!(actual, expected);
314    }
315
316    #[test]
317    fn event_data_descriptor_default_selects_the_plain_payload_type() {
318        let descriptor = EVENT_DATA_DESCRIPTOR::default();
319        assert_eq!(
320            unsafe { descriptor.Anonymous.Reserved },
321            crate::bindings::EVENT_DATA_DESCRIPTOR_TYPE_NONE
322        );
323    }
324}