icss_timeSyncApi.h

Go to the documentation of this file.

/*
 *  Copyright (C) 2024 Texas Instruments Incorporated
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions
 *  are met:
 *
 *    Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 *    Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the
 *    distribution.
 *
 *    Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
#ifndef ICSS_TIMESYNC_API_H_
#define ICSS_TIMESYNC_API_H_
 
#ifdef __cplusplus
extern "C" {
#endif
 
 
/* ========================================================================== */
/*                             Include Files                                  */
/* ========================================================================== */
 
#include <networking/icss_emac/icss_emac.h>
#include <kernel/dpl/HwiP.h>
#include <kernel/dpl/TimerP.h>
#include <kernel/dpl/TaskP.h>
#include <kernel/dpl/EventP.h>
 
#define lswap(x) ((((x) & 0xff000000) >> 24) | \
                  (((x) & 0x00ff0000) >>  8) | \
                  (((x) & 0x0000ff00) <<  8) | \
                  (((x) & 0x000000ff) << 24))
 
#define htonl_ts(l) (lswap(l))
#define ntohl_ts(l) (lswap(l))
 
#define htons_ts(s) ((u_short)((u_short)(s) >> 8) | (u_short)((u_short)(s) << 8))
#define ntohs_ts(s) htons_ts(s)
/* ========================================================================== */
/*                           Macros & Typedefs                                */
/* ========================================================================== */
 
/*TODO: Review this*/
#define TASK_STACK_SIZE (2048)
 
#define ICSS_TIMESYNC_EVENT_BIT0    (0x000001)
#define ICSS_TIMESYNC_EVENT_BIT1    (0x000002)
#define ICSS_TIMESYNC_EVENT_BIT2    (0x000004)
#define ICSS_TIMESYNC_EVENT_BIT3    (0x000008)
#define ICSS_TIMESYNC_EVENT_BIT4    (0x000010)
#define ICSS_TIMESYNC_EVENT_BIT5    (0x000020)
#define ICSS_TIMESYNC_EVENT_BIT6    (0x000040)
#define ICSS_TIMESYNC_EVENT_BIT7    (0x000080)
 
/* Data types */
/* Primitive data types */
 
#define SYNT_DEPTH  3
 
#define TS_NUM_DOMAINS  1
 
/*Below are the masks used for PTP state machine*/
 
#define  TS_STATE_MACHINE_FIRST_ADJUSTMENT_DONE             1
 
#define  TS_STATE_MACHINE_LINE_DELAY_COMPUTED               2
 
#define  TS_STATE_MACHINE_SYNC_INTERVAL_COMPUTED            4
 
#define  TS_STATE_MACHINE_READY_FOR_SYNC                    7
 
#define  TS_STATE_MACHINE_DEVICE_IN_SYNC                    8
 
#define OFFSET_ALGO_BIN_SIZE    5
 
#define OFFSET_ALGO_CLUSTER_SIZE   3
 
typedef enum
{
    INITIALIZING       =  1,
    FAULTY             =  2,
    DISABLED           =  3,
    LISTENING          =  4,
    PRE_MASTER         =  5,
    MASTER             =  6,
    PASSIVE            =  7,
    UNCALIBRATED       =  8,
    SLAVE              =  9
 
} port_State;
 
typedef enum
{
 
    UDP_IPV4 = 1,
    UDP_IPV6 = 2,
    IEEE_802_3 = 3,
    DEVICE_NET = 4,
    CONTROL_NET = 5,
    PROFINET = 6,
    UNKNOWN = 0xFFFE
 
} netWorkProtType;
 
typedef enum
{
 
    TC  = 1,
    OC =  2,
    BOTH = 3
} deviceConfig;
 
typedef enum
{
    E2E  = 1,
    P2P =  2
} delayType;
 
typedef enum
{
    NON_SYNC_DELAY_FRAME  = 0,
    SYNC_FRAME =  1,
    DELAY_REQ_FRAME =  2,
    DELAY_RESP_FRAME =  3
 
} ptpFrameTypes_t;
 
typedef enum
{
    ATOMIC_CLOCK = 0x10,
    GPS = 0x20,
    TERRESTRIAL_RADIO = 0x30,
    PTP = 0x40,
    NTP = 0x50,
    HAND_SET = 0x60,
    OTHER = 0x90,
    INTERNAL_OSCILLATOR = 0xA0,
} timeSource;
 
typedef enum
{
    ICSS_IEP_CLK_FREQ_200MHZ = 200000000,
    ICSS_IEP_CLK_FREQ_250MHZ = 250000000,
    ICSS_IEP_CLK_FREQ_333MHZ = 333333333,
} icssIepClkFreq;
 
typedef enum
{
    PTP_NO_COMPENSATION_REQUIRED = 0,
    PTP_TIME_RECEIVER_FASTER,
    PTP_TIME_TRANSMITTER_FASTER,
} compensationType;
 
typedef struct
{
    uint64_t seconds;           
    uint32_t nanoseconds;       
} timeStamp;
 
 
typedef struct
{
    uint64_t seconds;                   
    uint64_t fractionalNanoseconds;     
} ExtendedTimestamp;
 
typedef void (*TimeSync_SyncLossCallBack_t)(void);
 
typedef void (*TimeSync_stackResetCallback_t)(void *arg);
 
typedef struct
{
    uint8_t clockIdentity[8];
    uint16_t ptpPortNumber;
    uint16_t observedOffsetScaledLogVariance;
    int32_t observedClockPhaseChangeRate;
} TimeSync_parent_params_t;
 
typedef struct
{
    uint8_t priority1;
    uint8_t priority2;
    uint8_t clockClass;
    uint8_t clockAccuracy;
    uint8_t timeSource;
    uint16_t stepRemoved;
    uint16_t clockVariance;
    /*Current UTC offset*/
    uint16_t UTCOffset;
    uint8_t gmIdentity[8];
 
    /*PTP Flag params. See standard
     * index 0 - PTP Leap second 61
     * index 1 - PTP Leap second 59
     * ....
     * ....
     * index 11 - PTP Security*/
 
    uint8_t ptp_flags[12];
 
} TimeSync_master_params_t;
 
typedef struct
{
    /*Rx buffers*/
    uint8_t *pdelayReq_RxBuf[2];
    uint8_t *pdelayRes_RxBuf[2];
    uint8_t *pdelayResFlwUp_RxBuf[2];
    /*For E2E master. Not supported right now*/
    uint8_t *delayReq_RxBuf[2];
 
    /*Tx buffers*/
    uint8_t *pdelayReq_TxBuf[2];
    uint8_t *pdelayRes_TxBuf[2];
    uint8_t *pdelayResFlwUp_TxBuf[2];
    uint8_t *sync_TxBuf;
    uint8_t *announce_TxBuf;
    uint8_t *followUp_TxBuf[2];
    uint8_t *delayReq_TxBuf;
 
    /*Buffer sizes. These change based on whether
     * it's Annex E or Annex F. Pdelay buffer size and
     * delay request (E2E) buffer sizes are fixed
     * because we only support fixed modes*/
    uint8_t  syncBuf_size;
    uint8_t  flwUpBuf_size;
    uint8_t  announceBuf_size;
 
} TimeSync_frame_buffers_t;
 
typedef struct
{
    uint8_t domainNumber[TS_NUM_DOMAINS];
    uint32_t syncOut_sync0Start;
    uint32_t syncOut_sync0PWidth;
    /*Synchronization loss callback function*/
    TimeSync_SyncLossCallBack_t timeSyncSyncLossCallBackfn;
    /*PTP stack reset callback function*/
    TimeSync_stackResetCallback_t ptpDrvStackReset;
    int8_t  logPDelReqPktInterval;
 
    int8_t  logSyncInterval;
 
    int8_t  logAnnounceSendInterval;
 
    int8_t  logAnnounceRcptTimeoutInterval;
 
    uint32_t pDelReqPktInterval;
 
    uint32_t syncSendInterval;
 
    uint32_t announceSendInterval;
 
    uint32_t announceRcptTimeoutInterval;
 
    deviceConfig config;
 
    netWorkProtType protocol;
 
    delayType type;
 
    uint32_t  txIntNum;
 
    uint16_t asymmetryCorrection[ICSS_EMAC_MAX_PORTS_PER_INSTANCE];
 
    uint32_t  pdelayBurstInterval;
 
    uint8_t   pdelayBurstNumPkts;
 
    uint8_t clockIdentity[8];
 
    uint32_t sync0_interval;
 
    uint8_t hsrEnabled;
 
    uint8_t ll_has_hsrTag;
 
    uint8_t custom_tx_api;
 
    uint8_t timestamp_from_shared_ram;
 
    uint8_t emac_mode;
 
    uint8_t frame_offset;
 
    /*OS tick period (in microseconds). Normalized value is 1000 means factor of 1, 500 means
     * OS counts twice as fast so divide time period by 2*/
    uint32_t tickPeriod;
 
    /* Rx PHY Latency in nano seconds */
    uint32_t rxPhyLatency;
 
    /* Tx PHY Latency in nano seconds */
    uint32_t txPhyLatency;
 
    /* Priority of task which sends Pdelay request frames */
    uint8_t delayReqSendTaskPriority;
 
    /* Priority of task which takes time stamp and processes them */
    uint8_t txTsTaskPriority;
 
    /* Priority of task which processes Peer delay frames in the background and      calculate peer delay. NRT stands for non real time.*/
    uint8_t nrtTaskPriority;
 
    /* Priority of task which Checks for Sync timeout and performs offset stabilization */
    uint8_t backgroundTaskPriority;
 
    TimeSync_master_params_t masterParams;
 
    uint32_t icssIepClkFreq;
    
} TimeSync_Config_t;
 
