ptp_tracking.h

Go to the documentation of this file.

// Copyright 2023-2024 The Aerospace Corporation.
// This file is a part of SatCat5, licensed under CERN-OHL-W v2 or later.
 
#pragma once
 
#include <satcat5/cfgbus_pps.h>
#include <satcat5/list.h>
#include <satcat5/polling.h>
#include <satcat5/ptp_filters.h>
#include <satcat5/ptp_measurement.h>
#include <satcat5/ptp_source.h>
#include <satcat5/ptp_time.h>
#include <satcat5/timeref.h>
#include <satcat5/utils.h>
 
namespace satcat5 {
    namespace ptp {
        constexpr s64 RATE_ONE_PPB  = satcat5::ptp::SUBNS_PER_NSEC;
        constexpr s64 RATE_ONE_PPM  = 1000 * satcat5::ptp::RATE_ONE_PPB;
        constexpr s64 RATE_ONE_PPK  = 1000 * satcat5::ptp::RATE_ONE_PPM;
 
        class TrackingClock {
        public:
            virtual satcat5::ptp::Time clock_now() = 0;
 
            virtual satcat5::ptp::Time clock_adjust(
                const satcat5::ptp::Time& amount) = 0;
 
            virtual void clock_rate(s64 offset) = 0;
 
            s64 get_rate() const {return m_offset;}
 
        protected:
            constexpr TrackingClock() : m_offset(0), m_next(0) {}
            s64 m_offset;
 
        private:
            // Pointer to the next element in a linked list.
            friend satcat5::util::ListCore;
            satcat5::ptp::TrackingClock* m_next;
        };
 
        class TrackingController
            : public satcat5::ptp::Callback
            , public satcat5::cfg::PpsEventListener {
        public:
            TrackingController(
                satcat5::ptp::TrackingClock* clk,
                satcat5::ptp::Source* source = 0);
 
            void ptp_ready(const satcat5::ptp::Measurement& data) override;
 
            inline void add_clock(satcat5::ptp::TrackingClock* clock)
                { m_clocks.push_front(clock); }
            inline void remove_clock(satcat5::ptp::TrackingClock* clock)
                { m_clocks.remove(clock); }
 
            inline void add_filter(satcat5::ptp::Filter* filter)
                { m_filters.push_back(filter); }
 
            inline void remove_filter(satcat5::ptp::Filter* filter)
                { m_filters.remove(filter); }
 
            void reset(bool linear=false);
 
            inline void reacquire() {
                if (m_lock_state == LockState::TRACK) {
                    m_lock_state = LockState::ACQUIRE;
                }
            }
 
            void update(const satcat5::ptp::Time& delta);
 
            inline bool is_locked() const
                { return m_lock_state == LockState::TRACK ||
                         m_lock_state == LockState::LINEAR; }
 
        protected:
            // Coarse acquisition and lock/unlock state.
            s64 coarse(const satcat5::ptp::Time& delta);
 
            // Run each filter one timestep.
            void filter(u32 elapsed_usec, s64 delta_subns);
 
            // Notify each registered clock object.
            // The primary clock (first added) sets the return value.
            satcat5::ptp::Time clock_adjust(const satcat5::ptp::Time& amount);
            void clock_rate(s64 offset);
 
            // PPS events immediately trigger an update from observed delta.
            inline void pps_event(
                satcat5::ptp::Time& ts, satcat5::ptp::Time& delta) override
                { update(delta); }
 
            // Internal state for fast-acquisition mode.
            enum class LockState {RESET, ACQUIRE, TRACK, LINEAR};
 
            // Internal state.
            satcat5::util::List<satcat5::ptp::TrackingClock> m_clocks;
            satcat5::util::List<satcat5::ptp::Filter> m_filters;
            satcat5::util::TimeVal m_tref;
            s64 m_freq_accum;
            u32 m_lock_alarm;
            u32 m_lock_usec;
            satcat5::ptp::TrackingController::LockState m_lock_state;
        };
 
        class TrackingSimple : public satcat5::ptp::TrackingController {
        public:
            TrackingSimple(
                satcat5::ptp::TrackingClock* clk,
                satcat5::ptp::Source* source);
 
        protected:
            satcat5::ptp::AmplitudeReject m_ampl;
            satcat5::ptp::ControllerPII m_ctrl;
        };
 
        class TrackingCoarse : public satcat5::ptp::Callback {
        public:
            TrackingCoarse(
                satcat5::ptp::TrackingClock* clk,
                satcat5::ptp::Source* source);
 
            void ptp_ready(const satcat5::ptp::Measurement& data) override;
 
        protected:
            // Internal state.
            satcat5::ptp::TrackingClock* m_clock;
        };
    }
}