ptp_client.h

// Copyright 2023-2025 The Aerospace Corporation.
// This file is a part of SatCat5, licensed under CERN-OHL-W v2 or later.
// Client for the IEEE 1588-2019 Precision Time Protocol (PTP)
 
#pragma once
 
#include <satcat5/igmp_client.h>
#include <satcat5/io_readable.h>
#include <satcat5/list.h>
#include <satcat5/polling.h>
#include <satcat5/ptp_dispatch.h>
#include <satcat5/ptp_header.h>
#include <satcat5/ptp_measurement.h>
#include <satcat5/ptp_source.h>
 
namespace satcat5 {
    namespace ptp {
        enum class ClientMode {
            DISABLED,       // Complete shutdown (Section 9.2.5)
            MASTER_L2,      // Master only, Ethernet mode (Section 9.2.2.1)
            MASTER_L3,      // Master only, UDP mode (Section 9.2.2.1)
            SLAVE_ONLY,     // Slave only, ordinary mode (Section 9.2.2.2)
            SLAVE_SPTP,     // Slave only, SPTP mode
            PASSIVE,        // Passive mode (for Pdelay) (Section 9.2.5)
        };
 
        enum class ClientState {
            DISABLED,       // Manual shutdown
            LISTENING,      // Waiting for ANNOUNCE to select a master
            MASTER,         // Actively providing time to other clients
            PASSIVE,        // Passively responding to peer requests
            SLAVE,          // Actively synchronizing local clock to master
        };
 
        const char* to_string(satcat5::ptp::ClientMode mode);
        const char* to_string(satcat5::ptp::ClientState state);
 
