netstack3_base/tcp/
timestamp.rs

1// Copyright 2025 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5//! TCP Timestamp Option as defined in RFC 7323.
6
7use core::cmp::{Ord, Ordering, PartialOrd};
8use core::marker::PhantomData;
9use core::ops::Add;
10use core::time::Duration;
11use derivative::Derivative;
12
13/// A timestamp to be used in the TCP Timestamp Option.
14///
15/// Per RFC 7323 Section 5.2:
16///   the "timestamps" are 32-bit unsigned integers in a modular 32-bit space.
17///
18/// Note: timestamps have no inherent units. The sender and receiver are each
19/// free to decide upon the units relevant to the timestamps they generate.
20/// However, per RFC 7323 Section 5.4:
21///   (a)  The timestamp clock must not be "too slow". [...]
22///   (b)  The timestamp clock must not be "too fast". [...]
23///   Based upon these considerations, we choose a timestamp clock frequency in
24///   the range 1 ms to 1 sec per tick.
25#[derive(Debug, Derivative, Clone, Copy)]
26#[derivative(Eq(bound = ""), PartialEq(bound = ""))]
27pub struct Timestamp<U> {
28    timestamp: u32,
29    unit: PhantomData<U>,
30}
31
32/// A marker type indicating that the backing units of a [`Timestamp`] are
33/// unknown.
34#[derive(Debug, Clone, Copy)]
35pub enum Unitless {}
36
37/// A marker type indicating that the backing units of a [`Timestamp`] are
38/// milliseconds.
39///
40/// Note: Based on the considerations from RFC 7323 section 5.4, milliseconds
41/// are the most appropriate units to use for timestamps generated by ourselves.
42/// This choice supports bandwidths up to 8 Tbps, and idle connections up to 24
43/// days.
44#[derive(Debug, Clone, Copy)]
45pub enum Milliseconds {}
46
47impl<U> Timestamp<U> {
48    /// Constructs a new [`Timestamp`] from a raw [`u32`].
49    pub const fn new(timestamp: u32) -> Self {
50        Timestamp { timestamp, unit: PhantomData::<U> }
51    }
52
53    /// Retrieve the raw 32-bit timestamp value.
54    pub const fn get(&self) -> u32 {
55        let Timestamp { timestamp, unit: _ } = self;
56        *timestamp
57    }
58}
59
60impl<U> Ord for Timestamp<U> {
61    fn cmp(&self, rhs: &Timestamp<U>) -> Ordering {
62        let Timestamp { timestamp: lhs, unit: _ } = self;
63        let Timestamp { timestamp: rhs, unit: _ } = rhs;
64        // Per RFC 7323 Section 5.2:
65        //   Thus, "less than" is defined the same way it is for TCP sequence
66        //   numbers, and the same implementation techniques apply.  If s and t
67        //   are timestamp values,
68        //       s < t  if 0 < (t - s) < 2^31,
69        //   computed in unsigned 32-bit arithmetic.
70        let delta = rhs.wrapping_sub(*lhs);
71        if delta == 0 {
72            Ordering::Equal
73        } else if delta > 0 && delta < (1 << 31) {
74            Ordering::Less
75        } else {
76            Ordering::Greater
77        }
78    }
79}
80
81impl<U> PartialOrd for Timestamp<U> {
82    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
83        Some(self.cmp(other))
84    }
85}
86
87impl Add<Duration> for Timestamp<Milliseconds> {
88    type Output = Self;
89
90    fn add(self, rhs: Duration) -> Self::Output {
91        let Timestamp { timestamp: lhs, unit } = self;
92        let rhs: u128 = rhs.as_millis();
93        // The following `as` coercion is sound because `Timestamp` exists in
94        // modular 32-bit space. This drops the higher order bits from the
95        // original value, which is representative of the `Timestamp` wrapping
96        // around.
97        let rhs = rhs as u32;
98        Timestamp { timestamp: lhs.wrapping_add(rhs), unit }
99    }
100}
101
102/// The TCP timestamp option as defined in RFC 7323, Section 3.
103#[derive(Debug, PartialEq, Eq, Clone, Copy)]
104pub struct TimestampOption {
105    /// The timestamp value.
106    pub(super) ts_val: Timestamp<Unitless>,
107    /// The timestamp echo reply.
108    pub(super) ts_echo_reply: Timestamp<Unitless>,
109}
110
111/// Like `TimestampOption` but with units appropriate for a timestamp option
112/// sent by us.
113#[derive(Debug, PartialEq, Eq, Clone, Copy)]
114pub struct TxTimestampOption {
115    /// The timestamp value.
116    ///
117    /// The timestamps sent by us use `Milliseconds`.
118    pub ts_val: Timestamp<Milliseconds>,
119    /// The timestamp echo reply.
120    pub ts_echo_reply: Timestamp<Unitless>,
121}
122
123/// Like `TimestampOption` but with units appropriate for a timestamp option
124/// sent by the peer.
125#[derive(Debug, PartialEq, Eq, Clone, Copy)]
126pub struct RxTimestampOption {
127    /// The timestamp value.
128    pub ts_val: Timestamp<Unitless>,
129    /// The timestamp echo reply.
130    ///
131    /// The timestamps sent by us use `Milliseconds` so any "echoed" timestamps
132    /// we receive from the peer should also be `Milliseconds`.
133    pub ts_echo_reply: Timestamp<Milliseconds>,
134}
135
136impl From<TxTimestampOption> for TimestampOption {
137    fn from(timestamp: TxTimestampOption) -> TimestampOption {
138        let TxTimestampOption { ts_val, ts_echo_reply } = timestamp;
139        // NB: Drop the units from `ts_val`.
140        let ts_val = Timestamp::<Unitless>::new(ts_val.timestamp);
141        TimestampOption { ts_val, ts_echo_reply }
142    }
143}
144
145impl From<TimestampOption> for RxTimestampOption {
146    fn from(timestamp: TimestampOption) -> RxTimestampOption {
147        let TimestampOption { ts_val, ts_echo_reply } = timestamp;
148        // NB: Assume `Millisecond` units for `ts_echo_reply`.
149        let ts_echo_reply = Timestamp::<Milliseconds>::new(ts_echo_reply.timestamp);
150        RxTimestampOption { ts_val, ts_echo_reply }
151    }
152}
153
154impl From<&packet_formats::tcp::options::TimestampOption> for TimestampOption {
155    fn from(timestamp: &packet_formats::tcp::options::TimestampOption) -> TimestampOption {
156        Self {
157            ts_val: Timestamp::new(timestamp.ts_val()),
158            ts_echo_reply: Timestamp::new(timestamp.ts_echo_reply()),
159        }
160    }
161}
162
163impl From<&TimestampOption> for packet_formats::tcp::options::TimestampOption {
164    fn from(timestamp: &TimestampOption) -> packet_formats::tcp::options::TimestampOption {
165        let TimestampOption { ts_val, ts_echo_reply } = timestamp;
166        packet_formats::tcp::options::TimestampOption::new(ts_val.get(), ts_echo_reply.get())
167    }
168}
169
170#[cfg(test)]
171mod tests {
172    use super::*;
173
174    use test_case::test_case;
175
176    #[test_case(1, 2 => Ordering::Less; "less_than")]
177    #[test_case(1, 1 => Ordering::Equal; "equal_to")]
178    #[test_case(2, 1 => Ordering::Greater; "greater_than")]
179    #[test_case(u32::MAX, 0 => Ordering::Less; "wrapped")]
180    #[test_case(0, (1<<31) - 1 => Ordering::Less; "last_in_bounds")]
181    #[test_case(0, 1<<31 => Ordering::Greater; "first_out_of_bounds")]
182    fn timestamp_ordering(lhs: u32, rhs: u32) -> Ordering {
183        let lhs = Timestamp::<Unitless>::new(lhs);
184        let rhs = Timestamp::<Unitless>::new(rhs);
185        lhs.cmp(&rhs)
186    }
187
188    #[test_case(1, 1 => 2; "add")]
189    #[test_case(u32::MAX, 1 => 0; "wrap_in_add")]
190    #[test_case(1, (u32::MAX as u64) + 1 => 1; "wrap_in_duration")]
191    fn timestamp_add_millis(lhs: u32, rhs: u64) -> u32 {
192        let lhs = Timestamp::<Milliseconds>::new(lhs);
193        let rhs = Duration::from_millis(rhs);
194        let result = lhs + rhs;
195        result.get()
196    }
197}
netstack3_base/tcp/timestamp.rs

netstack3_base/tcp/
timestamp.rs
