wrs-user-manual.in

\input texinfo    @c -*-texinfo-*-
%
% wrs-user-manual.in - main file for the documentation
%
%%%%

%------------------------------------------------------------------------------
%
%                         NOTE FOR THE UNAWARE USER
%                         =========================
%
%    This file is a texinfo source. It isn't the binary file of some strange
%    editor of mine. If you want ASCII, you should "make wrs-user-manual.txt".
%
%------------------------------------------------------------------------------

%
% This is not a conventional info file...
% I use three extra features:
%   - The '%' as a comment marker, if at beginning of line ("\%" -> "%")
%   - leading blanks are allowed (this is something I cannot live without)
%   - braces are automatically escaped when they appear in example blocks
%

@comment %**start of header
@documentlanguage en
@documentencoding ISO-8859-1
@setfilename wrs-user-manual.info
@settitle wrs-user-manual
@iftex
@afourpaper
@end iftex
@paragraphindent none
@comment %**end of header

@setchapternewpage off

@set update-month January 2015
@c the release name below is substituted at build time
@set release __RELEASE_GIT_ID__

@finalout

@titlepage
@title White Rabbit Switch: User's Manual
@subtitle Information about configuring the White Rabbit switch, for final users
@subtitle @value{update-month} (@value{release})
@author Alessandro Rubini, Benoit Rat, Federico Vaga et al.
@end titlepage
@headings single

@c ##########################################################################
@iftex
@contents
@end iftex

@c ##########################################################################
@c in texinfo we are mandated to have a Top node
@node Top
@top Introduction

The White Rabbit switch (or @sc{wrs}) is a major component of the
White Rabbit (@sc{wr}) network.  Like any modern managed switch, the
@sc{wrs} includes a CPU with its own operating system.

This manual is for people installing @sc{wrs} devices, who need to
configure them in their network.

@c ##########################################################################
@node WRS Documentation
@chapter WRS Documentation

Up to and including release 4.0 of @sc{wrs} software this manual
didn't exist, and the ``WRS Build Manual'' included some information
about configuration.

@c ==========================================================================
@node The Official Manuals
@section The Official Manuals

This is the current set of manuals that accompany the @sc{wrs}:

@itemize @bullet

@item @i{White Rabbit Switch: Startup Guide}: hardware installation
   instructions. This manual is provided by the manufacturer: it describes
   handling measures, the external connectors, hardware features and the
   initial bring-up of the device.

