\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
@copying
Copyright CERN 2023.
This document is licensed under the Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license.
@end copying

@setchapternewpage off

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

@comment %**useful declaration used in the document
@set release_version 6.0
@set release_version_tiny 0
@set url_docs https://www.ohwr.org/project/wr-switch-sw/wikis/Documents#files

@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 J-C. Bau, G. Daniluk, M. Lipinski, B. Rat, A. Rubini,
@author F. Vaga, A. Wujek
@insertcopying
@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 v4.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 etc.  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}: describes various
   failure scenarios of a switch and ways how to recognize them.
   Additionally, it describes 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}:
(@uref{@value{url_docs}})).
This doesn't apply to release v4.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{@uref{@value{url_docs}}}.

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 v5.0, then update script
performs the check of md5 sums of all files inside the @t{wrs-firmware.tar}.
If at least one checksum is incorrect, the update is aborted and an error is
reported via SNMP (object @t{wrsFwUpdateStatus}) until the next successful update.
Additionally, 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 to version pre-v5.0) appropriate warning
message is printed to the console.

If this method of upgrading firmware works for you, you can ignore the rest of
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 Upgrade from v5.0.1 to v@value{release_version}
@section Upgrade from v5.0.1 to v@value{release_version}

Apart from following the instructions in the previous section, there
is no special action needed from the user when upgrading firmware from
v5.0.1 to v@value{release_version}. Yet, special attention should be payed
to a number of improvements in configuration and slight changes in
the behavior of the WR Switch. Here are highlights:
@itemize

@item @b{IP address of the management port}

  WR switch running the defult configuration file included in the v6.0 release
  will try to get dynamic IP address for the management port at boot time.
  In case the DHCP server is not responding, WR switch will use default static
  IP assignment:
  @smallexample
  IP address: 192.168.1.254
  Netmask:    255.255.255.0
  Network:    192.168.1.0
  Broadcast:  192.168.1.255
  Gateway:    192.168.1.1
  @end smallexample
  
@item @b{Low Phase Drift Calibration (LPDC)}

  Low Phase Drift Calibration is a new feature added in release v6.0 that
  improves phase stability between WR switch restarts to <10ps. Due to FPGA
  limitations this functionality is present only on ports 1-12. 
  The LPDC requires an additional, automated calibration procedure to run for Tx
  and Rx path of each affected FPGA transceiver. The Tx calibration is performed
  once for all ports at startup of the WR switch. The Rx calibration is performed
  each time a link goes up on a port. Both Tx and Rx calibration is indicated by
  blinking of @i{Link/WR Mode} LED (left).
  The downside is that the calibration makes startup of the WR switch longer.
  Similarly, the time between connecting a fiber and the link going up
  (e.g. as observed in @i{wr_mon}) is noticeably longer.

@item @b{Configuration of the WR switch} - while it was feasible to edit by
  hand the @i{dot-config} file in the pre-v6.0 firmware versions, it is
  highly discouraged now. Since the number of configuration options increased
  greatly, the @i{dot-config} file is very long and complex. Therefore,
  @b{it is highly recommended to use the menuconfig to generate the
  @i{dot-config}} (e.g.  @i{wrs_menuconfig} tool on the WR switch).
  Highlights of the changes to configuration are provided in the following 
  bullet points.

@item @b{Configuration of PTP/PPSi in menuconfig} - up to firmware
  v5.0.1, the configuration of PPSi in @i{menuconfig} was limited to a global timing
  mode (e.g. GM, BC) and per-port proto (raw, udp), rx/tx delays, role (e.g, 
  master, slave, auto) and fiber id. Any more complex configuration of PPSi had to
  be done via a custom @t{ppsi.conf} file and this was also limited. It was
  a known issue that the @i{auto} role that uses PTP's Best Master Clock
  Algorithm was not implemented correctly. We have updated PPSi fixing all known
  issues related to compliance with IEEE1588-2008 (PTPv2) and we have already
  introduced a number of new features from the IEEE1588-2019 (PTPv2.1) edition.
  This resulted in a substantial increase and reorganization of configuration 
  parameters for PPSi in @i{menconfig} and @t{dot-config}. In short, the default
  behavior of Grand-Master, Free-Running Master and Boundary Clock are preserved,
  yet with different names for the configuration options which are compliant
  with the  IEEE1588-2019. Here are the highlights of the changes
  @itemize
  @item @b{Port Timing Configuration} is organized in per-port sub-menus 
    instead of a simple configuration strings. On each physical port,
    zero or one PTP Instance can configured (in future release we will allow more
    than one PTP Instance). If you do not want to use PTP on a given physical port,
    zero PTP Instances should be used. For each PTP Instance, a number of
    configuration parameters can be selected, including:
    @itemize
    @item @b{Network Protocol} - it allows to set PTP Mapping to 
      IEEE 802.3 or UPD/Ipv4, it used to be called @b{proto}
    @item @b{Delay Mechanism} - it allows to set E2P or P2P mechanism, previously
      possibly only via custom @t{ppsi.conf}
    @item @b{SNMP monitoring} - it can be disabled which was the case
      previously when @b{role} was set to @b{non-wr}
    @item @b{Profile} - it allows to chose between WR and standard PTP,
      the choice made previously via the @b{role} setting
    @item @b{Desired State} for BC or @b{BMCA mode} for GM - they replaces the
       @b{role} function for the Master/Slave/auto settings.
    @item @b{timestampCorrectionPortDS.egressLatency} - it replaces the @b{tx} delay
    @item @b{timestampCorrectionPortDS.ingressLatency} - it replaces the @b{rx} delay
    @item @b{externalPortConfigurationEnabled} - External Port Configuration is
      a new concept (optional feature) introduced in the IEEE1588-2019 (PTPv2.1)
      that legalizes what had been done in WR switches since long: manual
      assignment of the Master/Slave role per port. This option is used
      when a WR switch is set to @b{Boundary Clocks} Timing Mode. With this option
      enabled, the Best Master Clock Algorithm is disabled and each port must be
      assigned with the @b{Desired State}: Master/Slave/Passive. If External Port
      Configuration is disabled, the Best Master Clock Algorithm is used. Note
      that this option is global, i.e. it is not allowed to use it only on some
      ports.
    @item @b{MasterOnly} - MasterOnly is a new concept (optional feature) introduced
      in the IEEE1588-2019 (PTPv2.1) that legalizes per-port assigment of
      Master role, equivalent of setting role to be Master in the pre-v6.0 firmware.
      This assigment can be done on per-port basis and it coexists with the
      Best Master Clock Algorithm. This option is used when a WR switch is set
      to @b{Grand-Master}, @b{Free-Running Master}, or @b{Arbitrary Grand-Master}.
    @end itemize
  @item @b{PTP options} - it is a new sub-menu that allows to set a number
    of global PTP parameters which previously had to be modified by customizing
    @t{ppsi.conf} file. Thise include: domain, priority1, priority2, clockClass.
    While these parameters are pre-filled automatically depending on the Timing
    Mode, they can be overriden if need be.
  @item @b{Timing Mode} - setting timing mode provides default configuration for
    all the above-mentioned options such that the behavior of the WR switch is
    equivalent to the same Timing Mode in pre-v6.0 firmware versions. There are
    two new modes available now: @b{Arbitrary Grand-Master} and @b{Custom}. The
    @b{Arbitrary Grand-Master} mode is similar to @b{Grand-Master} but has 
    different clockClass and ARB timescale. The @b{Custom} allows full control
    over PTP settings, otherwise limited to options allowed for a given Timing
    Mode. 
  @end itemize
@item @b{Configuration of VLANs in menuconfig} - pre-v6.0 firmware provided
  limited/simplified VLAN per-port configuration that did not allow setting some
  less-common configurations, otherwise allowed by CLI (@i{wrsw_vlan}).
  As of v6.0 firmware, such more user-friendly setting is still provided by
  default, yet it can be extended by setting @b{Enable raw ports configuration}.
@item @b{New configuration options in menuconfig}
  @itemize
  @item @b{Source for a run-time replacement of leap seconds file} - the 
    leap seconds file can be now fetch from a server and updated in
    runtime.
  @item @b{PPS generation} - it is now possible to specify a number
    of aspects of the PPS generation, @b{the default configuration might be
    slightly different from the pre-v6.0 firmware}.
  @item @b{LLDP options} - it provides configuration of Link Layer Discovery
    Protocol (LLDP) which is now supported. It is enabled by default. @b{Note that
    LLDP sends Ethernet frames of approximately 200 bytes. In the worst-case,
    transmission of such frames can increase traffic latency by 0.8us
     @footnote{The maximum PTP frame size is 96 bytes which translates into 0.76us
     latency increase to the data traffic, in case the PTP frame is sent to a
     port at the same time as the data traffic frame is to be forwarded to
     this port. An additional 100 bytes of the LLDP 
     frame, translates into additional 0.8us latency introduced by protocol 
     frames.}.} If you
    do not use LLDP and latency is of concern, you should disable LLDP option.
    Alternatively consider use of the option to limit LLDP frame size to about 
    60-70 bytes.
  @item @b{Disable web interface} - web interface is now disabled by default
    and considered deprecated (no effort was put in making sure it works
    properly). @b{Users are strongly discouraged from using the web interface}.
    A number of serious security vulnerabilities were found in the web interface
    (including CVE-2023-22577).
    Please note that it is still possible to enable web interface in run-time.
    @b{Users are strongly discouraged from using the web interface}.
    In exceptional cases the use of web-interface can be limited to well
    controlled networks.
  @end itemize

@item @b{DHCP forever configuration in menuconfig} - this behavior can be set 
  for two parameters:
  @b{Management port configuration} and @b{Source for a run-time replacement
  of dot-config} (it is called @i{Force to get the URL to a dot-config via
  DHCP} in the second case). In case the DHCP server was not available, in 
  the pre-v6.0 firmware, the WR switch would start with local dot-config and
  no IP. As of v6.0, with these settings, the WR switch waits forever
  for the DHCP server to reply. This behavior was introduced to ensure that
  operational WR switches always boot with desired remote dot-config file.
  Even if, in case of a power cut, DHCP server takes longer to boot than a WR
  Switch. Unfortunately, the downside is that while waiting for the DHCP server,
  WR switch it is not accessible via
  the management port or management USB. The only way to stop the endless loop
  is to connect via the back USB (ARM Test) and follow the instructions, i.e.
  press Enter.

@item @b{Updated look of wr_mon} - this mostly commonly used Command Line 
  Interface tool in the WR switch has been updated to provide more information,
  here are the highlights:
    @itemize
    @item @b{Timing Mode} indicates the current timing mode of the Soft PLL,
      it is not the intended @i{Timing Mode} configured in the @t{dot-config}
      file. So, a GM or BC switch will show the @b{Timing Mode} to be @i{FR}
      (free running) until it locks to the source of time, i.e. input 10MHz &
      1PPS or Slave port, respectively. 
    @item @b{PTP/EXT/PDETECT states} provides information about
      @itemize
      @item @b{PTP} - indicates the PTP state of a given port, as established
        by Best Master Clock Algorithm, or configured via External Port 
        Configuration. Note that ports which are down (not connected) are always
        placed in @i{DISABLED} state.
      @item @b{EXT} - indicates the state of the currently used extension,
        for v6.0 firmware, it is the state of the White Rabbit state machine
        (more extensions in future will be supported). In the pre-v6.0 firmware,
        the state of PTP or extension was provided in the @i{PTP state} column.
      @item @b{PDETECT} - indicates the state of a state machine that governs
        the detection of extensions. When a WR link is being established, it 
        shows @i{WA_MSG}, when it is succesfully established, it shows 
        @i{EXT_ON}
      @end itemize
    @item @b{Synchronization status} - most of the parameter names were replaced
      with their equivalents used in the IEEE1588 standard:
      @itemize
      @item @b{DelayMM} is the previously  @i{Round-trip time (mu)}
      @item @b{DelayMS} is the previously  @i{Master-slave delay}
      @item @b{Total link asymmetry}is the previously  @i{delayAsymmetry}
      @item @b{delayCoefficient} is the previously @i{alpha}
      @item @b{ingressLatency} is the previously @i{Slave PHY delay RX} without the bitslide
      @item @b{egressLatency}  @i{Slave PHY delay TX}
      @item @b{offsetFrmoMaster} is the previously @i{Clock offset}
      @item @b{semistaticLatency} is a new parameter that inditactes the bistlide value
      @end itemize
    @end itemize
