From 73f319c58d5d8b74bb5c2a097ad809dda4582240 Mon Sep 17 00:00:00 2001
From: Adam Wujek <adam.wujek@cern.ch>
Date: Tue, 20 Sep 2016 14:39:18 +0200
Subject: [PATCH] doc/wrs-user-manual: add the description of VLANs
configuration
Signed-off-by: Adam Wujek <adam.wujek@cern.ch>
---
doc/wrs-developer-manual.in | 2 +-
doc/wrs-user-manual.in | 351 ++++++++++++++++++++++++++++++++----
2 files changed, 315 insertions(+), 38 deletions(-)
diff --git a/doc/wrs-developer-manual.in b/doc/wrs-developer-manual.in
index 0b273a1c..1e75646d 100644
--- a/doc/wrs-developer-manual.in
+++ b/doc/wrs-developer-manual.in
@@ -1345,7 +1345,7 @@ ever erase this memory; if it happens, the system won't boot and
you'll be forced to re-flash it entirely, which requires access to the back
side of the switch..
-NAND memory is used for user-data: tke boot loader configuration, the
+NAND memory is used for user-data: the boot loader configuration, the
kernel and the filesystem.
This is how the memory is used:
diff --git a/doc/wrs-user-manual.in b/doc/wrs-user-manual.in
index 63111f31..230ded00 100644
--- a/doc/wrs-user-manual.in
+++ b/doc/wrs-user-manual.in
@@ -843,6 +843,69 @@ value is changed by the web interface, proper action is taken.
@t{CONFIG_RTU_HP_MASK_ENABLE}.
@t{CONFIG_RTU_HP_MASK_VAL} contains 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_PORTXX_MODE_ACCESS
+@itemx CONFIG_VLANS_PORTXX_MODE_TRUNK
+@itemx CONFIG_VLANS_PORTXX_MODE_DISABLED
+@itemx CONFIG_VLANS_PORTXX_MODE_UNQUALIFIED
+
+ VLANs 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_PORTXX_UNTAG_ALL
+@itemx CONFIG_VLANS_PORTXX_UNTAG_NONE
+
+ Define whether to remove a tag from VLAN frames on a port 1..18.
+
+@item CONFIG_VLANS_PORTXX_PRIO
+
+ Priority value used when tagging frames or to override priority
+ passed to RTU. -1 disables the priority overwrite. Valid values are
+ from -1 to 7.
+
+@item CONFIG_VLANS_PORTXX_VID
+
+ VID value used when tagging frames or to override VID passed to RTU.
+ VID takes values 0..4094.
+ For details please refer to the @ref{VLANs Configuration}
+
+@item CONFIG_VLANS_VLANXXXX
+
+ Provide the 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. 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 value takes
+ precedence over port priority
+ @item If @t{drop} is set to @t{y}, 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} and @t{n}
+ @item @t{ports} is a list of ports separated with the colon sign
+ VLANs configuration per VLANS.
+ @end itemize
+ Example:
+
+ @t{fid=4,prio=2,drop=n,ports=1:15}
+
+ It sets fid as 4, priority 2, don't drop frames belonging to this VLAN,
+ assign ports 1 and 15 to this VLAN.
+
+ For more details about VLANs configuration please refer to the @ref{VLANs Configuration}
+
@end table
@c ==========================================================================
@@ -972,24 +1035,240 @@ with the @i{difference} between them and the @t{AXGE} devices.
@node VLANs Configuration
@section VLANs Configuration
-Unfortunately, the current firmware release does not support VLAN configuration
-in the main @t{dot-config} file. Therefore, if you want to use VLANs you
-have to manually configure them using the @i{wrs_vlans} tool described
-in @ref{wrs_vlans}.
+The 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
+ @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}
+ @item @i{null} -- tag that has VID=@t{0xFFF}
+@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, their tag is unchanged, the value
+ of VID provided to the RTU is overridden with the
+ configured in @t{pvid}. 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 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}
+ @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. Their tag is unchanged, the value
+ of VID provided to the RTU is overridden with the
+ configured in @t{pvid}. 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}: discarded.
+ @end itemize
+@end itemize
+
+Modes and their behaviour are summarized in the table below:
+
+@center @image{VLAN_modes, 14cm,, VLAN_modes}
+
+From the version 4.3, it is possible to configure VLANs in the main
+@t{dot-config} file (for an example configuration please see
+@ref{Example VLAN configuration by dot-config}).
-In addition to that, to have synchronization working with VLANs, you have to
-prepare a custom @i{PPSi} configuration file with VLANs specified per-port. You
+As an alternative it is possible to use @i{wrs_vlans} tool
+described in @ref{wrs_vlans} together with a custom config file for @i{PPSi}.
+
+To have synchronization working with VLANs, the custom @i{PPSi} configuration
+file should contain 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.
-For every VLAN-enabled port you should add the following line:
+@t{dot-config} files for your switches are stored and fetched on boot time or
+permamently store it in the switch's flash (for details, please check
+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 <VID>
@end example
-where @i{VID} is a VLAN ID configured on the port. To let your switch use the
-modified @i{ppsi.conf}, you should add it as @t{CONFIG_PTP_REMOTE_CONF} option
-in the @t{dot-config} (@ref{Configuration Items that Apply at Run Time}). This
-way it will be fetched and applied every time your switch boots.
+where @i{VID} is a VLAN ID configured on the port.
+
+For an example configuration please see
+@ref{Example VLAN configuration by tools}).
+
+@c =-------------------------------------------------------------------------
+@node Example VLAN configuration
+@subsection Example VLAN configuration
+
+This subsection describes how to configure VLANs on a switch using the
+@t{dot-config} and available command line tools.
+
+An example configuration of VLANs for ports (wri) 1-3 is provided below.
+The descriptions assumes, for simplicity, that switch has only this 3 ports.
+
+In this configuration, port 1 is synchronised to an upstream WR device and this
+device does not need to have any VLAN configuration. Port 1 is in @t{ACCESS} mode,
+thus it tags the ingress Ethernet frames. A VLAN-tags with VID 1 and priority
+4 is added so that frames received at this port belong to VLAN 1. Port 1 also
+untags the egress frames. In this configuration, it is only the port 1 that
+belongs to VLAN 1 which means that none of the traffic received on port 1 is
+forwarded to other ports. The only traffic received at port 1 that is not
+dropped are the PTP messages which are forwarded to the PTP daemon (@i{PPSi}). Such
+an arrangement can be useful if the synchronisation is to be propagated through
+WR network, i.e. between the upstream and this switch, but the data needs to be
+separated.
+
+The data is forwarded between ports 2 and 3. These ports belong to VLAN 2
+(VID=2). Port 3 is in @t{ACCESS} mode and it tags the ingress frames with VID 2
+and priority 7. This could be a port connected to a WR node that is a source of
+critical traffic. This WR node does not need to support VLANs, however its
+traffic needs to have the highest precedence in the network.
+
+The traffic from port 3 is forwarded only to port 2. This port is in @t{TRUNK}
+mode. It does not untag egress frames which means that the device connected to
+it (a switch or a node) must be VLAN-aware. Port 2 accepts only frames that are
+already tagged with the VLAN-tag. Out of the frames received at port 2, only
+the frames 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 @t{dot-config} has to contain the
+following config options:
+
+@smallexample
+CONFIG_PORT01_PARAMS="name=wri1,proto=raw,tx=0,rx=0,role=slave,fiber=0,ppsi_vlans=1"
+CONFIG_PORT02_PARAMS="name=wri2,proto=raw,tx=0,rx=0,role=master,fiber=0,ppsi_vlans=2"
+CONFIG_PORT03_PARAMS="name=wri3,proto=raw,tx=0,rx=0,role=master,fiber=0,ppsi_vlans=2"
+
+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_PRIO=-1
+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=no,ports=1"
+CONFIG_VLANS_VLAN0002="fid=2,prio=4,drop=no,ports=2:3"
+@end smallexample
+
+@c =-------------------------------------------------------------------------
+@node Example VLAN configuration by tools
+@subsubsection Example VLAN configuration by tools
+
+To configure the switch in the way descibed in the
+@ref{Example VLAN configuration}, using the command line tools please perform
+the following actions:
+
+Set ports' configuration by using the @t{wrs_vlans}:
+@smallexample
+# wrs_vlans \
+ --port 1 --pmode 0 --pprio 4 --pvid 1 --puntag 1 \
+ --port 2 --pmode 1 --pprio -1 \
+ --port 3 --pmode 0 --pprio 4 --pvid 2 --puntag 1
+@end smallexample
+
+Set VID configuration by using @t{wrs_vlans}:
+@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 sould be placed into @t{ppsi.conf}:
+@smallexample
+port wri1-raw
+proto raw
+iface wri1
+role slave
+extension whiterabbit
+vlan 1
+
+port wri2-raw
+proto raw
+iface wri2
+role master
+extension whiterabbit
+vlan 2
+
+port wri3-raw
+proto raw
+iface wri3
+role master
+extension whiterabbit
+vlan 2
+@end smallexample
@c ==========================================================================
@node Front panel's LEDs
@@ -1293,7 +1572,8 @@ The following tools and scripts are provided:
@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.
+ lists all configuration items of the tool. For details please
+ refer to the @ref{wrs_vlans}.
@item apply_dot-config
The script is used to apply @t{dot-config} settings to the
@@ -1421,25 +1701,21 @@ The following option flags are supported:
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 the
-@ref{Configuration Items that Apply at Build Time})
+@t{--file} parameter (for @t{dot-config} config options' details please check
+the @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 the section and subsections
+of the @ref{VLANs Configuration}.
-The configuration is divided into two parts:
+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 to:
- @itemize @bullet
- @item ACCESS - tags untagged frames with configured VID and priority, drops
- tagged frames not belonging to the configured VLAN
- @item TRUNK - passes only tagged frames, drops all untagged frames
- @item Disabled - VLANs disabled
- @item Unqualified port - passes all frames regardless of VLAN configuration
- @end itemize
+ frames tagging, egress untagging and port mode. For port modes please refer
+ to the @ref{VLANs Configuration}.
@item wrs_vlans --rvid <vid> [options]
@@ -1476,18 +1752,19 @@ For per-port configuration, multiple ways of specifying ports are supported:
To configure each Endpoint the following options may be used:
@table @code
-@item --pmode <mode No.>
- Sets qmode for a port (0 - ACCESS, 1 - TRUNK, 2 - disabled, 3 - unqualified)
+@item --pmode <0..3>
+ Sets qmode for a port (@t{0} -- @t{ACCESS}, @t{1} -- @t{TRUNK},
+ @t{2} -- @t{DISABLED}, @t{3} -- @t{UNQUALIFIED})
-@item --pvid <vid>
+@item --pvid <0..4094>
Sets VLAN id for tagging ingress frames.
-@item --pprio <priority>
- Sets priority for tagging ingress frames.
+@item --pprio <-1|0..7>
+ Sets priority for tagging ingress frames. @t{-1} disables priority overwrite.
-@item --pumask <hex mask>
- Sets mask for egress untagging. By default, if you configure ingress tagging,
- all VIDs are untagged on egress.
+@item --puntag <0|1>
+ Disables or enables egress untagging. By default, if you configure ingress
+ tagging, all VIDs are untagged on egress.
@end table
@@ -1500,18 +1777,18 @@ VLAN id to be set up and then the list of configuration options:
Possible RTU VLAN configuration options:
@table @code
-@item --rmask <hex mask>
+@item --rmask <0x0..0x3ffff>
Mask defines which physical ports of the WRS belong to a configured VLAN.
-@item --rfid <fid>
+@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 <prio>
- Forces 802.1q priority override for VLAN. Setting @i{prio} to -1, cancels the
- override.
+@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
--
GitLab