\section{SNMP exports (WIP)}
\label{sec:snmp_exports}
This section describes SNMP objects exported by wrs switch. Objects within
\texttt{WR\--SWITCH\--MIB} are divided into two categories. Operator/basic objects
(section \ref{sec:snmp_exports:basic}) providing basic status of the WR Switch.
It should be used by control system operators and people without deep knowledge
of the White Rabbit internals. These values report the general status of the
device and high level errors.

Expert/extended status objects (section \ref{sec:snmp_exports:expert})
can be used by White Rabbit experts for the in-depth diagnosis of
the switch failures. These values are verbose and should not be used by
operators.


\subsection{Operator/basic objects}
\label{sec:snmp_exports:basic}
This section describes MIB objects that are calculated based on other objects'
values and switch version's objects.

Most of the status objects described in this section can have one of the
following values:
\begin{itemize}%[leftmargin=0pt]
  \item \texttt{NA} -- Status value was not calculated at all (returned value
	is 0). Something bad has happened.
  \item \texttt{OK} -- Status of particular object is correct.
  \item \texttt{Warning} -- Objects used to calculate this value are outside
	proper values, but problem in not important enough to report
	\texttt{Error}.
  \item \texttt{WarningNA} -- At least one of the objects used to calculate
	status has value \texttt{NA} or \texttt{WarningNA}.
  \item \texttt{Error} -- Error in values used to calculate particular object.
  \item \texttt{FirstRead} -- Object's value cannot be calculated because at
	least one condition uses deltas between current and previous value.
	This values should appear only at first SNMP read. Threated as correct
	value.
  \item \texttt{Bug} -- Something wrong happened while calculating object's
	value. If you see this please report.
\end{itemize}

\noindent {\bf General Status objects}:
\begin{itemize}%[leftmargin=0pt]
  \item \texttt{wrsGeneralStatusGroup} -- Group containing collective statuses
	of particular subsystems and main system status, describing status of
	entire switch.
    \begin{itemize}
      \item \texttt{wrsMainSystemStatus} -- WRS general status of a switch can
	    be OK, Warning or Error. When there is an error or warning please
	    check values of \texttt{wrsOSStatus}, \texttt{wrsTimingStatus}
	    and \texttt{wrsNetworkingStatus} to find out which subsystem is
	    causing problems.
      \item \texttt{wrsOSStatus} -- Collective status of a
	    \texttt{wrsOSStatusGroup}. For details please check group's content.
      \item \texttt{wrsTimingStatus} -- Collective status of a
	    \texttt{wrsTimingStatusGroup}. For details please check group's
	    content.
      \item \texttt{wrsNetworkingStatus} -- Collective status of a
	    \texttt{wrsNetworkingStatusGroup}. For details please check group's
	    content.
    \end{itemize}
  \item \texttt{wrsDetailedStatusesGroup} -- Branch with collective statuses of
	switch's subsystems.
    \begin{itemize}
      \item \texttt{wrsOSStatusGroup} -- Group with collective statuses of
	switch's Operating System.
	\begin{itemize}
	  \item \texttt{wrsBootSuccessful} -- Grouped status of
		\texttt{wrsBootStatusGroup}, indicating whether boot was
		successful. Error when dot-config source is wrong, unable to
		get dot-config, dot-config contains errors, unable to read
		hwinfo, unable to load FPGA bitstream, unable to load LM32
		software, any kernel modules are missing or userspace daemons
		are missing (issue \ref{fail:other:boot},
		\ref{fail:other:dot-config}).
	  \item \texttt{wrsTemperatureWarning} -- Report whether temperature
		thresholds are not set or are exceeded (issue
		\ref{fail:other:temp}).
	  \item \texttt{wrsMemoryFreeLow} -- Warning when 50\% of memory is
		used, error when more than 80\% of memory is used (issue
		\ref{fail:other:no_mem}).
	  \item \texttt{wrsCpuLoadHigh} -- Warning when average CPU load is
		more than 2 for 1min, 1.5 for 5min or 1 for 15min. Error when
		average CPU load is more than 3 for 1min, 2 for 5min or 1.5 for
		15min (issue \ref{fail:other:cpu}).
	  \item \texttt{wrsDiskSpaceLow} -- Warning when more than 80\% of any
		disk partition is used. Error when more than 90\% of any disk
		partition is used. (issue \ref{fail:other:no_disk}).
	\end{itemize}
      \item \texttt{wrsTimingStatusGroup} -- Group with collective statuses of
	    switch's timing subsystem.
	\begin{itemize}
	  \item \texttt{wrsPTPStatus} -- Error when any of PTP error counters
		in \texttt{wrsPtpDataTable} (\texttt{wrsPtpServoStateErrCnt},
		\texttt{wrsPtpClockOffsetErrCnt} or\\ \texttt{wrsPtpRTTErrCnt})
		increased since last scan (issues
		\ref{fail:timing:ppsi_track_phase},
		\ref{fail:timing:offset_jump},
		\ref{fail:timing:rtt_jump}), at least one of the 
		$\Delta_{TXM}$, $\Delta_{RXM}$, $\Delta_{TXS}$ is equal to 0
		(issue \ref{fail:timing:deltas_report}) or ptp servo
		updates counter not increased.
	  \item \texttt{wrsSoftPLLStatus} -- Error when \texttt{wrsSpllSeqState} not
		ready, or \\ \texttt{wrsSpllAlignState} is not locked for
		grand master, or one of \texttt{wrsSpllHlock},
		\texttt{wrsSpllMlock} equals to 0 for SoftPLL slave mode (issue
		\ref{fail:timing:spll_unlock}).\\
		Warning when \texttt{wrsSpllDelCnt} $>$ 0 for grand master mode
		or \texttt{wrsSpllDelCnt} changed any for all modes.
	  \item \texttt{wrsSlaveLinksStatus} -- Error when link to master is
		down for switch in slave mode (issue
		\ref{fail:timing:master_down}). Additionally, error when link
		to master is up for switch in free running master or grand
		master (issue \ref{fail:timing:master_up}).
	  \item \texttt{wrsPTPFramesFlowing} -- Error when there is no
		increment of RX and TX PTP packets on all links up that are 
		configured as master or slave (issue
		\ref{fail:timing:no_frames}). Report the first run.
	\end{itemize}
      \item \texttt{wrsNetworkingStatusGroup} -- Group with collective statuses
	    of switch's networking subsystem.
	\begin{itemize}
	  \item \texttt{wrsSFPsStatus} -- Error when any of SFPs reports error.
		To find out which SFP caused a problem check
		\texttt{wrsPortStatusSfpError.<n>} (issue
		\ref{fail:timing:wrong_sfp}, \ref{fail:other:sfp})
	  \item \texttt{wrsEndpointStatus} -- Error when there is a fault in
		the Endpoint's transmission/reception path (issue
		\ref{fail:data:ep_txrx}).
	  \item \texttt{wrsSwcoreStatus} -- Not used in this release. Always
		reports that it is ok.
	  \item \texttt{wrsRTUStatus} -- Error when RTU is full and cannot
		accept more requests (issue \ref{fail:data:rtu_full}).

	\end{itemize}
    \end{itemize}
  \item \texttt{wrsVersionGroup} -- Hardware, gateware and software versions.
	Additionally switch's serial number and other hardware information.
    \begin{itemize}
      \item \texttt{wrsVersionSwVersion} -- The software version, as returned
	    from \texttt{git describe} at build time.
      \item \texttt{wrsVersionSwBuildBy} -- The software build by, as returned
	    from \texttt{git config --get-all user.name} at build time
      \item \texttt{wrsVersionSwBuildDate} -- The build date of the software,
	    \texttt{\_\_DATE\_\_} at build time
      \item \texttt{wrsVersionBackplaneVersion} -- The hardware version of
	    minibackplane PCB
      \item \texttt{wrsVersionFpgaType} -- The hardware type of FPGA
      \item \texttt{wrsVersionManufacturer} -- The name of the manufacturing
	    company of the switch
      \item \texttt{wrsVersionSwitchSerialNumber} -- The serial number (or
	    string) of the switch
      \item \texttt{wrsVersionScbVersion} -- The version of the SCB (switch's
	    motherboard)
      \item \texttt{wrsVersionGwVersion} -- The version of gateware (FPGA
	    bitstream)
      \item \texttt{wrsVersionGwBuild} -- The build ID of gateware (FPGA
	    bitstream)
      \item \texttt{wrsVersionSwitchHdlCommitId} -- The gateware version:
	    commit ID of \texttt{wr\_switch\_hdl}
      \item \texttt{wrsVersionGeneralCoresCommitId} -- The gateware version:
	    commit of \texttt{general-cores}
      \item \texttt{wrsVersionWrCoresCommitId} -- The gateware version: commit
	    of \texttt{wr-cores}
      \item \texttt{wrsVersionLastUpdateDate} -- Date and time of last firmware
	    update, this information may not be accurate, due to hard restarts
	    or lack of proper time at update.
    \end{itemize}
