Martino FerrariandClaude Opus 4.6
3270284cfe
Round 3 of the Task 4 review. Three defects, all in FrameDecoder rule 3. The resync backstop was one-directional. `predicted` is never below lastEmittedEnd + dt, so rejecting a correction that would step backwards meant only a LAGGING chain could ever be pulled back; a chain running fast drifted ahead without bound. Two hosts' crystals differ by tens of ppm, so a declared SamplingRate is always slightly wrong in one direction or the other and this is certain on a long session. A leading timeline cannot be corrected in one burst without going backwards -- lastEmittedEnd is by definition past arrival -- so the excess is bled off by drawing each burst 10 % narrower until the timeline is back inside the threshold. A repeated packet counter was treated as a normal packet. The C client de-duplicates fragments only, so an unfragmented update reaching a host that joined the group on two interfaces was emitted twice, doubling the values and advancing the timeline by a burst that never existed. The samplingRate == 0 path differenced two HrtRateFit::toSeconds() results. toSeconds() divides an absolute tick count -- ~1e11 on a producer that has been up a day -- by a rate refitted on every packet, so its few-parts-in-1e4 wobble arrives multiplied by the whole elapsed epoch: tens of milliseconds of jitter on a value whose consecutive difference is a few milliseconds. Raw ticks are differenced instead, anchored on the first usable packet so the wobble applies only to the interval since attach. The existing hrt-gap test could not have caught the last one: its 10 ms producer period made the expected answer exactly kDefaultDt, so a decoder that derived nothing passed. It now uses 25 ms. Four tests added, all sabotage-proven. The plan is updated to match. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
302 lines
14 KiB
C++
302 lines
14 KiB
C++
#include "FrameDecoder.h"
|
|
|
|
#include <cmath>
|
|
|
|
namespace udpscope {
|
|
|
|
/** Fallback cycle period before the first inter-packet gap is known. */
|
|
static constexpr double kDefaultDt = 1.0e-3;
|
|
|
|
/**
|
|
* How far a chained burst prediction may sit from where arrival time says it
|
|
* should be before the chain is abandoned and time is re-anchored on arrival.
|
|
*
|
|
* This is a backstop, not the primary mechanism: the packet counter normally
|
|
* accounts for lost datagrams exactly, so the prediction and arrival agree.
|
|
* It catches what the counter cannot describe — a producer restart (the
|
|
* counter returns to zero), a counter that never advances, and a declared
|
|
* sampling rate that does not match the producer's real one. A kernel draining
|
|
* a backlog of queued datagrams can legitimately put the prediction a couple of
|
|
* hundred milliseconds from arrival, so the threshold sits well clear of that.
|
|
* Same value and same reasoning as ClockOffset::kRecalibThresholdS.
|
|
*/
|
|
static constexpr double kBurstResyncThresholdS = 0.5;
|
|
|
|
/**
|
|
* Largest counter gap still read as a loss count.
|
|
*
|
|
* A producer restart returns the counter to zero and a reordered datagram makes
|
|
* the unsigned gap wrap to near 2^32; multiplying either by a sample count and
|
|
* calling it elapsed time would fabricate centuries. A million lost updates is
|
|
* already far beyond any outage worth reconstructing.
|
|
*/
|
|
static constexpr uint32_t kMaxCounterGap = 1000000u;
|
|
|
|
/**
|
|
* Burst width, as a fraction of nominal, while a leading timeline is being
|
|
* pulled back. See the sole use site for why a leading chain cannot be
|
|
* corrected in one burst and must be bled off instead.
|
|
*/
|
|
static constexpr double kLeadBleedFactor = 0.9;
|
|
|
|
void FrameDecoder::setSignals(const std::vector<SignalMeta>& signals) {
|
|
signals_ = signals;
|
|
state_.assign(signals_.size(), SigState{});
|
|
hrtFit_.reset();
|
|
}
|
|
|
|
void FrameDecoder::reset() {
|
|
state_.assign(signals_.size(), SigState{});
|
|
hrtFit_.reset();
|
|
}
|
|
|
|
void FrameDecoder::beginFrame(const FrameView& f) {
|
|
if (f.hrt != 0u) { hrtFit_.add(f.hrt, f.recvTime); }
|
|
}
|
|
|
|
bool FrameDecoder::packetBurst(uint32_t idx, uint32_t nElems, double wallNow,
|
|
std::vector<double>& tsOut) {
|
|
SigState& st = state_[idx];
|
|
if (!st.lastPacketValid || wallNow <= st.lastPacketWall) {
|
|
/* No previous arrival to span from, or time went backwards. Remember
|
|
* this one and drop the samples rather than store them at made-up
|
|
* spacing. */
|
|
st.lastPacketWall = wallNow;
|
|
st.lastPacketValid = true;
|
|
return false;
|
|
}
|
|
|
|
const double dt = (wallNow - st.lastPacketWall) / static_cast<double>(nElems);
|
|
tsOut.resize(nElems);
|
|
for (uint32_t e = 0; e < nElems; e++) {
|
|
tsOut[e] = st.lastPacketWall + static_cast<double>(e + 1u) * dt;
|
|
}
|
|
st.lastPacketWall = wallNow;
|
|
return true;
|
|
}
|
|
|
|
bool FrameDecoder::timestamps(const FrameView& f, uint32_t idx,
|
|
std::vector<double>& tsOut) {
|
|
tsOut.clear();
|
|
if (idx >= signals_.size() || idx >= f.numSignals ||
|
|
f.counts == nullptr || f.values == nullptr) {
|
|
return false;
|
|
}
|
|
|
|
const SignalMeta& d = signals_[idx];
|
|
const uint32_t nElems = f.counts[idx];
|
|
if (nElems == 0u) { return false; }
|
|
|
|
const double wallNow = f.recvTime;
|
|
SigState& st = state_[idx];
|
|
|
|
/* A repeated counter is a duplicated datagram — the same update arriving
|
|
* twice because the host joined the multicast group on two interfaces, say.
|
|
* The C client only de-duplicates fragments, so an unfragmented update
|
|
* reaches us intact both times; emitting it again would double the values
|
|
* and advance the timeline by a burst that never existed. Counter zero is
|
|
* excluded because a producer that never sets one leaves it there. */
|
|
if (st.lastEmittedValid && f.counter != 0u && f.counter == st.lastCounter) {
|
|
return false;
|
|
}
|
|
|
|
/* hasTimeSignal() bounds the index against the FRAME's signal count, but
|
|
* the time signal's type code is read from our own table, whose size is
|
|
* independent — a frame carrying more signals than the installed table
|
|
* (briefly possible after a CONFIG change) would otherwise read past it. */
|
|
const bool hasTimeSig = d.hasTimeSignal(f.numSignals) &&
|
|
d.timeSignalIdx < signals_.size();
|
|
const uint32_t tIdx = hasTimeSig ? d.timeSignalIdx : 0u;
|
|
const double tScale = hasTimeSig
|
|
? TimeSignalScale(signals_[tIdx].typeCode)
|
|
: 1.0e-6;
|
|
|
|
/* Rule 1: one stamp per element, straight from the time signal. */
|
|
if (d.timeMode == kTimeFullArray && hasTimeSig &&
|
|
f.counts[tIdx] >= nElems && f.values[tIdx] != nullptr) {
|
|
const double* tv = f.values[tIdx];
|
|
const double t0 = tv[0] * tScale;
|
|
(void) st.offset.map(t0, wallNow);
|
|
const double base = st.offset.offset();
|
|
tsOut.resize(nElems);
|
|
for (uint32_t e = 0; e < nElems; e++) {
|
|
tsOut[e] = base + tv[e] * tScale;
|
|
}
|
|
return true;
|
|
}
|
|
|
|
/* Rule 2: anchor from the time signal, spread by the sampling rate. */
|
|
if ((d.timeMode == kTimeFirstSample || d.timeMode == kTimeLastSample) &&
|
|
hasTimeSig && f.counts[tIdx] >= 1u && f.values[tIdx] != nullptr) {
|
|
const double anchor = st.offset.map(f.values[tIdx][0] * tScale, wallNow);
|
|
const double dt = (d.samplingRate > 0.0) ? (1.0 / d.samplingRate) : 0.0;
|
|
tsOut.resize(nElems);
|
|
for (uint32_t e = 0; e < nElems; e++) {
|
|
tsOut[e] = (d.timeMode == kTimeFirstSample)
|
|
? (anchor + static_cast<double>(e) * dt)
|
|
: (anchor - static_cast<double>(nElems - 1u - e) * dt);
|
|
}
|
|
return true;
|
|
}
|
|
|
|
/* Rule 3: accumulated scalar, based on declared sampling rate or hrt.
|
|
*
|
|
* When samplingRate is declared the inter-element step is exact and we
|
|
* anchor from the end of the previous burst rather than from arrival time
|
|
* or hrt. This makes the output immune to arrival jitter: even when the
|
|
* kernel delivers two packets microseconds apart each burst starts exactly
|
|
* one sample period after the previous burst ended.
|
|
*
|
|
* When samplingRate is absent we must derive dt from the hrt gap, which
|
|
* requires the HrtRateFit to be ready. Until then we fall back to
|
|
* packetBurst (arrival-time spanning), which is accurate during the normal
|
|
* pre-burst delivery phase that precedes the fit becoming ready. */
|
|
if (d.numElements() == 1u && nElems > 1u) {
|
|
const double dt = (d.samplingRate > 0.0)
|
|
? (1.0 / d.samplingRate)
|
|
: 0.0;
|
|
|
|
if (d.samplingRate > 0.0) {
|
|
/* Where arrival time says this burst begins: its last element was
|
|
* acquired just before the packet landed. */
|
|
const double arrivalAnchor =
|
|
wallNow - static_cast<double>(nElems - 1u) * dt;
|
|
|
|
/* Chaining onto the end of the previous burst is immune to arrival
|
|
* jitter — a kernel draining several queued datagrams microseconds
|
|
* apart still yields contiguous timestamps. What a bare chain gets
|
|
* wrong is loss: it closes the hole a dropped datagram left, and
|
|
* every later sample is then dated early for the rest of the run.
|
|
*
|
|
* The wire says exactly how much is missing. counter increments
|
|
* once per update, so a gap of g means g-1 lost packets, each
|
|
* carrying (as far as we can tell) as many samples as the last one
|
|
* we saw. Reinstating that duration keeps the chain honest without
|
|
* consulting arrival time at all. */
|
|
double base = arrivalAnchor;
|
|
double step = dt;
|
|
if (st.lastEmittedValid) {
|
|
/* Unsigned subtraction wraps, so this stays right across the
|
|
* counter's own 2^32 rollover. A gap far larger than any real
|
|
* outage is a restart or a reordered datagram rather than a
|
|
* loss count; claim nothing and let the backstop below decide. */
|
|
const uint32_t gap = f.counter - st.lastCounter;
|
|
const double lost = (gap > 1u && gap <= kMaxCounterGap)
|
|
? static_cast<double>(gap - 1u) *
|
|
static_cast<double>(st.prevAccCount)
|
|
: 0.0;
|
|
const double predicted = st.lastEmittedEnd + dt * (1.0 + lost);
|
|
|
|
/* Backstop for what the counter cannot express: a producer
|
|
* restart, a counter stuck at zero, or a declared rate that is
|
|
* simply wrong. Beyond this the chain is not recoverable and
|
|
* arrival time is the better of two bad answers. */
|
|
if (std::fabs(predicted - arrivalAnchor) <= kBurstResyncThresholdS) {
|
|
base = predicted;
|
|
}
|
|
|
|
if (base <= st.lastEmittedEnd) {
|
|
/* Re-anchoring here would step backwards, and the ring, the
|
|
* trigger and the exporter all require a signal's stamps to
|
|
* increase. Rejecting the correction outright is not an
|
|
* option either: `predicted` is never less than
|
|
* lastEmittedEnd + dt, so rejection would make the backstop
|
|
* one-directional and let a timeline that runs FAST — two
|
|
* hosts' crystals differ by tens of ppm, so this is certain
|
|
* on a long session, not hypothetical — drift ahead of the
|
|
* wall clock without bound.
|
|
*
|
|
* So compress instead of stepping back: start immediately
|
|
* after the previous burst and spread this one out to
|
|
* arrival. A single packet is drawn narrower than its true
|
|
* width, and in exchange the timeline is back in step. */
|
|
if (wallNow > st.lastEmittedEnd) {
|
|
step = (wallNow - st.lastEmittedEnd) /
|
|
static_cast<double>(nElems);
|
|
base = st.lastEmittedEnd + step;
|
|
} else {
|
|
/* The timeline has run PAST arrival: our last burst is
|
|
* dated later than the moment this packet landed. There
|
|
* is no room to spread into, and no single burst can
|
|
* remove the excess without stepping back. So bleed it
|
|
* off — draw each burst a fixed fraction narrower than
|
|
* nominal until the timeline is back inside the
|
|
* threshold, then normal chaining resumes. The factor
|
|
* only has to shrink a burst faster than the clock
|
|
* mismatch grows it, and a 10 % squeeze outruns the
|
|
* tens-of-ppm crystal error that causes this by orders
|
|
* of magnitude. */
|
|
step = dt * kLeadBleedFactor;
|
|
base = st.lastEmittedEnd + step;
|
|
}
|
|
}
|
|
}
|
|
tsOut.resize(nElems);
|
|
for (uint32_t e = 0; e < nElems; e++) {
|
|
tsOut[e] = base + static_cast<double>(e) * step;
|
|
}
|
|
st.lastEmittedEnd = tsOut[nElems - 1u];
|
|
st.lastCounter = f.counter;
|
|
st.prevAccCount = nElems;
|
|
st.lastEmittedValid = true;
|
|
return true;
|
|
}
|
|
|
|
/* No declared rate: need hrt-derived dt. */
|
|
if (!hrtFit_.ready() || f.hrt == 0u) {
|
|
return packetBurst(idx, nElems, wallNow, tsOut);
|
|
}
|
|
const double rate = hrtFit_.ticksPerSecond();
|
|
|
|
/* Difference raw TICKS, never two toSeconds() results.
|
|
*
|
|
* hrt counts from the producer's boot, so it is already ~1e11 ticks when
|
|
* the scope attaches, while the fit is re-estimated on every packet and
|
|
* wobbles by a few parts in 1e4. toSeconds() multiplies that relative
|
|
* wobble by the whole elapsed epoch: tens of milliseconds of jitter on a
|
|
* value whose consecutive difference is a few milliseconds. Subtracting
|
|
* two such results measures the wobble, not the interval.
|
|
*
|
|
* Anchoring on the first usable packet keeps the wobble on the elapsed
|
|
* interval since attach, which is short, and ClockOffset absorbs the
|
|
* arbitrary epoch that anchoring leaves behind exactly as it would
|
|
* absorb the producer's boot epoch. */
|
|
if (!st.hrtRefValid) {
|
|
st.hrtRef = f.hrt;
|
|
st.hrtRefValid = true;
|
|
}
|
|
const double sinceRef = (f.hrt >= st.hrtRef)
|
|
? static_cast<double>(f.hrt - st.hrtRef) / rate
|
|
: -static_cast<double>(st.hrtRef - f.hrt) / rate;
|
|
const double base = st.offset.map(sinceRef, wallNow);
|
|
|
|
double hrtDt = kDefaultDt;
|
|
if (st.lastAccValid && st.prevAccCount > 0u && f.hrt > st.lastAccHrt) {
|
|
/* The flushes carry contiguous RT cycles, so the gap divided by the
|
|
* previous packet's sample count is exactly one cycle period. */
|
|
hrtDt = (static_cast<double>(f.hrt - st.lastAccHrt) / rate) /
|
|
static_cast<double>(st.prevAccCount);
|
|
}
|
|
|
|
tsOut.resize(nElems);
|
|
for (uint32_t e = 0; e < nElems; e++) {
|
|
tsOut[e] = base + static_cast<double>(e) * hrtDt;
|
|
}
|
|
st.lastAccHrt = f.hrt;
|
|
st.lastAccValid = true;
|
|
st.prevAccCount = nElems;
|
|
return true;
|
|
}
|
|
|
|
/* Rule 4: PACKET burst with no time reference at all. */
|
|
if (nElems > 1u) {
|
|
return packetBurst(idx, nElems, wallNow, tsOut);
|
|
}
|
|
|
|
/* Rule 5: plain scalar. */
|
|
tsOut.assign(1, wallNow);
|
|
return true;
|
|
}
|
|
|
|
} /* namespace udpscope */
|