Debian Codegraph @

srtcore/tsbpd_time.h

raw
1 /*
2 * SRT - Secure, Reliable, Transport
3 * Copyright (c) 2021 Haivision Systems Inc.
4 *
5 * This Source Code Form is subject to the terms of the Mozilla Public
6 * License, v. 2.0. If a copy of the MPL was not distributed with this
7 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
8 *
9 */
10
11 #ifndef INC_SRT_TSBPD_TIME_H
12 #define INC_SRT_TSBPD_TIME_H
13
14 #include "platform_sys.h"
15 #include "sync.h"
16 #include "utilities.h"
17
18 namespace srt
19 {
20
21 /// @brief TimeStamp-Based Packet Delivery Mode (TSBPD) time conversion logic.
22 /// Used by the receiver to calculate delivery time of data packets.
23 /// See SRT Internet Draft Section "Timestamp-Based Packet Delivery".
24 class CTsbpdTime
25 {
26 typedef srt::sync::steady_clock steady_clock;
27 typedef steady_clock::time_point time_point;
28 typedef steady_clock::duration duration;
29 typedef srt::sync::SharedMutex SharedMutex;
30
31 public:
32 CTsbpdTime()
33 : m_iFirstRTT(-1)
34 , m_bTsbPdMode(false)
35 , m_tdTsbPdDelay(0)
36 , m_bTsbPdWrapCheck(false)
37 {
38 }
39
40 /// Set TimeStamp-Based Packet Delivery Mode (receiver).
41 /// @param [in] timebase local time base (uSec) of packet time stamps including buffering delay.
42 /// @param [in] wrap wrapping period.
43 /// @param [in] delay negotiated TsbPD delay (buffering latency).
44 void setTsbPdMode(const time_point& timebase, bool wrap, duration delay);
45
46 /// @brief Check if TSBPD logic is enabled.
47 /// @return true if TSBPD is enabled.
48 bool isEnabled() const { return m_bTsbPdMode; }
49
50 /// @brief Apply new state derived from other members of a socket group.
51 /// @param timebase TSBPD base time.
52 /// @param wrp wrap period (enabled or not).
53 /// @param delay TSBPD delay.
54 /// @param udrift clock drift.
55 void applyGroupTime(const time_point& timebase, bool wrp, uint32_t delay, const duration& udrift);
56
57 /// @brief Apply new clock state (TSBPD base and drift) derived from other members of a socket group.
58 /// @param timebase TSBPD base time.
59 /// @param wrp state of the wrapping period (enabled or disabled).
60 /// @param udrift clock drift.
61 void applyGroupDrift(const time_point& timebase, bool wrp, const duration& udrift);
62
63 /// @brief Add new drift sample from an ACK-ACKACK pair.
64 /// ACKACK packets are sent immediately (except for UDP buffering).
65 /// Therefore their timestamp roughly corresponds to the time of sending
66 /// and can be used to estimate clock drift.
67 ///
68 /// @param [in] pktTimestamp Timestamp of the arrived ACKACK packet.
69 /// @param [in] tsPktArrival packet arrival time.
70 /// @param [in] usRTTSample RTT sample from an ACK-ACKACK pair. If no sample, pass '-1'.
71 ///
72 /// @return true if TSBPD base time has changed, false otherwise.
73 bool addDriftSample(uint32_t pktTimestamp, const time_point& tsPktArrival, int usRTTSample);
74
75 /// @brief Handle timestamp of data packet when 32-bit integer carryover is about to happen.
76 /// When packet timestamp approaches CPacket::MAX_TIMESTAMP, the TSBPD base time should be
77 /// shifted accordingly to correctly handle new packets with timestamps starting from zero.
78 /// @param usPktTimestamp timestamp field value of a data packet.
79 void updateBaseTime(uint32_t usPktTimestamp);
80
81 /// @brief Get TSBPD base time adjusted for carryover, which occurs when
82 /// a packet's timestamp exceeds the UINT32_MAX and continues from zero.
83 /// @param [in] usPktTimestamp 32-bit value of packet timestamp field (microseconds).
84 ///
85 /// @return TSBPD base time for a provided packet timestamp.
86 time_point getBaseTime(uint32_t usPktTimestamp) const;
87
88 /// @brief Get packet TSBPD time without buffering delay and clock drift, which is
89 /// the target time for delivering the packet to an upstream application.
90 /// Essentially: getBaseTime(usPktTimestamp) + usPktTimestamp
91 /// @param [in] usPktTimestamp 32-bit value of packet timestamp field (microseconds).
92 ///
93 /// @return Packet TSBPD base time without buffering delay.
94 time_point getPktBaseTime(uint32_t usPktTimestamp) const;
95
96 /// @brief Get packet TSBPD time with buffering delay and clock drift, which is
97 /// the target time for delivering the packet to an upstream application
98 /// (including drift and carryover effects, if any).
99 /// Essentially: getPktBaseTime(usPktTimestamp) + m_tdTsbPdDelay + drift()
100 /// @param [in] usPktTimestamp 32-bit value of packet timestamp field (microseconds).
101 ///
102 /// @return Packet TSBPD time with buffering delay.
103 time_point getPktTime(uint32_t usPktTimestamp) const;
104
105 /// @brief Get current drift value.
106 /// @return current drift value.
107 int64_t drift() const { return m_DriftTracer.drift(); }
108
109 /// @brief Get current overdrift value.
110 /// @return current overdrift value.
111 int64_t overdrift() const { return m_DriftTracer.overdrift(); }
112
113 /// @brief Get internal state to apply to another member of a socket group.
114 /// @param w_tb TsbPd base time.
115 /// @param w_udrift drift value.
116 /// @param w_wrp wrap check.
117 void getInternalTimeBase(time_point& w_tb, bool& w_wrp, duration& w_udrift) const;
118
119 private:
120 /// @brief Get TSBPD base time adjusted for carryover, which occurs when
121 /// a packet's timestamp exceeds the UINT32_MAX and continues from zero.
122 /// Does not lock the internal state.
123 /// @param [in] usPktTimestamp 32-bit value of packet timestamp field (microseconds).
124 ///
125 /// @return TSBPD base time for a provided packet timestamp.
126 time_point getBaseTimeNoLock(uint32_t usPktTimestamp) const;
127
128 /// @brief Get packet TSBPD time without buffering delay and clock drift, which is
129 /// the target time for delivering the packet to an upstream application.
130 /// Essentially: getBaseTime(usPktTimestamp) + usPktTimestamp
131 /// Does not lock the internal state.
132 /// @param [in] usPktTimestamp 32-bit value of packet timestamp field (microseconds).
133 ///
134 /// @return Packet TSBPD base time without buffering delay.
135 time_point getPktBaseTimeNoLock(uint32_t usPktTimestamp) const;
136
137
138 int m_iFirstRTT; // First measured RTT sample.
139 bool m_bTsbPdMode; // Receiver buffering and TSBPD is active when true.
140 duration m_tdTsbPdDelay; // Negotiated buffering delay.
141
142 /// @brief Local time base for TsbPd.
143 /// @note m_tsTsbPdTimeBase is changed in the following cases:
144 /// 1. Initialized upon SRT_CMD_HSREQ packet as the difference with the current time:
145 /// = (NOW - PACKET_TIMESTAMP), at the time of HSREQ reception.
146 /// 2. Shifted forward on timestamp overflow (@see CTsbpdTime::updateBaseTime), when overflow
147 /// of the timestamp field value of a data packet is detected.
148 /// += CPacket::MAX_TIMESTAMP + 1
149 /// 3. Clock drift (@see CTsbpdTime::addDriftSample, executed exclusively
150 /// from ACKACK handler). This is updated with (positive or negative) TSBPD_DRIFT_MAX_VALUE
151 /// once the value of average drift exceeds this value in either direction.
152 /// += (+/-)TSBPD_DRIFT_MAX_VALUE
153 ///
154 /// @note The TSBPD base time is expected to hold the following condition:
155 /// (PACKET_TIMESTAMP + m_tsTsbPdTimeBase + drift) == NOW.
156 /// Then it can be used to estimate the origin time of a data packet, and calculate its delivery time
157 /// with buffering delay applied.
158 time_point m_tsTsbPdTimeBase;
159
160 /// @note Packet timestamps wrap around every 01h11m35s (32-bit in usec).
161 /// A wrap check period starts 30 seconds (TSBPD_WRAP_PERIOD) before the wrap point.
162 /// During the wrap check period, packet timestamps smaller than 30 seconds
163 /// are considered to have been wrapped around.
164 /// The wrap check period ends 30 seconds after the wrap point,
165 /// after which the TSBPD base time is adjusted.
166 bool m_bTsbPdWrapCheck; // true: check packet time stamp wraparound (overflow).
167 static const uint32_t TSBPD_WRAP_PERIOD = (30 * 1000000); // 30 seconds (in usec) for timestamp wrapping period.
168
169 /// Maximum clock drift (microseconds) above which TsbPD base time is already adjusted.
170 static const int TSBPD_DRIFT_MAX_VALUE = 5000;
171 /// Number of samples (ACKACK packets) on which to perform drift calculation and compensation.
172 static const int TSBPD_DRIFT_MAX_SAMPLES = 1000;
173 DriftTracer<TSBPD_DRIFT_MAX_SAMPLES, TSBPD_DRIFT_MAX_VALUE> m_DriftTracer;
174
175 /// Protect simultaneous change of state (read/write).
176 mutable SharedMutex m_mtxRW;
177 };
178
179 } // namespace srt
180
181 #endif // INC_SRT_TSBPD_TIME_H