Differences

This shows you the differences between two versions of the page.

--- docs:techref:swconfig [2018/02/20 18:52] – ↷ Links adapted because of a move operation
+++ docs:techref:swconfig [2021/03/08 10:46] (current) – Fixed broken link jaimet
@@ Line 1: / Line 1: @@
 ====== swconfig ======
-The program ''swconfig'' allows you to configure //configurable// [[docs:hardware:switch|Ethernet network switches]].
+The program ''swconfig'' allows you to configure //configurable// [[docs:techref:hardware:switch|Ethernet network switches]].
-<color red>Make sure you can [[docs:user-guide:failsafe_and_factory_reset|safemode]] or TTL before changing network/switch settings</color>
+It is considered legacy and new switch drivers should use the DSA (distributed switch architecture) kernel framework which makes it possible to use standard userspace tools such as ''ip'' to configure the switches.
-==== Supported hardware =====
+<color red>Make sure you can [[docs:guide-user:troubleshooting:failsafe_and_factory_reset|safemode]] or TTL before changing network/switch settings</color>
+===== Supported hardware ======
 ''swconfig'' supports the following hardware switches using the mentioned ''swconfig'' driver;
-| Driver | Ethernet switches models | Hardware wiring |
+^ Driver ^ Ethernet switches models ^ Hardware wiring ^
 | [[https://dev.openwrt.org/browser/trunk/target/linux/generic/files/drivers/net/phy/adm6996.c|adm6996]] | Infineon/ADMTek 6996M/L/FC | MDIO / GPIO |
 | [[https://dev.openwrt.org/browser/trunk/target/linux/generic/files/drivers/net/phy/ar8216.c|ar8216]] | Qualcomm/Atheros AR8216/8236/8316/8327/8337| MDIO |
@@ Line 21: / Line 22: @@
 ===== Usage examples =====
 ===== Show =====
   * <code>swconfig list</code>
   * <code>swconfig dev switch0 show</code>
@@ Line 92: / Line 91: @@
 ===== Change =====
 Note: Make sure to apply any changes made previously with the "**set**" command.
@@ Line 101: / Line 99: @@
 ==== Design and rationale ====
 Generic Netlink Switch configuration API
 ===== Introduction =====
+The following documentation covers the Linux Ethernet switch configuration API which is based on the Generic Netlink infrastructure.
-The following documentation covers the Linux Ethernet switch configuration API
-which is based on the Generic Netlink infrastructure.
 ===== Scope and rationale =====
+Most Ethernet switches found in small routers are managed switches which allow the following operations:
-Most Ethernet switches found in small routers are managed switches which allow
-the following operations:
   * configure a port to belong to a particular set of VLANs either as tagged or untagged
   * configure a particular port to advertise specific link/speed/duplex settings
@@ Line 119: / Line 111: @@
   * any other vendor specific feature: rate limiting, single/double tagging...
-Such switches can be connected to the controlling CPU using different hardware
+Such switches can be connected to the controlling CPU using different hardware busses, but most commonly:
-busses, but most commonly:
   * SPI/I2C/GPIO bitbanging
   * MDIO
   * Memory mapped into the CPU register address space
-As of today the usual way to configure such a switch was either to write a
+As of today the usual way to configure such a switch was either to write a specific driver or to write an user-space application which would have to know about the hardware differences and figure out a way to access the switch registers (spidev, SIOCIGGMIIREG, mmap...) from user-space.
-specific driver or to write an user-space application which would have to know
-about the hardware differences and figure out a way to access the switch
-registers (spidev, SIOCIGGMIIREG, mmap...) from user-space.
 This has multiple issues:
   * proliferation of ad-hoc solutions to configure a switch both open source and proprietary
   * absence of common software reference for switches commonly found on the market (Broadcom, Lantiq/Infineon/ADMTek, Marvell, Qualcomm/Atheros...) which implies a duplication effort for each implementer
   * inability to leverage existing hardware representation mechanisms such as Device Tree (spidev, i2c-dev.. do not belong in Device Tree and rely on Linux-specific "forwarder" drivers) to describe a switch device
-The goal of the switch configuration API is to provide a common basis to build
+The goal of the switch configuration API is to provide a common basis to build re-usable and extensible switch drivers with the following ideas in mind:
-re-usable and extensible switch drivers with the following ideas in mind:
   * having a central point of configuration on top of which a reference user-space implementation can be provided but also allow for other user-space implementations to exist
   * ensure the Linux kernel is in control of the actual hardware access
   * be extensible enough to support per-switch features without making the generic implementation too heavy weighted and without making user-space changes each and every time a new feature is added
-Based on these design goals the Generic Netlink kernel/user-space communication
+Based on these design goals the Generic Netlink kernel/user-space communication mechanism was chosen because it allows for all design goals to be met.
-mechanism was chosen because it allows for all design goals to be met.
 ===== Distributed Switch Architecture vs. swconfig =====
+The Marvell Distributed Switch Architecture (DSA) drivers is an existing solution which is a heavy switch driver infrastructure, is
+[[docs:techref:hardware:soc:soc.marvell|Marvell]]-centric, only supports MDIO connected switches, mangles an Ethernet driver transmit/receive paths and does not offer a central control path for the user.
-The Marvell Distributed Switch Architecture (DSA) drivers is an existing
+swconfig is vendor agnostic, does not mangle the transmit/receive path of an Ethernet driver and is focused on the control path of the switch rather that the data path.
-solution which is a heavy switch driver infrastructure, is
+It is based on Generic Netlink to allow for each switch driver to easily extend the swconfig API without causing major core parts rework
-[[docs:hardware:soc:soc.marvell|Marvell]]-centric, only supports MDIO
+each and every time someone has a specific feature to implement and offers a central configuration point with a well-defined API.
-connected switches, mangles an Ethernet driver transmit/receive paths
-and does not offer a central control path for the user.
-swconfig is vendor agnostic, does not mangle the transmit/receive path
-of an Ethernet driver and is focused on the control path of the switch rather
-that the data path. It is based on Generic Netlink to allow for each switch
-driver to easily extend the swconfig API without causing major core parts rework
-each and every time someone has a specific feature to implement and offers a
-central configuration point with a well-defined API.
  * More info e.g. at [[https://lwn.net/Articles/720313/|LWN.net 2017-04-19: The rise of Linux-based networking hardware]]:
-"The Linux kernel manipulates switches with three different operation structures: ''switchdev_ops'', ''ethtool_ops'' and ''netdev_ops''. Certain switches, however, also need distributed switch architecture (DSA).
+"The Linux kernel manipulates switches with three different operation structures: ''switchdev_ops'', ''ethtool_ops'' and ''netdev_ops''.
+Certain switches, however, also need distributed switch architecture (DSA).
-DSA's development was parallel to swconfig, written by the OpenWrt project. The main difference between swconfig and DSA is that DSA-supported switches show one network interface per port, whereas swconfig-configured switches show up as a single port, which limits the amount of information that can be extracted from the switch. For example, you cannot have per-port traffic statistics with swconfig. That limitation is what led to the creation of the switchdev framework, when swconfig was proposed (then refused) for inclusion in mainline. Another goal of switchdev was to support bridge hardware offloading and network interface card (NIC) virtualization…"
+DSA's development was parallel to swconfig, written by the OpenWrt project.
+The main difference between swconfig and DSA is that DSA-supported switches show one network interface per port, whereas swconfig-configured switches show up as a single port, which limits the amount of information that can be extracted from the switch.
+For example, you cannot have per-port traffic statistics with swconfig.
+That limitation is what led to the creation of the switchdev framework, when swconfig was proposed (then refused) for inclusion in mainline.
+Another goal of switchdev was to support bridge hardware offloading and network interface card (NIC) virtualization…"
 =====  Switch configuration API ======
+The main data structure of the switch configuration API is a "struct switch_dev" which contains the following members:
-The main data structure of the switch configuration API is a "struct switch_dev"
-which contains the following members:
   * a set of common operations to all switches (struct switch_dev_ops)
@@ Line 180: / Line 158: @@
   * a CPU specific port index
-A particular switch device is registered/unregistered using the following pair
+A particular switch device is registered/unregistered using the following pair of functions:
-of functions:
 register_switch(struct switch_dev *sw_dev, struct net_device *dev);
 unregister_switch(struct switch_dev);
-A given switch driver can be backed by any kind of underlying bus driver (i2c
+A given switch driver can be backed by any kind of underlying bus driver (i2c client, GPIO driver, MMIO driver, directly into the Ethernet MAC driver...).
-client, GPIO driver, MMIO driver, directly into the Ethernet MAC driver...).
-The set of common operations to all switches is represented by the "struct
-switch_dev_ops" function pointers, these common operations are defined as such:
+The set of common operations to all switches is represented by the "struct switch_dev_ops" function pointers, these common operations are defined as such:
   * get the port list of a VLAN identifier
   * set the port list of a VLAN identifier
@@ Line 201: / Line 175: @@
   * get a port statistics counters
-The switch_dev_ops structure also contains an extensible way of representing and
+The switch_dev_ops structure also contains an extensible way of representing and querying switch specific features, 3 different types of attributes are available:
-querying switch specific features, 3 different types of attributes are
-available:
   * global attributes: attributes global to a switch (name, identifier, number of ports)
   * port attributes: per-port specific attributes (MIB counters, enabling port mirroring...)
   * vlan attributes: per-VLAN specific attributes (VLAN id, specific VLAN information)
-Each of these 3 categories must be represented using an array of "struct
+Each of these 3 categories must be represented using an array of "struct switch_attr" attributes.
-switch_attr" attributes. This structure must be filed with:
+This structure must be filed with:
   * an unique name for the operation
   * a description for the operation
@@ Line 219: / Line 189: @@
   * eventual min/max limits to validate user input data
-The "struct switch_attr" directly maps to a Generic Netlink type of command and
+The "struct switch_attr" directly maps to a Generic Netlink type of command and will be automatically discovered by the "swconfig" user-space utility without requiring user-space changes.
-will be automatically discovered by the "swconfig" user-space utility without
-requiring user-space changes.
 ===== References =====
-  * [[http://inst.eecs.berkeley.edu/~pathorn/ip175c/]] FIXME link down
+  * [[https://web.archive.org/web/20081205103732/http://inst.eecs.berkeley.edu/~pathorn/ip175c/]] (links to archive.org; content of original site is gone)
   * [[https://web.archive.org/web/20110831151445/http://inst.eecs.berkeley.edu/~pathorn/ip175c/phylib-swconfig/]] (links to archive.org; content of original site is gone)
   * [[http://www.debwrt.net/2010/11/07/switch-configuration-command-line-tool-swconfig-ported-2/]]
@@ Line 233: / Line 200: @@
   * [[https://forum.openwrt.org/viewtopic.php?id=27485|Is VLAN trunking on WR1034ND with VLAN id higher than 15 possible]]
-===== Tags =====
-{{tag>swconfig rtl8366rb AR8316}}