typedef struct
{
    uint8_t enabled;
 
    uint8_t stateMachine;
 
    uint16_t pDelReqSequenceID[ICSS_EMAC_MAX_PORTS_PER_INSTANCE];
 
    uint16_t delReqSequenceID;
 
    uint16_t syncSequenceID;
 
    uint16_t announceSequenceID;
 
    uint16_t curSyncSeqId[ICSS_EMAC_MAX_PORTS_PER_INSTANCE];
 
    uint32_t currSyncInterval;
    uint32_t ltaSyncInterval;
    uint32_t firstSyncInterval;
 
    int32_t currOffset;
    int32_t prevOffset[2];
 
    /*Flags to determine if values in prevOffset[] are valid*/
    int32_t prevOffsetValid[2];
 
    int32_t initialOffset;
 
    /*Once drift stabilizes, this is set to 1*/
    uint8_t driftStable;
 
    /*Once offset becomes zero, this is set to 1*/
    uint8_t offsetStable;
 
    uint8_t  syncPortNum;
 
    uint32_t pathDelay[ICSS_EMAC_MAX_PORTS_PER_INSTANCE];
 
    /*Place holder to calculate line delay.
     * Since line delay can sometimes be negative, we need a persistent variable*/
    int64_t meanPathDelay;
 
    uint32_t clockDrift;
 
    /*long term average of offset. Compare with initial offset to find drift*/
    int32_t ltaOffset;
 
    /*Flags to determine if ltaOffset value is valid*/
    int32_t ltaOffsetValid;
 
    uint32_t avgCorrectionField;
 
    uint64_t tickCounter;
 
    uint32_t syncLastSeenCounter;
 
    uint32_t syncTimeoutInterval;
 
    uint8_t forced2step[ICSS_EMAC_MAX_PORTS_PER_INSTANCE];
 
    /*debug*/
    uint8_t bmcaDone;
 
    TimeSync_master_params_t masterParams;
 
    TimeSync_parent_params_t parentParams;
 
} timeSync_RuntimeVar_t;
 
typedef struct
{
    uint8_t lastSeen_good_drift_index;
 
    uint8_t driftThreshold;
 
    uint8_t num_entries_index;
 
    uint8_t binFull;
 
    int32_t correction[OFFSET_ALGO_BIN_SIZE];
 
} timeSync_Offset_Stable_Algo_t;
 
typedef struct
{
    uint8_t ifTwoStep;
 
    uint64_t correctionField;
 
    uint64_t originTsSec;
    uint32_t originTsNs;
 
    uint32_t rxTs;
 
    uint64_t rxTsSec;
 
    uint32_t txTs;
 
    uint64_t txTsSec;
 
} syncParam_t;
 
typedef struct
{
    uint64_t syncIngressTs[SYNT_DEPTH];
 
    uint64_t correctedMasterTs[SYNT_DEPTH];
 
    double  rcf;
 
    uint8_t   index;
 
    uint8_t    syntEnable;
 
    uint32_t   syntIndex;
 
} timeSync_SyntInfo_t;
 
