MARTe-Integrated-Components/Client/udpscope/FrameDecoder.cpp

#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 the forward-chained prediction for an accumulated burst may sit from
 * where arrival time says it should be before the chain is abandoned.
 *
 * A kernel draining a backlog of queued datagrams can legitimately put the
 * prediction a few hundred milliseconds ahead of arrival, so the threshold has
 * to be well clear of that. Anything larger is not delivery jitter: it is lost
 * packets or a declared sampling rate that does not match the producer's real
 * one, and both must resynchronise rather than accumulate forever. Same value
 * and same reasoning as ClockOffset::kRecalibThresholdS.
 */
static constexpr double kBurstResyncThresholdS = 0.5;

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) {
        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];

    const bool     hasTimeSig = d.hasTimeSignal(f.numSignals);
    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 from the end of the previous burst is immune to arrival
             * jitter — a kernel draining several queued datagrams microseconds
             * apart still yields contiguous timestamps. But a pure chain is
             * blind: one lost datagram, or a declared rate that does not match
             * the producer's real one, displaces every later sample and never
             * recovers. So the chain is a PREDICTION, checked each packet
             * against arrival and abandoned when the two disagree by more than
             * a delivery backlog can explain. That bounds the error instead of
             * letting it accumulate. */
            double base = arrivalAnchor;
            if (st.lastEmittedValid) {
                const double predicted = st.lastEmittedEnd + dt;
                if (std::fabs(predicted - arrivalAnchor) <= kBurstResyncThresholdS) {
                    base = predicted;
                }
            }
            tsOut.resize(nElems);
            for (uint32_t e = 0; e < nElems; e++) {
                tsOut[e] = base + static_cast<double>(e) * dt;
            }
            st.lastEmittedEnd   = tsOut[nElems - 1u];
            st.lastEmittedValid = true;
            return true;
        }

        /* No declared rate: need hrt-derived dt. */
        if (!hrtFit_.ready()) {
            return packetBurst(idx, nElems, wallNow, tsOut);
        }
        const double hrtSec = hrtFit_.toSeconds(f.hrt);
        const double base   = st.offset.map(hrtSec, wallNow);

        double hrtDt;
        if (st.lastAccValid && st.prevAccCount > 0u && hrtSec > st.lastAccHrtSec) {
            /* 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) /
                    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;
        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 */