Merge greg-failures branch into master

Improve doc/wrs_failures document.

Signed-off-by: Adam Wujek <adam.wujek@cern.ch>

doc/wrs_failures/Makefile

@@ -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

+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/intro.tex

 \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/wrs_failures.tex

@@ -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}