\end{itemize}

\newpage
\subsection{Expert/extended status}
\label{sec:snmp_exports:expert}

\noindent {\bf Expert Status}:
\begin{itemize}
  \item \texttt{wrsOperationStatus}
    \begin{itemize}
      \item \texttt{wrsCurrentTimeGroup}
	\begin{itemize}
	  \item \texttt{wrsDateTAI}
	  \item \texttt{wrsDateTAIString}
	\end{itemize}
      \item \texttt{wrsBootStatusGroup}
	\begin{itemize}
	  \item \texttt{wrsBootCnt}
	  \item \texttt{wrsRebootCnt}
	  \item \texttt{wrsRestartReason}
	  \item \texttt{wrsFaultIP} -- Not implemented
	  \item \texttt{wrsFaultLR} -- Not implemented
	  \item \texttt{wrsConfigSource}
	  \item \texttt{wrsConfigSourceHost}
	  \item \texttt{wrsConfigSourceFilename}
	  \item \texttt{wrsBootConfigStatus}
	  %below boot status values
	  \item \texttt{wrsBootHwinfoReadout}
	  \item \texttt{wrsBootLoadFPGA}
	  \item \texttt{wrsBootLoadLM32}
	  \item \texttt{wrsBootKernelModulesMissing} -- List of kernel modules
		is defined in source code.
	  \item \texttt{wrsBootUserspaceDaemonsMissing} -- List of daemons
		is defined in source code.
	  \item \texttt{wrsGwWatchdogTimeouts} -- Number of times the watchdog
		has restarted the HDL module responsible for the Ethernet
		switching process (issue \ref{fail:other:hdl_freeze}).
	  \item \texttt{wrsRestartReasonMonit} -- Process that caused
	        \texttt{monit} to trigger restart.
	\end{itemize}
      \item \texttt{wrsTemperatureGroup}
	\begin{itemize}
	  \item \texttt{wrsTempFPGA}
	  \item \texttt{wrsTempPLL}
	  \item \texttt{wrsTempPSL}
	  \item \texttt{wrsTempPSR}
	  \item \texttt{wrsTempThresholdFPGA}
	  \item \texttt{wrsTempThresholdPLL}
	  \item \texttt{wrsTempThresholdPSL}
	  \item \texttt{wrsTempThresholdPSR}
	\end{itemize}
      \item \texttt{wrsMemoryGroup}
	\begin{itemize}
	  \item \texttt{wrsMemoryTotal}
	  \item \texttt{wrsMemoryUsed}
	  \item \texttt{wrsMemoryUsedPerc}
	  \item \texttt{wrsMemoryFree}
	\end{itemize}
      \item \texttt{wrsCpuLoadGroup}
	\begin{itemize}
	  \item \texttt{wrsCPULoadAvg1min}
	  \item \texttt{wrsCPULoadAvg5min}
	  \item \texttt{wrsCPULoadAvg15min}
	\end{itemize}
      \item \texttt{wrsDiskTable} -- Table with a row for every partition.
	\begin{itemize}
	  \item \texttt{wrsDiskIndex}
	  \item \texttt{wrsDiskMountPath}
	  \item \texttt{wrsDiskSize}
	  \item \texttt{wrsDiskUsed}
	  \item \texttt{wrsDiskFree}
	  \item \texttt{wrsDiskUseRate}
	  \item \texttt{wrsDiskFilesystem}
	\end{itemize}
    \end{itemize}

  \item \texttt{wrsStartCntGroup}
    \begin{itemize}
      \item \texttt{wrsStartCntHAL} \ref{fail:timing:hal_crash}, \ref{fail:other:daemon_crash}
      \item \texttt{wrsStartCntPTP} \ref{fail:timing:ppsi_crash}, \ref{fail:other:daemon_crash}
      \item \texttt{wrsStartCntRTUd} \ref{fail:data:rtu_crash}, \ref{fail:other:daemon_crash}
      \item \texttt{wrsStartCntSshd}
      \item \texttt{wrsStartCntHttpd}
      \item \texttt{wrsStartCntSnmpd}
      \item \texttt{wrsStartCntSyslogd}
      \item \texttt{wrsStartCntWrsWatchdog}
    \end{itemize}

  \item \texttt{wrsSpllState}
    \begin{itemize}
      \item \texttt{wrsSpllVersionGroup}
	\begin{itemize}
	  \item \texttt{wrsSpllVersion}
	  \item \texttt{wrsSpllBuildDate}
	\end{itemize}
      \item \texttt{wrsSpllStatusGroup}
	\begin{itemize}
	  \item \texttt{wrsSpllMode}
	  \item \texttt{wrsSpllIrqCnt}
	  \item \texttt{wrsSpllSeqState}
	  \item \texttt{wrsSpllAlignState}
	  \item \texttt{wrsSpllHlock}
	  \item \texttt{wrsSpllMlock}
	  \item \texttt{wrsSpllHY}
	  \item \texttt{wrsSpllMY}
	  \item \texttt{wrsSpllDelCnt}