@end itemize

@c ==========================================================================
@node Upgrade from pre-v5.0 to v5.0.1 or later
@section Upgrade from pre-v5.0 to v5.0.1 or later

During the update from the pre-v5.0 firmware to v5.0.1 or later (or later) you might see
the following errors on the console.
@example
/wr/bin/sdb-read: can't load library 'libm.so.1'
Creating SDB filesystem in /dev/mtd5
cp: can't stat '/wr/etc/sdb-for-dataflash': No such file or directory
 done
@end example
Please ignore this message, no real error occurred nor @i{hwinfo} partition
(@t{/dev/mtd5}) was overwritten. The error is caused by an old firmware trying
to run a binary (@t{sdb-read} to be precise) from the new firmware image.
The problem became visible now, because between v4.2 and v5.0 we uplifted
the buildroot, which changed the version of @t{libm} library from @t{libm.so.0}
to @t{libm.so.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.

The @i{hwinfo} structure is written to @i{dataflash} by the manufacturer. It is
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. The 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 and later
@section Upgrading from v4.0 and later

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 the problem was fixed using
non-blocking operations (it is better to loose messages than to block the
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 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 v4.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 and later}.
When flashing version 4.0 you'll need to pass your MAC addresses on
the command line of the flasher, so please take note 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

The switch can boot embedded Linux using its internal @sc{nand} memory or as an
NFS-Root host. In the latter case is especially useful for development, when
binaries of various software daemons might need to be updated regularly.
But this option implies
some network traffic on your management network, as well as an NFS
server able to host all of your switches.

The configuration of every @sc{wrs} is described in a Kconfig-generated file.
This configuration file can be found in the filesystem of @sc{wrs} under
@t{/wr/etc/dot-config}. The switch runs by default with a configuration
provided with the stable firmware release. If you are running a small WR
network, or just a single switch for lab tests, you can modify various
settings directly from the shell or web interface. After logging to @sc{wrs}
(e.g. using @t{ssh}) you can call ``@t{wrs_menuconfig}`` command
to modify the locally stored configuration file in a convenient way.
However, this approach doesn't scale well to large installations, because if a device
needs to be replaced, its own configuration is lost.

For operational networks, it is recommended to setup
a DHCP/TFTP server for central management of configuration files and to let @sc{wrs}
download its @t{dot-config} file at boot time. This also facilitates recovering a
@sc{wr} network in case of @sc{wrs} hardware failure. It takes only a change in
the DHCP database to boot new @sc{wrs} without losing the desired configuration.
In this case, 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}, @sc{ip} address or @sc{hostname} of the device, to allow
running several switches with different configurations in the same
network. The location of the configuration file can be stored in the
@t{dot-config} or 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 can create this file either by running ``@t{make
menuconfig}'' within the local clone of @t{wr-switch-sw} repo or directly in the
shell of your switch (e.g. through @t{ssh}), and making your choices.
You can also edit the text file using external tools, or run other configurators: @t{make config},
@t{make xconfig}, @t{make gconfig}, @t{make nconfig}.

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 rest of this section describes various options that are provided through the
configuration (@t{dot-config}) file.

@table @t

@item CONFIG_DOTCONF_FW_VERSION
@itemx CONFIG_DOTCONF_HW_VERSION

	Free-text items to describe switch's firmware
	@t{CONFIG_DOTCONF_FW_VERSION} and hardware
	@t{CONFIG_DOTCONF_HW_VERSION} version. Additionally, the default value
	of @t{CONFIG_DOTCONF_FW_VERSION} can be used as a version of a Kconfig
	file. These fields do not affect any functionality of the switch.

@item CONFIG_DOTCONF_INFO

	Free-text item to descibe any additional information about dot-config.
  This field does not affect any functionality of the switch.

@end table

The next configuration item is a choice 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 @t{dot-config} in the ``@t{filename}'' configuration field of the
        DHCP server. In this case, provided URL has to be in the same form
        as @t{CONFIG_DOTCONF_URL}. 
        
        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.
        
        If the DHCP service is not available at boot time, the switch will wait
        forever until it has obtained the DHCP lease from the server. If the DHCP server is reachable 
        but switch fails to download @t{dot-config} file, it will report appropriate error over SNMP.
         
        This choice is only available if CONFIG_ETH0_DHCP is chosen for network configuration. 
        

@item CONFIG_DOTCONF_SOURCE_TRY_DHCP
	The same as @t{CONFIG_DOTCONF_SOURCE_FORCE_DHCP}, but this option does
        not trigger errors in SNMP's objects if 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 and it passes the validation process, the new @t{dot-config} will replace
a local copy. In case there are errors or unknown
configuration entries in the retrieved file, the old, local @t{dot-config} will be used.

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{HOSTNAME}, @t{IPADDR} and @t{MACADDR} are substituted with the
current hostname, IP address or MAC address of the management port of the
switch. By this, the same configuration string can be used to set up a batch
of switches with different configurations.

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}. Alternatively DNS configuration can
        be taken from the DHCP server.  The values
        in the current @t{dot-config} are used to load the new file.

@item path

	The pathname can include directory components and any of @t{HOSTNAME},
	@t{IPADDR}, @t{MACADDR}.

@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

It results 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 running switch 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.
@c 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{Configuration of the Device}
        and @ref{The Configuration File} for details.

@item CONFIG_LEAPSEC_SOURCE_LOCAL
@itemx CONFIG_LEAPSEC_SOURCE_REMOTE_FORCE
@itemx CONFIG_LEAPSEC_SOURCE_REMOTE_TRY
@itemx CONFIG_LEAPSEC_URL
	The @t{/etc/leap-seconds.list} file is used to get the current TAI offset. @xref{wr_date}.
	The @t{CONFIG_LEAPSEC_SOURCE_LOCAL} choice forces the use the local leap seconds file that
  is stored locally on the switch (under @t{/etc/leap-seconds.list}). 
	
	@t{CONFIG_LEAPSEC_SOURCE_REMOTE_FORCE} and @t{CONFIG_LEAPSEC_SOURCE_REMOTE_TRY} provide
  similar functionality. In both cases the @t{leap-seconds.list} is downloaded at boot
  time using the URL defined in @t{CONFIG_LEAPSEC_URL}. The address is defined in the
  same format as @t{CONFIG_DOTCONF_URL}. If the downloaded file is newer than the
  local copy stored in @t{/etc/leap-seconds.list}, it is used to update the local
  copy.
  In case the @sc{wrs} is unable to fetch a leap seconds file from the provided location,
  using @t{CONFIG_LEAPSEC_SOURCE_REMOTE_FORCE} will result in an error generated through
  SNMP, while using @t{CONFIG_LEAPSEC_SOURCE_REMOTE_TRY} will suppress the alarm.

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

	Disable root access via ssh. With this option enabled it is still
	possible to use sudo to get root privileges.

