hyperv_ic_protocol/
lib.rs

1// Copyright (c) Microsoft Corporation.
2// Licensed under the MIT License.
3
4//! IC protocol definitions.
5
6#![forbid(unsafe_code)]
7
8pub mod heartbeat;
9pub mod kvp;
10pub mod shutdown;
11pub mod timesync;
12pub mod vss;
13
14use bitfield_struct::bitfield;
15use open_enum::open_enum;
16use std::fmt::Display;
17use zerocopy::FromBytes;
18use zerocopy::Immutable;
19use zerocopy::IntoBytes;
20use zerocopy::KnownLayout;
21
22/// Maximum message size between guest and host for IC devices.
23pub const MAX_MESSAGE_SIZE: usize = 13312;
24
25/// Protocol version.
26#[repr(C)]
27#[derive(
28    Debug, Copy, Clone, IntoBytes, Immutable, KnownLayout, FromBytes, PartialEq, Eq, PartialOrd, Ord,
29)]
30pub struct Version {
31    /// Major version.
32    pub major: u16,
33    /// Minor version.
34    pub minor: u16,
35}
36
37/// Framework version 1.0.
38pub const FRAMEWORK_VERSION_1: Version = Version::new(1, 0);
39/// Framework version 3.0.
40pub const FRAMEWORK_VERSION_3: Version = Version::new(3, 0);
41
42impl Version {
43    /// Create a new IC version instance.
44    pub const fn new(major: u16, minor: u16) -> Self {
45        Version { major, minor }
46    }
47}
48
49impl Display for Version {
50    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
51        write!(f, "{}.{}", self.major, self.minor)
52    }
53}
54
55open_enum! {
56    /// Type of message
57    #[derive(IntoBytes, Immutable, KnownLayout, FromBytes)]
58    pub enum MessageType: u16 {
59        /// Initial version negotiation between host and guest.
60        VERSION_NEGOTIATION = 0,
61        /// Heartbeat / check if alive.
62        HEARTBEAT = 1,
63        /// KVP exchange.
64        KVP_EXCHANGE = 2,
65        /// Request shutdown.
66        SHUTDOWN = 3,
67        /// Synchronize time.
68        TIME_SYNC = 4,
69        /// VSS
70        VSS = 5,
71        /// RDV
72        RDV = 6,
73        /// Guest interface.
74        GUEST_INTERFACE = 7,
75        /// VM Session.
76        VM_SESSION = 8,
77    }
78}
79
80/// Common message header for IC messages.
81#[repr(C)]
82#[derive(IntoBytes, Immutable, KnownLayout, FromBytes, Debug)]
83pub struct Header {
84    /// Version of the IC framework.
85    pub framework_version: Version,
86    /// Type of message.
87    pub message_type: MessageType,
88    /// Version of message content.
89    pub message_version: Version,
90    /// Size in bytes of the message.
91    pub message_size: u16,
92    /// Status code used for message response.
93    pub status: Status,
94    /// Transaction ID; should be matched by response message.
95    pub transaction_id: u8,
96    /// Message flags.
97    pub flags: HeaderFlags,
98    /// Reserved -- should be zero.
99    pub reserved: [u8; 2],
100}
101
102open_enum! {
103    /// Status code for a message response.
104    #[derive(IntoBytes, Immutable, KnownLayout, FromBytes)]
105    pub enum Status: u32 {
106        /// Message was processed successfully.
107        SUCCESS = 0,
108        /// There are no more items to process.
109        NO_MORE_ITEMS = 0x80070103,
110        /// Generic failure.
111        FAIL = 0x80004005,
112        /// The operation is not supported.
113        NOT_SUPPORTED = 0x80070032,
114        /// Not found.
115        NOT_FOUND = 0x80041002,
116    }
117}
118
119/// Flags for IC messages.
120#[bitfield(u8)]
121#[derive(IntoBytes, Immutable, KnownLayout, FromBytes)]
122pub struct HeaderFlags {
123    /// Message expects a response.
124    pub transaction: bool,
125    /// Message is a request.
126    pub request: bool,
127    /// Message is a response.
128    pub response: bool,
129    /// Reserved - must be zero.
130    #[bits(5)]
131    _reserved: u8,
132}
133
134/// Version negotiation message.
135#[repr(C)]
136#[derive(IntoBytes, Immutable, KnownLayout, FromBytes)]
137pub struct NegotiateMessage {
138    /// The number of supported framework versions, located directly after
139    /// this structure.
140    pub framework_version_count: u16,
141    /// The number of supported message versions, located after the framework
142    /// versions.
143    pub message_version_count: u16,
144    /// Reserved -- must be zero.
145    pub reserved: u32,
146}
hyperv_ic_protocol/lib.rs

hyperv_ic_protocol/
lib.rs
