| axiethernet Vitis Drivers API Documentation

- Overview
- Data Structures
- APIs
- File List
- Examples

Functions
xavb_ptp_bmca.c File Reference

## Overview

The XAvb driver.

Functions in this file all relate to the Best Master Clock Algorithm (BMCA) which is performed on the AVB network to select a network Grand Master Clock.

    MODIFICATION HISTORY:

    Ver   Who  Date     Changes

    1.00a mbr  09/19/08 First release
    1.01a mbr  06/24/09 PTP frame format updates for IEEE802.1 AS draft 5-0
    2_02a mbr  09/16/09 Updates for programmable PTP timers
    2_04a kag  07/23/10 PTP frame format updates for IEEE802.1 AS draft 6-7
    3_01a kag  08/29/11 Added new APIs to update the RX Filter Control Reg.
                  Fix for CR:572539. Updated bit map for Rx Filter
                  control reg.

## Functions
void | XAvb_DecodeTxAnnounceFrame (XAvb *InstancePtr)
| A New Announce Packet has been written to this device to transmit. More...
void | XAvb_DecodeRxAnnounceFrame (XAvb *InstancePtr, u32 PtpFrameBaseAddr)
| A New Announce Packet has been received. More...
void | XAvb_ReadAnnounceFrame (u32 BaseAddress, u32 PtpFrameBaseAddr, XAvb_BmcData *AnnounceFrame)
| A New Announce Packet is to be analyzed. More...
void | XAvb_ReadAnnounceReceiptTimeout (u32 BaseAddress, u32 PtpFrameBaseAddr, XAvb_BmcData *AnnounceFrame)
| This function reads the logMessageinteval from an RX PTP Buffer and updates the AnnounceFrame struct with the value read. More...
u32 | XAvb_BestMasterClockAlgorithm (XAvb_BmcData *AnnounceFrame, XAvb_BmcData *CurrentBmc)
| This function will accept the data pointer to the current BMCA records, accept a pointer to an equivalent data structure for the new Announce Packet. More...
void | XAvb_UpdateBmcRecords (XAvb_BmcData *NewMaster, XAvb_BmcData *CurrentBmc)
| This function will accept the data pointer to the current BMCA records, accept an equivalent pointer to a new (winning) Grand Masters Announce Packet information. More...
void | XAvb_BecomeRtcMaster (XAvb *InstancePtr, u8 txAnnounceHasWon)
| This function will make any adjustments needed when the node becomes the Grand Master, including resetting the RTC to its nominal value. More...
void | XAvb_BecomeRtcSlave (XAvb *InstancePtr)
| This function will make any adjustments needed when the node becomes a PTP slave. More...
void | XAvb_ChangePTPLockStatus (XAvb *InstancePtr, u8 locked)
| Operations needed when PTP locks or unlocks. More...
void | XAvb_ChangePeerASCapability (XAvb *InstancePtr, u8 capable)
| Operations needed when the peer's AS capability changes. More...
void | XAvb_SetGMDiscontinuityHandler (XAvb *InstancePtr, XAvb_Handler FuncPtr, void *CallBackRef)
| This function sets the handler that will be called when a GM discontinuity event is identified by the driver. More...

## Function Documentation

void XAvb_BecomeRtcMaster | ( | XAvb * | InstancePtr,
|  | u8 | txAnnounceHasWon
| ) |  |

This function will make any adjustments needed when the node becomes the Grand Master, including resetting the RTC to its nominal value.

Parameters

  InstancePtr | is a pointer to the XAvb instance to be worked on
  txAnnounceHasWon | indicates that this function has been called from the function XAvb_DecodeTxAnnounceFrame(). Is this is set then this function has no need to repeat actions that have been already performed.

Returns
  None.

Note
  None.

Update the BMCA records to this device's information

Read the attributes in the Tx PTP buffer

Update records

reset the RTC to a nominal value

set timestamp uncertainty if new status

inform the rest of the system

References XAvb_Config::BaseAddress, XAvb::Config, XAvb::CurrentBmc, XAvb::GMDiscCallBackRef, XAvb::GMDiscHandler, XAvb_BmcData::IAmTheRtcMaster, XAvb_ReadAnnounceFrame(), XAVB_RTC_INCREMENT_NOMINAL_RATE, XAVB_RTC_INCREMENT_OFFSET, XAvb_UpdateBmcRecords(), and XAvb_WriteReg.