%		xxx wrsSpllHoldover
%		xxx wrsSpllHoldoverTime
%		xxx (...)
	\end{itemize}
%     \item \texttt{wrsSpllPerPortTable[18]
%	\begin{itemize}
%		xxx wrsSpllBlock
%		xxx wrsSpllErr
%	\end{itemize}
    \end{itemize}

  \item \texttt{wrsPstatsTable} -- Table with pstats values, one row per port.
    \begin{itemize}
      \item \texttt{wrsPstatsIndex}
      \item \texttt{wrsPstatsPortName}
      \item \texttt{wrsPstatsTXUnderrun}
      \item \texttt{wrsPstatsRXOverrun}
      \item \texttt{wrsPstatsRXInvalidCode}
      \item \texttt{wrsPstatsRXSyncLost}
      \item \texttt{wrsPstatsRXPauseFrames}
      \item \texttt{wrsPstatsRXPfilterDropped}
      \item \texttt{wrsPstatsRXPCSErrors}
      \item \texttt{wrsPstatsRXGiantFrames}
      \item \texttt{wrsPstatsRXRuntFrames}
      \item \texttt{wrsPstatsRXCRCErrors}
      \item \texttt{wrsPstatsRXPclass0}
      \item \texttt{wrsPstatsRXPclass1}
      \item \texttt{wrsPstatsRXPclass2}
      \item \texttt{wrsPstatsRXPclass3}
      \item \texttt{wrsPstatsRXPclass4}
      \item \texttt{wrsPstatsRXPclass5}
      \item \texttt{wrsPstatsRXPclass6}
      \item \texttt{wrsPstatsRXPclass7}
      \item \texttt{wrsPstatsTXFrames}
      \item \texttt{wrsPstatsRXFrames}
      \item \texttt{wrsPstatsRXDropRTUFull}
      \item \texttt{wrsPstatsRXPrio0}
      \item \texttt{wrsPstatsRXPrio1}
      \item \texttt{wrsPstatsRXPrio2}
      \item \texttt{wrsPstatsRXPrio3}
      \item \texttt{wrsPstatsRXPrio4}
      \item \texttt{wrsPstatsRXPrio5}
      \item \texttt{wrsPstatsRXPrio6}
      \item \texttt{wrsPstatsRXPrio7}
      \item \texttt{wrsPstatsRTUValid}
      \item \texttt{wrsPstatsRTUResponses}
      \item \texttt{wrsPstatsRTUDropped}
      \item \texttt{wrsPstatsFastMatchPriority}
      \item \texttt{wrsPstatsFastMatchFastForward}
      \item \texttt{wrsPstatsFastMatchNonForward}
      \item \texttt{wrsPstatsFastMatchRespValid}
      \item \texttt{wrsPstatsFullMatchRespValid}
      \item \texttt{wrsPstatsForwarded}
      \item \texttt{wrsPstatsTRURespValid}
    \end{itemize}

  \item \texttt{wrsPtpDataTable} -- Table with a row per PTP servo instance.
    \begin{itemize}
      \item \texttt{wrsPtpIndex}
      \item \texttt{wrsPtpPortName} -- On which port instance is running.
      \item \texttt{wrsPtpGrandmasterID} -- Not implemented.
      \item \texttt{wrsPtpOwnID} -- Not implemented.
      \item \texttt{wrsPtpMode}
      \item \texttt{wrsPtpServoState}
      \item \texttt{wrsPtpServoStateN}
      \item \texttt{wrsPtpPhaseTracking}
      \item \texttt{wrsPtpSyncSource}
      \item \texttt{wrsPtpClockOffsetPs}
      \item \texttt{wrsPtpClockOffsetPsHR}
      \item \texttt{wrsPtpSkew}
      \item \texttt{wrsPtpRTT}
      \item \texttt{wrsPtpLinkLength}
      \item \texttt{wrsPtpServoUpdates}
      \item \texttt{wrsPtpDeltaTxM}
      \item \texttt{wrsPtpDeltaRxM}
      \item \texttt{wrsPtpDeltaTxS}
      \item \texttt{wrsPtpDeltaRxS}
      \item \texttt{wrsPtpServoStateErrCnt} -- Number of servo updates when
	    servo was out of TRACK\_PHASE (issue
	    \ref{fail:timing:ppsi_track_phase}).
      \item \texttt{wrsPtpClockOffsetErrCnt} -- Number of servo updates when
	    offset was bigger than 1000ps or smaller than -1000ps (issue
	    \ref{fail:timing:offset_jump}).
      \item \texttt{wrsPtpRTTErrCnt} -- number of servo updates when RTT delta
	    between servo updates was bigger than 1000ps or smaller than
	    -1000ps (issue \ref{fail:timing:rtt_jump}).
    \end{itemize}

  \item \texttt{wrsPortStatusTable} -- Table with a row per port.
    \begin{itemize}
      \item \texttt{wrsPortStatusIndex}
      \item \texttt{wrsPortStatusPortName}
      \item \texttt{wrsPortStatusLink}
      \item \texttt{wrsPortStatusConfiguredMode}
      \item \texttt{wrsPortStatusLocked}
      \item \texttt{wrsPortStatusPeer}
      \item \texttt{wrsPortStatusSfpVN}
      \item \texttt{wrsPortStatusSfpPN}
      \item \texttt{wrsPortStatusSfpVS}
      \item \texttt{wrsPortStatusSfpInDB}
      \item \texttt{wrsPortStatusSfpGbE}
      \item \texttt{wrsPortStatusSfpError}
      \item \texttt{wrsPortStatusPtpTxFrames}
      \item \texttt{wrsPortStatusPtpRxFrames}
    \end{itemize}


\end{itemize}

%%%%%%%%%%%%%%%%%%5
%% Other notes
%
% What else should be reported in the future
% Status of Primary Slave port and backup links
% For backup timing links, report parameters from Backup SPLL channels and PTP servo
% What can be reported regarding eRSTP ?
% %	role of the bridge - root/designated
% % port role - root/designated/backup/alternate/disabled
% % number of exchanged BPDUs
%
% * we could use information from RSTP to visualize the topology of network made of switches
% * switches exchange BPDU messages to leard about other switches
% * RFC 2674 - Bridges with priority, multicast pruning and VLAN