typedef struct
{
    uint64_t deviceRxTS[SYNT_DEPTH];
 
    uint64_t correctedPeerTS[SYNT_DEPTH];
 
    double  nrr;
 
    uint8_t   curIndex;
 
    uint8_t    nrrEnable;
 
    uint32_t   nrrIndex;
 
} timeSync_NrrInfo_t;
 
 
typedef struct
{
    uint64_t correctionField;
 
    uint64_t   timeStampSec;
    uint32_t   timeStampNS;
 
    uint32_t delReqTxTsSec;
    uint32_t delReqTxTsNS;
 
} delayReqRespParams_t;
 
typedef struct
{
    uint8_t ifTwoStep;
 
    uint32_t T1Sec;
 
    uint32_t T1Nsec;
 
    uint64_t T2Sec;
 
    uint32_t T2Nsec;
 
    uint64_t T3Sec;
 
    uint32_t T3Nsec;
 
    uint64_t T4Sec;
 
    uint32_t T4Nsec;
 
    uint64_t pDelayReqRcvdTSSec;
 
    uint32_t pDelayReqRcvdTSNsec;
 
    uint64_t delayResCorrField;
 
    uint64_t delayResFwUpCorrField;
 
} peerDelayParams_t;
 
typedef struct
{
 
    uint32_t srcIP;
 
    uint32_t dstIP;
 
    uint8_t dscp;
 
    uint8_t ttlVal;
 
} ipParams_t;
 
typedef struct
{
    uint8_t generalFrameFlag;
    uint8_t ptpGeneralFrame[ICSS_EMAC_MAXMTU];
    uint16_t ptpGeneralSize;
    uint8_t ptpSrcMacID[6];
 
} ptpDparams_t;
 
typedef struct TimeSync_ParamsHandle_s
{
    ICSS_EMAC_Handle emacHandle;
 
    uint8_t             macId[6];
    /* MAC ID passed to ICSS-EMAC during ICSS-EMAC initialization*/
 
    PRUICSS_Handle pruicssHandle;
 
    uint8_t enabled;
 
    /*Get TX timestamp*/
    ptpFrameTypes_t
    txFrameType;        
    uint8_t txPort;                     
    uint8_t txprotocol;                 
    uint8_t sequenceIdOut_txTS;         
    /*Get RX timestamp*/
    ptpFrameTypes_t
    rxFrameType;                
    uint8_t rxPort;                     
    uint8_t rxprotocol;                 
    timeStamp *rxTimestamp_gPTP;        
    uint8_t sequenceIdOut_rxTS;         
    /*Set clock*/
    timeStamp clockTime;                
    uint8_t sequenceIdIn;               
    /*Adjust clock*/
    int32_t drift;                      
    uint32_t syncInterval;              
    ptpDparams_t stackParams;
 
    uint32_t pathDelay[ICSS_EMAC_MAX_PORTS_PER_INSTANCE];
 
    uint8_t syntIndexMap[3];
    uint8_t prevIndexMap[3];
 
 
    TaskP_Object timeSync_pDelayReqSendTask;
 
    TaskP_Object timeSync_delayReqSendTask;
 
    /*-----------------Slave tasks, semaphores and events----------------*/
 
    TaskP_Object timeSync_TxTSTaskP1;
    TaskP_Object timeSync_TxTSTaskP2;
 
    TaskP_Object timeSync_NRT_Task;
 
    TaskP_Object timeSync_backgroundTask;
 
    EventP_Object txTSAvailableEvtObject[ICSS_EMAC_MAX_PORTS_PER_INSTANCE];
 
    EventP_Object ptpPdelayResEvtObject[ICSS_EMAC_MAX_PORTS_PER_INSTANCE];
    EventP_Object ptpPdelayReqEvtObject[ICSS_EMAC_MAX_PORTS_PER_INSTANCE];
    EventP_Object ptpSendFollowUpEvtObject[ICSS_EMAC_MAX_PORTS_PER_INSTANCE];
 
    uint32_t eventIdSync;
    uint32_t eventIdPdelayReq;
    uint32_t eventIdPdelayResp;
    uint32_t eventIdPdelayRespFlwUp;
    uint32_t eventIdDelayReq;
    uint32_t eventIdFlwUpGenerated;
 
    /*Semaphore for sending Delay Request frames*/
    SemaphoreP_Object delayReqTxSemObject;
 
    HwiP_Object timeSync_txTSIsrObject;
 
    /*Number of sync frames missed*/
    uint32_t numSyncMissed;
 
    timeSync_Offset_Stable_Algo_t *offsetAlgo;
 
    ipParams_t udpParams;
 
    peerDelayParams_t pDelayParams[ICSS_EMAC_MAX_PORTS_PER_INSTANCE];
 
    delayReqRespParams_t *delayParams;
 
    /*Time sync configuration handle*/
    TimeSync_Config_t timeSyncConfig;
 
    /*Rx and Tx frame buffers*/
    TimeSync_frame_buffers_t timeSyncBuff;
 
    timeSync_SyntInfo_t *tsSyntInfo;
 
    timeSync_NrrInfo_t *tsNrrInfo[ICSS_EMAC_MAX_PORTS_PER_INSTANCE];
 
    syncParam_t *syncParam[ICSS_EMAC_MAX_PORTS_PER_INSTANCE];
 
    timeSync_RuntimeVar_t *tsRunTimeVar;
 
    uint32_t pDelayReqSendTaskStack[TASK_STACK_SIZE/sizeof(uint32_t)]   __attribute__((aligned(32)));
    uint32_t delayReqSendTaskStack[TASK_STACK_SIZE/sizeof(uint32_t)]    __attribute__((aligned(32)));
    uint32_t txTSTaskP1Stack[TASK_STACK_SIZE/sizeof(uint32_t)]          __attribute__((aligned(32)));
    uint32_t txTSTaskP2Stack[TASK_STACK_SIZE/sizeof(uint32_t)]          __attribute__((aligned(32)));
    uint32_t NRT_TaskStack[TASK_STACK_SIZE/sizeof(uint32_t)]            __attribute__((aligned(32)));
    uint32_t backgroundTaskStack[TASK_STACK_SIZE/sizeof(uint32_t)]      __attribute__((aligned(32)));
 
} TimeSync_ParamsHandle;
 
