/**
 * @file TimeArrayGAM.h
 * @brief GAM that expands a scalar timer value into a per-sample uint32 time array.
 * @date 19/05/2026
 * @author Martino Ferrari
 *
 * @details Each Execute() call reads one uint32 scalar input (time in microseconds,
 * e.g. from LinuxTimer) and fills a uint32[N] output array where element[k] holds
 * the reconstructed timestamp of sample k:
 *
 *   Anchor = FirstSample:  out[k] = input + k * period_us
 *   Anchor = LastSample:   out[k] = input - (N-1-k) * period_us
 *   Anchor = Continuous:   out[k] = input(first cycle) + (n + k) * period_us
 *
 * FirstSample/LastSample re-read the timer every cycle, so they propagate any
 * cycle the RT thread loses: LinuxTimer re-phases (counter += nCycles) and the
 * emitted time base jumps by a whole period while only one array of samples is
 * produced, leaving a hole. Continuous anchors once and then advances an
 * internal sample counter by N per cycle, which is what an acquisition card
 * with its own clock does — use it when the data signal is itself contiguous
 * (SineArrayGAM, for instance, never skips phase on a lost cycle).
 *
 * The resulting time array is suitable as the TimeSignal for a UDPStreamer signal
 * configured with TimeMode = FullArray, providing exact per-sample timestamps.
 *
 * Configuration:
 * <pre>
 * +TimeArrayGAM1 = {
 *     Class         = TimeArrayGAM
 *     SamplingRate  = 1000000.0    // Sample rate in Hz (must match data signal)
 *     Anchor        = FirstSample  // FirstSample (default), LastSample or Continuous
 *     InputSignals = {
 *         Time = { DataSource = DDB; Type = uint32 }
 *     }
 *     OutputSignals = {
 *         TimeArray = { DataSource = DDB; Type = uint32; NumberOfElements = 1000 }
 *     }
 * }
 * </pre>
 *
 * Exactly one uint32 input signal and one uint32 output array are required.
 */

#ifndef TIMEARRAYGAM_H_
#define TIMEARRAYGAM_H_

#include "CompilerTypes.h"
#include "GAM.h"

namespace MARTe {

class TimeArrayGAM : public GAM {
public:
    CLASS_REGISTER_DECLARATION()

    TimeArrayGAM();
    virtual ~TimeArrayGAM();

    virtual bool Initialise(StructuredDataI &data);
    virtual bool Setup();
    virtual bool Execute();

private:
    float64  samplingRate;   /**< Sample rate [Hz] */
    bool     anchorIsFirst;  /**< true = FirstSample anchor, false = LastSample */
    bool     anchorIsCont;   /**< true = Continuous anchor (internal sample counter) */
    bool     contStarted;    /**< Continuous: origin has been latched */
    uint64   contOriginNs;   /**< Continuous: timer value latched on the first cycle */
    uint64   contSamples;    /**< Continuous: samples emitted so far */
    uint32   nElements;      /**< Number of output elements */
    uint32  *inputTime;      /**< Pointer to scalar input (microseconds, uint32 from LinuxTimer) */
    uint64  *outputBuf;      /**< Pointer to output array (nanoseconds, uint64) */
};

} /* namespace MARTe */

#endif /* TIMEARRAYGAM_H_ */