Skip to main content

Firmware Stats

This document describes all stats exported by Terragraph firmware.


Terragraph firmware stats are prefixed with "tgf", and take the following format:

tgf.<peer MAC address>.<stat type>.<member>

Stat types are defined in tgfStatsType in fb_tg_fw_pt_if.h. These can be divided into two categories: per-link stats and system stats. For system stats, the MAC address portion is set to 00:00:00:00:00:00.

Different types of stats are published at different frequencies, though most stats are published once per second. Not all stat types are enabled by default, particularly the high-frequency stats. Stats can be toggled at runtime via the FW_STATS_CONFIGURE_REQ message, or persistently using the node configuration field radioParamsBase.fwStatsConfig. For example, to enable beamforming stats, set radioParamsBase.fwStatsConfig.TGF_STATS_BF to true.

Stats are pushed from the firmware (as tgfStatsSample) to driver-if using the TGF_PT_NB_STATS message. These are then parsed and processed in PassThru::getStats(), which also sets the key names. Lastly, driver-if publishes the stats over a ZMQ port (see Stats, Events, Logs for details). They can be polled locally by running the command tg2 stats driver-if.

The table below lists all per-link stats.

TGF_STATS_STA_PKTFrom wgc_bh_get_statistics()Every 1 sec
tgf.MAC.staPkt.txOkNumber of successfully transmitted frames/MPDUs (counter)
tgf.MAC.staPkt.txFailNumber of transmission failures
tgf.MAC.staPkt.rxOkNumber of successfully received frames/MPDUs
tgf.MAC.staPkt.rxFailNumber of CRC failed frames received (once CRC fail, cannot trust RA as well)
tgf.MAC.staPkt.rxPlcpFilNumber of received frames with HCS failed PLCP header
tgf.MAC.staPkt.perE6Instantaneous TX packet error rate x 10^6
tgf.MAC.staPkt.mcsTX MCS at the time of logging
tgf.MAC.staPkt.txBaNumber of block acks transmitted
tgf.MAC.staPkt.txPpduNumber of PPDUs transmitted
tgf.MAC.staPkt.rxBaNumber of block acks received
tgf.MAC.staPkt.rxPpduNumber of PPDUs received
tgf.MAC.staPkt.txPowerIndexTransmit Power Index (values 0-31); this is same value as tpcStats.txPowerIndex, but is reported at a higher frequency
tgf.MAC.staPkt.txLifetimeExpTotal number of TX packets dropped due to lifetime expiry
tgf.MAC.staPkt.rxDiscBufTotal RX Discard count due to Buffer overflow (per STA)
tgf.MAC.staPkt.rxDiscEncTotal RX Discard count due to Encryption failure (per STA)
tgf.MAC.staPkt.rxDiscRaTotal RX Discard count due to RA mismatch (per STA)
tgf.MAC.staPkt.rxDiscUnexpTotal RX Discard count due to other unexpected reasons or PER emulator (per STA)
tgf.MAC.staPkt.txSlotTimeTotal TX Data slot time in 256us unit
tgf.MAC.staPkt.txAirTimeTotal TX data air time in 256us unit
tgf.MAC.staPkt.linkAvailableCounter that increments every BWGD if firmware in LINK_UP state
tgf.MAC.staPkt.txSlotEffTX slot efficiency in units of 0.01%
tgf.MAC.staPkt.mgmtLinkUpCounter that increments every BWGD if link up for mgmt packets
tgf.MAC.staPkt.rxPerE6RX packet error rate (analogous to perE6) at the receiver
tgf.MAC.staPkt.txMpduCountNumber of transmitted MPDUs (since last reported stat epoch)
tgf.MAC.staPkt.rxMpduCountNumber of received MPDUs (since last reported stat epoch)
TGF_STATS_PHYSTATUSPHY status statistics from management packetsEvery 1 sec
tgf.MAC.phystatus.ssnrEstShort training field (STF) SNR (in dB) measured during management packets (KA, HB, ULBWREQ)
tgf.MAC.phystatus.spostSNRdBPost equalizer SNR (in dB) measured during management packets (KA, HB, ULBWREQ)
tgf.MAC.phystatus.srssiReceiver signal strength indicator (RSSI) (in dBm) measured during management packets (KA, HB, ULBWREQ)
tgf.MAC.phystatus.gainIndexIfSee phystatusdata.gainIndexIf
tgf.MAC.phystatus.gainIndexRfSee phystatusdata.gainIndexRf
tgf.MAC.phystatus.rawAdcRssiSee phystatusdata.rawAdcRssi
tgf.MAC.phystatus.rxStartNormalizedNormalized rxStart for last management packet
tgf.MAC.phystatus.maxGainIndexIfMaximum IF gain set by max AGC tracking
tgf.MAC.phystatus.maxGainIndexRfMaximum RF gain set by max AGC tracking
tgf.MAC.phystatus.numTotalSyndromesNumber of failed LDPC codewords
tgf.MAC.phystatus.numTotalCodewordsTotal number of codewords (N_CW in 802.11ad)
tgf.MAC.phystatus.plcpLengthPLCP packet length in bytes
tgf.MAC.phystatus.ldpcIterationsTotal number of LDPC iterations over all N_CW codewords
tgf.MAC.phystatus.rxMcsRX MCS calculated from plcp_0
TGF_STATS_PHYSTATUSPHY status statistics from data packetsEvery 1 sec
tgf.MAC.phystatusdata.ssnrEstShort training field (STF) SNR (in dB) measured during the first data packet in the superframe (if available)
tgf.MAC.phystatusdata.spostSNRdBPost equalizer SNR (in dB) measured during the first data packet in the superframe (if available)
tgf.MAC.phystatusdata.srssiReceiver signal strength indicator (RSSI) (in dBm) measured during the first data packet in the superframe (if available)
tgf.MAC.phystatusdata.gainIndexIfIF gain index (range 0-31) is read when we receive a mgmt or data packet; the gain setting that was used to receive the packet
tgf.MAC.phystatusdata.gainIndexRfRF gain index (range 0-15) is read when we receive a mgmt or data packet; the gain setting that was used to receive the packet
tgf.MAC.phystatusdata.rawAdcRssiRaw ADC RSSI is the raw calculated RSSI after the ADC output, but before any post-processing to refer the RSSI back to the input (mainly used for debugging - units are related to dB)
tgf.MAC.phystatusdata.rxStartNormalizedNormalized rxStart for the first data packet in the superframe (if available)
tgf.MAC.phystatusdata.maxGainIndexIfMaximum IF gain set by max AGC tracking
tgf.MAC.phystatusdata.maxGainIndexRfMaximum RF gain set by max AGC tracking
tgf.MAC.phystatusdata.numTotalSyndromesNumber of failed LDPC codewords
tgf.MAC.phystatusdata.numTotalCodewordsTotal number of codewords (N_CW in 802.11ad)
tgf.MAC.phystatusdata.plcpLengthPLCP packet length in bytes
tgf.MAC.phystatusdata.ldpcIterationsTotal number of LDPC iterations over all N_CW codewords
tgf.MAC.phystatusdata.rxMcsRX MCS calculated from plcp_0
Management packet statistics, {Tx/Rx} = Tx or RxEvery 1 sec
tgf.MAC.mgmt{Tx/Rx}.bfTrainingReqCounter for BF_TRAINING_REQ
tgf.MAC.mgmt{Tx/Rx}.bfTrainingRspCounter for BF_TRAINING_RSP
tgf.MAC.mgmt{Tx/Rx}.bfTrainingRspAckCounter for BF_TRAINING_RSP_ACK
tgf.MAC.mgmt{Tx/Rx}.bfTrainingUrxCounter for BF_TRAINING_URX
tgf.MAC.mgmt{Tx/Rx}.assocReqCounter for ASSOC_REQ
tgf.MAC.mgmt{Tx/Rx}.assocRspCounter for ASSOC_RSP
tgf.MAC.mgmt{Tx/Rx}.assocRspAckCounter for ASSOC_RSP_ACK
tgf.MAC.mgmt{Tx/Rx}.keepAliveCounter for KEEP_ALIVE
tgf.MAC.mgmt{Tx/Rx}.heartBeatCounter for HEART_BEAT
tgf.MAC.mgmt{Tx/Rx}.uplinkBwreqCounter for UPLINK_BWREQ
tgf.MAC.mgmt{Tx/Rx}.bfRetrainingReqCounter for BF_RETRAINING_REQ
tgf.MAC.mgmt{Tx/Rx}.bfRetrnUrxChgReqCounter for BF_RETRN_URX_CHG_REQ
tgf.MAC.mgmt{Tx/Rx}.bfRetrnUrxChgReqAckCounter for BF_RETRN_URX_CHG_REQ_ACK
tgf.MAC.mgmt{Tx/Rx}.dissocReqCounter for DISASSOC_REQ
TGF_STATS_BWHAN_LINKPer-link bandwidth handler statisticsEvery 1 sec
tgf.MAC.bwhanLink.totalTxDataTimeUsTotal TX time (in us)
tgf.MAC.bwhanLink.totalRxDataTimeUsTotal RX time (in us)
tgf.MAC.bwhanLink.totalTxDataSlotsTotal number of TX slots
tgf.MAC.bwhanLink.totalRxDataSlotsTotal number of RX slots
tgf.MAC.bwhanLink.currTxTimePercentCurrent L2 scheduler-proposed TX time percentage
tgf.MAC.bwhanLink.currRxTimePercentCurrent L2 scheduler-proposed RX time percentage
tgf.MAC.bwhanLink.currTxSlotPercentCurrent actual TX slot percentage
tgf.MAC.bwhanLink.currRxSlotPercentCurrent actual RX slot percentage
tgf.MAC.bwhanLink.txCtrlFallbackCountTX map control-only fallback counter
tgf.MAC.bwhanLink.rxCtrlFallbackCountRX map control-only fallback counter
tgf.MAC.bwhanLink.localBytesPendingQueue size (in bytes)
tgf.MAC.bwhanLink.localArrivalRateArrival rate (in bytes/ms)
tgf.MAC.bwhanLink.peerBytesPendingQueue size at peer (in bytes)
tgf.MAC.bwhanLink.peerArrivalRateArrival rate at peer (in bytes/ms)
TGF_STATS_TPCTransmit Power Control (TPC) statisticsEvery 1 sec
tgf.MAC.tpcStats.effSnr"Effective SNR" is a filtered version of the peer mgmt SNR as reported in mgmt packets from the far end
tgf.MAC.tpcStats.tsIirRssiFiltered version of the peer RSSI as reported in mgmt packets from the far end
tgf.MAC.tpcStats.tsIirRssiTargetMgmtTarget RSSI used for open loop power control (when there is no data traffic)
TGF_STATS_MAX_AGCMaximum automatic gain control (AGC) statisticsEvery 5 sec
tgf.MAC.maxAgcStats.maxGainIndexIfMaximum IF gain set by max AGC tracking
tgf.MAC.maxAgcStats.maxGainIndexRfMaximum RF gain set by max AGC tracking
tgf.MAC.maxAgcStats.numBwgdsInFreeRunNumber of BWGDs in which the max AGC was free-running
tgf.MAC.maxAgcStats.iirAvgRssiAverage RSSI at the receiver
tgf.MAC.maxAgcStats.minRssiCurrent minimum RSSI
TGF_STATS_BFBeamforming (BF) statistics40-5000 per sec or ASYNC mode type (REQ / RSP / ACK) Beam Index Beam Index LQM RSSI Start based on TSF Packet Index number in BF window number in SF
TGF_STATS_RECV_MGMTReceived management packet info40-5000 per sec
tgf.MAC.recvMgmt.actionCodeSame as sMgmtPkt.mgmtHdr.actionCode
tgf.MAC.recvMgmt.rxstartSame as wgc_bh_mgmt_rxdesp_t.rxstart
tgf.MAC.recvMgmt.sizeSame as wgc_bh_mgmt_rxdesp_t.size
tgf.MAC.recvMgmt.plcp{n}Same as wgc_bh_mgmt_rxdesp_t.plcp_{n} (n=0,1,2)
tgf.MAC.recvMgmt.beamRxSame as wgc_bh_rx_phystatus_t.beamRx
tgf.MAC.recvMgmt.phyStatus{n}Same as wgc_bh_rx_phystatus_t.phy_status_{n} (n=0,1,2,3)
TGF_STATS_MGMT_DATAReceived management packet data40-5000 per sec
TGF_STATS_MISC_LINKMiscellaneous per-link statisticsEvery 1 sec
tgf.MAC.miscLink.dataTxSlotDurDuration in us of BH_SLOT_TYPE_TX
tgf.MAC.miscLink.dataRxSlotDurDuration in us of BH_SLOT_TYPE_RX
tgf.MAC.miscLink.bfTxSlotDurDuration in us of BH_SLOT_TYPE_BEAMFORMING_TX
tgf.MAC.miscLink.bfRxSlotDurDuration in us of BH_SLOT_TYPE_BEAMFORMING_RX
tgf.MAC.miscLink.txstatusFlagAckCounter for WGC_BH_TXSTATUS_FLAG_ACK
tgf.MAC.miscLink.txstatusLifetimeExpCounter for WGC_BH_TXSTATUS_LIFETIME_EXPIRED
tgf.MAC.miscLink.txstatusFlushedCounter for WGC_BH_TXSTATUS_FLUSHED
tgf.MAC.miscLink.currentLinkStateCurrent link state (from fsmState)
tgf.MAC.miscLink.mtpoRunCounterCounter that increments when MTPO is triggered (and FB response is OK) at initiator
tgf.MAC.miscLink.mtpoSuccessCounterCounter that increments when MTPO runs successfully at initiator
tgf.MAC.miscLink.mtpoApplyNewPhaseCounterCounter that increments when MTPO runs successfully at initiator and applies a new phase
tgf.MAC.miscLink.mtpoRejectCounterCounter that increments when MTPO requested but rejected
tgf.MAC.miscLink.mtpoFailCounterCounter that increments when initiator response indicates failure
tgf.MAC.miscLink.mtpoResponderTimeoutCounterCounter that increments when response from responder indicates timeout
tgf.MAC.miscLink.mtpoCurrentPhases0xABCD where A,B,C,D are the phases (D is tile 0); only populated after MTPO succeeds
TGF_STATS_PHY_PERIODICPeriodic Beamforming statsEvery 300 sec, or whenever beam changes during scans
tgf.MAC.phyPeriodic.txBeamIdxCurrently selected TX beam index
tgf.MAC.phyPeriodic.rxBeamIdxCurrently selected RX beam index
tgf.MAC.phyPeriodic.txRficBitmapTransmit RFIC Bitmap
tgf.MAC.phyPeriodic.rxRficBitmapReceive RFIC Bitmap
tgf.MAC.phyPeriodic.pktLqmInitial beamforming SNR (in dB) for the best beam combination
tgf.MAC.phyPeriodic.pktRssiInitial beamforming RSSI (in dBm, not calibrated) for the best beam combination
TGF_STATS_LA_TPCLink Adaptation and Transmit Power Control (LA/TPC) statisticsEvery 1 sec
tgf.MAC.latpcStats.laTpcOffsetdBQ24Offset that drives the LA/TPC algorithm (offset = laTpcOffsetdBQ24/2^24); positive offset indicates good link conditions
tgf.MAC.latpcStats.noTrafficCountSFRunning counter that increments every SF when that SF has no data traffic
tgf.MAC.latpcStats.numSFsAtLowerLimitRunning counter that increments every SF when the algorithm wants to lower MCS or increase power but can't because it hits the limits
tgf.MAC.latpcStats.nCWRunning counter of the number of peer LDPC codewords
tgf.MAC.latpcStats.nSynRunning counter of the number of peer LDPC syndromes
tgf.MAC.latpcStats.nIterRunning counter of the number of peer LDPC iterations
tgf.MAC.latpcStats.synPERQ16PER as calculated based on LDPC stats
TGF_STATS_LINK_DOWNLink down eventsWhenever link goes down
tgf.MAC.linkDown.causeCause of link going down (tgLinkFailureCause)