typedef struct TimeSync_ParamsHandle_s *TimeSync_ParamsHandle_t;
 
/* ========================================================================== */
/*                                Error Codes                                 */
/* ========================================================================== */
#define TIMESYNC_OK                     (0)
#define ERROR_TX_FRAMETYPE_NOTVALID     (-1)
#define ERROR_TX_PORTNUMBER_NOTVALID    (-2)
#define ERROR_HANDLE_INVALID            (-3)
#define ERROR_RX_FRAMETYPE_NOTVALID     (-4)
#define ERROR_RX_PORTNUMBER_NOTVALID    (-5)
 
/* ========================================================================== */
/*                          Function Declarations                             */
/* ========================================================================== */
 
int32_t TimeSync_getRxTimestamp(TimeSync_ParamsHandle_t timeSyncParamsHandle,
                                ptpFrameTypes_t rxFrameType, uint8_t rxPort, \
                                uint32_t *nanoseconds, uint64_t *seconds);
 
int32_t TimeSync_getRxTimestampFromFrame(TimeSync_ParamsHandle_t timeSyncParamsHandle,
                                uint8_t rxPort, \
                                uint32_t *nanoseconds, uint64_t *seconds, uint8_t* TimeStampFromFrame);
/* API */
 
int32_t TimeSync_config(TimeSync_ParamsHandle_t timeSyncHandle);
 
int32_t TimeSync_getTxTimestamp(TimeSync_ParamsHandle_t timeSyncParamsHandle, \
                                ptpFrameTypes_t txFrameType, uint8_t txPort, \
                                uint32_t *nanoseconds, uint64_t *seconds);
 
 
int8_t TimeSync_adjTimeSlowComp(TimeSync_ParamsHandle_t timeSyncParamsHandle,
                                int32_t adjOffset);
 
 
int32_t TimeSync_setClockTime(TimeSync_ParamsHandle_t timeSyncParamsHandle);
 
void TimeSync_getCurrentTime(TimeSync_ParamsHandle_t timeSyncParamsHandle,
                             uint32_t *nanoseconds, uint64_t *seconds);
 
void TimeSync_updateDomainNumberInPTPFrames(TimeSync_ParamsHandle_t timeSyncHandle);
 
void TimeSync_updateLogMessageIntervalInPTPFrames(TimeSync_ParamsHandle_t timeSyncHandle);
 
void TimeSync_updateDscpValueInDelayRequestFrame(TimeSync_ParamsHandle_t timeSyncHandle,
                                                 uint8_t dscpValue);
 
#ifdef __cplusplus
}
#endif
 
#endif /* ICSS_TIMESYNC_API_H_ */