martino/MARTe-Integrated-Components
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(udpscope): bound the reconstructed timeline against the wall clock

Browse Source 
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>
This commit is contained in:
Martino Ferrari
2026-08-27 21:55:33 +02:00
co-authored by Claude Opus 4.6
parent 7102412a9f
commit 3270284cfe
5 changed files with 478 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Client/udpscope/FrameDecoder.cpp
+97 -19
View File
@@ -22,6 +22,23 @@ static constexpr double kDefaultDt = 1.0e-3;
*/
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{});
@@ -73,6 +90,16 @@ bool FrameDecoder::timestamps(const FrameView& f, uint32_t idx,
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
@@ -147,11 +174,14 @@ bool FrameDecoder::timestamps(const FrameView& f, uint32_t idx,
* 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. */
* 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)
const double lost = (gap > 1u && gap <= kMaxCounterGap)
? static_cast<double>(gap - 1u) *
static_cast<double>(st.prevAccCount)
: 0.0;
@@ -164,17 +194,46 @@ bool FrameDecoder::timestamps(const FrameView& f, uint32_t idx,
if (std::fabs(predicted - arrivalAnchor) <= kBurstResyncThresholdS) {
base = predicted;
}
/* Re-anchoring must never move time backwards: the ring, the
* trigger and the exporter all assume a signal's timestamps
* increase. A backward resync would be indistinguishable from
* corruption downstream, so give up the correction instead. */
if (base <= st.lastEmittedEnd) {
base = st.lastEmittedEnd + dt;
/* 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) * dt;
tsOut[e] = base + static_cast<double>(e) * step;
}
st.lastEmittedEnd = tsOut[nElems - 1u];
st.lastCounter = f.counter;
@@ -184,29 +243,48 @@ bool FrameDecoder::timestamps(const FrameView& f, uint32_t idx,
}
/* No declared rate: need hrt-derived dt. */
if (!hrtFit_.ready()) {
if (!hrtFit_.ready() || f.hrt == 0u) {
return packetBurst(idx, nElems, wallNow, tsOut);
}
const double hrtSec = hrtFit_.toSeconds(f.hrt);
const double base = st.offset.map(hrtSec, wallNow);
const double rate = hrtFit_.ticksPerSecond();
double hrtDt;
if (st.lastAccValid && st.prevAccCount > 0u && hrtSec > st.lastAccHrtSec) {
/* 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 = (hrtSec - st.lastAccHrtSec) /
hrtDt = (static_cast<double>(f.hrt - st.lastAccHrt) / rate) /
static_cast<double>(st.prevAccCount);
} else {
hrtDt = kDefaultDt;
}
tsOut.resize(nElems);
for (uint32_t e = 0; e < nElems; e++) {
tsOut[e] = base + static_cast<double>(e) * hrtDt;
}
st.lastAccHrtSec = hrtSec;
st.lastAccValid = true;
st.prevAccCount = nElems;
st.lastAccHrt = f.hrt;
st.lastAccValid = true;
st.prevAccCount = nElems;
return true;
}
Client/udpscope/FrameDecoder.h
+6 -1
View File
@@ -50,7 +50,12 @@ private:
ClockOffset offset;
double lastPacketWall = 0.0;
bool lastPacketValid = false;
double lastAccHrtSec = 0.0;
/** Raw ticks, not seconds — see the comment in the samplingRate == 0
* branch for why a tick difference is the only safe way to measure a
* producer-side interval while the rate is still being re-estimated. */
uint64_t lastAccHrt = 0u;
uint64_t hrtRef = 0u;
bool hrtRefValid = false;
bool lastAccValid = false;
uint32_t prevAccCount = 0;
/** For accumulated scalars with a declared sampling rate: end timestamp
Client/udpscope/TimeBase.h
+9
View File
@@ -71,6 +71,15 @@ public:
* from its own boot, not from the Unix epoch. Pass the result to
* ClockOffset::map() to land it on the wall clock; latching that arbitrary
* epoch difference is precisely what ClockOffset is for.
*
* @warning Never subtract two of these results to measure a short interval.
* The rate is refitted on every add() and wobbles by a few parts in 1e4,
* while hrt is already ~1e11 ticks by the time a scope attaches to a
* long-running producer — so the division carries that relative wobble
* multiplied by the entire elapsed epoch, tens of milliseconds of jitter on
* an absolute value. The jitter is common to both operands only if the rate
* did not change between them, which is exactly what it does. To measure an
* interval, difference the raw ticks and divide once by ticksPerSecond().
*/
double toSeconds(uint64_t hrt) const;
void reset();
Client/udpscope/tests/FrameDecoderTest.cpp
+102 -10
View File
@@ -269,12 +269,101 @@ TEST(FrameDecoder, AccumulatedScalarNeverStepsBackwardsWhenResyncing) {
dec.beginFrame(f);
ASSERT_TRUE(dec.timestamps(f, 0, ts));
/* Arrival (500.000) is behind our timeline, so there is nothing to spread
* into; the burst is drawn narrower instead, which starts to bleed the lead
* off while still moving strictly forwards. */
EXPECT_NEAR(ts[0], 500.0909, 1e-9);
EXPECT_GT(ts[0], prevEnd) << "resync stepped backwards over the previous burst";
for (size_t i = 1; i < ts.size(); i++) {
EXPECT_GT(ts[i], ts[i - 1]);
}
}
// When the chain has to be abandoned but arrival lies just ahead of where the
// last burst ended, the correction is made by COMPRESSING this one burst rather
// than by stepping back. Rejecting the correction instead would be one-directional
// — `predicted` is never below lastEmittedEnd + dt — and a timeline running fast
// could then never be pulled back.
TEST(FrameDecoder, AccumulatedScalarCompressesOneBurstRatherThanStepBack) {
FrameDecoder dec;
dec.setSignals({accSignal()});
std::vector<double> ts;
primeTenBursts(dec, ts, /*withCounter=*/true);
/* A counter gap far beyond any real outage: the prediction is unusable, and
* the arrival anchor (500.086) sits behind the previous burst end. */
FrameBuilder fb;
fb.addSignal(std::vector<double>(10, 1.0));
const FrameView& f = fb.build(0, 500.095, 10, 900011u);
dec.beginFrame(f);
ASSERT_TRUE(dec.timestamps(f, 0, ts));
EXPECT_GT(ts[0], 500.090) << "compressed burst must still start after the last one";
EXPECT_NEAR(ts[9], 500.095, 1e-9) << "and end exactly on arrival";
EXPECT_NEAR(ts[1] - ts[0], 0.0005, 1e-9) << "spread over the available room";
}
// The whole point of compressing: a declared SamplingRate is a hand-written
// config value, and even a correct one is measured against the producer host's
// crystal, not ours. Tens of ppm of difference is certain over a long session,
// so the reconstructed timeline WILL run away from the wall clock. It has to be
// pulled back, and it has to stay monotonic while that happens.
TEST(FrameDecoder, AccumulatedScalarDoesNotDriftAwayFromTheWallClockForever) {
FrameDecoder dec;
dec.setSignals({accSignal()}); /* declares 1 kHz */
/* The producer really runs 1 % fast: 10 samples take 9.9 ms of wall time,
* so a chain stepping the declared 10 ms per packet gains 0.1 ms every
* packet. This is the direction re-anchoring alone cannot fix: arrival is
* always BEHIND the chain, so anchoring on it would step backwards and is
* refused. Only compression pulls the timeline back. */
double worstLead = 0.0;
double lastEnd = 0.0;
for (int p = 0; p < 20000; p++) {
FrameBuilder fb;
fb.addSignal(std::vector<double>(10, 1.0));
const double arrival = 500.0 + p * 0.0099;
const FrameView& f =
fb.build(0, arrival, 10, static_cast<uint32_t>(p + 1));
dec.beginFrame(f);
std::vector<double> ts;
ASSERT_TRUE(dec.timestamps(f, 0, ts));
for (size_t i = 0; i < ts.size(); i++) {
ASSERT_GT(ts[i], lastEnd) << "timeline went backwards at packet " << p;
lastEnd = ts[i];
}
worstLead = std::max(worstLead, ts[9] - arrival);
}
/* Unchecked, 20000 packets at 0.1 ms each would put the trace 2 s ahead. */
EXPECT_LT(worstLead, 0.6) << "timeline drifted " << worstLead << " s ahead";
}
// The C client de-duplicates fragments but not whole unfragmented updates, so a
// host subscribed on two interfaces sees each datagram twice. Emitting the
// repeat would double the values and advance time by a burst that never was.
TEST(FrameDecoder, AccumulatedScalarDropsADuplicatedDatagram) {
FrameDecoder dec;
dec.setSignals({accSignal()});
std::vector<double> ts;
primeTenBursts(dec, ts, /*withCounter=*/true);
const double endBefore = ts[9];
FrameBuilder fb;
fb.addSignal(std::vector<double>(10, 1.0));
const FrameView& dup = fb.build(0, 500.1001, 10, 10u); /* counter 10 again */
dec.beginFrame(dup);
EXPECT_FALSE(dec.timestamps(dup, 0, ts));
/* And the drop must not have disturbed the chain: the genuine next packet
* still lands one period after burst 10 ended. */
const FrameView& next = fb.build(0, 500.109, 10, 11u);
dec.beginFrame(next);
ASSERT_TRUE(dec.timestamps(next, 0, ts));
EXPECT_NEAR(ts[0], endBefore + 0.001, 1e-9);
}
TEST(FrameDecoder, AccumulatedScalarDerivesDtFromTheHrtGapWhenNoRateIsDeclared) {
FrameDecoder dec;
SignalMeta m;
@@ -288,15 +377,17 @@ TEST(FrameDecoder, AccumulatedScalarDerivesDtFromTheHrtGapWhenNoRateIsDeclared)
for (int p = 0; p < 40; p++) {
FrameBuilder fb;
fb.addSignal(std::vector<double>(10, 1.0));
const double producerSec = 100.0 + p * 0.010; /* 10 ms per packet */
/* Zero-mean arrival jitter, so the rate fit still converges but any
* single arrival GAP is wrong. Without it, uniform arrivals make
* packetBurst and the hrt path return the same number and the test
* cannot tell which branch produced it. The last packet's gap is
* 7 ms, which arrival-spanning would render as a 0.7 ms period. */
/* 25 ms per packet, deliberately NOT 10: at 10 the expected 1 ms period
* equals kDefaultDt, so a decoder that never derived anything and just
* returned the default would pass a test named for the derivation. */
const double producerSec = 100.0 + p * 0.025;
/* Zero-mean arrival jitter, so the rate fit still converges but no
* single arrival GAP is right. Without it, uniform arrivals make
* packetBurst and the hrt path return the same number by construction
* and the test cannot tell which branch answered. */
const double jitter[4] = {0.0, 0.003, 0.0, -0.003};
const FrameView& f = fb.build(static_cast<uint64_t>(producerSec * ticks),
700.0 + p * 0.010 + jitter[p % 4], 10,
700.0 + p * 0.025 + jitter[p % 4], 10,
static_cast<uint32_t>(p + 1));
dec.beginFrame(f);
std::vector<double> ts;
@@ -304,9 +395,10 @@ TEST(FrameDecoder, AccumulatedScalarDerivesDtFromTheHrtGapWhenNoRateIsDeclared)
}
ASSERT_EQ(last.size(), 10u);
/* 10 ms of producer time across 10 samples is a 1 ms period, whatever the
* datagrams did on the way over. */
EXPECT_NEAR(last[1] - last[0], 0.001, 1e-5);
/* 25 ms of producer time across 10 samples is a 2.5 ms period, whatever the
* datagrams did on the way over. Arrival-spanning the last gap (22 ms)
* would give 2.2 ms; defaulting would give 1 ms. */
EXPECT_NEAR(last[1] - last[0], 0.0025, 2e-5);
}
// A PACKET burst has no per-element time at all. Elements span