Skip to content

W
White Rabbit Switch - Software
Commit f7aea4ee authored by Adam Wujek's avatar Adam Wujek 💬
Browse files
Options

Merge greg-failures branch into master 

Improve doc/wrs_failures document.
Signed-off-by: Adam Wujek's avatarAdam Wujek <adam.wujek@cern.ch>
parents dea09a23 065bef73
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 1492 additions and 769 deletions
doc/wrs_failures/Makefile
View file @ f7aea4ee
......@@ -4,10 +4,14 @@ all : wrs_failures.pdf
RELEASE = $(shell git describe --always --dirty)
wrs_failures.pdf : wrs_failures.tex fail.tex intro.tex snmp_exports.tex
wrs_failures.pdf : wrs_failures.tex fail.tex intro.tex snmp_exports.tex snmp_objects.tex
@echo '\\newcommand{\\gitrevinfo}{'$(RELEASE)'}' > revinfo.tex
pdflatex wrs_failures.tex
pdflatex wrs_failures.tex
# To speed up generation of document for development, please comment out:
# % print alphabetical list
# \printnoidxglossary[type=snmp_all,style=tree,sort=letter]
# from doc/wrs_failures/snmp_exports.tex file.
clean :
rm -f *.eps *.dat *.log *.out *.aux *.dvi *.ps *.toc *.pdf revinfo.tex
......
doc/wrs_failures/diamon_example.tex 0 → 100644
View file @ f7aea4ee
This section presents an example how a problem could be diagnosed and
appropriate procedure applied by the operator of a WR Switch based on the
general status objects described in section \ref{sec:snmp_exports:basic}. The
screenshots included in this example were made from \emph{Diamon} tool used at
CERN for diagnostics. Any other SNMP manager (like \emph{Nagios} or
\emph{Icinga}) can be used to fetch the value of these status objects.
\begin{enumerate}
\item Operator gets an e-mail/sms alarm or notices in the SNMP manager that
the status of a WR switch has changed to \texttt{Error}
(fig.\ref{fig:diamon:wrs_error})
\item By checking the general status objects
(\texttt{glshyperlink{WR-SWITCH-MIB::wrsOSStatus}},
\texttt{\glshyperlink{WR-SWITCH-MIB::wrsTimingStatus}},
\texttt{\glshyperlink{WR-SWITCH-MIB::wrsNetworkingStatus}}) one can realize
that the problem is reported by the synchronization subsystem. The value of
\texttt{\glshyperlink{WR-SWITCH-MIB::wrsTimingStatus}} is \emph{2}= error
(fig.\ref{fig:diamon:wrs_sync_error}).
\item Following the tree structure of status objects from figure
\ref{fig:snmp_oper}, if
\texttt{\glshyperlink{WR-SWITCH-MIB::wrsTimingStatus}} reports an error,
then status objects: \texttt{\glshyperlink{WR-SWITCH-MIB::wrsPTPStatus}},
\texttt{\glshyperlink{WR-SWITCH-MIB::wrsSoftPLLStatus}},\\
\texttt{\glshyperlink{WR-SWITCH-MIB::wrsSlaveLinksStatus}},
\texttt{\glshyperlink{WR-SWITCH-MIB::wrsPTPFramesFlowing}} should be
checked. In this example
\texttt{\glshyperlink{WR-SWITCH-MIB::wrsSlaveLinksStatus}} reports an error
(fig.\ref{fig:diamon:slave_link_error}).
\item The operator should search section \ref{sec:snmp_exports:basic} for
procedure to follow when
\texttt{\glshyperlink{WR-SWITCH-MIB::wrsSlaveLinksStatus}} reports an error.
\item In this example, the WR Switch that reports a problem works in the
Boundary Clock mode, which means that the first step according to the
procedure should be checking a fiber connection on the slave port.
\item Plugging the fiber to the slave port fixes the problem and WR Switch
does not report more errors (fig.\ref{fig:diamon:wrs_ok}).
\end{enumerate}
\begin{figure}
\begin{center}
\includegraphics[width=.9\textwidth]{img/wrs_error.png}
\caption{SNMP manager reports an error on a WR Switch}
\label{fig:diamon:wrs_error}
\end{center}
\end{figure}
\begin{figure}
\begin{center}
\includegraphics[width=.9\textwidth]{img/wrs_sync_error.png}
\caption{WR Switch has problem with the synchronization subsystem}
\label{fig:diamon:wrs_sync_error}
\end{center}
\end{figure}
\begin{figure}
\begin{center}
\includegraphics[width=.9\textwidth]{img/wrs_link_error.png}
\caption{\texttt{wrsSlaveLinksStatus} object reports an error}
\label{fig:diamon:slave_link_error}
\end{center}
\end{figure}
\begin{figure}
\begin{center}
\includegraphics[width=.9\textwidth]{img/wrs_ok.png}
\caption{WR Switch does not report any errors}
\label{fig:diamon:wrs_ok}
\end{center}
\end{figure}
doc/wrs_failures/fail.tex
View file @ f7aea4ee
This diff is collapsed.
doc/wrs_failures/intro.tex
View file @ f7aea4ee
\section{Introduction}
This document tries to list all possible ways the White Rabbit Switch can
break and describes the information exported from our device to help diagnose
the problems.
This document provides information about the diagnostics of White Rabbit
switches. It is a complementary documentation to the official \emph{White Rabbit
Switch: User's Manual} published with every stable firmware release. Please
refer to this user manual for a basic information about the switch and
guidelines on its configuration.\\
The document is organized in two parts. First one (section \ref{sec:failures})
tries to list all the possible failures that may disturb synchronization and
Ethernet switching. The structure of each failure description is the following:
\begin{itemize}[leftmargin=0pt]
\item [] \underline{Mode}: for timing failures, it says which modes are
affected. Possible values are:
\begin{itemize}
\item \emph{Slave} - WR Switch has at least one Slave port synchronized to
another WR device higher in the timing hierarchy (though it may be also
Master to other WR/PTP devices lower in the timing hierarchy).
\item \emph{Grand Master} - WR Switch at the top of the synchronization
hierarchy. It is synchronized to an external clock (e.g. GPSDO, Cesium)
and provides timing to other WR/PTP devices.
\item \emph{Free-Running Master} - WR Switch at the top of the
synchronization hierarchy. It provides timing to other WR/PTP devices
but runs from a local oscillator (not synchronized to external atomic
clock).
\end{itemize}
White Rabbit Switch firmware starting from \emph{v4.2} provides diagnostic
mechanisms in the form of SNMP objects and Syslog messages. This document is
organized in two parts. It starts with a description of the SNMP objects and
procedures to be followed if various errors are reported (section
\ref{sec:snmp_exports}). This first part is meant for the operators and people
integrating a WR switch into a control system, without the deep knowledge about
the White Rabbit internals. These people usually have to perform a quick
diagnostics and decide on actions to restore a WR network.
Second part of the document tries to list all the possible failures
that may disturb synchronization and Ethernet switching (section
\ref{sec:failures}). It is meant for the WR experts to help them with in-depth
diagnosis of the problems reported by SNMP.
\item [] \underline{Description}: What the problem is about, how important it
is and what bad may happen if it occurs.
\item [] \underline{SNMP objects}: Which SNMP objects should be monitored to
detect the failure. These may be objects from \texttt{WR-SWITCH-MIB} or one
of the standard MIBs used by the \emph{net-snmp}.
\item [] \underline{Notes}: Optional comment for SNMP implementation. It may describe current
implementation of ideas how to implement it in the future
\end{itemize}
Section \ref{sec:snmp_exports} is a documentation for people integrating WR
switch into a control system, operators and WR experts. It describes all
essential SNMP objects exported by the device divided into two groups:
\emph{Operator/basic objects}, \emph{Expert objects}
This document has many internal hyperlinks that associate general SNMP status
objects and expert SNMP objects with related problems' description and the other
way round. These links can be easily used when reading the document on a
computer.
doc/wrs_failures/snmp_exports.tex
View file @ f7aea4ee
This diff is collapsed.
doc/wrs_failures/snmp_objects.tex 0 → 100644
View file @ f7aea4ee
This diff is collapsed.
doc/wrs_failures/wrs_failures.tex
View file @ f7aea4ee
......@@ -12,6 +12,7 @@
\usepackage[latin1]{inputenc}
\usepackage{verbatim}
\usepackage{amsmath}
\usepackage{textcomp}
\usepackage{times,mathptmx}
\usepackage{chngcntr}
\usepackage{hyperref}
......@@ -22,17 +23,20 @@
\definecolor{light-gray}{gray}{0.95}
%\usepackage[firstpage]{draftwatermark}
% for glossary
% nopostdot - no dot at the end of index entires
\usepackage[nogroupskip,nopostdot,counter=subsubsection]{glossaries}
\renewcommand{\glossarysection}[2][]{}
\usepackage{listings}
\usepackage{cancel}
\graphicspath{ {../../../../figures/} }
\newenvironment{packed_enum}{
\begin{itemize}[leftmargin=0pt,topsep=-12pt]
\begin{enumerate}[leftmargin=0pt,topsep=-12pt]
\setlength{\itemsep}{1pt}
\setlength{\parskip}{0pt}
\setlength{\parsep}{0pt}
}{\end{itemize}}
}{\end{enumerate}}
\newenvironment{packed_items}{
\begin{itemize}[topsep=-12pt]
......@@ -41,6 +45,20 @@
\setlength{\parsep}{0pt}
}{\end{itemize}}
\newenvironment{pck_descr}{
\begin{itemize}[leftmargin=0pt,topsep=-12pt]
\setlength{\itemsep}{1pt}
\setlength{\parskip}{0pt}
\setlength{\parsep}{0pt}
}{\end{itemize}}
\newenvironment{pck_proc}{
\begin{enumerate}[topsep=2pt]
\setlength{\itemsep}{1pt}
\setlength{\parskip}{0pt}
\setlength{\parsep}{0pt}
}{\end{enumerate}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% creating subsubsubsection notation
......@@ -71,6 +89,146 @@
\newcommand{\eqdelay}[1]{{\text{delay}}_{#1}}
\newcommand{\eqasymm}{{\text{asymmetry}}}
% for glossary, set way of sorting entries
\makenoidxglossaries
% don't bold entries, texttt them
\renewcommand*{\glsnamefont}[1]{\texttt{\textmd{#1}}}
\newglossary*{snmp_status}{SNMP's status objects}
\newglossary*{snmp_expert}{SNMP's expert objects}
\newglossary*{snmp_other}{Objects from other MIBs}
% alphabetical list of all entries
\newglossary*{snmp_all}{All SNMP objects}
\defglsentryfmt[snmp_status]{\texttt{\glsentryfmt}}
\defglsentryfmt[snmp_expert]{\texttt{\glsentryfmt}}
\defglsentryfmt[snmp_other]{\texttt{\glsentryfmt}}
% macro to add entires
\newcommand{\snmpadd}[1]{
\glspl{#1}\glsadd{x#1}%
}
% helpers to add glossary entries
% add newline to non empty strings. For descriptions.
\newcommand{\descr}[1]{
\ifx&#1&%
%
\else% put fixed space
\\#1
\fi
}
% {MIB}{parent}{object}{comment}{glossary_name}
\newcommand{\snmpentry}[5]{%
\ifx&#2&% if parameter 2 is empty don't add parent
\newglossaryentry{#1::#3}{%
type=#5,%
name={#3},%
plural={#1::#3},% used to display name not plural
user1={#1},% MIB
description={\descr{#4}}%
}%
\else
\newglossaryentry{#1::#3}{%
type=#5,%
name={#3},%
description={\descr{#4}},%
plural={#1::#3},% used to display name not plural
user1={#1},% MIB
parent={#1::#2}%
}%
\fi
% add entry to alphabetical list
\newglossaryentry{x#1::#3}{%
type=snmp_all,%
name={#1::#3},%
description={}
}%
}
% {MIB}{parent}{object}{comment}
\newcommand{\snmpentrye}[4]{%
\snmpentry{#1}{#2}{#3}{#4}{snmp_expert}
}
% {MIB}{parent}{object}{comment}
\newcommand{\snmpentrys}[4]{%
\snmpentry{#1}{#2}{#3}{#4}{snmp_status}
}
% command to add snmp objects from other MIBs
% {MIB}{parent}{object}{comment}
\newcommand{\snmpentryo}[4]{%
\snmpentry{#1}{#2}{#3}{#4}{snmp_other}
}
% extra indent for lists
\newlength{\paraaindent}
% indent for new paragraphs
\newlength{\snmpentryindent}
% load glossary definitions from snmp_objects.tex
\loadglsentries{snmp_objects}
% use \kern 0.33em instead of \space to have fixed width space
\newglossarystyle{objtree}{%
\renewenvironment{theglossary}%
{\setlength{\parindent}{0pt}%
\setlength{\parskip}{0pt plus 0.3pt}}%
{}%
\renewcommand*{\glossaryheader}{}%
\renewcommand*{\glsgroupheading}[1]{}%
\renewcommand{\glossentry}[2]{%
\hangindent30pt\relax
% save indent for other paragraphs
\setlength{\snmpentryindent}{\hangindent}
\parindent0pt\relax
% set indent for lists entries
\setlength{\paraaindent}{\hangindent}
\addtolength{\paraaindent}{14pt}
\setlist[enumerate]{leftmargin=\paraaindent}
$\bullet$\kern 0.33em\glsentryitem{##1}\glstreenamefmt{\glstarget{##1}{\texttt{\textmd{\glsentryuseri{##1}}::}\glossentryname{##1}}}%
\ifglshassymbol{##1}{\kern 0.33em(\glossentrysymbol{##1})}{}%
\glossentrydesc{##1}\glspostdescription\kern 0.33em##2\par\vspace{12pt}
}%
\renewcommand{\subglossentry}[3]{%
\hangindent##1\glstreeindent\relax
\addtolength{\hangindent}{30pt}
% save indent for other paragraphs
\setlength{\snmpentryindent}{\hangindent}
\parindent##1\glstreeindent\relax
% set indent for lists entries
\setlength{\paraaindent}{\hangindent}
\addtolength{\paraaindent}{14pt}
\setlist[enumerate]{leftmargin=\paraaindent}
\ifnum##1=1\relax
$\circ$%
\fi
\ifnum##1=2\relax
$\ast$%
\fi
\kern 0.33em%
\ifnum##1=1\relax
\glssubentryitem{##2}%
\fi
\glstreenamefmt{\glstarget{##2}{\glossentryname{##2}}}%
\ifglshassymbol{##2}{\kern 0.33em(\glossentrysymbol{##2})}{}%
\glossentrydesc{##2}\glspostdescription\kern 0.33em##3\par\vspace{12pt}
}%
%redefine \glspar to support indentation in many paragraphs
\renewcommand{\glspar}{%
\par
\parindent\snmpentryindent % restore first line in paragraph indent
\hangindent\snmpentryindent % restore other lines in paragraph indent
}%
}
\newcommand{\ignore}[1]{}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}
\setcounter{tocdepth}{2}
\input{revinfo.tex}
......@@ -96,18 +254,31 @@
\newpage
\input{intro.tex}
\newpage
\input{snmp_exports.tex}
\newpage
\section{Possible Errors}
\label{sec:failures}
\input{fail.tex}
\appendix
\newpage
\input{snmp_exports.tex}
%\section{SNMP exports}
%\subsection{Operator/basic objects}
%\subsection{Expert objects}
\section{Operator's diagnostic example}
\input{diamon_example.tex}
\newpage
\section{Sorted list of all MIB objects}
\label{sec:snmp_exports:sorted}
% print alphabetical list
\printnoidxglossary[type=snmp_all,style=tree,sort=letter]
%\newpage
%\bibliographystyle{unsrt}
%\bibliography{references}
% add not used entries, but don't display their's section
% based on:
% http://tex.stackexchange.com/questions/115635/glossaries-suppress-pages-when-using-glsaddall
\forallglsentries{\thislabel}%
{%
\ifglsused{\thislabel}{}{\glsadd[format=ignore]{\thislabel}}%
}
\end{document}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment