\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 June 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.1
@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 Top node is not included in tex
@unnumbered 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}).
@item @i{White Rabbit Switch: Radius Vlan}: describes functionality and usage
of Radius Vlan which is a subset of IEEE 802.1X.
When a devices is detected on a configured port, a Radius server is queried
for authorization.
@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 v6.0.x to v@value{release_version}
@section Upgrade from v6.0.x to v@value{release_version}
Apart from the instructions in the previous section, there
is no special action needed from the user when upgrading firmware from
v6.0.x to v@value{release_version}.
The most important changes introduced in v6.1 are:
@itemize
@item Display information about GrandMaster in @t{wr_mon}
@item Informing about unrecognized SFP in @t{wr_mon}
@item Improved reporting of offset between NTP and WR time via SNMP
@item Support of disabling SFP's TX laser with @t{wrs_sfp_dump}
@item Fixes in handling of SFP's diagnostics (if SFP diagnostic is used with
firmware v6.0.x it can corrupt SFP's eeprom!)
@item Detection whether a switch is a low-jitter version (displayed in
@t{wrs_version}, SNMP and web interface), and fix to leap-seconds.list update
@item Addition of a subset of IP-MIB, BRIDGE-MIB and QBRIDGE-MIB objects
to SNMP support
@item Implementation of @t{sysObjectID} OID value to reflect WRS manufacturer and
HW version
@item Implementation of radius-802.1X for MAC authentication (subset of IEEE 802.1X)
@item Support of LLDP with VLANs
@end itemize
The following configuration items were added to the dot-config:
@itemize
@item LLDP related
@itemize
@item @t{CONFIG_VLANS_PORT@i{xx}_LLDP_TX_VID}
@item @t{CONFIG_VLANS_PORT@i{xx}_LLDP_TX_PRIO}
@end itemize
@item Radius related:
@itemize
@item @t{CONFIG_RVLAN_ENABLE}
@item @t{CONFIG_RVLAN_PMASK}
@item @t{CONFIG_RVLAN_AUTH_VLAN}
@item @t{CONFIG_RVLAN_NOAUTH_VLAN}
@item @t{CONFIG_RVLAN_OBEY_DOTCONFIG}
@item @t{CONFIG_RVLAN_RADIUS_SERVERS}
@item @t{CONFIG_RVLAN_RADIUS_SECRET}
@end itemize
@item SNMP related:
@itemize
@item @t{CONFIG_SNMP_SYSCONTACT}
@item @t{CONFIG_SNMP_SYSLOCATION}
@end itemize
@item @t{CONFIG_PPSGEN_FR_ON_SYNC_ONLY}
@end itemize
Firmware v6.1 uses the same GW as v6.0.x, so the calibration values remain
the same.
Please note that Web interface remains disabled by default.
@c ==========================================================================
@node Upgrade from v5.0.1 to v6.0.x
@section Upgrade from v5.0.1 to v6.0.x
Apart from the instructions in the introduction to this chapter, there
is no special action needed from the user when upgrading firmware from
v5.0.1 to v6.0.x. 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
@footnote{Actually, web interface is disabled by default from firmware
v6.0.2.
The documentation of v6.0 claimed that it was already disabled, but it was
wrong.}
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}@footnote{@i{PLL mode} from firmware v6.1}
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{delayAsymmetry} is the previously @i{Total link asymmetry}
@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{offsetFromMaster} 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_KRB5} for Kerberos authentication.
For the later one it is obligatory to specify Kerberos Realm
in @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
@itemx CONFIG_PPSGEN_FR_ON_SYNC_ONLY
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 by default always enabled.
If @t{CONFIG_PPSGEN_FR_ON_SYNC_ONLY} is set, then PPS is generated only
when a switch becomes slave and synchronize to another master.
@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 network hierarchy is
being established (during startup or re-organization). 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_RVLAN_ENABLE
@itemx CONFIG_RVLAN_PMASK
@itemx CONFIG_RVLAN_AUTH_VLAN
@itemx CONFIG_RVLAN_NOAUTH_VLAN
@itemx CONFIG_RVLAN_OBEY_DOTCONFIG
@itemx CONFIG_RVLAN_RADIUS_SERVERS
@itemx CONFIG_RVLAN_RADIUS_SECRET
Configuration items related to @i{radiusvlans}, which can be used to
limit access to WR network for connected devices based on MAC address.
For more details please refer to @i{White Rabbit Switch: Radius Vlan}.
@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_SYSCONTACT
Free text intended to be the textual identification of the contact
person for this switch, together with information on how to contact this
person. Reported by SNMP as SNMPv2-MIB::sysContact.0
@item CONFIG_SNMP_SYSLOCATION
Free text intended to be The physical location of this node.
Reported by SNMP as SNMPv2-MIB::sysLocation.0
@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 the timing parameters and wavelength for the
supported transceivers.
The matching algorithm reads from the SFP its vendor name (@i{vn}), part number (@i{pn}), vendor
serial (@i{vs}) and TX wavelength in @t{nm}. Note that it only reads the integer part (i.e. rounded down)
of the TX wavelength, as shown by @t{wrs_sfp_dump}. Then, these SFP parameters are compared
with the values stored in the @t{CONFIG_SFP@i{xx}_PARAMS} @t{dot-config} entries:
@itemize
@item
The @i{wl_txrx} field in the @t{CONFIG_SFP@i{xx}_PARAMS} must contain the transmit and receive
wavelengths of the SFP in @t{nm}, as integers, separated by a '+'. The TX wavelength as
reported by the SFP is matched against the tx entry (first number) in the @i{wl_txrx} entry. If these do
not match, then this @t{CONFIG_SFP@i{xx}_PARAMS} entry cannot match against this SFP.
@item
For the remaining parameters, first a match against all the vendor SFP identifiers
(@i{vn}, @i{pn} and @i{vs}) is attempted.
@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,wl_txrx=1490+1310"}
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=1490+1310"}
This entry may be matched only to all SFPs with vendor name "Axcen Photonics",
part number "AXGE-3454-0531" and a TX wavelength of 1490 nm, with exception of 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-1254-0531,tx=0,rx=0,wl_txrx=1310+1490"}
This entry will be matched to all SFPs with part number "AXGE-3454-0531" and TX wavelength of
1310 nm, 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. Each entry has the form @t{alpha_1310_1490=2.6787e-4}, where the numbers
are again the wavelength in integer @t{nm}. Note that only one value of alpha is needed for
each pair of wavelengths, the switch will calculate the correct value of alpha when the wavelengths
are switched around.
Example: @t{CONFIG_FIBER00_PARAMS="alpha_1310_1490=2.6787e-04"}
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 configuration, "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 synchronized 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 synchronization 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.
Note that the IP address of the TFTP server can be specified using the DHCP
@t{next-server <address>} configuration option.
@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
by 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 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 assembly_snmpd_conf.sh
The script is used to assembly SNMP daemon's 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 com
The program is a simple program for talking with serial ports.
@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 on WRS with the
following commands:
``@t{ethtool -s wriX autoneg off}'' disables (or enable if @t{on})
autonegotiation @footnote{WRS does not support other link speeds
than 1Gbps, thus when autonegotation is enabled, no other link speed
can be actually negotiated}
``@t{ethtool --set-priv-flags wriX "Unidirectional Enable" on}'' enables
(or disables if @t{off}) transmission 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
@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-lm32
@itemx load-virtex
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.
@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 ppsi_conf
The tool that can be used to change some of PPSi's parameters in
runtime.
Some parameters that can be changed are global (e.g. @t{priority1},
@t{servo tracking}), other are specific for PPSi instance
(e.g. @t{delay-req-interval}, @t{sync-interval}).
This tool supports a change of parameter's value for all instances on
a given port or for all existing instances.
NOTE: This tool can be used to change in runtime diagnostics level
(verbocity) of PPSi, global and per instance.
For more information about supported parameters please refer to
PPSi's documentation or tool's help (@t{--help} parameter).
@item ptpdump
This is a sniffer for @sc{ptp} frames. It reports all Ethernet frames
and UDP datagrams that talk @sc{ptp}, from a specific network interface.
The output format is line-oriented to help running @i{grep} over log
files.
The number of blank lines between frames depends on how much time
elapsed between them; this should help identifying sync/follow-up
pairs at a glimpse of the eye.
The program receives one optional argument on the command line, which is
the name of the interface where it should listen; by default it uses
@t{eth0}.
@item rtu_stat
The tool allows to configure switching rules
for each port via RTU daemon. The @t{--help} option
lists all configuration items of the tool.
@item rvlan-status
@item rvlan-debug
The tools allow to check status, as well as debug and throttle verbosity
of the Radius Vlan mechanism, if enabled. See details in a separate
manual: @i{White Rabbit Switch: Radius Vlan}.
@item sdb-read
The tool, copied from the @t{fpga-config-space} project.
For details please refer to the @ref{sdb-read}.
@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.
@c spll_dbg_proxy
@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 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 wr_phytool
A tool to read and write PHY registers in the switch.
@item wrs_auxclk
The tool allows to setup the parameters of a clock generated on the
@i{clk2} SMC output on the front panel.
For details please refer to the @ref{wrs_auxclk}.
@item wrs_checkcfg
Simple program performing a basic validation of a @t{dot-config}.
Used during startup for validation of a received @t{dot-config}.
@item wrs_dump_shmem
Probably the most useful tool for advanced debugging of a switch.
It can dump and interpret many internal variables from HAL, rtud, PPSi
and SoftPLL.
The output is presented in a grep-friendly format as "@t{NAME: VALUE}".
Please check its help (@t{--help} parameter) for more information.
@item wrs_leapsec
This tools read the local time and checks for an incoming leap second.
If it detects a incoming leap seconds in the next 12 hours,
the information is set in the kernel and will be available for PPSi.
@item wrs_menuconfig
@itemx wrs_nconfig
wrs_menuconfig and wrs_nconfig use a different framework to display and
change switch configuration.
This is the preferred way over manual editing of @t{dot-config},
since menuconfig can preserve number of constraints on values and
between configuration items.
Please make sure that after the changes are done, the local config
is configured to be used
(configuration item @t{CONFIG_DOTCONF_SOURCE_LOCAL}).
@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 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.
For details please refer to the @ref{wrs_pstats}.
@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_status_led
Simple tool used during startup and restart to control the status LED.
@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 wrs_version
Print information about the software, gateware, hardware version of the WRS.
Please check the help message.
@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 wrs_watchdog
A daemon used to reset the SWcore HDL if there is still some hidden bug
inside. The number of occurred timeouts can be read using
@t{-g} parameter and is also reported via SNMP in
@t{WR-SWITCH-MIB.txt::wrsGwWatchdogTimeouts}.
@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_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 2ns. The @code{--sigdel} parameter allows to add a precise delay
to the FPGA-generated clock to avoid such jitter. This delay is specified in
steps, where each step is around 150ps. This value, same as the
@code{--cshift} parameter, is constant for a given bitstream so should be
verified only once.
@item --ppshift <steps>
If one needs to precisely align 1-PPS output with the @i{clk2} aux clock using
@code{--cshift} parameter is not enough as it has 4ns granularity. In that
case @code{--ppshift} lets you shift 1-PPS output by a configured number
of 150ps steps. However, please have in mind that 1-PPS output is used as a
reference for WR calibration procedure. Therefore, once this parameter is
modified, the device should be re-calibrated. Otherwise, 1-PPS output
will be shifted from the WR timescale by <steps>*150ps.
@end table
@c --------------------------------------------------------------------------
@node wrs_pstats
@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 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
@b{Note:} The above operation is not atomic, i.e. the configuration will be
applied to one port at a time.
@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 information through the standard @i{net-snmp}
installation.
In addition it implements the subset of @t{BRIDGE-MIB} (switching table,
defined in RFC 1493),
@t{Q-BRIDGE-MIB} (VLANs entries, defined in RFC 4363) and
@t{LLDP-MIB} (if LLDP is enabled in dot-config).
The OID @t{SNMPv2-MIB::sysObjectID} is filled depending on manufacturer and
hardware version based on the information stored in @t{hwinfo}.
OIDs @t{SNMPv2-MIB::sysContact} and @t{SNMPv2-MIB::sysLocation} can be defined
a free text in dot-config.
The additional, switch-specific information are in the
``@t{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
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 from 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