| 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 |