Newer
Older
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
@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.
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
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
@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
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
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
Adam Wujek
committed
@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