\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 July 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, Adam Wujek, Benoit Rat, Federico Vaga, ...
@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 programs 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 (@t{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 all four manuals is maintained in @t{wr-switch-sw/doc}.
Within the repository, three of them the @i{User's Manual},
the @i{Developer's Manual} and the @i{Failures and Diagnostics}
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.

@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 sometimes 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 please copy @t{wrs-firmware.tar} file into
the @t{/update} partition via @t{scp} or web-interface and restart your switch.

When the running version during the update is at least 4.3, then update script
performs the check of md5sums of all files inside @t{wrs-firmware.tar}.
In case at least one checksum is wrong then update is aborted.
The @t{wrs-firmware.tar} containing corrupted file is renamed to
@t{wrs-firmware.tar.checksum_error}. This file is automatically removed during
the next successful update.

When checksums in the @t{wrs-firmware.tar} are not available
(for example during downgrading) appropriate warning message is printed.

If this method works for you, you can ignore this chapter, which
explains a transition between the initial way we passed MAC addresses
and the safer approach we introduced in v4.1

@c ==========================================================================
@node hwinfo for pre-v4.1
@section hwinfo for pre-v4.1

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 performing 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 proper 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 firmware 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 firmware 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 firmware 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.

Starting with release 4.2, we added ``@t{make config}'' support at run
time, to be run in @t{/wr/etc}; the file is called @t{dot-config}, and
not @t{.config}.  This is meant to be useful for developers, when
testing different configurations in the lab, rather than in
production. We also support ``@t{make config}'', ``@t{make
defconfig}'', @t{make oldconfig}'' and ``@t{make menuconfig}''.

@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. The location of the configuration file can also be retrieved from DHCP
server.

@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 about source of the @t{dot-config} file
(items starting with @t{CONFIG_DOTCONF_SOURCE_}).  The following @t{dot-config}
sources are implemented in current version:
@table @t

@item CONFIG_DOTCONF_SOURCE_LOCAL

	Use local @t{dot-config} file stored in @t{/wr/etc/dot-config}.
        In this case no network access is performed.

@item CONFIG_DOTCONF_SOURCE_REMOTE

	Get a @t{dot-config} file from the URL provided in @t{CONFIG_DOTCONF_URL}.

@item CONFIG_DOTCONF_SOURCE_FORCE_DHCP
	Get a network location of a @t{dot-config} file from a DHCP server.
        Server can be configured in a way to provide the entire URL to
        the dot-config in the ``@t{filename}'' configuration field of the DHCP
        server. As an alternative, ``@t{filename}'' can be configured only as a
        path. It will be then interpreted as a path on a tftp server, which IP
        address is taken from the configuration field
        ``@t{The BOOTP next server option}'' of a DHCP server.
        In the case the URL is used it has to be in the same form as
        @t{CONFIG_DOTCONF_URL}.

@item CONFIG_DOTCONF_SOURCE_TRY_DHCP
	The same as @t{CONFIG_DOTCONF_SOURCE_FORCE_DHCP}, but this option does
        not cause errors in SNMP's objects if the switch fails to retrieve the
        URL to the @t{dot-config} via DHCP. Note that syntax and download
        errors of @t{dot-config} are notified in the same way as for other
        choices.

@end table

If the selected option triggers @sc{wrs} to download a new @t{dot-config}
file, it will replace the copy in the local storage if it is different.

The URL (stored in @t{CONFIG_DOTCONF_URL} or retrieved via DHCP) 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_SOURCE_REMOTE=y
   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{CONFIG_DOTCONF_SOURCE_*} 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_SOURCE_LOCAL
@itemx CONFIG_DOTCONF_SOURCE_REMOTE
@itemx CONFIG_DOTCONF_SOURCE_FORCE_DHCP
@itemx CONFIG_DOTCONF_SOURCE_TRY_DHCP
@itemx CONFIG_DOTCONF_URL

	The source and 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_HOSTNAME_DHCP
@itemx CONFIG_HOSTNAME_STATIC
@itemx CONFIG_HOSTNAME_STRING

	These options describe how to set hostname of the switch. From DHCP
	(@t{CONFIG_HOSTNAME_DHCP}) or use a predefined value
	(@t{CONFIG_HOSTNAME_STATIC}) defined in option @t{CONFIG_HOSTNAME_STRING}.

@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 the format ``@t{S} @i{level} @i{facility}'' (e.g.
        ``@t{S 2 daemon}''). For example, ``@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. NOTE: It looks
	like @t{Notice} is not a default logging priority as writen in manual.

@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_PORT01_PARAMS
@itemx CONFIG_PORT02_PARAMS
@itemx ...
@itemx CONFIG_PORT18_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, without 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
@itemx CONFIG_PTP_REMOTE_CONF

	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{wri1} 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}).

	Finally, you can choose @t{PTP_REMOTE_CONF} and be able to
        specify an URL (@t{http://}, @t{ftp://} or @t{tftp://}) whence
        the switch will download the @t{ppsi.conf} at boot time.
        The filename in the URL can include @t{IPADDR} and/or @t{MACADDR},
        so the same configuration string can be used to set up a batch
        of switches with different configurations.

        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_PTP_CONF_URL

	If you choose @t{CONFIG_PTP_REMOTE_CONF} this is the URL
        used to download @t{ppsi.conf} at each system boot.

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

@item CONFIG_FAN_HYSTERESIS
@itemx CONFIG_FAN_HYSTERESIS_T_DISABLE
@itemx CONFIG_FAN_HYSTERESIS_T_ENABLE
@itemx CONFIG_FAN_HYSTERESIS_PWM_VAL

	Use hysteresis to control switch's fans. Enable fans with PWM value
	@t{CONFIG_FAN_HYSTERESIS_PWM_VAL} when PLL's temperature exceeds
	@t{CONFIG_FAN_HYSTERESIS_T_ENABLE}. Disable fans when temperature drops
	below @t{CONFIG_FAN_HYSTERESIS_T_DISABLE}. These options are intended to
	be used during development to reduce noise generated by switch.

@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=wri9,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{wri9}, 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
protocol (@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 entries 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 mono-modal 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 VLANs Configuration
@section VLANs Configuration

Unfortunately, the current firmware release does not support VLAN configuration
in the main @i{dot-config} file. Therefore, if you want to use VLANs you
have to manually configure them using the @i{wrs_vlans} tool described
in @ref{wrs_vlans}.

In addition to that, to have synchronization working with VLANs, you have to
prepare a custom @i{PPSi} configuration file with VLANs specified per-port. You
can simply copy the file generated in the WRS filesystem
(@i{/wr/etc/ppsi.conf}) to a central @t{tftp}/@t{http}/@t{ftp} server where
@i{dot-config} files for your switches are stored and fetched on boot time.
For every VLAN-enabled port you should add the following line:
@example
  vlan <VID>
@end example
where @i{VID} is a VLAN ID configured on the port. To let your switch use the
modified @i{ppsi.conf}, you should add it as @t{CONFIG_PTP_REMOTE_CONF} option
in the @i{dot-config} (@ref{Configuration Items that Apply at Run Time}). This
way it will be fetched and applied every time your switch boots.

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



 Tools
are build from source files in @file{userspace/tools} while the
scripts are copied directly from @file{userspace/rootfs_override/wr/bin}.

The following tools and scripts are provided:

@table @file

@item load-virtex
@itemx load-lm32

	They load into the FPGA the gateware and the LM32 application.
        They are used by the init scripts of the Linux system. The LM32
        loader can also change variables in the loaded binary, and
        read or write variables without stopping the running CPU.
        This is limited to 32-bit integer variables, though. See the
        commit message for details.
@c FIXME: document better load-lm32 for elf.

@item mapper
@itemx wmapper
	The former reads from a file using @i{mmap}
        (usually you run it on @i{/dev/mem}) and writes to @i{stdout}.
        The latter read from @i{stdin} and writes using @i{mmap}.
        They are classic tools distributed in the @i{Linux Device Drivers}
        examples since 1998.

@item com
	The program is a simple program for talking with serial ports.

@item wr_phytool
	A tool to read and write PHY registers in the switch.

@item wr_mon
	A simple monitor of White Rabbit status. It prints to @i{stdout}
        using the standard escape sequences for color output. The
        @t{-b} command line options removes color change (b/w).

@item wrs_pps_control
        A tool to switch the PPS output on and off. Usage ``@t{wrs_pps_control
        on}'' switches the PPS output on, and ``@t{wrs_pps_control off}''
        switches the PPS output off. Switching the output on/off is independent
        of the PPSi process, but PPSi switches the PPS output back on when a
        link restart is detected and PPSi comes into @t{'TRACK_PHASE'} state.

@item wrs_port_tx_control
        A tool to switch the TX (laser) of a port on and off by use of the @t{TX
        disable} pin on the SFP. Usage ``@t{wrs_port_tx_control <port_no> on}''
        switches the TX on, and ``@t{wrs_port_tx_control <port_no> off}''
        switches the TX off. The port number @t{<port_no>} ranges from 1 to 18.

@item wr_date

	The program can read or set the White Rabbit date. When setting,
        using ``@t{wr_date set} @i{value}'' assigns an arbitrary date,
        and ``@t{wr_date set host}'' passes the host time to White Rabbit.
        If the file @t{/etc/leap-seconds.list} exists, it is used to
        pass the TAI offset to the kernel, and to consider it in setting
        White Rabbit time to the current TAI value.  The program is
        meant to prime the White Rabbit counter at boot time, and is
        run by @t{/etc/init.d/wr_date} -- this script uses NTP
        to set host time as a first step, if @t{/wr/etc/wr_date.conf}
        exists and includes a line of the form @t{ntpserver 192.168.16.1}.

        With ``@t{wr_date get}'' you can read White Rabbit time, and
        by using @t{wr_date get tohost}'' you can set host time from
        White Rabbit time. This can be useful in slave switches that
        are not synced to NTP at boot.

@item wrs_version
	Print information about the SW & HW version of the WRS. Please
        check the help message.

@item shw_ver
	A symbolic link to @t{wrs_version}, to be compatible with
        older versions that used this tool name. The name is
        inconsistent with anything else in the switch, so it is being
        replaced.

@item wrs_vlans
	The tool allows to configure and unconfigure the VLAN settings
        for each port and for the RTU daemon. The @t{--help} option
        lists all configuration items of the tool.

@item apply_dot-config
	The script is used to apply @t{dot-config} settings to the
        current configuration files.  It is run at boot time before
        any service is started and by web interface to apply changes in
        the local dot-config.
        The @t{dot-config} mechanism is documented in @ref{Configuration of the
        Device}.

@item assembly_ppsi_conf.sh
	The script is used to assembly ppsi configuration file based on
        information stored in @t{PORTxx_PARAMS}.
        This script is called by @i{apply_dot-config}.

@item change_dot-config
	This script changes the current @t{dot-config} file. It is
        designed to be the back-end of the web interface, when changing
        configuration items.  The script does nothing to @i{apply}
        the changes, and it only performs editing.
        It is the responsibility of the caller to ensure the proper
        service is restarted with the new configuration.

@item sdb-read
	The tool, copied from the @t{fpga-config-space} project,
	is documented in the next section,

@item wrs_auxclk
  The tool allows to setup the parameters of a clock generated on the @i{clk2}
  SMC.

@item wrs_sfp_dump
	Dump the content of SFPs internal memory. Please note that this tool
	cannot be used in production due to the race condition of i2c
	transactions. The race can cause errors while reading SFPs memory,
	wrong notification of LEDs, the false insert/remove SFP notifications.

@c FIXME: document lm32-vuart rtu_stat spll_dbg_proxy
@c FIXME: document wrs_pstats
@end table

@c --------------------------------------------------------------------------
@node sdb-read
@section sdb-read

[Note: this documentation section comes from the @t{ohwr} project
called @t{fpga-config-space}.]


The @i{sdb-read} program can be used to access an @i{sdbfs} image
stored in a disk file or an FPGA area in physical memory.
It works both as @i{ls} (to list the files
included in the image) and as @i{cat} (to print to its own @i{stdout}
one of the files that live in the binary image).

The program can be used in three ways:

@table @code

@item sdb-read [options] <image-file>

	This invocation lists the contents of the image. With @code{-l}
        the listing is @i{long}, including more information than the
        file name.

@item sdb-read [options] <image-file> <filename>

	When called with two arguments, the program prints to @i{stdout}
        the content of the named file, extracted from the image. Please
        note that if the file has been over-sized at creation time,
        the whole allocated data area is printed to standard output.

@item sdb-read [options] <image-file> <hex-vendor>:<hex-device>

	If the second argument is built as two hex numbers separated
        by a colon, then the program uses them as vendor-id and device-id
        to find the file.  If more than one file have the same identifiers,
        the @i{first} of them is printed.

@end table

The following option flags are supported:

@table @code

@item -l

	For listing, use @i{long} format. A @i{verbose} format will
        be added later.

@item -e <entrypoint>

	Specify the offset of the magic number in the image file.

@item -m <size>@@<addr>
@itemx -m <addr>+<size>

	Either form is used to specify a memory range. This is the
        preferred way to read from a memory-mapped area, like an FPGA
        memory space.  Please note that in general you should not
        read a ``file'' in FPGA space, because this would mean read
        all device registers. The form ``@t{<image-file> <filename>}''
        is thus discouraged for in-memory SDB trees (i.e. where
        @t{<image-file>} is @t{/dev/mem}).

@item -r

	Register the device with a @i{read} method instead of the @i{data}
        pointer. In this way the
        tool can be used to test the library with either access method.
        If @i{mmap} fails on the file (e.g., it is a non-mappable device),
        @i{read} is used automatically, irrespective of @t{-r}.

@end table

@c --------------------------------------------------------------------------
@node wrs_vlans
@section wrs_vlans

The @i{wrs_vlans} shell tool can be used to setup VLANs in the switch. The
configuration is divided into two parts:

@table @code

@item wrs_vlans --port <port number or range> [options]

  Per-port Endpoint VLAN configuration. Used to set VID and priority for ingress
  frames tagging, egress untagging and port mode to:
  @itemize @bullet
  @item ACCESS - tags untagged frames with configured VID and priority, drops
  tagged frames not belonging to the configured VLAN
  @item TRUNK - passes only tagged frames, drops all untagged frames
  @item Disabled - VLANs disabled
  @item Unqualified port - passes all frames regardless of VLAN configuration
  @end itemize

@item wrs_vlans --rvid <vid> [options]

  Per-VLAN configuration of the Routing Table Unit, used to configure port mask
  describing which port belong to a given VLAN. RTU uses this information to be
  able to forward incoming frames only to ports inside the VLAN.

@end table

Both per-port Endpoint and per-VLAN RTU configuration has to be performed in
order to have a full VLAN setup on a WR Switch.

For per-port configuration, multiple ways of specifying ports are supported:
@table @code

@item wrs_vlans --port 1 [options]

  Selected configuration will be applied only to port 1.

@item wrs_vlans --port 1,3,4 [options]

  Selected configuration will be applied to ports 1,3 and 4.

@item wrs_vlans --port 5-8 [options]

  Selected configuration will be applied to port range 5 to 8.

@item wrs_vlans --port 5-8,15 [options]

  Selected configuration will be applied to port range 5 to 8 and port 15.

@end table

To configure each Endpoint the following options may be used:
@table @code

@item --pmode <mode No.>
  Sets qmode for a port (0 - ACCESS, 1 - TRUNK, 2 - disabled, 3 - unqualified)

@item --pvid <vid>
  Sets VLAN id for tagging ingress frames.

@item --pprio <priority>
  Sets priority for tagging ingress frames.

@item --pumask <hex mask>
  Sets mask for egress untagging. By default, if you configure ingress tagging,
  all VIDs are untagged on egress.

@end table

To configure VLANs in RTU the tool has to be used with parameter specifying
VLAN id to be set up and then the list of configuration options:
@table @code
@item wrs_vlans --rvid <vid> [options]
@end table

Possible RTU VLAN configuration options:
@table @code

@item --rmask <hex mask>
  Mask defines which physical ports of the WRS belong to a configured VLAN.

@item --rfid <fid>
  Assigns filtering ID @i{fid} to the configured VLAN. Multiple VLANs can be
  configured to have the same @i{fid}. This way they create a group where
  learning a new MAC address in one VLAN implies learning this MAC in the rest
  of VLANs in the group as well.

@item --rprio <prio>
  Forces 802.1q priority override for VLAN. Setting @i{prio} to -1, cancels the
  override.

@item --rdrop <1/0>
  Forces (if set to 1) or disables (if set to 0) frames drop for the configured
  VLAN.

@item --del
  Deletes selected VLAN from the RTU configuration.

@end table

In addition to that @i{wrs_vlans} can be also used to display and clear current
VLAN configuration of the switch:

@table @code

@item wrs_vlans --plist

  Current Port VLAN configuration

@item wrs_vlans --list

  Current RTU VLAN configuration.

@item wrs_vlans --clear

@end table

@i{wrs_vlans} tool can be called multiple times to make a set of per-port and
per-VLAN configurations. However, it is also possible to configure multiple
ports/VLANs in one go. For example to configure ports 1,2,3,6 to VLAN 5 and
ports 4,5 to VLAN 6 with tagging ingress frames one could call @i{wrs_vlans}
with these parameters:

@example
  wrs_vlans --port 1-3,6 --pmode 0 --pvid 5 --port 4,5 --pmode 0 --pvid 6 \
    --rvid 5 --rmask 0x27 --rvid 6 --rmask 0x18
@end example

@c --------------------------------------------------------------------------
@node wrs_auxclk
@section wrs_auxclk

The @i{wrs_auxclk} shell tool can be used to configure parameters of a clock
signal generated on the @i{clk2} SMC connector.

@b{Note:} you need to have WRS hardware at least in version 3.4 to have @i{clk2}
output.

By default @i{wrs_auxclk} is called by init scripts to generate 10MHz clock
signal with 50% duty cycle. This configuration can be modified by using various
options:

@table @code

@item --freq <f>
  Desired frequency of the generated clock signal in MHz. Available range from
  4kHz to 250MHz.

@item --duty <frac>
  Desired duty cycle given as a fraction (e.g. 0.5, 0.4).

@item --cshift <csh>
  Coarse shift (granularity 2ns) of the generated clock signal. This parameter
  can be used to get desired delay relation between generated 1-PPS and
  @i{clk2}. The delay between 1-PPS and @i{clk2} is constant for a given
  bitstream but may be different for various hardware versions and
  re-synthesized gateware. Therefore it should be measured and adjusted only
  once for given hardware and gateware version.

@item --sigdel <steps>
  Clock signal generated from the FPGA is cleaned by a discrete flip-flop.
  It may happen that generated aux clock is in phase with the flip-flop clock.
  In that case it is visible on the oscilloscope that @i{clk2} clock is
  jittering by 4ns. The @code{--sigdel} parameter allows to add a precise delay
  to the FPGA-generated clock to avoid such jitter. This delay is specified in
  steps, where each step is around 150ps. This value, same as the
  @code{--cshift} parameter, is constant for a given bitstream so should be
  verified only once.

@item --ppshift <steps>
  If one needs to precisely align 1-PPS output with the @i{clk2} aux clock using
  @code{--cshift} parameter is not enough as it has 4ns granularity. In that
  case @code{--ppshift} lets you shift 1-PPS output by a configured number
  of 150ps steps. However, please have in mind that 1-PPS output is used as a
  reference for WR calibration procedure. Therefore, once this parameter is
  modified, the device should be re-calibrated. Otherwise, 1-PPS output
  will be shifted from the WR timescale by <steps>*150ps.
  

@end table

@c ##########################################################################
@node SNMP Support
@chapter SNMP Support

The White Rabbit Switch supports SNMP. The default read-only ``community'' name
is @t{private},
but you can change it from the @t{Kconfig} interface before building.
The default read-write community is @t{private}.

The switch supports all the standard information through the @i{net-snmp}
installation. The additional, switch-specific information are in the
``enterprise.96.100'' subtree, where @t{96} is CERN and @t{100} is White
Rabbit. The associated MIB is in the directory @t{userspace/snmpd},
where related source files live as well.

There is currently no support for traps.

@c ==========================================================================
@node The WRS MIB
@section The WRS MIB

This section contain a summary of the @t{WR-SWITCH-MIB}, for details please
refer to the document @i{White Rabbit Switch: Failures and Diagnostics}.
Objects from @t{96.100.2} to @t{96.100.5} are obsolete, they were used during early
implementation of switch's snmp.

@table @code

@item 96.100.1

	This is a simple scalar as a test. It is an integer value
        that is incremented each time you access it. It can be used to
        test basic functionality.

@item 96.100.6

	@b{wrsStatus} -- MIB's branch with collective statuses of entire
	switch.

@item 96.100.7

	@b{wrsExpertStatus} -- Branch with detailed statuses of switch
	subsystems.

@end table

@c @b{Note:} due to a bug in management of 64-bit values in @i{net-snmp},
@c we are using a bad work-around in the code, that may cause wrong values
@c to be returned by other versions of the agent, where this bug is fixed.

The easiest way to retrieve the values is using @i{snmpwalk}, telling
it to access our MIB file in order to use symbolic names. Assuming
@t{wrs} is the DNS name for your White Rabbit Switch and @t{WR_SWITCH_SW}
is an environment variable pointing to this package:

@smallexample
   snmpwalk -c public -v 2c wrs \
       -m +${WR_SWITCH_SW}/userspace/snmpd/WR-SWITCH-MIB.txt \
       1.3.6.1.4.1.96.100
@end smallexample

Using SNMP version 1 instead of 2c is fine as well, but you won't receive
the 64-bit values for slave/tracking information.

The output you will get back is something like the following. Clearly
the software commit in this example is my own development version while writing
this section:

@smallexample
WR-SWITCH-MIB::wrsScalar.0 = INTEGER: 1
WR-SWITCH-MIB::wrsMainSystemStatus.0 = INTEGER: ok(1)
WR-SWITCH-MIB::wrsOSStatus.0 = INTEGER: ok(1)
WR-SWITCH-MIB::wrsTimingStatus.0 = INTEGER: ok(1)
[...]
WR-SWITCH-MIB::wrsConfigSource.0 = INTEGER: remote(4)
WR-SWITCH-MIB::wrsConfigSourceUrl.0 = STRING: tftp://192.168.1.1/config-192.168.1.10
WR-SWITCH-MIB::wrsBootConfigStatus.0 = INTEGER: ok(1)
WR-SWITCH-MIB::wrsBootHwinfoReadout.0 = INTEGER: ok(1)
WR-SWITCH-MIB::wrsBootLoadFPGA.0 = INTEGER: ok(1)
WR-SWITCH-MIB::wrsBootLoadLM32.0 = INTEGER: ok(1)
[...]
WR-SWITCH-MIB::wrsPtpServoState.1 = STRING: TRACK_PHASE
WR-SWITCH-MIB::wrsPtpServoStateN.1 = INTEGER: trackPhase(4)
WR-SWITCH-MIB::wrsPtpPhaseTracking.1 = INTEGER: tracking(2)
WR-SWITCH-MIB::wrsPtpSyncSource.1 = STRING: 
WR-SWITCH-MIB::wrsPtpClockOffsetPs.1 = Counter64: 0
WR-SWITCH-MIB::wrsPtpClockOffsetPsHR.1 = INTEGER: 0
WR-SWITCH-MIB::wrsPtpSkew.1 = INTEGER: -1
WR-SWITCH-MIB::wrsPtpRTT.1 = Counter64: 943893
WR-SWITCH-MIB::wrsPtpLinkLength.1 = Gauge32: 91
WR-SWITCH-MIB::wrsPtpServoUpdates.1 = Counter32: 33
[...]
WR-SWITCH-MIB::wrsPortStatusPortName.1 = STRING: wri1
WR-SWITCH-MIB::wrsPortStatusPortName.2 = STRING: wri2
[...]
WR-SWITCH-MIB::wrsPortStatusLink.1 = INTEGER: up(2)
WR-SWITCH-MIB::wrsPortStatusLink.2 = INTEGER: up(2)
[...]
WR-SWITCH-MIB::wrsPortStatusConfiguredMode.1 = INTEGER: slave(2)
WR-SWITCH-MIB::wrsPortStatusConfiguredMode.2 = INTEGER: auto(4)
[...]
WR-SWITCH-MIB::wrsPortStatusSfpVN.1 = STRING: Axcen Photonics
WR-SWITCH-MIB::wrsPortStatusSfpVN.2 = STRING: Axcen Photonics
[...]
WR-SWITCH-MIB::wrsPortStatusSfpPN.1 = STRING: AXGE-3454-0531
WR-SWITCH-MIB::wrsPortStatusSfpPN.2 = STRING: AXGE-3454-0531
[...]
WR-SWITCH-MIB::wrsPstatsHCPortName.1 = STRING: wri1
WR-SWITCH-MIB::wrsPstatsHCPortName.2 = STRING: wri2
[...]
WR-SWITCH-MIB::wrsPstatsHCTXFrames.1 = Counter64: 232
WR-SWITCH-MIB::wrsPstatsHCTXFrames.2 = Counter64: 543
[...]
WR-SWITCH-MIB::wrsPstatsHCRXFrames.1 = Counter64: 255
WR-SWITCH-MIB::wrsPstatsHCRXFrames.2 = Counter64: 544

@end smallexample

Another example is to print all objects exported by switch.
@smallexample
snmpwalk -c public -v 2c wrs -m all \
        -M ${WRS_OUTPUT_DIR}/build/buildroot-2016.02/output/build/netsnmp-5.7.3/mibs/\
        :${WR_SWITCH_SW}/userspace/snmpd/ \
        1
@end smallexample

@c ==========================================================================
@node show-pstats
@section show-pstats

To visualize all port statistics in a single window, this package
includes the simple tool @t{userspace/snmpd/show-pstats}.  It is
a Tk script, so you need to install @t{tk8.5} or any other version.

The script receives one or more host names (or IP addresses) on the command
line. They must refer to a switch (or switches) or the program fails like this:

@smallexample
   laptopo% ./show-pstats morgana
   Error in snmpwalk for host morgana
   No log handling enabled - using stderr logging
   .1.3.6.1.4.1.96.100.2.1.: Unknown Object Identifier (Sub-id not found: enterprises -> )
@end smallexample

If everything goes well, you'll get a window like the following one:

@center @image{show-pstats, 10cm,, show-pstats}

Command @t{snmptable} can also be used to get simillar results:

@smallexample
snmptable -Cw 80 -c public -v 2c 192.168.1.10 -m all \
-M $WRS_OUTPUT_DIR/build/buildroot-2016.02/output/build/netsnmp-5.7.3/mibs/\
:userspace/snmpd/ WR-SWITCH-MIB::wrsPstatsHCTable
@end smallexample
Output is in text form and looks like:
@smallexample
SNMP table: WR-SWITCH-MIB::wrsPstatsHCTable

 wrsPstatsHCPortName wrsPstatsHCTXUnderrun wrsPstatsHCRXOverrun
                wri1                     0                    0
                wri2                     0                    0
                wri3                     0                    0
                wri4                     0                    0
                wri5                     0                    0
                wri6                     0                    0
                wri7                     0                    0
                wri8                     0                    0
                wri9                     0                    0
               wri10                     0                    0
               wri11                     0                    0
               wri12                     0                    0
               wri13                     0                    0
               wri14                     0                    0
               wri15                     0                    0
               wri16                     0                    0
               wri17                     0                    0
               wri18                     0                    0

SNMP table WR-SWITCH-MIB::wrsPstatsHCTable, part 2

 wrsPstatsHCRXInvalidCode wrsPstatsHCRXSyncLost wrsPstatsHCRXPauseFrames
                        0                     0                        0
                        0                     0                        0
                        0                     0                        0
                        0                     0                        0
                        0                     0                        0
                        0                     0                        0
                        0                     0                        0
                        0                     0                        0
                        0                     0                        0
                        0                     0                        0
                        0                     0                        0
                        0                     0                        0
                        0                     0                        0
                        0                     0                        0
                        0                     0                        0
                        0                     0                        0
                        0                     0                        0
                        0                     0                        0

(...)
@end smallexample
Unfortunately output due to the number of counters is very wide. Number of 
characters per line can be limited by switch @t{Cw}, in example was set to 80.

@c ##########################################################################
@node Bugs and Troubleshooting
@appendix Bugs and Troubleshooting

Even if the package is already released and used in production,
some details can be
suboptimal, while some procedures may be tricky and need more explanation.

We are collecting all those issues in the @i{wiki} page of the
project, to avoid frequent updates to this manual to just collect
those details.  So please visit
@url{www.ohwr.org/projects/wr-switch-sw/wiki/Bugs} and
@url{www.ohwr.org/projects/wr-switch-sw/wiki/Troubleshooting}
if you have any problem with this package, but feel free to reach us
on the mailing list if you don't find help there.

@c ##########################################################################
@bye


@c  LocalWords:  gnudd titlepage iftex texinfo CERN timestamping smallexample
@c  LocalWords:  LocalWords ietf timestamp misc timestamps ttstamp onestamp
@c  LocalWords:  Tomasz Wlostowski buildroot distclean defconfig wrswitch REPO
@c  LocalWords:  menuconfig config dataflash whiterabbit stdout stderr svnsync
@c  LocalWords:  filesystem diff ohwr http mkdir linux rubini itemize PTPd VHDL
@c  LocalWords:  noposix ptpd userspace libwr DataFlash NAND barebox FPGA
@c  LocalWords:  Atmel Kconfig minicom tinyserial ttyUSB bootloader logfile
@c  LocalWords:  nandflash gateware TFTP init wrboot wiki LEDs DHCP
@c  LocalWords:  SNMP hwinfo pathname CONFIG filename Busybox Barebox
@c  LocalWords:  rsyslog PARAMS subdirectory dhcp nand VLAN vlans
@c  LocalWords:  auxclk bitstream