System Stats

The table below lists all system stats.

TGF_STATS_GPSGPS module statisticsEvery 1 sec
tgf.MAC.gps.driverDelayDriver ioctl delay from PPS tsf boundary (in microseconds)
tgf.MAC.gps.maxDriverDelayMax of "driverDelay"
tgf.MAC.gps.numPpsErrNumber of PPS tsf read errors
tgf.MAC.gps.numTimelineErrNumber of errors due to firmware/driver taking more time
tgf.MAC.gps.numMissedSecNumber of times driver did not send GPS time (derived from tsf, and can increase by many counts per second)
tgf.MAC.gps.ppsJitterJitter for the last PPS tsf (in microseconds), only recording valid samples (i.e. PPS jitter <= 25us) used for GPS drift correction
tgf.MAC.gps.maxPpsJitterMax of "ppsJitter", but counting all received samples (including samples with high PPS jitter)
tgf.MAC.gps.tsfDriftCumulative drift in tsf
tgf.MAC.gps.ppsHwTsfHW TSF at last PPS
tgf.MAC.gps.ppsHwTsfNsHW TSF at last PPS ns portion
tgf.MAC.gps.ppsSwTsfSW TSF at last PPS
tgf.MAC.gps.ppsSwTsfNsSW TSF at last PPS ns portion
TGF_STATS_SLOTSlot programming statisticsEvery 1 sec
tgf.MAC.slot.numOfTxBfSlotsPgmrdCounter for BH_SLOT_TYPE_BEAMFORMING_TX (BF TX) slots
tgf.MAC.slot.numOfRxBfSlotsPgmrdCounter for BH_SLOT_TYPE_BEAMFORMING_RX (BF RX) slots
tgf.MAC.slot.numOfTxDataSlotsPgmrdCounter for BH_SLOT_TYPE_TX (Data TX) slots
tgf.MAC.slot.numOfRxDataSlotsPgmrdCounter for BH_SLOT_TYPE_RX (Data RX) slots
tgf.MAC.slot.numOfShortCalibSlotsCounter for short calibration slots (duration <= 200us)
tgf.MAC.slot.numOfLongCalibSlotsCounter for long calibration slots (duration > 200us)
TGF_STATS_BWHAN_SYSSystem bandwidth handler statisticsEvery 1 sec
tgf.MAC.bwhanSys.totalTxAssocTimeTotal TX time used for Association phase (in us)
tgf.MAC.bwhanSys.totalRxAssocTimeTotal RX time used for Association phase (in us)
TGF_STATS_MEMMemory management statistics10000 per sec
tgf.MAC.mem.mallocSizeCounter for wgc_bh_malloc()
tgf.MAC.mem.mfreeSizeCounter for wgc_bh_mfree()
TGF_STATS_MISC_SYSMiscellaneous system statisticsEvery 1 sec
tgf.MAC.miscSys.numMissedSfmNumber of superframes with missed slots programming
tgf.MAC.miscSys.mallocBytes malloc'ed
tgf.MAC.miscSys.freeBytes free'ed
tgf.MAC.miscSys.numFrameTimerNumber of times tgfFrameTimer() got called
tgf.MAC.miscSys.rfToGpsNumber of transitions from RF to GPS sync
tgf.MAC.miscSys.gpsToRfNumber of transitions from GPS to RF sync
tgf.MAC.miscSys.cpuLoadAvgCPU load average, expressed as an integer percent
tgf.MAC.miscSys.rftemperature{n}RFIC-{n} temperature, in degrees C (n=0,1,2,3)
tgf.MAC.miscSys.iftemperatureBaseband (IF) temperature, in degrees C
tgf.MAC.miscSys.getPktBufCounter for wgc_bh_getPktBuf() call
tgf.MAC.miscSys.recvMgmtCounter for bh_recv_mgmt() call
tgf.MAC.miscSys.freePktBufCounter for wgc_bh_freePktBuf() call
tgf.MAC.miscSys.sendMgmtCBCounter for bh_send_mgmtCB() call
tgf.MAC.miscSys.txstatusNoStaCounter for WGC_BH_TXSTATUS_NO_STA
tgf.MAC.miscSys.mgmtRxIncorrectHdrCounter for correct hdr.category and hdr.oui
tgf.MAC.miscSys.numBcastImTrnReqSentCounter for Broadcast BF_RETRAINING_REQ sent
tgf.MAC.miscSys.numBcastImTrnReqRecvdCounter for Broadcast BF_RETRAINING_REQ received
tgf.MAC.miscSys.numIncorrectBcastPktsRecvdCounter for unexpected Broadcast messages
TGF_STATS_TSFtsf module statisticsEvery 1 sec
tgf.MAC.tsf.syncModeGps1 if tsf is in "GPS sync" state, otherwise 0
tgf.MAC.tsf.syncModeRf1 if tsf is in "RF sync" state, otherwise 0
tgf.MAC.tsf.numRfFixNumber of times tsf offset fixed on "RF sync"
tgf.MAC.tsf.numGpsFixNumber of times tsf offset fixed on "GPS sync"
tgf.MAC.tsf.rfDriftLargest value of tsf drift over current stats interval with regard to the RF link
tgf.MAC.tsf.sumRfFixSum of tsf fixes for "RF sync"
tgf.MAC.tsf.sumGpsFixSum of tsf fixes for "GPS sync"
tgf.MAC.tsf.offsetLLow word of current offset (sw_tsf - hw_tsf)
tgf.MAC.tsf.offsetHHigh word of current offset (sw_tsf - hw_tsf)
tgf.MAC.tsf.driftPerWinAverage drift per window (e.g. per 10s)
Lifetime expiry stats for management packetsEvery 1 sec
tgf.MAC.lifetime{Expired/Ok}.{action}Counter per action type (action=0,1,...,11, e.g. ASSOC_REQ, KEEP_ALIVE)
TGF_STATS_CHNChannel module statisticsEvery 60 sec
tgf.MAC.chn.maxTickCodebookFetchMax time spent to fetch codebook
tgf.MAC.chn.maxTickChannelChangeMax time spent to change channel
tgf.MAC.chn.errInvalidChnInCount for invalid input error
tgf.MAC.chn.errSetChnCount for error in set_channel()
tgf.MAC.chn.errAssocCount for errors in assoc
tgf.MAC.chn.stateLast state
tgf.MAC.chn.channelLast operating channel
tgf.MAC.chn.configuredChannelLast configured channel
tgf.MAC.chn.numSwitchesNumber of channel switch attempts
TGF_STATS_SECURITYSecurity statisticsEvery 300 sec, and also during association and link-down phases encryption (wsec) status (tgWsecAuthType, i.e. 0=disabled, 1=PSK, 2=EAP)
TGF_STATS_BF_SCANBeamforming (BF) scan statisticsEvery 300 sec, and also after BF scans (when enabled)
tgf.MAC.bfScanStats.numOfScanReqRecvdNumber of scan request commands received
tgf.MAC.bfScanStats.numOfScanCompletedNumber of scans complete
tgf.MAC.bfScanStats.numOfScanDroppedNumber of scans dropped
tgf.MAC.bfScanStats.numOfScanAbortedNumber of scans aborted
tgf.MAC.bfScanStats.numOfScanAsInitiatorNumber of scans as initiator
tgf.MAC.bfScanStats.numOfScanAsResponderNumber of scans as Responder
tgf.MAC.bfScanStats.numOfPbfScanNumber of PBF scans
tgf.MAC.bfScanStats.numOfImScanNumber of IM scans
tgf.MAC.bfScanStats.numOfRtCalScanNumber of RTCAL scans
tgf.MAC.bfScanStats.numOfVbsScanNumber of VBS scans
tgf.MAC.bfScanStats.numOfCbfScanNumber of CBF scans