Referenced by XAvb_DecodeTxAnnounceFrame(), XAvb_PtpTimerInterruptHandler(), and XAvb_Reset().

void XAvb_BecomeRtcSlave | ( | XAvb * | InstancePtr | ) |

This function will make any adjustments needed when the node becomes a PTP slave.

Parameters

  InstancePtr | is a pointer to the XAvb instance to be worked on

Returns
  None.

Note
  None.

set timestamp uncertainty if new status

References XAvb_Counters::CounterSyncInterval, XAvb::CurrentBmc, XAvb::GMDiscCallBackRef, XAvb::GMDiscHandler, XAvb_BmcData::IAmTheRtcMaster, and XAvb::PtpCounters.

Referenced by XAvb_DecodeRxAnnounceFrame().

u32 XAvb_BestMasterClockAlgorithm | ( | XAvb_BmcData * | AnnounceFrame,
|  | XAvb_BmcData * | CurrentBmc
| ) |  |

This function will accept the data pointer to the current BMCA records, accept a pointer to an equivalent data structure for the new Announce Packet.

The Best Master Clock Algorithm (BMCA) is then performed on these two data structures by comparing the data fields

Parameters

  CurrentBmc | is a pointer to a suitable data structure, designed to record the current fields from the current Grand Master's Announce Packet.
  AnnounceFrame | is a pointer to a suitable data structure, designed to record the useful fields from the received Announce Packet

Returns
  An updated True/False decision as to whether there is to be a change of Grand Master in the network.

Note
  None.

Priority1 takes precedence over all over priorites

we have found a better master!

convert structs to u32 values for easy comparison

ClockQuality has the next priority

we have found a better master!

Priority2 provides fine grained ordering amongst otherwise equal clocks

we have found a better master!

Next compare the Clock Identities

we have found a better master!

we have found a better master!

Next compare stepsRemoved

we have found a better master!

Next compare SourcePortIdentity

we have found a better master!

we have found a better master!

If all else fails, the SourcePortIdentity Port Number must act as the tie-breaker

A new master has won on the tie-break!

References XAvb_ClockQuality::clockAccuracy, XAvb_ClockQuality::clockClass, XAvb_PortIdentity::ClockIdentityLower, XAvb_ClockIdentity::ClockIdentityLower, XAvb_PortIdentity::ClockIdentityUpper, XAvb_ClockIdentity::ClockIdentityUpper, XAvb_BmcData::ClockQuality, XAvb_BmcData::GrandmasterIdentity, XAvb_BmcData::GrandmasterPriority1, XAvb_BmcData::GrandmasterPriority2, XAvb_ClockQuality::offsetScaledLogVariance, XAvb_PortIdentity::PortNumber, XAvb_BmcData::SourcePortIdentity, and XAvb_BmcData::stepsRemoved.

Referenced by XAvb_DecodeRxAnnounceFrame(), and XAvb_DecodeTxAnnounceFrame().

void XAvb_ChangePeerASCapability | ( | XAvb * | InstancePtr,
|  | u8 | capable
| ) |  |

Operations needed when the peer's AS capability changes.

Parameters

  InstancePtr | is a pointer to the XAvb instance to be worked on
  capable | is 1 if the peer is ASCapable, 0 otherwise

Returns
  None.

Note
  None.

References XAvb::PeerASCapable.

Referenced by XAvb_CalcDelay(), XAvb_ChangePTPLockStatus(), XAvb_DecodeRxPDelayResp(), XAvb_PtpTimerInterruptHandler(), XAvb_Reset(), and XAvb_Start().

void XAvb_ChangePTPLockStatus | ( | XAvb * | InstancePtr,
|  | u8 | locked
| ) |  |

Operations needed when PTP locks or unlocks.

Parameters

  InstancePtr | is a pointer to the XAvb instance to be worked on
  locked | is 1 if changing to locked status, zero if unlocked

Returns
  None.

Note
  None.

set status variable

set timestamp uncertainty if necessary

References XAvb::GMDiscCallBackRef, XAvb::GMDiscHandler, XAvb::PTPLocked, and XAvb_ChangePeerASCapability().

Referenced by XAvb_UpdateRtcIncrement().

void XAvb_DecodeRxAnnounceFrame | ( | XAvb * | InstancePtr,
|  | u32 | PtpFrameBaseAddr
| ) |  |

A New Announce Packet has been received.