@item @i{White Rabbit Switch: User's Manual}: documentation about
   configuring the @sc{wrs}, at software level.  This guide is maintained
   by software developers.  The manual describes
   configuration in a deployed network, either as a standalone device or
   as network-booted equipment.  The guide also describes how to upgrade
   the switch, because we'll release new official firmware images over
   time, as new features are implemented.

@item @i{White Rabbit Switch: Developer's Manual}: it describes the
   build procedure and how internals work; use of scripts and
   @sc{wrs}-specific executables and so on.  The manual is by developers
   and for developers.  This is the
   document to check if you need to customize your @i{wrs} rebuild
   software from new repository commits that are not an official release
   point, or just install your @i{wrs} with custom configuration values.

@item @i{White Rabbit Switch: Failures and Diagnostics}: describe various
   failure scenarios of a switch and ways how to recognize them.
   Additionally describe SNMP exports of a switch (WR-SWITCH-MIB).

@end itemize

The official @sc{pdf} copy of these manuals at each release
is published in the @i{files} tab of the software project in @t{ohwr.org}:
(@url{http://www.ohwr.org/projects/wr-switch-sw/files}).
This doesn't apply to release 4.0 and earlier.

The source form of first three manuals is maintained in
@t{wr-switch-sw/doc}. Within the repository, both the @i{User's
Manual} and the @i{Developer's Manual} are always tracking the
software commits, while the @i{Startup Guide} may not be authoritative
because it is bound to device shipping rather than software
development.

The source of fourth document @i{White Rabbit Switch: Failures and Diagnostics} is in
external repository @url{git://ohwr.org/white-rabbit.git} under
@t{docs/specifications/management}.

@c ==========================================================================
@node Supported Hardware Versions
@section Supported Hardware Versions

This document applies to versions 3.3 and 3.4 of the @sc{wrs}
device.

Very few specimens of @t{wrs} 3.0 though 3.2 were manufactured; if you
are the owner of one of them, please refer to version 3.3 of the
@i{wrs-build} document, that includes appendixes about using older
versions. As usual, it is in the @i{files} tab of @t{ohwr.org}.

V1 and V2 were development items, never shipped.


@c ##########################################################################
@node Upgrading WRS Software
@chapter Upgrading WRS Software

The @sc{wrs} is shipped with a current version of its software image,
which is sometiems called @i{firmware}.
If your devices are running a previous version of the software you may
want to upgrade, or you may want to replace the firmware images after
rebuilding your own, as explained in the @i{Developer's Manual}.

If you run version 4.1 or later, you can ignore this chapter, that
explains a transition between the initial way we passed MAC addresses
and the safer approach we introduced in v4.1

@c ==========================================================================
@node hwinfo
@section hwinfo

Version 4.1 (October 2014) and later ones use a new way to pass
hardware information to all levels of software, such information
includes the MAC addresses for the management Ethernet and the
@sc{sfp} ports.  Information is now stored in a Flash partition called
@i{hwinfo}, using the @sc{sdb} file format. @sc{sdb} is defined in the
@t{fpga-configuration-space} within @t{ohwr.org}.  Before using
@sc{sdb} we used to edit the boot loader's configuration at flash
time, a bad practice developed in a hurry.

The @i{hwinfo} structure is now written to @i{dataflash} by the
manufacturer, and never changed even when perforiming a complete re-flash
of the device, because the flashing scripts preserve the @i{hwinfo}
memory area.

When upgrading from a pre-4.1 switch software, you need to create this
@i{hwinfo} data structure. This procedure is mostly automatic, but you
need to be aware of the steps involved, in case something goes wrong.

@c ==========================================================================
@node Upgrading from v4.0
@section Upgrading from v4.0

Version 4.0 and later of @t{wr-switch-sw} are able to upgrade
themselves if you place the profer files in the @i{/update} directory
of the @sc{wrs}.  However, in version 4.0 we forgot to provide for
an upgrade of the boot loader and didn't note that if the front USB
cable is not plugged, the upgrade procedure blocks.

This latter problem happens because messages are written to the
management USB port, to help people flashing from scratch, and the
write is a blocking one by default: if nobody collects the USB data,
the system waits for a recipient. With version 4.1.1 we fixed the
problem, using non-blocking operations; we'd better loose messages
than block installation because nobody is reading.

Thus, there are two different ways to upgrade; which one
you prefer we can't tell. Both work, each with its own drawbacks.
Each of them preserves the current MAC addresses.

@c =-------------------------------------------------------------------------
@node Upgrading from v4.0 with the USB cable
@subsection Upgrading from v4.0 with the USB cable

This is the procedure if you are able to walk to your @sc{wrs} and
connect to the management USB port, even if the port is not
actually used:

@itemize @bullet

   @item Copy your own @t{wrs-firmware.tar} for at least v4.1 into the
   @i{/update} partition.
   This can be the official firwmare or one you built yourself.
   Then reboot and wait for everything to settle (the system will reboot
   once more by itself).

   @item Copy @t{wrs-firmware.tar} again. And reboot again. The system
   will reboot once more by itself.

   @item Now you have a running updated version with your @i{hwinfo} in place
   and the old MAC addresses preserved.

@end itemize

We save you from the long description of what is happening in the
various steps. If needed, it is in the @i{git} history of @t{wr-switch-sw},
at release point @t{v4.1}.


@c =-------------------------------------------------------------------------
@node Upgrading from v4.0 remotely
@subsection Upgrading from v4.0 remotely

If you can't walk to the switch, the procedure is faster but more
commands need to be typed on the root shell of the switch.  We
support a single upgrade provided you change the kernel and initial
filesystem before rebooting.

@itemize

   @item Copy your own @t{wrs-firmware.tar} for at least v4.1 into the
   @i{/update} partition. This can be the official firwmare or one you built
   yourself.

   @item Create and mount @i{/boot} within the switch. This means
   running the following commands in @i{ssh}:

      @t{mkdir /boot}

      @t{mount -t ubifs ubi0:boot /boot}

   @item Copy @t{wrs-initramfs.gz} (which is to be found inside
   @t{wrs-firmware.tar}) to the @i{/boot} partition just mounted.  This
   ensures the new upgrade procedure will run, the one that doesn't block
   if the USB cable is unplugged.

   @item Copy @t{zImage} (again, to be found inside
   @t{wrs-firmware.tar}) to the @i{/boot} partition.  This is need to
   be able to access the @i{hwinfo} partition at next boot.

   @item Reboot and wait for everything to settle (the system will reboot
   once more by itself after upgrading everything).  The MAC addresses
   will be saved to @i{hwinfo} during the update procedure, thanks to
   the new kernel and new boot procedure you manually  copied to @i{/boot}.

@end itemize

@b{Note:} if you forget to place the new kernel or @t{wrs-initramfs.gz}
in @i{/boot}, no big damage will happen, but you'll have lost your
MAC address for the @sc{wr} ports.  You'll find a randomly-chosen value,
that will however be persistent over reboot (because it is saved to
@i{hwinfo} after you boot with the new kernel.

@c ==========================================================================
@node Upgrading from v3.x
@section Upgrading from v3.x

Upgrading from versions older than 4.0 (August 2014) requires physical
access to the device and, unfortunately, requires some extra steps
especially if you want to preserve your MAC addresses.

One possible path is flashing version 4.0 (please refer to v4.0
manuals) and then proceed as described in @ref{Upgrading from v4.0}.
When flashing version 4.0 you'll need to pass your MAC addresses on
the command line of the flasher, so please take not of what they are.

Another option is flashing the latest firwmare version and then build
your own @i{hwinfo} structure by specifying your MAC addresses.
@t{wr-switch-sw} includes specific tools for both steps. They are
described in the @i{Developer's Manual}, because they are expected to
only be performed by the manufacturer, not the final user.


@c ##########################################################################
@node Configuration of the Device
@chapter Configuration of the Device

After release 3.3 of this software package, we added Kconfig support
to wr-switch-sw.  If you build your software image (as documented
in the @i{@sc{wrs} Developer's Manual}),  you can make some
configuration choices for your customized firmware image.  But most
users are not expected to rebuild.

After release 4.1, we moved most of the configuration to run-time
(rather than build-time): the @t{.config} file that you create
with a ``@t{make menuconfig}'' or equivalent command, is now copied
to the @sc{wrs} filesystem and used during boot.  Moreover, the
switch can download a new configuration at boot time, if so
configured. This allows customization of each installed switch
through a central server, without modifying the filesystem image in
each specimen.

@c ==========================================================================
@node Dynamic WRS Configuration
@section Dynamic WRS Configuration

The switch can boot using its internal @sc{nand} memory or as an NFS-Root
host. In the latter case configuration can be changed on the server,
and if a unit is replaced, a change in the @sc{dhcp} database is all
that's needed to recover network operation.  But this option implies
some network traffic on your management network, as well as an NFS
server able to host all of your switches.

When a switch is booted from internal storage, we used to rely on
internal configuration (either selected at build time or modified
using @i{ssh} or the web interface).  This approach doesn't scale
well to large installation, because if a device needs to be replaced,
its own configuration is lost.

With @i{dynamic configuration}, each @sc{wrs} device loads its own
configuration file each time it is booted, and applies the choices
before starting any service.  The name of the configuration file can
include the @sc{mac} or @sc{ip} address of the device, to allow
running several switches with different configurations in the same
network.

@c ==========================================================================
@node The Configuration File
@section The Configuration File

The main configuration file for the @sc{wrs} is
@t{/wr/etc/dot-config}.  You create this file by running ``@t{make
menuconfig}'' within @t{wr-switch-sw}, and making your choices.
You can also edit the text file, or run other configurators: @t{make xconfig},
@t{make gconfig}, @t{make config}.

The configuration step creates @t{.config}, that you can copy to your
@sc{wrs} as @t{/wr/etc/dot-config}. After reboot, you'll see your
choices in effect.

The first configuration choice is @t{CONFIG_DOTCONF_URL}.  If the
selected string is not empty, the Switch will download a new @t{dot-config}
file, and replace the copy in local storage if it is different. If
the string is empty, no network access is performed.

@t{CONFIG_DOTCONF_URL} is of the form
``@i{protocol}@t{://}@i{host}@t{/}@i{pathname}''.  The special upper-case
strings @t{IPADDR} and @t{MACADDR} are substituted with the current
addresses of the management port of the switch.

The three parts of the URL are as follows:

@table @i

@item protocol

	We support @t{http}, @t{ftp} and @t{tftp}.  Any other protocols
        result in an error, and the @t{dot-config} file is not replaced.

@item host

	The host can be an IP address, or a name. In order to use
        a name you must specify a valid @t{CONFIG_DNS_SERVER} and
        optionally @t{CONFIG_DNS_DOMAIN}.  The values
        in the current @t{dot-config} are used to load the new file.

@item path

	The pathname can include directory components and @t{IPADDR}
        or @t{MACADDR} (or both).

@end table

For example this is a valid configuration for run-time update:

@smallexample
   CONFIG_DOTCONF_URL="tftp://morgana/wrs-config-IPADDR"
   CONFIG_DNS_SERVER="192.168.16.1"
   CONFIG_DNS_DOMAIN="i.gnudd.com"
@end smallexample

And it results, in my case, in @t{wrs-config-192.168.16.9} being
served to the @sc{wrs}.

Please remember that the new @t{dot-config} should include a valid
@t{DOTCONF_URL} setting, or you won't be able to update the configuration
at the next boot. In any case, you can always copy a configuration
file using @i{ssh}, or use the web interface to change the configuration.
Changes performed using the web interface are immediately active, because
the web server takes proper action; the new file copied over with @i{ssh},
or any hand-edits, are only effective at next boot, unless overwritten by
a remote configuration file.
In case there are errors or unknown configuration entries in the retrieved
file, the old one will be used.

@c ==========================================================================
@node Configuration Items that Apply at Build Time
@section Configuration Items that Apply at Build Time

The following items in @t{dot-config} are used at build time; changing
them in the installed version has no effect:

@table @code

@item CONFIG_BR2_CONFIGFILE

	This string option lists a file to be used as Buildroot (BR2)
        configuration. A simple filename or relative pathname refers to the 
        @t{configs/buildroot} directory; an absolute pathname is used
        unchanged.

@item CONFIG_KEEP_ROOTFS

	A boolean option for developers: if set the build script does
        not delete the temporary copy of the generated filesystem and
        reports its pathname in the build messages.

@end table

@c ==========================================================================
@node Configuration Items that Apply at Run Time
@section Configuration Items that Apply at Run Time

The following items in @t{dot-config} are used at run time: at every
boot the value (the old one or the just-downloaded one) is used in the
appropriate way, before the respective service is started.  When the
value is changed by the web interface, proper action is taken.

@table @code

@item CONFIG_DOTCONF_URL

	The location of a config file to be used at a replacement
        the next time the system boots. See @ref{Dynamic WRS Configuration}
        and @ref{The Configuration File} for details.

@item CONFIG_ETH0_DHCP
@itemx CONFIG_ETH0_DHCP_ONCE
@itemx CONFIG_ETH0_STATIC

	Configuration of management port's (@t{eth0}) IP. When
	@t{CONFIG_ETH0_DHCP} is used, then switch tries to obtain IP via DHCP
	forever. For option @t{CONFIG_ETH0_DHCP_ONCE} switch tries to get IP
	via DHCP once, if this try is unsuccessful then switch uses static IP.
	@t{CONFIG_ETH0_STATIC} forces switch to use provided static IP address.

@item CONFIG_ETH0_IP
@itemx CONFIG_ETH0_MASK
@itemx CONFIG_ETH0_NETWORK
@itemx CONFIG_ETH0_BROADCAST
@itemx CONFIG_ETH0_GATEWAY

	Management port's (@t{eth0}) static IP configuration when
	@t{CONFIG_ETH0_DHCP_ONCE} or @t{CONFIG_ETH0_STATIC} parameter is used.

@item CONFIG_ROOT_PWD_IS_ENCRYPTED
@itemx CONFIG_ROOT_PWD_CLEAR
@itemx CONFIG_ROOT_PWD_CYPHER

	This set of options allow setting the password for the ``root''
        user (the administrator). The password is used to login to
        your switch using @t{ssh} (secure shell).  If you choose
        @t{CONFIG_ROOT_PWD_IS_ENCRYPTED}, you will be prompted for a
        text version of a pre-encrypted password (@t{CONFIG_ROOT_PWD_CYPHER}).
        To encrypt your @i{magic} string, you must run ``@t{mkpasswd
	--method=md5} @i{magic}'' on your Linux host (or switch).
        If you choose to configure an unencrypted password, then you are
        asked to specify it as @t{CONFIG_ROOT_PWD_CLEAR}. In this latter
        case encryption is performed at run-time to use the normal @i{ssh}
        authentication, but the clear-text password will remain in dot-config.
        By default the root password is an empty string, like in the initial
        @i{wr-switch-sw} releases.

@item CONFIG_NTP_SERVER

	The NTP server used to prime White Rabbit time, at system boot.
        The option can be an IP address or a host name, if DNS is properly
        configured.  The configuration value is stored in
        @t{/wr/etc/wr_date.conf}. An empty string (default) disables
        NTP access at boot time.

@item CONFIG_DNS_SERVER
@itemx CONFIG_DNS_DOMAIN

	The DNS server (as an IP address) and default domain. The values
        end up in @t{/etc/resolv.conf} of the generated filesystem.
        By default the two strings are empty.

@item CONFIG_REMOTE_SYSLOG_SERVER
@itemx CONFIG_REMOTE_SYSLOG_UDP

	Configuration for system log. The name (or IP address) of the
        server is stored in @t{/etc/rsyslog.conf} of the generated
        filesystem.  The UDP option, set by default, chooses UDP transmission;
        if unset it selects TCP communication.

@item CONFIG_WRS_LOG_HAL
@itemx CONFIG_WRS_LOG_RTU
@itemx CONFIG_WRS_LOG_PTP
@itemx CONFIG_WRS_LOG_WRSWATCHDOG

	Logging options for the three main WRS processes. Each value
        can be a pathname, to select logging to file (and @t{/dev/kmsg}
        is a possible ``file'' target) or a @i{facility}.@i{level} string,
        like @t{daemon.debug}, for syslog-based logging.
        An empty strings selects no logging at all.  Please note that
        unknown facility names will generate a runtime error on the switch.
        All four strings default to ``@t{daemon.info}''.

@item CONFIG_WRS_LOG_SNMPD

	Value can be a pathname, to select logging to file (and
        @t{/dev/kmsg} is a possible ``file'' target) or a valid snmpd log
        option (without -L).
        Allowed strings are in format ``@t{s} @i{facility}'' (e.g.
        ``@t{s daemon}'') and ``@t{s} @i{level} @i{facility}'' (e.g.
        ``@t{s 2 daemon}''). For example, ``@t{sd}'' or ``@t{s daemon}'' will forward
        messages to syslog with daemon as facility. To set level (i.e. 5) use
	``@t{S 5 daemon}''. For details please check ``man snmpcmd''. An empty
	strings selects no logging at all. Please note that unknown facility
	names will generate a runtime error on the switch.

@item CONFIG_WRS_LOG_MONIT
	The string can be a pathname (e.g. @t{/dev/kmsg}) or a @t{syslog}
	string.
	An empty string is used to represent no logging. If it is needed to
	select facility and level please leave here empty string and change
	@t{/etc/monitrc} file directly.
	Please note that unknown facility names will generate a runtime error
	on the switch.

@item CONFIG_PORT00_PARAMS
@itemx CONFIG_PORT01_PARAMS
@itemx ...
@itemx CONFIG_PORT17_PARAMS

	These configuration items are used to set up port parameters;
        this includes the delays, the PTP role, PTP protocol type
        and the fiber type as an integer index.  Most likely
        the default values work for you. See @ref{Timing Configuration}
        for details.

@item CONFIG_SFP00_PARAMS
@itemx ...
@itemx CONFIG_SFP09_PARAMS

	Configuration for @sc{sfp} models. You should fill values for
        all @sc{sfp} models you are using in your @sc{wrs} and all
        wavelengths you are using. See @ref{Timing Configuration}
        for details.

@item CONFIG_FIBER00_PARAMS
@itemx ...
@itemx CONFIG_FIBER03_PARAMS

	Configuration for fiber types. You are expected to have no more
        than 4 fiber types installed in your deployment (if more, you need
        to add items to the @i{dot-config} file).  See @ref{Timing
        Configuration} for details.

@item CONFIG_TIME_GM
@itemx CONFIG_TIME_FM
@itemx CONFIG_TIME_BC

	The type of PTP clock this switch is. Only one of the three
        items should be set (running ``@t{make menuconfig}'' offers
        them as an exclusive choice). The options select a grand-master
        with external reference, from GPS or Cesium or both; a free-running
        master, used for isolated acquisition networks, withouth an
        external reference; or a normal ``boundary-clock'' device that
        is slave on some ports and master on other ports.

@item CONFIG_PTP_PORT_PARAMS
@itemx CONFIG_PTP_CUSTOM

	By default, PPSi configuration file is assembled based on role and
        protocol parameters stored in @t{PORTxx_PARAMS}. @t{TIME_BC} selected
        by @i{Kconfig} defaults role of port @t{wr0} to slave, other ports
        to master. For @t{TIME_GM} and @t{TIME_FM} all ports are mandated to
        master.
        Parameters @t{clock-class} and @t{clock-accuracy} can be changed
        or new global PPSi settings can be added by editing file
        @t{/wr/etc/ppsi-pre.conf}, which is used as begging of final
        ppsi configuration file.

	Alternatively PPSi can use custom user file for configuration
        (@t{CONFIG_PTP_CUSTOM}).
        Please see the help provided within @i{Kconfig} for more details about
        the various options we support.

@item CONFIG_PTP_CUSTOM_FILENAME

	If you chose @t{CONFIG_PTP_CUSTOM} in the choice above, you
        can provide your own filename for the PPSi configuration file;
        the chosen name is expected to be installed in the @sc{wrs}
        filesystem.

@item CONFIG_SNMP_TRAPSINK_ADDRESS
@itemx CONFIG_SNMP_TRAP2SINK_ADDRESS
@itemx CONFIG_SNMP_RO_COMMUNITY
@itemx CONFIG_SNMP_RW_COMMUNITY

	Configuration for the @sc{snmp} agent. Addresses can be IP addresses
        or names (if DNS is configured and working), they are unset by
        default. Community values are strings and they default to
        @t{public} and @t{private}.

@item CONFIG_SNMP_TEMP_THOLD_FPGA
@itemx CONFIG_SNMP_TEMP_THOLD_PLL
@itemx CONFIG_SNMP_TEMP_THOLD_PSL
@itemx CONFIG_SNMP_TEMP_THOLD_PSR
	Threshold levels for FPGA, PLL, Power Supply Left (PSL) and Power
        Supply Right (PSR) temperature sensors. When any temperature exceeds
        threshold level SNMP object @t{WR-SWITCH-MIB::tempWarning} will change
        accordingly.

@item CONFIG_SNMP_SWCORESTATUS_HP_FRAME_RATE

	Error via SNMP if rate of HP frames on any port exceed given value.

@item CONFIG_SNMP_SWCORESTATUS_RX_FRAME_RATE

	Error via SNMP if rate of RX frames on any port exceed given value.

@item CONFIG_SNMP_SWCORESTATUS_RX_PRIO_FRAME_RATE

	Error if frame rate of any RX priority exceed given value.

@item CONFIG_WRSAUXCLK_FREQ
@itemx CONFIG_WRSAUXCLK_DUTY
@itemx CONFIG_WRSAUXCLK_CSHIFT
@itemx CONFIG_WRSAUXCLK_SIGDEL
@itemx CONFIG_WRSAUXCLK_PPSHIFT

	Set of parameters passed to @t{wrs_auxclk} at boot time.
        For more information please check @ref{wrs_auxclk}.

@item CONFIG_MONIT_DISABLE

	Disable monitoring of running processes by monit. Monit by default
        re-spawns processes that have died. This option is useful mostly during
        development.

@end table

@c ==========================================================================
@node Timing Configuration
@section Timing Configuration

This section describes how timing configuration works in the switch.
Please note that up to version 4.1 (included) of @t{wr-switch-sw} things
were different and not really documented.

Timing configuration now depends on three sets of @i{dot-config}
variables: per-port information, per-sfp information and fiber
description.

This is, for explanation's sake, an example of such items:

@smallexample
CONFIG_PORT09_PARAMS="name=wr9,proto=raw,tx=226214,rx=226758,role=slave,fiber=2"
CONFIG_SFP00_PARAMS="pn=AXGE-1254-0531,tx=0,rx=0,wl_txrx=1310+1490"
CONFIG_FIBER02_PARAMS="alpha_1310_1490=2.6787e-04"
@end smallexample

When making timing calculation for port @t{wr9}, assuming the
auto-detected @sc{sfp} model is``AXGE-1254-0531'', the software
uses configuration in the following way:

@itemize @bullet

@item The port has known tx and rx delays (around 226ns); the
values depend on trace length and other hardware-specific details
and are determined by a calibration procedure.  These values are
used as constant delays in the @i{tx} and @i{rx} directions.

@item The port is also configured as slave (@i{role}) using raw whiterabbit
prootocol (@i{proto}) and is deployed using fiber type 2 -- this number
is just a local enumeration of fiber types; most likely you'll be
using type ``0'' in every port.

@item The transceiver installed uses 1310nm light for tx
and 1490nm light for rx (this is part of the specification of the
transceiver, but cannot be auto-detected). Moreover it has 0 constant
delay in both tx and rx, determined by calibration.

@item The fiber type being used (type 2 here), when driven
with 1310nm and 1490nm wavelengths, features an @i{alpha} parameter of
0.00026787 (i.e. a ratio of 1.00026787) between the speed of light in
the two directions.  This value depends on both the fiber type and
wavelength, and is determined, again, by calibration.

@end itemize

Please note that only one alpha value is provided, because the
opposite one (@t{alpha_1490_1310}) is calculated by software.

@subheading SFP name matching

SFP matching is based on vendor name (@i{vn}), part number (@i{pn}) and vendor
serial (@i{vs}). While matching SFP's values are compared with values stored in
@t{CONFIG_SFPxx_PARAMS}.
First try is to match all SFP identifiers (@i{vn}, @i{pn} and @i{vs}) with
stored in config. If match is not successful, @i{vn} and @i{pn} of SFP are
compared only with config entries without vendor serial. If match is still not
found SFP's values are compared with config entries, which has defined only
part number. Such approach prevents matching SFPs to config entires with
defined serial.

Below are shown matching examples:
@smallexample
CONFIG_SFP00_PARAMS="vn=Axcen Photonics,pn=AXGE-3454-0531,vs=AX12390009629,tx=0,rx=0,..."
@end smallexample
Above config may be matched only to one SFP.
@smallexample
CONFIG_SFP01_PARAMS="vn=Axcen Photonics,pn=AXGE-3454-0531,tx=0,rx=0,wl_txrx=1310+1490"
@end smallexample
Above config may be matched only to SFP with vendor name "Axcen Photonics" and
part number "AXGE-3454-0531", with exception to these SFPs that were matched to
example like above (with vendor serial defined).
@smallexample
CONFIG_SFP02_PARAMS="pn=AXGE-3454-0531,tx=0,rx=0,wl_txrx=1310+1490"
@end smallexample
Config above will be matched to all SFPs with part number "AXGE-3454-0531",
that were not matched by configs above.

@subheading Other Deployments

The example above matches the choices we make at CERN, where our
White Rabbit networks are all run with a single monomodal fiber
and  1310/1490 light.

If you are using dual-fiber transceivers, which is acceptable for
short links, you use the same wavelength in both direction, over two
fibers of the same length. In this case you may choose to avoid
writing the @t{wl_txrx} parameter in @sc{sfp} configuration and the
@t{alpha_XX_XX} parameter in fiber configuration.  The missing
parameters will cause warning messages to log destination, but are not
fatal, and a default alpha of 0 is used.

If you are using a pair of transceivers with different wavelengths,
and long fibers, you should provide an appropriate value of alpha,
according to laboratory measures on your fiber type. The
@t{CONFIG_FIBERxx_PARAMS} items are parsed as a list of
comma-separated assignments, so you can specify and number of
wavelength pairs.  The accuracy of your value depends on the length
of the fiber link.  For a 10km fiber (100us round-trip) you need to know
alpha up to 1e-7 if you want the related uncertainty to be
less than 10ps.

@subheading Calibration

Calibration of per-port and per-@sc{sfp} delays is described in the
White Rabbit wiki:
@url{http://www.ohwr.org/projects/white-rabbit/wiki/Calibration}.  The
procedure can measure the total constant delays, but splitting between
the what depends on the port and what depends on the transceiver is
arbitrary (also, the split between the tx and rx paths is arbitrary).

The delays used in this example come from values listed in the above
web page, and you should not be surprised by the fact that the
transceiver specifies the delays as zero.  By performing the
calibration procedure using this very transceiver type, the hardware
engineers decided to assign the whole of the delay to the port (any
split of the measured value is equally right).  Other transceiver
types can be calibrated to either positive or negative values, to cope
with the @i{difference} between them and the @t{AXGE} devices.

@c ==========================================================================
@node Front panel's LEDs
@section Front panel's LEDs

There are two LEDs on front panel describing switch's status and two LEDs for
each switch's port. Each LED can be off, light with green or orange color, or
combination of both giving yellow.
For more details please refer to following subsections.

@c =-------------------------------------------------------------------------
@node Status LEDs
@subsection Status LEDs

The status LED is placed together with power indicator LED on the left side of
switch's front panel. The status LED is the right one.

During barebox/kernel boot the status LED is off. When startup-mb.sh starts
the LED is set to yellow. If the HAL starts successfully then the LED is set to
green. If the HAL caught a SIGNAL sent by other process, HAL sets the status
LED to orange.
When reboot is performed status LED is turned off.

@c =-------------------------------------------------------------------------
@node Ports' LEDs
@subsection Ports' LEDs

Under each switch's port there are two LEDs. The left LED is on when particular
port is populated with a SFP and the link is up. It's color is dependent on
the configured function. For ports configured as a slave the LED is green, for
non-wr ports the LED is orange. For ports configured as a master and other
cases (including wrong configuration) the left LED is yellow.

The right LED blinks when packet is transmitted or received on a port.

@c ############################################################################
@node Booting with Barebox
@chapter Booting with Barebox

After the initial installation, the boot loader offers an
interactive  menu, where the first entry is selected by default.
The menu is a simple ASCII interface on the serial port, and looks
like the following:

@example
   Welcome on WRSv3 Boot Sequence
       1: boot from nand (default)
       2: boot from TFTP script
       3: edit config
       4: exit to shell
       5: reboot
@end example

If flashing of the whole system was successful, the first entry will
simply work, booting the switch without any network access.  Although
a DCHP client runs by default after boot, everything will work even if
you leave the Ethernet port unconnected or you have no DHCP server
when the switch is operational.

If booting from NAND memory fails (for example because you erased the
kernel or incurred in other mishaps during development)
the menu is re-entered automatically.

The other entries are provided to help developers.

@c ==========================================================================
@node Description of the menus
@section Description of the menus

The individual menu items perform the following actions:
@table @code

@item 1: boot from nand (default)

	This entry is selected by default after 10 seconds of
        inactivity on the serial port. It boots the system from its
        own NAND memory. This ``just works''.

@item 2: boot from TFTP script

	This entry tries to download a @i{barebox} script from your TFTP
        server; if successful it then executes it. Developers are
        expected to customize the script to support any kind of environment,
        from customized kernel command-line to NFS-Root environments.
        See @ref{Using wrboot} for details.

@item 3: edit config

	This fires the editor on the configuration file, and
        saves it to flash when the user is done. This is useful to
        change the MAC address of the ARM network port. Please note
        that saving save the whole @file{/env} file tree, so you
        can also change the init scripts interactively and have them
        stored persistently on the flash. Users are not expected to
        change any configuration, though, as further updates may fail.

@item 4: exit to shell

	By choosing this entry, the user can access the shell-like
        interface of @i{barebox}. The entry is aimed at developers
        who know what they are going to type.

@item 5: reboot

	This entry is useful to see and log the exact boot messages.
        Since the serial-USB converter is @i{switch-powered} and not
        @i{USB-powered}, you won't be able to hook at the serial port
        soon enough after power-on.  Actually, the menu startup time
        is a few seconds long for the very same reason.

@end table

@c ==========================================================================
@node Using wrboot
@section Using wrboot

If you use the @i{wrboot} script option, you can for example run
an NFS-Root system or do whatever customization and testing you want.

The complete filesystem after a successful build is called
@t{images/wrs-image.tar.gz}, and is not included in the release
firmware file, because an installed switch runs an @i{initramfs}
system with a separate @t{/usr} partition in flash memory.

@sp 1

The @i{boot from TFTP script} menu entry looks for the script
using three
different names, from most specific to most generic; the first found
is be used.  When using the boot script, the @sc{wrs} first performs
a @sc{dhcp} query, and then uses that IP address to retrieve
the script using the following names (the @t{eth0.ethaddr} is
stored by the manufacturer in static storage and retrieved by the
boot loader; the @t{eth0.ipaddr} comes from @sc{dhcp}):

@smallexample
   wrboot-$eth0.ethaddr
   $eth0.ipaddr/wrboot
   wrboot
@end smallexample

As an example, the following excerpt shows what I see in my logs when
only providing @file{wrboot}.  The last message uses a different IP
address because my script forces a static address into the kernel,
whereas the initial one was assigned to the boot loader using
@sc{dhcp}.

@smallexample
   dhcpd: DHCPOFFER on 192.168.16.224 to 02:0b:ad:c0:ff:ee via eth0
   atftpd[5623]: Serving wrboot-02:0B:AD:C0:FF:EE to 192.168.16.224:1029
   atftpd[5623]: Serving 192.168.16.224/wrboot to 192.168.16.224:1030
   atftpd[5623]: Serving wrboot to 192.168.16.224:1031
   mountd[21014]: NFS mount of /tftpboot/192.168.16.9 attempted from 192.168.16.9
@end smallexample

We chose to place the IP-address-based name in a subdirectory because
this is the default place where the NFS-Root filesystem is mounted
from, as shown in the log excerpt above. So you'll have your
@file{wrboot} in the same place.

@b{Note:} recent @i{barebox} versions require scripts to include a
leading @t{#!/bin/sh}. Examples in @i{wr-switch-sw} did not include the
line until April 2014 included.

The @file{binaries} subdirectory of @t{wr-switch-sw} includes a number
of known-working wrboot scripts as examples;

@table @t

@item wrboot-static-ip

	The script forces a static IP address, server and gateway, and
        a custom mount point for an NFS-root system.

@item wrboot-dhcp

	The script preserves the @sc{dhcp}-assigned address, and runs
        a custom NFS-root system.

@item wrboot-install

	This performs an installation, by loading everything to RAM
        and forcing install mode. Please check comments in the script.

@item wrboot-nand

	This script is a copy of the default boot script executed
        bt standalone switches.  Booting from a script allows
        changing the kernel command line or anything else it may
        be useful to developers.

@end table

@c ==========================================================================
@node Creating an NFS-Root Environment for WRS
@section Creating an NFS-Root Environment for WRS

In order to create an NFS root directory, you should uncompress
@t{wrs-image.tar.gz} that is created at build time.  If you use
a released @t{wrs-firmware.tar}, however, you'll have no overall
filesystem for the switch, and you should rebuild it from two
parts.  This is how to create your NFS filesystem (please adapt
for your local pathnames):

@example
   FW=/tftpboot/wrs-firmware.tar
   DIR=/opt/root/wrs-3

   mkdir -p $DIR
   tar xOf $FW wrs-initramfs.gz | zcat | \
       (cd $DIR && sudo cpio --make-directories --extract)
   tar xOf $FW wrs-usr.tar.gz | sudo tar xzf - -C $DIR/usr
@end example

The above commands extract to @i{stdout} the two parts of the @sc{wrs}
filesystem, to then uncompress them to the proper directories.  The
first @i{tar} pipe is less friendly because the @i{initramfs} is a
compressed @i{cpio} archive, and @i{cpio} as a command lacks automatic
decompression and the @t{-C} (change directory) option.


@c ##########################################################################
@node WRS Command-Line Tools
@chapter WRS Command-Line Tools