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().