We need to decode it and rerun the Best Master Clock Algorithm (BMCA)

Parameters

  InstancePtr | is a pointer to the XAvb instance to be worked on
  PtpFrameBaseAddr | is the base address of the received Announce Packet in the Rx PTP Packet Buffer

Returns
  None. But an updated True/False decision as to whether this device should operate as a clock master or a slave is written into the CurrentBmc data structure.

Note
  None.

Read the attributes for the new Announce frame received

If the received packet's clockIdentity matches our clockIdentity, ignore the packet

If the received packet's stepsRemoved field is >= 255, ignore the packet

If the Announce packet's GMID matches that of our current GM record, then update its records based on the current packet, just in case something (such as priority) has changed.

update timeout information

Compare against this device's information to see if we should be GM

run BMCA on this announce to see if it is better than me

Update records with the NEW best master

Capture the Announce Receipt Timeout Interval. Reset the announce receipt timeout interval to use the new value.

New Rx Announce Packet has won - so this device cannot be a master

References XAvb_BmcData::AnnounceIntervalDuration, XAvb_Config::BaseAddress, XAvb_ClockQuality::clockClass, XAvb_ClockIdentity::ClockIdentityLower, XAvb_ClockIdentity::ClockIdentityUpper, XAvb_BmcData::ClockQuality, XAvb::Config, XAvb_Counters::CounterAnnounceInterval, XAvb::CurrentBmc, XAvb_BmcData::GrandmasterIdentity, XAvb_BmcData::GrandmasterPriority1, XAvb_BmcData::GrandmasterPriority2, XAvb_BmcData::IAmTheRtcMaster, XAvb_BmcData::logMessageInterval, XAvb::portIdLocal, XAvb::PtpCounters, XAvb_BmcData::SourcePortIdentity, XAvb_BmcData::stepsRemoved, XAvb_BecomeRtcSlave(), XAvb_BestMasterClockAlgorithm(), XAvb_CompareClockIdentity(), XAvb_ComparePortIdentity(), XAvb_ConvertLogMeanToDuration(), XAvb_DecodeTxAnnounceFrame(), XAvb_ReadAnnounceFrame(), XAvb_ReadAnnounceReceiptTimeout(), and XAvb_UpdateBmcRecords().

Referenced by XAvb_PtpRxInterruptHandler().

void XAvb_DecodeTxAnnounceFrame | ( | XAvb * | InstancePtr | ) |

A New Announce Packet has been written to this device to transmit.

We need to decode it and rerun the Best Master Clock Algorithm (BMCA)

Parameters

  InstancePtr | is a pointer to the XAvb instance to be worked on

Returns
  None. But an updated True/False decision as to whether this device should operate as a clock master or a slave is written into the CurrentBmc data structure.

Note
  None.

Read the attributes for the new Announce frame in the Tx PTP buffer

Compare the clock attributes between then new Announce frame and the current master

Update records with the NEW best master

Our new Tx Announce Packet has won - so this device must be the master

References XAvb_Config::BaseAddress, XAvb_ClockQuality::clockClass, XAvb_ClockIdentity::ClockIdentityLower, XAvb_ClockIdentity::ClockIdentityUpper, XAvb_BmcData::ClockQuality, XAvb::Config, XAvb::CurrentBmc, XAvb_BmcData::GrandmasterIdentity, XAvb_BmcData::GrandmasterPriority1, XAvb_BmcData::GrandmasterPriority2, XAvb_BmcData::IAmTheRtcMaster, XAvb_BecomeRtcMaster(), XAvb_BestMasterClockAlgorithm(), XAvb_ReadAnnounceFrame(), and XAvb_UpdateBmcRecords().

Referenced by XAvb_DecodeRxAnnounceFrame(), and XAvb_Start().

void XAvb_ReadAnnounceFrame | ( | u32 | BaseAddress,
|  | u32 | PtpFrameBaseAddr,
|  | XAvb_BmcData * | AnnounceFrame
| ) |  |

A New Announce Packet is to be analyzed.

This function will read in the packet, decode it, and extract the relevant information fields to the "AnnounceFrame" data pointer.

Parameters

  BaseAddress | is the base address of the device
  PtpFrameBaseAddr | is the base address of the received Announce Packet in the Rx PTP Packet Buffer
  AnnounceFrame | is a pointer to a suitable data structure, designed to record the useful fields from the received Announce Packet

Returns
  The AnnounceFrame data structure is updated.

Note
  None.

Get the Source Port Identity of the port sending the Announce Packet

Read priority1 and top half of ClockQuality

Read bottom half of ClockQuality, priority2, and top byte of GMID

Read bytes 4-7 of GMID

Read bytes 1-3 of GMID and high byte of stepsRemoved

Read low byte of stepsRemoved

References XAvb_ClockQuality::clockAccuracy, XAvb_ClockQuality::clockClass, XAvb_PortIdentity::ClockIdentityLower, XAvb_ClockIdentity::ClockIdentityLower, XAvb_PortIdentity::ClockIdentityUpper, XAvb_ClockIdentity::ClockIdentityUpper, XAvb_BmcData::ClockQuality, XAvb_BmcData::GrandmasterIdentity, XAvb_BmcData::GrandmasterPriority1, XAvb_BmcData::GrandmasterPriority2, XAvb_ClockQuality::offsetScaledLogVariance, XAvb_BmcData::SourcePortIdentity, XAvb_BmcData::stepsRemoved, XAvb_GetPortIdentity(), XAvb_ReadPtpBuffer, and XAvb_ReorderWord().

Referenced by XAvb_BecomeRtcMaster(), XAvb_DecodeRxAnnounceFrame(), and XAvb_DecodeTxAnnounceFrame().

void XAvb_ReadAnnounceReceiptTimeout | ( | u32 | BaseAddress,
|  | u32 | PtpFrameBaseAddr,
|  | XAvb_BmcData * | AnnounceFrame
| ) |  |

This function reads the logMessageinteval from an RX PTP Buffer and updates the AnnounceFrame struct with the value read.

Parameters

  BaseAddress | is the base address of the device
  PtpFrameBaseAddr | is the base address of the received Announce Packet in the Rx PTP Packet Buffer
  AnnounceFrame | is a pointer to a suitable data structure, designed to record the useful fields from the received Announce Packet

Returns
  The AnnounceFrame data structure is updated.

Note
  None.

References XAvb_BmcData::logMessageInterval, XAvb_ReadPtpBuffer, and XAvb_ReorderWord().

Referenced by XAvb_DecodeRxAnnounceFrame().

void XAvb_SetGMDiscontinuityHandler | ( | XAvb * | InstancePtr,
|  | XAvb_Handler | FuncPtr,
|  | void * | CallBackRef
| ) |  |

This function sets the handler that will be called when a GM discontinuity event is identified by the driver.

The purpose of the handler is to allow application specific processing to be performed.

Parameters

  InstancePtr | is a pointer to the XAvb instance.
  FuncPtr | is the pointer to the callback function.
  CallBackRef | is the upper layer callback reference passed back when the callback function is invoked.

Returns
  None.

Note
  There is no assert on the CallBackRef since the driver doesn't know what it is (nor should it)

References XAvb::GMDiscCallBackRef, XAvb::GMDiscHandler, and XAvb::IsReady.

Referenced by main().

void XAvb_UpdateBmcRecords | ( | XAvb_BmcData * | NewMaster,
|  | XAvb_BmcData * | CurrentBmc
| ) |  |

This function will accept the data pointer to the current BMCA records, accept an equivalent pointer to a new (winning) Grand Masters Announce Packet information.

The CurrentBmc data structure is then updated with the information from the NewMaster.

Parameters

  NewMaster | is a pointer to a suitable data structure which has recorded the relevant Announce Packet fields of the new (winning) Grand Master.
  CurrentBmc | is a pointer to a suitable data structure which has recorded the current fields of the current Grand Master's Announce Packet.

Returns
  The CurrentBmc data structure is updated.

Note
  None.

References XAvb_PortIdentity::ClockIdentityLower, XAvb_ClockIdentity::ClockIdentityLower, XAvb_PortIdentity::ClockIdentityUpper, XAvb_ClockIdentity::ClockIdentityUpper, XAvb_BmcData::ClockQuality, XAvb_BmcData::GrandmasterIdentity, XAvb_BmcData::GrandmasterPriority1, XAvb_BmcData::GrandmasterPriority2, XAvb_PortIdentity::PortNumber, XAvb_BmcData::SourcePortIdentity, and XAvb_BmcData::stepsRemoved.

Referenced by XAvb_BecomeRtcMaster(), XAvb_DecodeRxAnnounceFrame(), and XAvb_DecodeTxAnnounceFrame().