        class Client
            : public satcat5::poll::Timer
            , public satcat5::ptp::Source
        {
        public:
            Client(
                satcat5::ptp::Interface* ptp_iface,
                satcat5::ip::Dispatch* ip_dispatch,
                satcat5::ptp::ClientMode mode = ClientMode::DISABLED);
            ~Client() SATCAT5_OPTIONAL_DTOR;
 
            inline void set_clock(const satcat5::ptp::ClockInfo& clk)
                { m_clock_local = clk; }
            inline satcat5::ptp::ClockInfo get_clock() const
                { return m_clock_local; }
            inline satcat5::ptp::ClockInfo get_remote() const
                { return m_clock_remote; }
            inline satcat5::ptp::Time get_time_now()
                { return m_iface.ptp_time_now(); }
 
            inline s16 get_utc_offset() const
                { return m_utc_offset; }
 
            inline void set_utc_offset(s16 offset)
                { m_utc_offset = offset; }
 
            void set_mode(satcat5::ptp::ClientMode mode);
            inline satcat5::ip::Dispatch* get_iface() const {return m_iface.iface();}
            inline satcat5::ptp::ClientMode get_mode() const {return m_mode;}
            inline satcat5::ptp::ClientState get_state() const {return m_state;}
            inline satcat5::ptp::PortId get_source() const {return m_current_source;}
 
            void set_announce_rate(int rate);
 
            void set_sync_rate(int rate);
 
            void set_pdelay_rate(int rate);
 
            bool send_sync_unicast(
                const satcat5::eth::MacAddr& mac,
                const satcat5::ip::Addr& ip = satcat5::ip::ADDR_NONE,
                const satcat5::eth::VlanTag& vtag = satcat5::eth::VTAG_NONE);
 
            void ptp_rcvd(satcat5::io::LimitedRead& rd);
 
        protected:
            // Timer event handler.
            void timer_event() override;
 
            // Timer setup based on current state.
            void timer_reset();
 
            // Handling for various error events.
            void cache_miss();
            void client_timeout();
 
            // Handlers for TLV and measurement events.
            unsigned tlv_send(
                const satcat5::ptp::Header& hdr,
                satcat5::io::Writeable* wr);
            void notify_if_complete(
                const satcat5::ptp::Measurement* meas);
 
            // Handlers for specific incoming messages.
            void rcvd_announce(
                const satcat5::ptp::Header& hdr,
                satcat5::io::ArrayRead& rd);
            void rcvd_delay_req(
                const satcat5::ptp::Header& hdr,
                satcat5::io::ArrayRead& rd);
            void rcvd_pdelay_req(
                const Header& hdr,
                satcat5::io::ArrayRead& rd);
            void rcvd_delay_resp(
                const satcat5::ptp::Header& hdr,
                satcat5::io::ArrayRead& rd);
            void rcvd_pdelay_resp(
                const satcat5::ptp::Header& hdr,
                satcat5::io::ArrayRead& rd);
            void rcvd_follow_up(
                const satcat5::ptp::Header& hdr,
                satcat5::io::ArrayRead& rd);
            void rcvd_pdelay_follow_up(
                const satcat5::ptp::Header& hdr,
                satcat5::io::ArrayRead& rd);
            void rcvd_sync(
                const satcat5::ptp::Header& hdr,
                satcat5::io::ArrayRead& rd);
            void rcvd_unexpected(
                const satcat5::ptp::Header& hdr);
 
            // Create PTP message header of the given type.
            satcat5::ptp::Header make_header(u8 type, u16 seq_id);
 
            // Generate and send specific outgoing messages.
            bool send_announce();
            bool send_sync(
                satcat5::ptp::DispatchTo addr,
                u16 seq_id, u16 flags = 0, u64 tref = 0);
            bool send_sync_bcast();
            bool send_follow_up(
                satcat5::ptp::DispatchTo addr,
                u16 seq_id, u16 flags = 0, u64 tref = 0);
            void send_delay_req_sptp();
            bool send_delay_req(u16 seq_id, u16 flags = 0);
            bool send_delay_resp(const satcat5::ptp::Header& ref);
            bool send_pdelay_req();
            bool send_pdelay_resp(const satcat5::ptp::Header& ref);
            bool send_pdelay_follow_up(const satcat5::ptp::Header& ref);
 
            // PTP dispatch object.
            satcat5::ptp::Dispatch m_iface;
 
            // Bind to required PTP multicast addresses.
            satcat5::igmp::Address m_mcast_primary;
            satcat5::igmp::Address m_mcast_pdelay;
 
            // List of registered TLV handlers (see "ptp_tlv.h").
            friend satcat5::ptp::TlvHandler;
            satcat5::util::List<satcat5::ptp::TlvHandler> m_tlv_list;
 
            // Other working state.
            satcat5::ptp::ClientMode m_mode;
            satcat5::ptp::ClientState m_state;
            satcat5::ptp::MeasurementCache m_cache;
            satcat5::ptp::ClockInfo m_clock_local;
            satcat5::ptp::ClockInfo m_clock_remote;
            satcat5::ptp::PortId m_current_source;
            unsigned m_announce_count;
            unsigned m_announce_every;
            unsigned m_sync_count;
            unsigned m_sync_every;
            unsigned m_cache_wdog;
            unsigned m_request_wdog;
            int m_announce_rate;
            int m_sync_rate;
            int m_pdelay_rate;
            u16 m_announce_id;
            u16 m_sync_id;
            u16 m_pdelay_id;
            s16 m_utc_offset;
        };
 
        class SyncUnicastL2 : public satcat5::poll::Timer {
        public:
            explicit SyncUnicastL2(satcat5::ptp::Client* client);
 
            inline void connect(const satcat5::eth::MacAddr& addr)
                { m_dstmac = addr; }
 
        protected:
            // Call inherited method timer_every(...) to set message rate.
            void timer_event();
 
            satcat5::ptp::Client* const m_client;
            satcat5::eth::MacAddr m_dstmac;
        };
 
        class SyncUnicastL3 : public satcat5::poll::Timer {
        public:
            explicit SyncUnicastL3(satcat5::ptp::Client* client);
 
            inline void connect(const satcat5::ip::Addr& dstaddr)
                { m_addr.connect(dstaddr); }
 
            inline void close()
                { m_addr.close(); }
 
        protected:
            // Call inherited method timer_every(...) to set message rate.
            void timer_event();
            satcat5::ptp::Client* const m_client;
            satcat5::ip::Address m_addr;
        };
    }
}