@item CONFIG_LDAP_ENABLE
@itemx CONFIG_LDAP_SERVER
@itemx CONFIG_LDAP_SEARCH_BASE
@itemx CONFIG_LDAP_FILTER_NONE
@itemx CONFIG_LDAP_FILTER_EGROUP
@itemx CONFIG_LDAP_FILTER_CUSTOM
@itemx CONFIG_LDAP_FILTER_EGROUP_STR
@itemx CONFIG_LDAP_FILTER_CUSTOM_STR

        Set of options related to providing an authorization via LDAP for ssh.
        To be able to use LDAP please enable an option @t{CONFIG_LDAP_ENABLE},
        provide LDAP server (@t{CONFIG_LDAP_SERVER}) and the search base
        (@t{CONFIG_LDAP_SEARCH_BASE}). It is possible to limit the access
        to a particular e-group used at CERN (@t{CONFIG_LDAP_FILTER_EGROUP}
        to enable and @t{CONFIG_LDAP_FILTER_EGROUP_STR} to provide
        the e-group's name) or to provide the custom filtering string
        (@t{CONFIG_LDAP_FILTER_CUSTOM} to enable and
        @t{CONFIG_LDAP_FILTER_CUSTOM_STR} to provide the filter).
        For more information please refer to the @i{Kconfig}'s help.


@item CONFIG_AUTH_LDAP
@itemx CONFIG_AUTH_KRB5
@itemx CONFIG_AUTH_KRB5_SERVER

        Choose the authentication method. @t{CONFIG_AUTH_LDAP} for LDAP
        authentication, @t{CONFIG_AUTH_LDAP} for Kerberos authentication.
        For the later one it is obligatory to specify Kerberos Realm
        @t{CONFIG_AUTH_KRB5_SERVER}.

@item CONFIG_ROOT_PWD_IS_ENCRYPTED
@itemx CONFIG_ROOT_PWD_CLEAR
@itemx CONFIG_ROOT_PWD_CYPHER

	This set of options allows 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
        @t{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{/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 runtime filesystem.
        By default the two strings are empty. If @t{CONFIG_ETH0_DHCP} or
        @t{CONFIG_ETH0_DHCP_ONCE} is used, @t{/etc/resolv.conf} file will be
        populated with DNS settings received from the DHCP server.
        If configuration items for static (@t{CONFIG_DNS_*}) and dynamic
        (@t{CONFIG_ETH0_DHCP}) DNS configuration are used simultaneously
        then information from both sources end up in the @t{/etc/resolv.conf}
        file. However, information from @t{CONFIG_DNS_*} is placed first.

@item CONFIG_REMOTE_SYSLOG_SERVER
@itemx CONFIG_REMOTE_SYSLOG_UDP
@itemx CONFIG_LOCAL_SYSLOG_FILE
	Configuration for system log. The name (or IP address) of the
        server is stored in @t{/etc/rsyslog.conf} of the runtime
        filesystem.  The UDP option, set by default, chooses UDP transmission;
        if unset it selects TCP communication.
	    @t{CONFIG_LOCAL_SYSLOG_FILE} option indicates the file to which
      syslog messages will be stored in a local filesystem of the @sc{wrs}.
	The file is rotated when reaching 1MB. The rotation is done through 10
	indexed files @i{syslog}, @i{syslog.1-9}. By default these files are
	created in @i{/tmp} filder.
	If remote server is specified, the messages go to both, server and local file.

@item CONFIG_WRS_LOG_HAL
@itemx CONFIG_WRS_LOG_RTU
@itemx CONFIG_WRS_LOG_PTP
@itemx CONFIG_WRS_LOG_OTHER

	Logging options for the three main WRS processes and other programs.
	@t{CONFIG_WRS_LOG_OTHER} is currently used by:
	@itemize
	@item @t{wrs_watchdog} daemon
	@item @t{wrs_throttling} executed once at boot up
	@item @t{wrs_auxclk} executed once at boot up
	@item @t{wrs_custom_boot_script.sh} executed once at boot up
	@item Setting VLANs with @t{vlan.sh} at boot up
	@end itemize
	Each value
        can be a pathname, either to a file (e.g. @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 string suppresses all logging for a given daemon.  Please note, that
        unknown facility names will generate a runtime error on the switch.
        All four strings default to ``@t{daemon.info}''.

	@b{Note:} all messages produced by these programs if syslog is
	configured will be passed to the syslog at the same
	configured @i{<facility>.<level>}, no matter the verbosity of a message.
	To change the verbosity of programs please use
	@t{CONFIG_WRS_LOG_LEVEL_*}.

@item CONFIG_WRS_LOG_LEVEL_HAL
@itemx CONFIG_WRS_LOG_LEVEL_RTU
@itemx CONFIG_WRS_LOG_LEVEL_OTHER

	Specify verbosity of programs as a string or number. The following
	levels are supported:
	@itemize
	@item @t{ALERT} or 1
	@item @t{ERROR} or 3
	@item @t{WARNING} or 4
	@item @t{INFO} or 6
	@item @t{DEBUG} or 7
	@end itemize
	Not supported levels are ceiled to the valid one.

	By leaving this item empty, programs will use its default verbosity
	level (@t{INFO}).

	@b{Note:} all messages produced by these programs if syslog is
	configured will be passed to the syslog at the same
	configured @i{<facility>.<level>}, no matter of verbosity of a message.

@item CONFIG_WRS_LOG_LEVEL_PTP

	Specify verbosity of PPSi daemon as a string. This string will be
	passed to the PPSI after @t{-d} parameter. Please refer to the PPSI's
	documentation for more details.

	By leaving this item empty, PPSi daemon will use its default
	verbosity level.
	
	@b{Note:} all messages produced by PPSi if syslog is
	configured will be passed to the syslog at the same
	configured @i{<facility>.<level>}, no matter of verbosity of a message.

@item CONFIG_WRS_LOG_SNMPD

	Value can be a pathname, either to a file (e.g. 
        @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 @t{man snmpcmd}. An empty
	string turns suppresses all logging. Please note that unknown facility
	names will generate a runtime error on the switch.

  @b{Note:} It looks
	like @t{Notice} is not a default logging priority as written in
	@i{net-snmp} 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 an empty string here and change
	@t{/etc/monitrc} or @t{/usr/etc/monitrc} file directly.
	Please note that unknown facility names will generate a runtime error
	on the switch.

@item CONFIG_PTP_OPT_EXT_PORT_CONFIG_ENABLED
@itemx CONFIG_PORT@i{xx}_@i{zz}
@itemx ...

	These configuration items are used to set up timing parameters of all
	WR ports. 
	
	Items are named according to the format  @t{CONFIG_PORT@i{xx}_@i{zz}} where : 

	@itemize
		@item @i{xx} -- represents the port number ('01' to '18')
		@item @i{zz} -- is the property name for the given port @i{xx} 
    @end itemize

    The default configuration provided with the firmware release will
    most likely work for the majority of @sc{wr} networks. In case some
    customization of these parameters is required, please see
    @ref{Timing Configuration} for details.

@item CONFIG_N_SFP_ENTRIES
@itemx CONFIG_SFP00_PARAMS
@itemx ...
@itemx CONFIG_SFP17_PARAMS

   Configuration for @sc{sfp} models.
   
   @t{CONFIG_N_SFP_ENTRIES} indicates the number of SFP entries defined. Up to 18 SFPs
   can be defined. 
    
   @t{CONFIG_SFP@i{xx}_PARAMS} with index @i{xx} in range 00 to 17, contains @sc{sfp} parameters.
	 All @sc{sfp} models their respective wavelengths you are using in your @sc{wrs}
   should be entered here.
	@itemize
		@item @t{vn} (@i{optional}) -- Vendor Name of an SFP
		@item @t{pn} -- Part Number of an SFP
		@item @t{vs} (@i{optional}) -- Vendor Serial (serial number) of
					       an SFP
		@item @t{tx} -- TX delay of an SFP in picoseconds
		@item @t{rx} -- RX delay of an SFP in picoseconds
		@item @t{wl_txrx} -- Tx wavelength separated by "+" with Rx
				     wavelength of an SFP;
				     for example @t{wl_txrx=1490+1310} (for
				     1490nm Tx wavelength and 1310nm Rx
				     wavelength)
        @end itemize
        See @ref{Timing Configuration} for details.

@item CONFIG_N_FIBER_ENTRIES
@item CONFIG_FIBER00_PARAMS
@itemx ...
@itemx CONFIG_FIBER17_PARAMS

	These parameters specify the characteristics of fiber types used in your @sc{WR} installation.
	
	@t{CONFIG_N_FIBER_ENTRIES} indicates the number of fiber types defined. Up to 18 
	different fiber types can be defined. 
   
	@t{CONFIG_FIBER@i{xx}_PARAMS} with index @i{xx} in range 00 to 17, specifies
  the alpha value for each pair of used wavelengths.
	This parameter follows the format:

	@t{alpha_@i{xxxx}_@i{yyyy}=1.23e-04,alpha_@i{aaaa}_@i{bbbb}=4.56e-04,...}

	Where:
	@itemize
	@item @t{@i{xxxx}_@i{yyyy}} and @t{@i{aaaa}_@i{bbbb}} are pairs of used wavelengths
	@item @t{1.23e-04} and @t{4.56e-04} are alpha values to be used for
	      a particular combination of wavelengths.
	@end itemize
	The index (@t{00} to @t{17}) is then entered as @t{CONFIG_PORT@i{xx}_FIBER}
  port parameter to reference the connected fiber type.
  @xref{Timing Configuration}.

	You are expected to have no more than 18 fiber types installed in
	your @sc{WR} network.

@item CONFIG_TIME_GM
@itemx CONFIG_TIME_ARB_GM
@itemx CONFIG_TIME_FM
@itemx CONFIG_TIME_BC
@itemx CONFIG_TIME_CUSTOM

	The type of PTP clock this switch is. Only one of the five first
        items should be set (e.g. running ``@t{make menuconfig}'' offers
        them as an exclusive choice). The options select: 
        @itemize 
	        @item @t{CONFIG_TIME_GM} a grand-master with external reference, e.g. GPS or Cesium.
	        @item @t{CONFIG_TIME_ARB_GM} a arbitrary grand-master which designates 
	        	a clock that is synchronized to an application-specific source of time. 
	        @item @t{CONFIG_TIME_FM} a free-running master (FM), used for isolated 
	        	acquisition networks, without an external reference. 
	        @item @t{CONFIG_TIME_BC} a normal ``boundary-clock'' device that
	        	is slave on some ports and master on other ports.  
 	        @item @t{CONFIG_TIME_CUSTOM} an option which leaves the possibility
            to define freely the PTP clock class.
        @end itemize
    
@item CONFIG_PTP_OPT_DOMAIN_NUMBER
	A domain consists of one or more PTP devices communicating with each
	other as defined by the PTP protocol. A domain defines the scope of
	PTP message communication, state, operations, data sets, and
	timescale. PTP devices may participate in multiple domains.
	For more details please refer to the IEEE 1588-2008 standard.

@item CONFIG_PTP_OPT_PRIORITY1
	A user configurable designation that a clock belongs to an ordered
	set of PTP devices from which a PTP Master is selected.
	For more details please refer to the IEEE 1588-2008 standard.

@item CONFIG_PTP_OPT_PRIORITY2
	A user configurable designation that provides finer grained ordering
	among otherwise equivalent PTP devices.
	For more details please refer to the IEEE 1588-2008 standard.

@item CONFIG_PTP_OPT_CLOCK_CLASS

	An attribute defining the TAI traceability, synchronization state and
	expected performance of the time or frequency distributed by a
	Boundary Clock or Ordinary Clock.
	Its value can be set only if @t{CONFIG_TIME_CUSTOM} parameter is selected.
  The following table shows the default values
	used depending on the timing mode ''@t{CONFIG_TIME_@i{xx}}'' choice:
		@multitable @columnfractions .3 .4
		@headitem  Timing mode @tab CONFIG_PTP_OPT_CLOCK_CLASS 
		@item  CONFIG_TIME_GM @tab 6
		@item  CONFIG_TIME_ARB_GM @tab 13
		@item  CONFIG_TIME_FM @tab 193
		@item  CONFIG_TIME_BC @tab 248
		@end multitable

	For more details please refer to the IEEE 1588-2008 standard.

	
@item CONFIG_PTP_OPT_CLOCK_ACCURACY

	An attribute defining the accuracy of the Local Clock (e.g. local
	oscillator) of a Boundary Clock or Ordinary Clock.
	Its value is set automatically according to the timing mode ''@t{CONFIG_TIME_@i{xx}}'' choice.
	It can be also manually set when either @t{CONFIG_PTP_OPT_OVERWRITE_ATTRIBUTES} is set 
	or the timing mode ``@t{CONFIG_TIME_CUSTOM}`` is selected.
	The following table gives the default values depending on the timing mode
  ''@t{CONFIG_TIME_@i{xx}}'' choice :
		@multitable @columnfractions .3 .4
		@headitem  Timing mode @tab CONFIG_PTP_OPT_CLOCK_ACCURACY 
		@item  CONFIG_TIME_GM @tab 33
		@item  CONFIG_TIME_ARB_GM @tab 33
		@item  CONFIG_TIME_FM @tab 32
		@item  CONFIG_TIME_BC @tab 254
		@end multitable

	For more details please refer to the IEEE 1588-2008 standard.
	
@item CONFIG_PTP_OPT_CLOCK_ALLAN_VARIANCE
	An attribute defining the stability of the Local Clock of a
	Boundary Clock or Ordinary Clock.
	Its value is set automatically according to the timing mode ''@t{CONFIG_TIME_@i{xx}}'' choice.
	It can be also manually set either @t{CONFIG_PTP_OPT_OVERWRITE_ATTRIBUTES} is set 
	or the timing mode ``@t{CONFIG_TIME_CUSTOM}`` is selected.
	The following table gives the default values depending on the timing mode
  ''@t{CONFIG_TIME_@i{xx}}'' choice :
		@multitable @columnfractions .3 .4
		@headitem  Timing mode @tab CONFIG_PTP_OPT_CLOCK_ALLAN_VARIANCE 
		@item  CONFIG_TIME_GM @tab 47360
		@item  CONFIG_TIME_ARB_GM @tab 47360
		@item  CONFIG_TIME_FM @tab 50973
		@item  CONFIG_TIME_BC @tab 65535
		@end multitable

	For more details please refer to the IEEE 1588-2008 standard.


@item CONFIG_PTP_OPT_TIME_SOURCE
	This information-only attribute indicates the source of time used
	by the grandmaster or free-running master. In case the timing mode is set to
  ``@t{CONFIG_TIME_BC}`` this configuration option is not used and thus hidden
  from options available e.g. through ``@t{make menuconfig}''.
	
	The following table gives the default values depending on the timing mode
  ''@t{CONFIG_TIME_@i{xx}}'' choice :
		@multitable @columnfractions .3 .4
		@headitem  Timing mode @tab CONFIG_PTP_OPT_TIME_SOURCE 
		@item  CONFIG_TIME_GM @tab 32 (GNSS)
		@item  CONFIG_TIME_ARB_GM @tab 32 (GNSS)
		@item  CONFIG_TIME_FM @tab 160 (INTERNAL_OSCILLATOR)
		@item  CONFIG_TIME_BC @tab --
		@end multitable
		
@item CONFIG_PTP_PORT_PARAMS
@itemx CONFIG_PTP_CUSTOM
@itemx CONFIG_PTP_REMOTE_CONF

	By default (@t{CONFIG_PTP_PORT_PARAMS}), PTP daemon (PPSi) configuration file
  is generated based on the values stored in @t{CONFIG_PORT@i{xx}_@i{zz}}
  parameters. 
  If VLANs are configured, the items @t{CONFIG_VLANS_PORT@i{xx}_VID} are used as well.
  Any additional, global PPSi settings can be added by editing manually the
  @t{/wr/etc/ppsi-pre.conf} file, which is then used as the base for the final
  PPSi configuration file.

	Alternatively, PPSi can use a fully custom, user-defined file for
  configuration (@t{CONFIG_PTP_CUSTOM}).

	Finally, you can choose @t{PTP_REMOTE_CONF} to
        specify an URL whence the switch will download the @t{ppsi.conf} at
        boot time.

        Please see the help provided within @i{Kconfig} for more details about
        the various supported options.
	

@item CONFIG_PTP_CUSTOM_FILENAME

	If you chose @t{CONFIG_PTP_CUSTOM} from the options described above, you
  can provide your own filename for the PPSi configuration file.
  The introduced filename is expected to be installed in the @sc{wrs}
  filesystem.

@item CONFIG_PTP_CONF_URL

	If you choose @t{CONFIG_PTP_REMOTE_CONF} 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{HOSTNAME}, @t{IPADDR}
        and/or @t{MACADDR}, so the same configuration string can be used to set
        up a batch of switches with different configurations (similar to the
        @t{CONFIG_DOTCONF_URL}, please refer to @ref{The Configuration File}).

@item CONFIG_PPSGEN_PTP_FALLBACK
@itemx CONFIG_PPSGEN_PTP_THRESHOLD_MS
@itemx CONFIG_PPSGEN_GM_DELAY_TO_GEN_PPS_SEC
@itemx CONFIG_PPSGEN_FORCE

	Configuration of the 1-PPS (Pulse Per Second) output.
  The generation of 1-PPS output heavily depends on the configured timing mode:
  @itemize
    @item GrandMaster (@t{CONFIG_TIME_GM}, PTP clock class 6)
      PPS generation is always enabled.
    @item Free-running Master (@t{CONFIG_TIME_FM}, PTP clock class 193)
      PPS generation is always enabled.
    @item Arbitrary GrandMaster (@t{CONFIG_TIME_ARB_GM}, PTP clock class 13)
      PPS generation is disabled unless @t{CONFIG_PPSGEN_FORCE} is set
    @item Boundary Clock (@t{CONFIG_TIME_BC}, PTP clock class 248)
      PPS is generated only when the device is synchronized. If @t{CONFIG_PPSGEN_FORCE}
      is set, PPS is generated at all times.
    @item Custom mode (@t{CONFIG_TIME_CUSTOM})
      PPS generation depends on configured PTP clock class, e.g. if PTP clock class
      is set to 6, PPS generation scheme will be the one of the GrandMaster
      listed above. If @t{CONFIG_PPSGEN_FORCE} is set, PPS is generated at all times.
  @end itemize

  Additionally to the conditions listed above, if PTP Best Master Clock Algorithm (BMCA) is enabled
  some spurious PPS can be generated during the transitory phase e.g. when the whole network is
  initialized. To suppress those @t{CONFIG_PPSGEN_GM_DELAY_TO_GEN_PPS_SEC} defines a delay time
  in seconds from the moment @sc{wrs} became a PTP grandmaster to the moment PPS starts to be generated.
  By default this parameter is set to 60s.
  
	The @t{CONFIG_PPSGEN_PTP_THRESHOLD_MS} option is applied when @sc{wrs} is synchronized to a regular
  (non-@sc{wr}) PTP master. This threshold defines a maximum offset to master
  (in miliseconds) when the @sc{wrs} is considered synchronized. Once the calculated offset falls
  below the configured threshold, PPS generation starts. To disable PPS, PTP offset must be
  greater than the @t{CONFIG_PPSGEN_PTP_THRESHOLD_MS} + 20%.
	Setting this parameter to 0 will block any PPS generation for those cases. 
	  
	The @t{CONFIG_PPSGEN_PTP_FALLBACK} option, if activated, enables the PPS generation
  when a slave instance programmed to use an extension protocol (WR, L1Sync, ...)
  is falling back to regular PTP synchronization. 
	
@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} (@t{RO_COMMUNITY}) and @t{private} (@t{RW_COMMUNITY}).

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

	Force SNMP object @t{wrsSwcoreStatus} to be always OK. It can be used
	to ignore all Ethernet frames switching related issues.

@c @item CONFIG_SNMP_SWCORESTATUS_HP_FRAME_RATE
@c
@c	Error via SNMP if the rate of HP frames on any port exceed given value.
@c	(currently not implemented)

@c@item CONFIG_SNMP_SWCORESTATUS_RX_FRAME_RATE
@c
@c	Error via SNMP if rate of RX frames on any port exceed given value.
@c	(currently not implemented)

@c@item CONFIG_SNMP_SWCORESTATUS_RX_PRIO_FRAME_RATE
@c
@c	Error if frame rate of any RX priority exceed given value.
@c	(currently not implemented)

@item CONFIG_SNMP_SYSTEM_CLOCK_MONITOR_ENABLED
@itemx CONFIG_SNMP_SYSTEM_CLOCK_DRIFT_THOLD
@itemx CONFIG_SNMP_SYSTEM_CLOCK_UNIT_DAYS
@itemx CONFIG_SNMP_SYSTEM_CLOCK_UNIT_HOURS
@itemx CONFIG_SNMP_SYSTEM_CLOCK_UNIT_MINUTES
@itemx CONFIG_SNMP_SYSTEM_CLOCK_CHECK_INTERVAL_DAYS
@itemx CONFIG_SNMP_SYSTEM_CLOCK_CHECK_INTERVAL_HOURS
@itemx CONFIG_SNMP_SYSTEM_CLOCK_CHECK_INTERVAL_MINUTES

	When @t{CONFIG_SNMP_SYSTEM_CLOCK_MONITOR_ENABLED} option is set, 
  the local system time is compared to the time 
  acquired from the external NTP server (according to @t{CONFIG_NTP_SERVER}).
  If the difference of time exceeds a given threshold
  (defined by @t{CONFIG_SNMP_SYSTEM_CLOCK_DRIFT_THOLD})
  expressed in seconds, an error is reported through SNMP.
		
	This comparison is done periodically at a rate expressed either in days 
	(@t{CONFIG_SNMP_SYSTEM_CLOCK_UNIT_DAYS}), hours (@t{CONFIG_SNMP_SYSTEM_CLOCK_UNIT_HOURS}) or
	minutes (@t{CONFIG_SNMP_SYSTEM_CLOCK_UNIT_MINUTES}).
	
	According to the selected unit, the repetition rate will be stored in the appropriate location:  
	@multitable @columnfractions .3 .7
	@headitem  Unit @tab Storage 
	@item  @t{...UNIT_DAYS} @tab @t{...CHECK_INTERVAL_DAYS}
	@item  @t{...UNIT_HOURS} @tab @t{...CHECK_INTERVAL_MINUTES}
	@item  @t{...UNIT_MINUTES} @tab @t{...CHECK_INTERVAL_MINUTES}
	@end multitable
	
	The @t{CONFIG_SNMP_SYSTEM_CLOCK_MONITOR_ENABLED} option is available only if a
	NTP server has been defined (@t{CONFIG_NTP_SERVER}).

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

  Configuration parameters to generate WR-synchronized 10MHz clock on the
  @i{clk2} output of the @sc{wrs} front panel. All these parameters are directly
  passed to @t{wrs_auxclk} tool of @sc{wrs}.
  In case you need to generate another clock frequency, please refer to
  @ref{wrs_auxclk}.

@item CONFIG_NIC_THROTTLING_ENABLED
@itemx CONFIG_NIC_THROTTLING_VAL

	Limit the Rx bandwidth of the traffic that goes from WR ports to Linux.
	Throttling can be enabled to prevent Linux using 100% of the processing
	power to receive Ethernet frames coming from WR ports to the CPU.
	To enable the throttling set @t{CONFIG_NIC_THROTTLING_ENABLED}.
	@t{CONFIG_NIC_THROTTLING_VAL} contains maximum allowed bandwidth
	in KB/s.

@item CONFIG_PPS_IN_TERM_50OHM
	Enable 50ohm termination for 1-PPS input.

@item CONFIG_CUSTOM_BOOT_SCRIPT_ENABLED
@itemx CONFIG_CUSTOM_BOOT_SCRIPT_SOURCE_LOCAL
@itemx CONFIG_CUSTOM_BOOT_SCRIPT_SOURCE_REMOTE
@itemx CONFIG_CUSTOM_BOOT_SCRIPT_SOURCE_REMOTE_URL

	It is possible to run a custom script at boot time. In this case please
        set @t{CONFIG_CUSTOM_BOOT_SCRIPT_ENABLED}.
        To run a script @t{/wr/bin/custom_boot_script.sh} from the local
        filesystem please set @t{CONFIG_CUSTOM_BOOT_SCRIPT_SOURCE_LOCAL}.

	As an alternative, you can choose
        @t{CONFIG_CUSTOM_BOOT_SCRIPT_SOURCE_REMOTE} and specify an URL
        (@t{http://}, @t{ftp://} or @t{tftp://}) in
        @t{CONFIG_CUSTOM_BOOT_SCRIPT_SOURCE_REMOTE_URL} whence
        the switch will download the script to be executed at boot time.
        The filename in the URL can include @t{HOSTNAME}, @t{IPADDR}
        and/or @t{MACADDR}, so the same configuration string can be used to set
        up a batch of switches with different configurations (similar to the
        @t{CONFIG_DOTCONF_URL}, please refer to @ref{The Configuration File}).

@item CONFIG_LLDPD_DISABLE
@itemx CONFIG_LLDPD_TX_INTERVAL
@itemx CONFIG_LLDPD_MANAGEMENT_PORT_DISABLE
@itemx CONFIG_LLDPD_MINIMUM_FRAME_SIZE

	Set of parameters related to the LLDP daemon (lldpd) configuration.
	Starting from version 6.0, switch by default sends LLDP frames on all
	ports (including management). In some installations it may be necessary
	to disable LLDP traffic on the management port (option
	@t{CONFIG_LLDPD_MANAGEMENT_PORT_DISABLE}). Additionally, in some cases
	(e.g. low latency networks) it may be necessary to disable
	LLDP at all (@t{CONFIG_LLDPD_DISABLE}).

	The transmission frequency of LLDP frames can be changed using option
	@t{CONFIG_LLDPD_TX_INTERVAL}.

	Networks that would benefit from the LLDP, but have low latency
	constraints can use option @t{CONFIG_LLDPD_MINIMUM_FRAME_SIZE}. With
	this option LLPD daemon includes only minimal set of information into
	LLPD frames.
	
	The table below contains comparison of LLDP frame fields for standard
	and minimal frame size (with
	@t{CONFIG_LLDPD_MINIMUM_FRAME_SIZE} option enabled). Size of some of
	those fields (like @t{System name} or	@t{System Description}) depends on
	the network configuration.

@multitable @columnfractions .25 .25 .35
@headitem Standard frame @tab Minimum frame @tab Description
@item 14
@tab 14
@tab ETH header
@item 9
@tab 9
@tab Chasis ID (with MAC)
@item 9
@tab 9
@tab Port ID (with MAC)
@item 4
@tab 4
@tab Time To Live
@item 2+len(System name)
@tab 2+len(System name)
@tab System name
@item 2+len(System desc.)
@tab 2+len(@t{WR-SWITCH})
@tab System description
@item 6
@tab 0
@tab Capabilities
@item 14
@tab 0
@tab Management Address
@item 7
@tab 7
@tab Port description
@item 2
@tab 2
@tab End of LLDP frame

@item 69

+len(System name)

+len(System desc.)
@tab 58

+len(System name)
@tab Total length

@end multitable

@item CONFIG_HTTPD_DISABLE

	Disable web interface on a switch.
	Web interface is now disabled by default and considered deprecated.
	A number of security vulnerabilities were found in the web interface
	(including CVE-2023-22577).
	Please note that it is still possible to enable web interface in
	run-time.
	@b{Users are strongly discouraged from using the web interface}.
	In exceptional cases the use of web-interface can be limited to well
	controlled networks.

@item CONFIG_MONIT_DISABLE

	Disable monitoring of running processes by @i{Monit}. @i{Monit} by
        default
        re-spawns processes that have died. This option should be used only 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 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 a switch.
	Don't use in production as this may affect the synchronization
	performance.

@item CONFIG_READ_SFP_DIAG_ENABLE

	Enable readout of additional monitoring information (DOM) like temperature,
  Tx/Rx power, from SFP transceivers. Please note that not all Gigabit Ethernet
  SFP transceivers provide the DOM structure.

@item CONFIG_OPTIMIZATION_DEBUGGING
@itemx CONFIG_OPTIMIZATION_NONE_DEBUGGING
@itemx CONFIG_OPTIMIZATION_SIZE_SPEED
@itemx CONFIG_OPTIMIZATION_SPEED
	
	Compilation options. Chose one of these four choices to control the 
	compilation flags.
	
	@t{CONFIG_OPTIMIZATION_DEBUGGING}: Should be the optimization level choice 
	  for the standard edit-compile-debug cycle.
	
	@t{CONFIG_OPTIMIZATION_NONE_DEBUGGING}: Compile without optimization and with debug information
	
	@t{CONFIG_OPTIMIZATION_SIZE_SPEED}: Optimize for size. Enables all -O2 optimizations except those 
	  that often increase the code size.
	
	@t{CONFIG_OPTIMIZATION_SPEED}: GCC performs nearly all supported optimizations 
	  that do not involve a space-speed trade-off.
	 
@item CONFIG_RTU_HP_MASK_ENABLE
@itemx CONFIG_RTU_HP_MASK_VAL

	Set the mask which VLAN priorities are considered High Priority traffic
	(this
	only concerns the traffic which is fast-forwarded).
	To enable a custom mask please set
	@t{CONFIG_RTU_HP_MASK_ENABLE}.
	@t{CONFIG_RTU_HP_MASK_VAL} shall contain the mask to be used.

@item CONFIG_VLANS_ENABLE

	Enable VLANs configuration. All below VLAN config options
	(@t{CONFIG_VLANS_*}) require this filed to be set.

@item CONFIG_VLANS_PORT@i{xx}_MODE_ACCESS
@itemx CONFIG_VLANS_PORT@i{xx}_MODE_TRUNK
@itemx CONFIG_VLANS_PORT@i{xx}_MODE_DISABLED
@itemx CONFIG_VLANS_PORT@i{xx}_MODE_UNQUALIFIED

	VLANs port mode configuration for ports 1..18.
	It can be one of: Access, Trunk, Disabled or Unqualified.
	For details please refer to the @ref{VLANs Configuration}

@item CONFIG_VLANS_PORT@i{xx}_UNTAG_ALL
@itemx CONFIG_VLANS_PORT@i{xx}_UNTAG_NONE

	Define whether to remove a VLAN tag from egress frames on port 1..18.

@item CONFIG_VLANS_PORT@i{xx}_PRIO

	Priority value used when tagging incoming frames or to locally override
	the priority (in Unqualified and Disabled modes).
	-1 disables the priority overwrite. Valid values are
	from -1 to 7.

@item CONFIG_VLANS_PORT@i{xx}_VID

  Define the  VID tagging incoming frames and notify PPSi which 
  VLAN shall be used for synchronization; only one VLAN number 
  shall be used.
  This parameter is available for @t{MODE_ACCESS} mode.
	The range of a valid VID is from 0 to 4094.

 	For details please refer to the @ref{VLANs Configuration}

@item CONFIG_VLANS_PORT@i{xx}_PTP_VID

  Notify PPSi which VLAN(s) shall it use for synchronization; semicolon separated list is allowed.
  This parameter is available for @t{MODE_TRUNK}, @t{MODE_DISABLED} and
  @t{MODE_UNQUALIFIED} modes. 
  The range of a valid VID is from 0 to 4094.

	For details please refer to the @ref{VLANs Configuration}

@item CONFIG_VLANS_PORT@i{xx}_LLDP_TX_VID
@itemx CONFIG_VLANS_PORT@i{xx}_LLDP_TX_PRIO

  Notify lldpd which VLAN shall it use for sending LLDP frames.
  Incoming LLDP frames are accepted on all VLANs.
  This parameter is available for @t{MODE_TRUNK}, @t{MODE_DISABLED} and
  @t{MODE_UNQUALIFIED} modes. 
  The range of a valid VID is from 0 to 4094.
  @t{VLANS_PORTxx_LLDP_TX_PRIO} defines the priority to be inserted into
  a VLAN tag of LLDP frames sent by lldpd.

@item CONFIG_VLANS_RAW_PORT_CONFIG

  Expert mode. Allow to control all VLAN parameters (CONFIG_VLANS_PORT@i{xx}_PTP_VID,
  CONFIG_VLANS_PORT@i{xx}_VID, CONFIG_VLANS_PORT@i{xx}_MODE_@i{yy} and
  CONFIG_VLANS_PORT@i{xx}_UNTAG_@i{xx} ) without any restrictions. 
  The user must be aware of what it is doing.
  
@item CONFIG_VLANS_VLAN@i{xxxx}

	Provide a configuration for VLAN from the range 0000-4094.
	This option is a comma separated string in the following format:

	@t{fid=<0..4094>,prio=<-1|0..7>,drop=<y|n>,ports=<1;2;...;...-...;18>}

	Where:
	@itemize
	@item @t{fid} is a associated Filtering ID (FID) number. This parameter
	  may be useful for complex VLAN configurations. In simple cases it can
	  be omitted. One FID can be
	  associated with many VIDs. RTU learning is performed per-FID.
	  Associating many VIDs with a single FID allowed shared-VLANs
	  learning.
	@item @t{prio} is a priority of a VLAN; can take values between -1 and
	  7;
	  -1 disables priority override, any other valid number takes
	  precedence over the port priority
	@item If @t{drop} is set to @t{y}, @t{yes} or @t{1}, all frames
	  belonging to this VID are dropped (note that frame can belong to a
	  VID as a consequence of per-port Endpoint configuration); can take
	  values @t{y}, @t{yes}, @t{1}, @t{n}, @t{no}, @t{0}
	@item @t{ports} is a list of ports separated with a semicolon sign
	  (";"); ports ranges are supported (with a dash character)
	@end itemize
	Example:

	@t{fid=4,prio=2,drop=n,ports=1;3-5;15}

	It sets FID as 4, priority 2, don't drop frames belonging to this VLAN,
	assign ports 1, 3-5 and 15 to this VLAN.

	For more details about VLANs configuration please refer to the
	@ref{VLANs Configuration}

	
@end table

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

This section describes how timing configuration works in the switch.
Please note that, comparing to previous firmware releases, the timing configuration
has considerably evolved in version @value{release_version}.
 
Timing configuration now depends on four sets of @t{dot-config}
variables: common port information, per-port information, sfp information and fiber
description.

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

@smallexample
# common port information
PTP_OPT_EXT_PORT_CONFIG_ENABLED=yes
...
# per-port information
CONFIG_PORT09_IFACE="wri9"
CONFIG_PORT09_FIBER=2
CONFIG_PORT09_INSTANCE_COUNT_1=yes
CONFIG_PORT09_INST01_PROTOCOL_RAW=yes
CONFIG_PORT09_INST01_PROFILE_WR=yes
CONFIG_PORT09_INST01_DESIRADE_STATE_SLAVE=yes
CONFIG_PORT09_INST01_EGRESS_LATENCY=226214
CONFIG_PORT09_INST01_INGRESS_LATENCY=226758
...
# sfp information
CONFIG_SFP00_PARAMS="pn=AXGE-1254-0531,tx=0,rx=0,wl_txrx=1310+1490"
...
# fiber infomation
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 (@t{CONFIG_PORT09_INST01_EGRESS_LATENCY}) and 
rx (@t{CONFIG_PORT09_INST01_INGRESS_LATENCY}) delays (around 226ns); the
values depend on trace length and other hardware-specific details
and are determined by the @sc{wr}  calibration procedure.  These values are
used by the @sc{WR} PTP daemon for accurate estimation of the transmission
link asymmetry.

@item The port is configured as WR slave (@t{CONFIG_PORT09_INST01_DESIRADE_STATE_SLAVE}) 
using raw Ethernet (@t{CONFIG_PORT09_INST01_PROTOCOL_RAW}) to synchronize using the
White-Rabbit protocol (@t{CONFIG_PORT09_INST01_PROFILE_WR}) and is deployed using
fiber type 2 (@t{CONFIG_PORT09_FIBER}) -- this number
is just a local enumeration of fiber types corresponding to an entry in
the @i{fiber information} section of the configuration. Most typical @sc{wr}
installations use a single type of fiber, indexed as "0" for every port.

@item The SFP transceiver used in this example emits 1310nm light for tx
and receives 1490nm light (this is part of the specification of the
transceiver, and cannot be auto-detected). Moreover, it has 0 constant
delay in both directions (tx/rx), determined by the @sc{wr} calibration
procedure.

@item The relative asymmetry of the fiber type being used (type 2 here), when
driven with 1310nm and 1490nm wavelengths, is characterized with an @i{alpha}
parameter of 0.00026787 (i.e. a ratio of 1.00026787). This value depends on
both, the fiber type and the wavelength used, and is determined, again,
by the @sc{wr} calibration procedure.

@end itemize

Please note that only one alpha value has to be provided for each fiber type.
The @i{alpha} in the opposite direction (@t{alpha_1490_1310}) is calculated
by the software.

@subsection Common port configuration

The following table lists the configuration items that are common to all port
instances of the WR switch.

@table @code

@item CONFIG_PTP_OPT_EXT_PORT_CONFIG_ENABLED

	  This option enables forcing the PTP state for each port instance using
    @t{CONFIG_PORT@i{xx}_INST@i{yy}_DESIRADE_STATE_*} parameters. 
	  When set, each port instance can be forces to always stay either in the
    slave, master or passive state.
	  The PTP Best Master Clock Algorithm (BMCA) is then disabled.
	  This option is only available for a boundary clock (@t{CONFIG_TIME_BC}).
	  For more details please refer to the IEEE 1588-2020 (clause 17.6.2)
	  
@item CONFIG_PTP_SLAVE_ONLY

	  A slaveOnly Ordinary Clock utilizes the slaveOnly state machine
	  which does not enable transition to MASTER state.
	  This option is only available if @t{PTP_OPT_EXT_PORT_CONFIG_ENABLED}
	  is not used.
	  For more details please refer to the IEEE 1588-2020 (clause 9.2.2.1)
	
@end table

@subsection  Per-port configuration

@table @code
@item @t{CONFIG_PORT@i{xx}_INSTANCE_COUNT_1}
@item @t{CONFIG_PORT@i{xx}_INSTANCE_COUNT_0}

  Each physical @sc{wrs} port can be configured to run several PPSi instances.
  However, only one instance per-port can be active at any given moment. This functionality
  is required to support several PTP extensions (e.g. @sc{wr}, @sc{HA} - High Accuracy
  profile). The active instance will dependent then of the profile used by the peer on
  the other side of the link.

  WR switch firmware version @value{release_version} implements only a single,
  @sc{WR} extension, therefore the possibility of running several instances on a single
  port is disabled. The number of port instances must be set to either 1
  (@t{CONFIG_PORT@i{xx}_INSTANCE_COUNT_1=yes}) or 0 (@t{CONFIG_PORT@i{xx}_INSTANCE_COUNT_0=yes})
  if the port is not used. @i{xx} represents the port number in the range 01 to 18. 

@end table

@subheading  Common instance configuration

A set of parameters common to all instances running on the same physical port. The 
@i{xx} value in the parameter name represents the port number.

@table @code

@item  CONFIG_PORT@i{xx}_IFACE
	 Used to define the physical port interface name: "wri[1-18]"
	 
@item  CONFIG_PORT@i{xx}_FIBER
	Identify the fiber type. This is a number (@i{zz}) referring to the corresponding 
	@t{CONFIG_FIBER@i{zz}_PARAMS})
	
@item  CONFIG_PORT@i{xx}_CONSTANT_ASYMMETRY
	Defines an additional constant asymmetry (e.g. of a fiber amplifier used in longhaul @sc{wr}
  networks) that should be compensated by @sc{wr} PTP calculations.

@end table
  
@subheading  Instance information description

All port instance parameters shared the following naming scheme:
CONFIG_PORT@i{xx}_INST@i{yy}_@i{pp}, where @i{xx} represents the port number,
@i{yy} the instance number (01 to 02) and @i{pp} a key describing the
parameter itself. 

@table @code

@item  CONFIG_PORT@i{xx}_INST@i{yy}_PROTOCOL_RAW
@itemx  CONFIG_PORT@i{xx}_INST@i{yy}_PROTOCOL_UDP_IPV4
  Network transport layer selection, either raw Ethernet or UDP over IPv4 can be used.
 
@item  CONFIG_PORT@i{xx}_INST@i{yy}_PROFILE_WR
@itemx  CONFIG_PORT@i{xx}_INST@i{yy}_PROFILE_PTP
  Profile selection. @t{CONFIG_PORT@i{xx}_INST@i{yy}_PROFILE_WR} must be set to use the White Rabbit profile and 
  @t{CONFIG_PORT@i{xx}_INST@i{yy}_PROFILE_PTP} for pure PTP profile.
  
@item  CONFIG_PORT@i{xx}_INST@i{yy}_MECHANISM_E2E
@itemx  CONFIG_PORT@i{xx}_INST@i{yy}_MECHANISM_P2P
  PTP delay mechanism, either 'end-to-end' (E2E) or 'peer-to-peer' (P2P) can be used.
  
@item  CONFIG_PORT@i{xx}_INST@i{yy}_DESIRADE_STATE_MASTER
@itemx  CONFIG_PORT@i{xx}_INST@i{yy}_DESIRADE_STATE_SLAVE
@itemx  CONFIG_PORT@i{xx}_INST@i{yy}_DESIRADE_STATE_PASSIVE
  If @t{CONFIG_PTP_OPT_EXT_PORT_CONFIG_ENABLED} is enabled then the desired PTP state
  of the instance must be defined as follows:
  @multitable @columnfractions .2 .8 
  @headitem State @tab Parameter
  @item MASTER  @tab @t{CONFIG_PORT@i{xx}_INST@i{yy}_DESIRADE_STATE_MASTER}
  @item SLAVE   @tab @t{CONFIG_PORT@i{xx}_INST@i{yy}_DESIRADE_STATE_SLAVE}
  @item PASSIVE @tab @t{CONFIG_PORT@i{xx}_INST@i{yy}_DESIRADE_STATE_PASSIVE}
  @end multitable
  
@item  CONFIG_PORT@i{xx}_INST@i{yy}_ASYMMETRY_CORRECTION_ENABLE
  This option is only accessible when the PTP profile is selected otherwise this option is enabled by default. 
  It is used to force the servo to integrate on its calculation the computation of the delay asymmetry. 
  
  
@item  CONFIG_PORT@i{xx}_INST@i{yy}_BMODE_AUTO
@itemx  CONFIG_PORT@i{xx}_INST@i{yy}_BMODE_MASTER_ONLY
  Indicates the BMCA mode to be used. The choice is available only when
  @t{CONFIG_PTP_OPT_EXT_PORT_CONFIG_ENABLED} is disabled. Either the regular PTP BMCA
  (@t{BMODE_AUTO}) or PTP masterOnly feature (@t{BMODE_MASTER_ONLY})
  can be used.
  For more details please refer to the IEEE 1588-2020 (clause 9.2.2.2)
  
@item  CONFIG_PORT@i{xx}_INST@i{yy}_EGRESS_LATENCY
@itemx  CONFIG_PORT@i{xx}_INST@i{yy}_INGRESS_LATENCY
  Defines the reception (@t{CONFIG_PORT@i{xx}_INST@i{yy}_INGRESS_LATENCY}) and transmission 
  (@t{CONFIG_PORT@i{xx}_INST@i{yy}_EGRESS_LATENCY}) constant delays expressed in pico-seconds.
  
@item  CONFIG_PORT@i{xx}_INST@i{yy}_ANNOUNCE_INTERVAL
  The mean time interval between transmissions of successive
	PTP Announce messages. The value expressed as base 2 logarithm.
  
@item  CONFIG_PORT@i{xx}_INST@i{yy}_ANNOUNCE_RECEIPT_TIMEOUT
  The number of announceIntervals that must pass without receipt of an Announce
  message before the occurrence of the PTP event ANNOUNCE_RECEIPT_TIMEOUT_EXPIRES.
	The value expressed as base 2 logarithm. For more details please refer to
  IEEE 1588-2020 standard.
    
@item  CONFIG_PORT@i{xx}_INST@i{yy}_SYNC_INTERVAL
	  The mean time interval between transmission of successive
	  PTP Sync messages, i.e., the sync-interval, when transmitted
	  as multicast messages. The value expressed as base 2 logarithm.

@item  CONFIG_PORT@i{xx}_INST@i{yy}_MIN_DELAY_REQ_INTERVAL
	  The minDelayRequestInterval specifies the minimum permitted
	  mean time interval between successive Delay_Req messages.
    The value expressed as base 2 logarithm.
    This option is available when 'end-to-end' delay mechanism is selected 
    (@t{CONFIG_PORT@i{xx}_INST@i{yy}_MECHANISM_E2E}).

@item  CONFIG_PORT@i{xx}_INST@i{yy}_MIN_PDELAY_REQ_INTERVAL
	  The minPDelayRequestInterval specifies the minimum permitted
	  mean time interval between successive Pdelay_Req messages.
    The value expressed as base 2 logarithm.
    This option is only available when 'peer-to-peer' delay mechanism is selected
    (@t{CONFIG_PORT@i{xx}_INST@i{yy}_MECHANISM_P2P}).

@item  CONFIG_PORT@i{xx}_INST@i{yy}_MONITOR
  Option to decide whether timing-related errors for a given port will be reported
  through SNMP.

@c  --------------------------
@c Option that will be available whe HA will be deployed
@c @item  CONFIG_PORT@i{xx}_INST@i{yy}_L1SYNC_ENABLED
@c @item  CONFIG_PORT@i{xx}_INST@i{yy}_L1SYNC_INTERVAL
@c @item  CONFIG_PORT@i{xx}_INST@i{yy}_L1SYNC_RECEIPT_TIMEOUT
@c @item  CONFIG_PORT@i{xx}_INST@i{yy}_L1SYNC_TX_COHERENCY_IS_REQUIRED
@c @item  CONFIG_PORT@i{xx}_INST@i{yy}_L1SYNC_RX_COHERENCY_IS_REQUIRED
@c @item  CONFIG_PORT@i{xx}_INST@i{yy}_L1SYNC_CONGRUENCY_IS_REQUIRED
@c @item  CONFIG_PORT@i{xx}_INST@i{yy}_L1SYNC_OPT_PARAMS_ENABLED
@c @item  CONFIG_PORT@i{xx}_INST@i{yy}_L1SYNC_OPT_PARAMS_TS_CORRECTED_TX_ENABLED


@end table

@subsection SFP name matching

Each time you plug an SFP transceiver into any of the @sc{wrs} ports, it has to be matched
against @t{dot-config} entries specifying timing parameters for the supported transceivers.
The matching algorithm reads from the SFP its vendor name (@i{vn}), part number (@i{pn}) and vendor
serial (@i{vs}). Then, SFP parameters are compared with values stored in
@t{CONFIG_SFP@i{xx}_PARAMS} @t{dot-config} entries:
@itemize
@item 
  The first try is to match a complete set of SFP identifiers (@i{vn}, @i{pn} and @i{vs}).
@item
  If a corresponding entry cannot be found, the match is limited to @i{vn} and @i{pn} and
  compared only with those @t{dot-config} entries that do not specify any vendor serial.
@item
  If the match still cannot be found, it is limited again, to @i{pn} only.

@end itemize

To understand better the operation of SFP matching algorithm, please see below some examples:
@itemize @bullet
@item
  @t{CONFIG_SFP00_PARAMS="vn=Axcen Photonics,pn=AXGE-3454-0531,vs=AX12390009629,
  tx=0,rx=0,..."}

  This entry can be matched only to one SFP transceiver as it specifies full set of parameters,
  including the unique vendor serial number (@i{vs}).

@item
  @t{CONFIG_SFP01_PARAMS="vn=Axcen Photonics,pn=AXGE-3454-0531,tx=0,rx=0,
  wl_txrx=1310+1490"}

  This entry may be matched only to all SFPs with vendor name "Axcen Photonics" and
  part number "AXGE-3454-0531", with exception to the SFP that was already matched to
  the previous entry @t{CONFIG_SFP00_PARAMS} (with vendor serial defined).

@item
  @t{CONFIG_SFP02_PARAMS="pn=AXGE-3454-0531,tx=0,rx=0,wl_txrx=1310+1490"}

  This entry will be matched to all SFPs with part number "AXGE-3454-0531",
  that were not matched by any of the entries listed earlier.

@end itemize

@subsection Other Deployments

All examples from previous sections match typical @sc{wr} networks we setup at
CERN with a single mono-modal fiber and 1310/1490 nm light wavelengths.

If you are using dual-fiber transceivers, which is acceptable for
short links, you use the same wavelength in both directions, over two
fibers of the same length. In this case you may omit the 
@t{wl_txrx} parameter in @sc{sfp} @t{dot-config} configuration and the
@t{alpha_@i{xx}_@i{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 of your fiber type. The
@t{CONFIG_FIBER@i{xx}_PARAMS} items are parsed as a list of
comma-separated assignments, so you can specify multiple
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.

@subsection Calibration

Calibration of per-port and per-@sc{sfp} delays as well as alpha is described in the
White Rabbit Calibration procedure:
@url{http://www.ohwr.org/projects/white-rabbit/wiki/Calibration}.

The delays used in the examples come from values listed in the calibration wiki
page, and you should not be surprised by the fact that the
transceiver (SFP) specifies the delays as zero.  By performing the
calibration procedure using this very transceiver type, the whole delay is
assigned to the port.  Other transceiver
types can be calibrated to either positive or negative values, to cope
with the @i{difference} between them and the default @t{AXGE} devices.

@c ==========================================================================
@node VLANs Configuration
@section VLANs Configuration

VLANs are handled at two levels:

@itemize
    @item Per-port configuration of the Endpoint. It allows to:
    @itemize
	@item tag ingress frames with VLAN-tag and specific priority
	@item specify behaviour depending on whether the frames are tagged or
	      untagged (@t{pmode})
@c 	@item map priorities into @i{Traffic Class} that are provided to RTU
	@item override priority before it is mapped into @i{Traffic Class},
	      i.e. translate into @i{Traffic Class} different priority than
	      the one received in the VLAN-tag
	@item remove VLAN-tag of given VID(s) from egress frames
	@item override VID in the VLAN-tag of a priority-tagged frame (VID=0x0)
    @end itemize

    @item Per-VID by configuring the RTU. It allows to:
    @itemize
	@item limit the ports to which frames with a given VID are forwarded
%	@item limit the ports from which frames with given VID are accepted
%	      @footnote{Should, but does not now. There is a bug in HDL.}
	@item override priority (@i{Traffic Class}) for a given VID
	@item drop frames with a given VID
    @end itemize

@end itemize
In terms of VLAN-tag, there are four types of VLAN-tags that can extend
the Ethernet Frame header:
@itemize
    @item @i{none}     -- tag is not included in the Ethernet Frame
    @item @i{priority} -- tag that has VID=@t{0x0}
    @item @i{VLAN}     -- tag that has VID in the range @t{0x001} to @t{0xFFE}
                          (1 to 4094)
    @item @i{null}     -- tag that has VID=@t{0xFFF} (4095)
@end itemize
The behaviour of each @t{pmode} that can be set per-port depends on the type of
VLAN-tag in the received frame.

@itemize
    @item Mode @t{ACCESS} (0x0), frames with:
    @itemize
	@item @i{no VLAN-tag}: are admitted, tagged with the values of VID and
			priority that are configured in @t{pvid} and @t{pprio}
			respectively
	@item @i{priority tag}: are admitted, the value of VID in their VLAN-tag is
                        overridden with the value configured in n @t{pvid}. This
                        new value of VID is provided to the RTU. If @t{pprio} is
                        not -1, the value of priority provided to RTU is
                        overridden with the configured @t{pprio}, the value of
                        priority in the VLAN-tag is unchanged.
	@item @i{VLAN tag}: are discarded
	@item @i{null tag}: are discarded

    @end itemize
    @item Mode @t{TRUNK} (0x1), frames with:
    @itemize
	@item @i{no VLAN-tag}: are discarded
	@item @i{priority tag}: are discarded
	@item @i{VLAN tag}: are admitted; if @t{pprio} is not -1, the value of
			priority provided to RTU is overridden with
			the configured @t{pprio}, the value of
                        priority in the VLAN-tag is unchanged.
	@item @i{null tag}: are discarded

    @end itemize
    @item Mode @t{DISABLED} (0x2), frames with:
    @itemize
	@item @i{no VLAN-tag}: are admitted. No other configuration is used even
			if set.
	@item @i{priority tag}: are admitted; if @t{pprio} is not -1, the value
			of priority provided to RTU is overridden with
			the configured @t{pprio}
	@item @i{VLAN tag}: are admitted; if @t{pprio} is not -1, the value of
			priority provided to RTU is overridden with
			the configured @t{pprio}
	@item @i{null tag}: are admitted; if @t{pprio} is not -1, the value of
			priority provided to RTU is overridden with
			the configured @t{pprio}
    @end itemize
    @item Mode @t{UNQUALIFIED} (0x3), frames with:
    @itemize
	@item @i{no VLAN-tag}: are admitted. No other configuration is used even
			if set.
	@item @i{priority tag}: are admitted. The value of VID in their VLAN-tag is
                        overridden with the value configured in n @t{pvid}. This
                        new value of VID is provided to the RTU. If @t{pprio} is
                        not -1, the value of priority provided to RTU is
                        overridden with the configured @t{pprio}, the value of
                        priority in the VLAN-tag is unchanged.
			@b{Note:} From version v6.0, providing a VID for this mode
			is supported in the dot-config, "Raw ports configuration"
			needs to be enabled.
	@item @i{VLAN tag}: are admitted; if @t{pprio} is not -1, the value of
			priority provided to RTU is overridden with
			the configured @t{pprio}
	@item @i{null tag}: discarded.
    @end itemize
@end itemize

Modes and their behaviour are summarized in the table below:

@center @image{VLAN_modes, 14cm,, VLAN_modes}

@b{The best and recommended way to configure VLANs is to use the @i{wrs_menuconfig}
tool for generating the @t{dot-config} file.} The @t{dot-config} file is used at
startup to set:
@itemize
  @item @i{per-port and per-VLAN} configuration - the @t{dot-config} is read
   by the @i{wrs_vlans} tool at startup
  @item @i{PPSi PTP VLAN configuration} - the @t{ppsi.conf} file is generated
   at startup from the @t{dot-config} file, it is then read by PPSi.
@end itemize
For an example configuration using @i{wrs_menuconfig} and @t{dot-config},
please see @ref{Example VLAN configuration by dot-config}).

An alternative for VLAN configuration, especially when experimenting with VLANs,
is to use the  @i{wrs_vlans} tool directly and to provide a custom @t{ppsi.conf}.
Beware that this method is more error-prone.

To have synchronization working with VLANs, a proper PTP VID needs to be
provided for ports in TRUNK, DISABLED and UNQUALIFIED mode. In the @t{dot-config}
file, it is the @t{CONFIG_VLANS_PORT@i{xx}_PTP_VID} configuration option. For
ports in ACCESS mode, the PTP VID is derived from the VID
(@t{CONFIG_VLANS_PORT@i{xx}_VID} in the @t{dot-config} file).
As an alternative you can write a custom @i{PPSi} configuration file with 
VLANs specified per-port.
You can simply copy the file generated in the WRS filesystem
(@i{/etc/ppsi.conf}) to a central @t{tftp}/@t{http}/@t{ftp} server where
@t{dot-config} files for your switches are stored and fetched on boot time or
permanently store it in the flash (for details, please check the
configuration options @t{CONFIG_PTP_*} in the
@ref{Configuration Items that Apply at Run Time}).


In the @i{PPSi} config file, for every VLAN-enabled port you should add
the following line:
@example
  vlan <VID1>[,<VID2>,...]
@end example
where @i{VID} is a VLAN ID configured on the port.

For an example configuration please see
@ref{Example VLAN configuration by tools}).


From the firmware v5.0, configuration of VLANs via the @t{dot-config} file was
possible with some limitations/simplifications which made the life of the user easier
but prevented some exotic VLAN configurations. From the firmware v6.0, all 
possible configuration can be set via dot-config. By default, the more
user-friendly configuration is used (similar to the one in v5.0). To have
full control over VLAN configuratin, "raw ports configuration" must be enabled.

Another alternative working on pre-v5.0 to set VLANs is to use the web
interface. However, as it is in v5.0, the web-interface is not capable to store
VLANs configuration into a @t{dot-config}.


@c =-------------------------------------------------------------------------
@node Example VLAN configuration
@subsection Example VLAN configuration

This section describes how to configure VLANs on a switch using the
@t{dot-config} and available command line tools.
The description assumes that switch has only these 3 ports.

In this configuration, port 1 is synchronised to an upstream WR device. This
device does not need to have any VLAN configuration. Port 1 is in @t{ACCESS} mode,
thus it tags the ingress Ethernet frames. VLAN-tags with VID 1 and priority
4 are added so that frames received at this port belong to VLAN 1. Port 1 also
untags the egress frames. In this configuration, only port 1
belongs to VLAN 1, which means that none of the traffic received on port 1 is
forwarded to other ports. The only traffic received on port 1 that is not
dropped are the PTP messages which are forwarded to the PTP daemon (@i{PPSi}). Such
an arrangement can be useful if the synchronisation is to be propagated through
WR network, i.e. between the upstream and this switch, but the data needs to be
separated.

The data is forwarded between ports 2 and 3. These ports belong to VLAN 2
(VID=2). Port 3 is in @t{ACCESS} mode and it tags the ingress frames with VID 2
and priority 7. This could be a port connected to a WR node that is a source of
critical traffic. This WR node does not need to support VLANs, however its
traffic needs to have the highest precedence in the network.

The traffic from port 3 is forwarded only to port 2. This port is in @t{TRUNK}
mode. It does not untag egress frames which means that the device connected to
it (a switch or a node) must be VLAN-aware. Port 2 accepts only frames that are
already tagged with the VLAN-tag. Out of the frames received at port 2, only
these with VID=2 are forwarded, all the other frames are dropped. The
frames with VID=2 are forwarded to PTP daemon and to port 3.

@c =-------------------------------------------------------------------------
@node Example VLAN configuration by dot-config
@subsubsection Example VLAN configuration by dot-config

To configure the switch in the way descibed in the
@ref{Example VLAN configuration}, the @i{wrs_menuconfig} tool should
be used to generate the @t{dot-config} file. In the @i{wrs_menuconfig} tool,
VLANs needs to be enabled in the VLANs submenu. Then, the Ports and VLANs
configurations need to be filled in properly, as can be seen in the figure
below.

@center @image{Example_VLAN_config, 16cm,, Example_VLAN_config}


Such generated @t{dot-config} file will contain the following config options
(and much more, of course):

@smallexample
PTP_OPT_EXT_PORT_CONFIG_ENABLED=yes
# Port 1 configuration
CONFIG_PORT01_IFACE="wri1"
CONFIG_PORT01_FIBER=0
CONFIG_PORT01_INSTANCE_COUNT_1=yes
CONFIG_PORT01_INST01_PROTOCOL_RAW=yes
CONFIG_PORT01_INST01_PROFILE_WR=yes
CONFIG_PORT01_INST01_DESIRADE_STATE_SLAVE=yes
CONFIG_PORT01_INST01_EGRESS_LATENCY=0
CONFIG_PORT01_INST01_INGRESS_LATENCY=0
...
# Port 2 configuration
CONFIG_PORT02_IFACE="wri2"
CONFIG_PORT02_FIBER=0
CONFIG_PORT02_INSTANCE_COUNT_1=yes
CONFIG_PORT02_INST01_PROTOCOL_RAW=yes
CONFIG_PORT02_INST01_PROFILE_WR=yes
CONFIG_PORT02_INST01_DESIRADE_STATE_MASTER=yes
CONFIG_PORT02_INST01_EGRESS_LATENCY=0
CONFIG_PORT02_INST01_INGRESS_LATENCY=0
...
# Port 3 configuration
CONFIG_PORT03_IFACE="wri3"
CONFIG_PORT03_FIBER=0
CONFIG_PORT03_INSTANCE_COUNT_1=yes
CONFIG_PORT03_INST01_PROTOCOL_RAW=yes
CONFIG_PORT03_INST01_PROFILE_WR=yes
CONFIG_PORT03_INST01_DESIRADE_STATE_MASTER=yes
CONFIG_PORT03_INST01_EGRESS_LATENCY=0
CONFIG_PORT03_INST01_INGRESS_LATENCY=0
...
# Vlans configuration
CONFIG_VLANS_ENABLE=y
CONFIG_VLANS_PORT01_MODE_ACCESS=y
CONFIG_VLANS_PORT01_UNTAG_ALL=y
CONFIG_VLANS_PORT01_PRIO=4
CONFIG_VLANS_PORT01_VID="1"

CONFIG_VLANS_PORT02_MODE_TRUNK=y
CONFIG_VLANS_PORT02_PTP_VID="2"

CONFIG_VLANS_PORT03_MODE_ACCESS=y
CONFIG_VLANS_PORT03_UNTAG_ALL=y
CONFIG_VLANS_PORT03_PRIO=7
CONFIG_VLANS_PORT03_VID="2"

CONFIG_VLANS_ENABLE_SET1=y
CONFIG_VLANS_VLAN0001="fid=1,prio=4,drop=n,ports=1"
CONFIG_VLANS_VLAN0002="fid=2,prio=4,drop=n,ports=2;3"
@end smallexample


NOTE: It is highly discouraged to modify the @t{dot-config} file by hand.
It is very error-prone.

@c =-------------------------------------------------------------------------
@node Example VLAN configuration by tools
@subsubsection Example VLAN configuration by tools

To configure the switch in the way described in the
@ref{Example VLAN configuration}, using the @i{wrs_vlans} command line tool
and custom @t{ppsi.conf} file, please perform the following actions:

Clear the current configuration:
@smallexample
# wrs_vlans --clear
# wrs_vlans --rvid 0 --del
@end smallexample

Set ports' configuration by using the @t{wrs_vlans} tool:
@smallexample
# wrs_vlans \
    --port 1 --pmode 0 --pprio 4 --pvid 1 --puntag 1 \
    --port 2 --pmode 1 --pprio -1  \
    --port 3 --pmode 0 --pprio 7 --pvid 2 --puntag 1
@end smallexample

Set VID configuration by using the @t{wrs_vlans} tool:
@smallexample
# wrs_vlans \
    --rvid 1 --rprio 4 --rdrop 0 --rmask 0x00001 \
    --rvid 2 --rprio 4 --rdrop 0 --rmask 0x00006
@end smallexample

For details about @t{wrs_vlans} please refer to the @ref{wrs_vlans}.

@i{PPSi} configuration that should be placed into @t{ppsi.conf}:
@smallexample
port wri1-raw
proto raw
iface wri1
desiredState  slave
profile  wr
vlan 1

port wri2-raw
proto raw
iface wri2
desiredState  master
profile  wr
vlan 2

port wri3-raw
proto raw
iface wri3
desiredState  master
profile  wr
vlan 2
@end smallexample

NOTE: The @t{ppsi.conf} in /etc/ folder is automatically generated from the
@t{dot-config} file on startup, thus you will loose your changes if you
update directly @t{ppsi.conf} in /etc/. To use custom @t{ppsi.conf}, you
need to specify its path in dot-config using the parameter:
CONFIG_PTP_CUSTOM.

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

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

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

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

During barebox/kernel boot the status LED is off. When @t{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 (error) sent by other process, HAL sets the status
LED to orange.
When the regular reboot is performed status LED is turned off. In case of
a kernel crash the LED remains unchanged.

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

Under each WR port there are two LEDs, left and right. The left LED has two
functions. First: it blinks @i{orange} when a particular port is populated
with an SFP and the Low Phase Drift Calibration is ongoing; this happens after
inserting a fiber and after the WR switch start/reboots.
Second: it is on (permanently, not blinking) when a particular
port is populated with an SFP and the link is up. Its color depends on
the state of PTP instance running on the port:
@itemize
    @item @i{green}: WR slave
    @item @i{yellow}: WR master
    @item @i{orange}: all other
@end itemize
If there are multiple instances on a particular port the slave state (green)
takes precedence over master (orange). Master takes precedence over other
states (yellow).

The right LED is green when a particular port is synchronized to the master.
When a packet is transmitted or received on a port the right LED blinks orange.
If a port is also synced then it blinks yellow instead.


@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 5 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 may be useful to
        change the MAC or IP address of the ARM network port, change the
        autoboot timeout or change the autoselect choice. 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.

@b{Note}: with the Linux kernel 2.6.39 we suggested use of @t{root=nfs}, but
this convention is no more supported in Linux, please use @t{root=/dev/nfs}.

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 in a newly-created
empty directory:

@example
   tar xzf $WRS_OUTPUT_DIR/images/wrs-image.tar.gz
@end example

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 from a
released @t{wrs-firmware} file (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



Most of the 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 lm32-vuart
	The tool allows connecting to the virtual UART of the LM32 soft-core CPU.
	It can be used to observe log messages from the SoftPLL (the same as
	@i{FPGA Test}
	physical UART port available in the back of a WR switch). Use
	@code{Ctrl+C} escape combination to go back to WR Switch Linux shell.

@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 reads 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. Please check
        @t{wr_mon}'s help (@t{--help} parameter) for further information.
        (This is probably the most important diagnostic tool on the switch.)

@item wrs_pps_control
        A tool to manually enable/disable/read status of  PPS output.
        It can also enable/disable/read status of the 50ohm termination for 1-PPS input.
        Usage:

        ``@t{wrs_pps_control pps on}'' enables the PPS output,

        ``@t{wrs_pps_control pps off}'' disables the PPS output,

        ``@t{wrs_pps_control pps read}'' checks whether PPS output is enabled or disabled.

        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.
        To on/off/read the 50ohm termination for 1-PPS input use
        @t{wrs_pps_control} with a parameter @t{50ohm-term-in} followed by
        @t{on}, @t{off} or @t{read}.

@item wr_date
@anchor{wr_date}

	The program can read or set the White Rabbit date. Usage:
        
        ``@t{wr_date set} @i{value}'' sets an arbitrary date and time as the system time,

        ``@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{/etc/wr_date.conf}
        exists and includes a line of the form @t{ntpserver 192.168.16.1}.
        The file @t{/etc/wr_date.conf} is created at boot time by the script
        @t{apply_dot-config} if a NTP server is defined (@t{CONFIG_NTP_SERVER}).

        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 software, gateware, hardware 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 was
        replaced.

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

@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 the web interface to apply changes in
        the local @t{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{dot-config}.
        This script is called by @t{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 output on the front panel.

@item wrs_pstats
	The tool is used to read various per-port statistics counters from the
	console. Please note that the same values are also provided through SNMP
	objects.

@item wrs_sfp_dump
	Dump the content of SFPs internal memory. This tool can read SFP info
	from HAL's shmem or directly from SFPs via i2c bus. Please note that
	reading directly via i2c can cause race condition on i2c bus. The tool is not
	recommended to be used in production.
	The race condition can cause errors while reading SFPs memory,
	wrong notification of LEDs, the false insert/remove SFP notifications.

	This tool can also write SFPs internal memory. This functionality can
	be used to fix SFPs reporting i.e. wrong checksum. Use this option with
	care.
	
	For more details please refer to the tool's help.

@item wrs_throttling
	The tool is used to control Rx bandwidth throttling of the traffic that
	goes from WR ports to Linux. It configures the FPGA module with a
	maximum allowed bandwidth in KB/s. Throttling can be enabled to prevent
	Linux using 100% of the processing power to receive Ethernet frames
	coming from WR ports to the CPU. This tool is executed by default at
	boot time with parameters from the dot-config. For more
	information, please refer to the
	@ref{Configuration Items that Apply at Run Time}.

@item ethtool
  The standad Linux tool used to query or control network driver and hardware
  settings. In WRS the number of parameters that this tool can change is
  limited. However, this tool can be used to:

  ``@t{ethtool -s wriX autoneg off}'' disables (or enable if @t{on} is used)
  autonegotiation

  ``@t{ethtool --set-priv-flags wriX "Unidirectional Enable" on}'' enables
  (or disables if @t{off} is used) transmit regardless of whether a valid link
  has been established

  ``@t{ethtool --set-priv-flags wriX "Accept RX Jumbo Frames" on}'' accepts
  (or drops if @t{off} is used) RX Jumbo Frames

@c FIXME: document rtu_stat spll_dbg_proxy
@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 can be read from the @t{dot-config} file pointed by @t{-f} or
@t{--file} parameter (for @t{dot-config} details please check
@ref{Configuration Items that Apply at Build Time}).
Additionally, the configuration can be specified using parameters below.
The details of VLANs configuration are discussed in
@ref{VLANs Configuration}.

The @i{wrs_vlans} 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. For port modes please refer
  to the @ref{VLANs Configuration}.

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

  Per-VLAN configuration of the Routing Table Unit, used to configure port mask
  describing which ports 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 <0..3>
  Sets VLAN mode for a port (@t{0} -- @t{ACCESS}, @t{1} -- @t{TRUNK},
  @t{2} -- @t{DISABLED}, @t{3} -- @t{UNQUALIFIED})

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

@item --pprio <-1|0..7>
  Sets priority for tagging ingress frames. @t{-1} disables priority overwrite.

@item --puntag <0|1>
  Disables or enables 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 <0x0..0x3ffff>
  Mask defines which physical ports of the WRS belong to a configured VLAN.

@item --rfid <0..4094>
  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 <-1|0..7>
  Forces 802.1q priority override for VLAN. Setting @i{prio} to @t{-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

  Clear configuration. Add a default rule to pass all traffic between ports.

@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 on the front panel.

@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

@section wrs_pstats

The @i{wrs_pstats} shell tool can be used to read per-port statistics counters
from FPGA. When it is executed without any parameters all displayed values are
counted from the moment the tool was started. In case you're interested in the
values gathered from the start of WR switch, you can use @i{-s} option. The
following counters for each port are reported:

@multitable @columnfractions .18 .8
@headitem Counter @tab Description
@item @code{0:Tu-run} @tab Number of TX underrun errors
@item @code{1:Ro-run} @tab Number of RX overrun errors
@item @code{2:Riv-cd} @tab Number of invalid 8B10B characters received
@item @code{3:Rsyn-l} @tab Number of RX link synchronization lost events
@item @code{4:Rpause} @tab Number of received pause frames
@item @code{5:Rpf-dp} @tab Number of received frames dropped by the Packet Filter
@item @code{6:Rpcs-e} @tab Number of PCS errors during frame reception
@item @code{7:Rgiant} @tab Number of received giant frames
@item @code{8:Rrunt} @tab Number of received runt frames (smaller than 64 bytes)
@item @code{9:Rcrc_e} @tab Number of CRC errors in received frames
@item @code{10-17:Rpcl_0-7} @tab Number of received frames qualified by Packet Filter to classes 0 to 7
@item @code{18:Tframe} @tab Number of transmitted frames
@item @code{19:Rframe} @tab Number of received frames
@item @code{20:Rrtu_f} @tab Number of RX frames dropped due to RTU full
@item @code{21-28:Rpri_0-7} @tab Number of received 802.1Q frames with priorities 0 to 7
@item @code{29:RTUreq} @tab Number of RTU requests
@item @code{30:RTUrsp} @tab Number of RTU responses
@item @code{31:RTUdrp} @tab Number of frames dropped by the RTU
@item @code{32:RTUhp} @tab Number of high priority frames routed by RTU
@item @code{33:RTUf-f} @tab Number of forwarded frames matched by RTU fast match engine
@item @code{34:RTUn-f} @tab Number of not forwarded frames matched by RTU fast match engine
@item @code{35:RTUfst} @tab Number of RTU fast match decisions
@item @code{36:RTUful} @tab Number of RTU full match decisions
@item @code{37:RTUfwd} @tab Total number of frames forwarded by RTU
@item @code{39:NIC_Tx} @tab Number of frames sent from WR Switch ARM to that port

@end multitable

@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 the WRS 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 the 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, is something like the following:

@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 the 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 similar 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 our project pages. Please visit:
@itemize
   @item Frequently Asked Questions: @url{http://www.ohwr.org/project/white-rabbit/wiki/FAQswitch}
   @item Issues for WR Switch SW project: @url{http://www.ohwr.org/project/wr-switch-sw/issues}
   @item Issues for WR Switch HDL project: @url{http://www.ohwr.org/project/wr-switch-hdl/issues}
@end itemize
If you have any problem with this firmware and you don't find help in the above links,
feel free to reach us on the @i{white-rabbit-dev} mailing list.


@c ==========================================================================
@node Dumping WRS state (wrs_dump)
@section Dumping WRS state (wrs_dump)

The @t{wrs_dump.sh} can dump the current state of a switch. Its use can be
helpful when reporting a bug or saving a switch's state for later analysis.

The tool can be found in WRS software repository (or accessed directly via
weblink @url{https://ohwr.org/project/wr-switch-sw/blob/master/userspace/host_tools/wrs_dump.sh}).

The @t{wrs_dump.sh} is independent from the WR software, it can be used on
different versions of firmware.
It can be run from a host computer or even WR switch
(however, @t{wrs_dump.sh} is not included in the firmware).
It connects form a host machine via @t{ssh} to a switch and gets the following
information in the order:
@itemize
  @item firmware version information (output of @t{wrs_version})
  @item logged users and uptime (output of @t{w} command)
  @item process list (output of @t{ps} command)
  @item dump of shared memory of WR specific daemons (output of @t{wrs_dump_shmem})
  @item detailed port statistics (output of @t{wrs_pstats})
  @item timing status and configuration (output of @t{wr_mon})
  @item local disk usage (output of @t{df})
  @item information about free memory (output of @t{free})
  @item detailed information about memory usage (output of @t{/proc/meminfo})
  @item information about network interfaces (output of @t{ifconfig})
  @item traffic on working WR ports; using @t{tcpdump} of up ports (or on
        specified ports depending on the parameter)
  @item output of PPSI's verbose messages (if selected by the parameter);
        it may affect synchronization (not seen in practice)
  @item output of @t{dmesg}
  @item information about VLAN configuration (output of @t{wrs_vlans --list}
        and  @t{wrs_vlans --plist})
  @item information about routing (switching) rules (output of @t{rtu_stat})
  @item SFP information (output of @t{wrs_sfp_dump -L -d -x})
  @item copy of dot-config
  @item copy of shared memory files of WR specific daemons
  @item copy content of /tmp
@end itemize
During the run of this tool many parameters could have changed their values.
Such information might be  important during further investigation. For this
reason the tool reads once more some information:
@itemize
  @item process list (output of @t{ps} command)
  @item dump of shared memory of WR specific daemons (output of @t{wrs_dump_shmem})
  @item detailed port statistics (output of @t{wrs_pstats})
  @item timing status and configuration (output of @t{wr_mon})
  @item local disk usage (output of @t{df})
  @item information about free memory (output of @t{free})
  @item detailed information about memory usage (output of @t{/proc/meminfo})
  @item information about network interfaces (output of @t{ifconfig})
@end itemize

By default, the gathered information is stored in the directory
@t{wrs_dump-<hostname>-<date>}. If needed the output directory can be changed
with @t{--output} parameter.
It is possible to define the list of ports that @t{tcpdump} shall be run on.
The verbosity of PPSi can be set to the predefined value
(@t{--ppsi-verbose <verbose_mode>}) or set to dump all messages
(@t{--ppsi-verbose-all}) for 60 seconds.

If for some reason it is not possible to use password or ssh-keys for
authentication to login to the switch, the user can store the password in
host's @t{WRS_PSWD} environment variable.
The content of this environment variable will be passed to the @t{sshpass}
command instead.

Example run of @t{wrs_dump.sh}:
@smallexample
$ ./wrs_dump.sh root@@wrs
Example printout:
root@@wrs ppsi_verbose_mode=
Open ssh connection...
Provide password
Password:
ssh connection established
Store data in the directory wrs_dump-wrs-2022-08-28_04-46-52
Get version... Done
Get w (logged users and uptime)... Done
Get process list... Done
Get output of wrs_dump_shmem... Done
Get output of wrs_pstats... Done
Get output of wr_mon... Done
Get output of df... Done
Get output of free... Done
Get output of /proc/meminfo... Done
Get output of ifconfig... Done
Get tcpdump for up ports: wri1 wri4 wri15
Get output of tcpdump wri1... Done
Get output of tcpdump wri4... Done
Get output of tcpdump wri15... Done
Get output of dmesg... Done
Get output of wrs_vlans --list... Done
Get output of wrs_vlans --plist... Done
Get output of rtu_stat... Done
Get output of wrs_sfp_dump -L -d -x... Done
Copy dot-config... Done
Copy shmem... Done
Copy /tmp... Done
Get again process list... Done
Get again output of wrs_dump_shmem... Done
Get again output of wrs_pstats... Done
Get again output of wr_mon... Done
Get again output of df... Done
Get again output of free... Done
Get again output of /proc/meminfo... Done
Get again output of ifconfig... Done
Closing ssh connection... Done
@end smallexample

@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
