wrs-user-manual.in

        to set host time as a first step, if @t{/wr/etc/wr_date.conf}
        exists and includes a line of the form @t{ntpserver 192.168.16.1}.

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

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

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

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

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

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

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

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

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

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

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

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


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

The program can be used in three ways:

@table @code

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

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

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

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

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

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

@end table

The following option flags are supported:

@table @code

@item -l

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

@item -e <entrypoint>

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

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

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

@item -r

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

@end table

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

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

@table @code

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

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

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

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

@end table

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

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

@item wrs_vlans --ep 1 [options]

  Selected configuration will be applied only to port 1.

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

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

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

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

@item wrs_vlans --ep 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 --emode <mode No.>
  Sets qmode for a port (0 - ACCESS, 1 - TRUNK, 2 - disabled, 3 - unqualified)

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

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

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

@end table

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

Possible RTU VLAN configuration options:
@table @code

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

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

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

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

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

@end table

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

@table @code

@item wrs_vlans --elist

  Current Endpoints VLAN configuration

@item wrs_vlans --list

  Current RTU VLAN configuration.

@item wrs_vlans --clear

@end table

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

@example
  wrs_vlans --ep 0-2,5 --emode 0 --evid 5 --ep 3,4 --emode 0 --evid 6 \
    --rvid 5 --rmask 0x27 --rvid 6 --rmask 0x18
@end example

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

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

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

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

@table @code

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

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

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

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

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

@end table

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

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

The switch supports all the standard information through the @i{net-snmp}
installation.  We'll remove some of the items in a later release, because
nobody wants to check running processes or disk space usage.

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

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

This a summary of the available tables and scalars:

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

	Port statistics, as an SNMP table.  The first column is the
        name of each counter, and further columns represent interfaces
        @t{wr0} through @t{wr17}. Each counters is shown in a table line,
        as the number and names of the counters may change in the future.

@item 96.100.3

	White Rabbit specific information.  Subid @t{.1} is the global
        items, and subid @t{.2} is a table with per-port items.

@item 96.100.4

	Hardware, gateware and software versions, plus serial
        number and other hardware information.

@item 96.100.5

	The internal White Rabbit time, as a number and a string.

@end table

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

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

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

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

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

@smallexample
WR-SWITCH-MIB::wrsScalar.0 = INTEGER: 2
WR-SWITCH-MIB::pstatsDescr.1 = STRING: TX Underrun
WR-SWITCH-MIB::pstatsDescr.2 = STRING: RX Overrun
WR-SWITCH-MIB::pstatsDescr.3 = STRING: RX Invalid Code
[...]
WR-SWITCH-MIB::pstatsDescr.38 = STRING: Forwarded
WR-SWITCH-MIB::pstatsDescr.39 = STRING: TRU Resp Valid
WR-SWITCH-MIB::pstatsWR0.1 = Counter32: 0
[...]
WR-SWITCH-MIB::pstatsWR17.38 = Counter32: 50819
WR-SWITCH-MIB::pstatsWR17.39 = Counter32: 0
WR-SWITCH-MIB::pstatsEntry.20 = Counter32: 0
WR-SWITCH-MIB::ppsiGrandmaterID.0 = Hex-STRING: 00 00 00 00 00 00 00 00
WR-SWITCH-MIB::ppsiOwnID.0 = Hex-STRING: 00 00 00 00 00 00 00 00
WR-SWITCH-MIB::ppsiMode.0 = INTEGER: unknown(0)
WR-SWITCH-MIB::ppsiServoState.0 = STRING:
WR-SWITCH-MIB::ppsiPhaseTracking.0 = INTEGER: not-tracking(0)
[...]
WR-SWITCH-MIB::portLink.14 = INTEGER: down(0)
WR-SWITCH-MIB::portLink.15 = INTEGER: up(1)
WR-SWITCH-MIB::portLink.16 = INTEGER: down(0)
[...]
WR-SWITCH-MIB::portPeer.18 = Hex-STRING: FF FF FF FF FF FF FF FF
WR-SWITCH-MIB::ppsiPort.5 = Hex-STRING: FF FF FF FF FF FF FF FF
WR-SWITCH-MIB::wrsVersionSw.0 = STRING: v4.0-rc1-42-gcec7805+
WR-SWITCH-MIB::wrsVersionGw1.0 = STRING: 7cce708
WR-SWITCH-MIB::wrsVersionGw2.0 = STRING: 5118070
WR-SWITCH-MIB::wrsVersionGw3.0 = STRING: 7efeb16
WR-SWITCH-MIB::wrsVersionHw1.0 = STRING: 3.30
WR-SWITCH-MIB::wrsVersionHw2.0 = STRING: LX240T
WR-SWITCH-MIB::wrsManufacturer.0 = STRING: Seven Solutions
WR-SWITCH-MIB::wrsSerialNumber.0 = STRING: 12345
WR-SWITCH-MIB::wrsScbVersion.0 = STRING: 3.3
WR-SWITCH-MIB::wrsDateTAI.0 = Counter64: 1406623390
WR-SWITCH-MIB::wrsDateString.0 = STRING: 2014-07-29-08:43:10
@end smallexample

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

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

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

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

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

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

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

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

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

 wrsPstatsPortName wrsPstatsTXUnderrun wrsPstatsRXOverrun wrsPstatsRXInvalidCode
               wr0                   0                  0                      0
               wr1                   0                  0                      0
               wr2                   0                  0                      0
               wr3                   0                  0                      0
               wr4                   0                  0                      0
               wr5                   0                  0                      0
               wr6                   0                  0                      0
               wr7                   0                  0                      0
               wr8                   0                  0                      0
               wr9                   0                  0                      0
              wr10                   0                  0                      0
              wr11                   0                  0                      0
              wr12                   0                  0                      0
              wr13                   0                  0                      0
              wr14                   0                  0                      0
              wr15                   0                  0                      0
              wr16                   0                  0                      0
              wr17                   0                  0                      0

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

 wrsPstatsRXSyncLost wrsPstatsRXPauseFrames wrsPstatsRXPfilterDropped
                   0                      0                         0
                   0                      0                         0
                   0                      0                         0
                   0                      0                         0
                   0                      0                         0
                   0                      0                         0
                   0                      0                         0
                   0                      0                         0
                   0                      0                         0
                   0                      0                         0
                   0                      0                         0
                   0                      0                         0
                   0                      0                         0
                   0                      0                         0
                   0                      0                         0
                   0                      0                         0
                   0                      0                         0
                   0                      0                         0

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

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

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

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

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


@c  LocalWords:  gnudd titlepage iftex texinfo CERN timestamping smallexample
@c  LocalWords:  LocalWords ietf timestamp misc timestamps ttstamp onestamp
@c  LocalWords:  Tomasz Wlostowski buildroot distclean defconfig wrswitch REPO
@c  LocalWords:  menuconfig config dataflash whiterabbit stdout stderr svnsync
@c  LocalWords:  filesystem diff ohwr http mkdir linux rubini itemize PTPd VHDL
@c  LocalWords:  noposix ptpd userspace libwr DataFlash NAND barebox FPGA
@c  LocalWords:  Atmel Kconfig minicom tinyserial ttyUSB bootloader logfile
@c  LocalWords:  nandflash gateware TFTP init wrboot wiki