Differences

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

doc:techref:swconfig [2012/11/06 17:40]
uvray313
doc:techref:swconfig [2014/08/06 05:05] (current)
phip
Line 1: Line 1:
====== Swconfig ====== ====== Swconfig ======
-The program ''swconfig'' allows you to configure //configurable// switches, like the +The program ''swconfig'' allows you to configure //configurable// [[doc:hardware:switch|Ethernet network switches]]. 
- * [[http://www.realtek.com.tw/products/productsView.aspx?Langid=1&PNid=18&PFid=15&Level=5&Conn=4&ProdID=197|RealTek RTL8366RB 5-port Gigabit switch]], e.g. in the [[toh/tp-link/tl-wr1043nd|WR1043ND]]. + 
- * [[http://www.realtek.com.tw/press/newsViewOne.aspx?NewsID=182|RealTek RTL8366S]], e.g. in the [[toh/d-link/DIR-825]] +==== Supported hardware ===== 
- * Atheros AR8316, e.g. in the [[toh/ubiquiti/routerstation.pro|RouterStation Pro]], [[toh/buffalo/WBMR-HP-G300H]], ... + 
-  * AR8216 +''swconfig'' supports the following hardware switches using the mentioned ''swconfig'' driver; 
-  * IC+ IP17xx + 
-  * Realtek RTL8306S +| Driver | Ethernet switches models | Hardware wiring | 
-  * AR7240 built-in switch +| [[https://dev.openwrt.org/browser/trunk/target/linux/generic/files/drivers/net/phy/adm6996.c|adm6696]] | Infineon/ADMTek 66996M/L/FC | MDIO / GPIO | 
-  * FIXME please fill on all supported switches FIXME+| [[https://dev.openwrt.org/browser/trunk/target/linux/generic/files/drivers/net/phy/ar8216.c|ar8216]] | Qualcomm/Atheros AR8216/8236/8316/8327/8337| MDIO | 
 +| [[https://dev.openwrt.org/browser/trunk/target/linux/generic/files/drivers/net/phy/b53|b53]] | Broadcom BCM5325/5365/5395/5398/53115/53125/53128/53010/53011/53012/53018/53019/63xx | MDIO / SPI / MMIO | 
 +| [[https://dev.openwrt.org/browser/trunk/target/linux/generic/files/drivers/net/phy/ip17xx.c|ip17xx]] | IC+ IP178C IP175A/C/D | MDIO | 
 +| [[https://dev.openwrt.org/browser/trunk/target/linux/generic/files/drivers/net/phy/psb6970.c|psb6970]] | Lantiq PSB6970 | MDIO | 
 +| [[https://dev.openwrt.org/browser/trunk/target/linux/generic/files/drivers/net/phy/rtl8306.c|rtl8306]] | Realtek RTL8306S/SD/SDM | MDIO | 
 +| [[https://dev.openwrt.org/browser/trunk/target/linux/generic/files/drivers/net/phy/rtl8366s.c|rtl8366s]] | Realtek RTL8366S | MDIO GPIO/SMI | 
 +| [[https://dev.openwrt.org/browser/trunk/target/linux/generic/files/drivers/net/phy/rtl8366rb.c|rtl8366rb]] | Realtek RTL8366RB | MDIO GPIO/SMI | 
 +| [[https://dev.openwrt.org/browser/trunk/target/linux/generic/files/drivers/net/phy/rtl8367.c|rtl8367]] | Realtek RTL8367 | MDIO | 
 +| [[https://dev.openwrt.org/browser/trunk/target/linux/generic/files/drivers/net/phy/rtl8367b.c|rtl8367b]] | Realtek RTL8367B | MDIO |
===== Usage examples ===== ===== Usage examples =====
-  * LEDs:<code>swconfig dev rtl8366s port 0 set led 2</code>+ 
 +===== Show ===== 
 + 
 +  * <code>swconfig list</code> 
 +  * <code>swconfig dev switch0 show</code>
  * Show current configuration<code>   * Show current configuration<code>
swconfig dev rtl8366rb show swconfig dev rtl8366rb show
Line 25: Line 37:
</code> </code>
  * Show available features<code>   * Show available features<code>
-swconfig dev eth0 help+swconfig dev rt305x help 
 +switch0: rt305x(rt305x-esw), ports: 7 (cpu @ 6), vlans: 4096 
 +    --switch 
 +        Attribute 1 (int): enable_vlan (VLAN mode (1:enabled)) 
 +        Attribute 2 (int): alternate_vlan_disable (Use en_vlan instead of doubletag to disable VLAN mode) 
 +        Attribute 3 (none): apply (Activate changes in the hardware) 
 +        Attribute 4 (none): reset (Reset the switch) 
 +    --vlan 
 +        Attribute 1 (ports): ports (VLAN port mapping) 
 +    --port 
 +        Attribute 1 (int): disable (Port state (1:disabled)) 
 +        Attribute 2 (int): doubletag (Double tagging for incoming vlan packets (1:enabled)) 
 +        Attribute 3 (int): untag (Untag (1:strip outgoing vlan tag)) 
 +        Attribute 4 (int): led (LED mode (0:link, 1:100m, 2:duplex, 3:activity, 4:collision, 5:linkact, 6:duplcoll, 7:10mact, 8:1) 
 +        Attribute 5 (int): lan (HW port group (0:wan, 1:lan)) 
 +        Attribute 6 (int): recv_bad (Receive bad packet counter) 
 +        Attribute 7 (int): recv_good (Receive good packet counter) 
 +        Attribute 8 (int): pvid (Primary VLAN ID) 
 +        Attribute 9 (string): link (Get port link information) 
 +</code>or<code> 
 +swconfig dev rtl8366rb help 
 +switch1: rtl8366rb(RTL8366RB), ports: 6 (cpu @ 5), vlans: 4096 
 +    --switch 
 +        Attribute 1 (int): enable_learning (Enable learning, enable aging) 
 +        Attribute 2 (int): enable_vlan (Enable VLAN mode) 
 +        Attribute 3 (int): enable_vlan4k (Enable VLAN 4K mode) 
 +        Attribute 4 (none): reset_mibs (Reset all MIB counters) 
 +        Attribute 5 (int): blinkrate (Get/Set LED blinking rate (0 = 43ms, 1 = 84ms, 2 = 120ms, 3 = 170ms, 4 = 340ms, 5 = 670ms)) 
 +        Attribute 6 (int): enable_qos (Enable QOS) 
 +        Attribute 7 (none): apply (Activate changes in the hardware) 
 +        Attribute 8 (none): reset (Reset the switch) 
 +    --vlan 
 +        Attribute 1 (string): info (Get vlan information) 
 +        Attribute 2 (int): fid (Get/Set vlan FID) 
 +        Attribute 3 (ports): ports (VLAN port mapping) 
 +    --port 
 +        Attribute 1 (none): reset_mib (Reset single port MIB counters) 
 +        Attribute 2 (string): mib (Get MIB counters for port) 
 +        Attribute 3 (int): led (Get/Set port group (0 - 3) led mode (0 - 15)) 
 +        Attribute 4 (int): disable (Get/Set port state (enabled or disabled)) 
 +        Attribute 5 (int): rate_in (Get/Set port ingress (incoming) bandwidth limit in kbps) 
 +        Attribute 6 (int): rate_out (Get/Set port egress (outgoing) bandwidth limit in kbps) 
 +        Attribute 7 (int): pvid (Primary VLAN ID) 
 +        Attribute 8 (string): link (Get port link information)
</code> </code>
 +
 +===== Change =====
 +
 +Note: Make sure to apply any changes made previously with the "**set**" command.
 +
 +  * LEDs:<code>swconfig dev rtl8366s port 0 set led 2
 +wconfig dev rtl8366rb set apply</code>
 +  * Disable VLANs:<code>swconfig dev switch0 set enable_vlan 0
 +swconfig dev switch0 set apply</code>
 +
 +==== 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.
 +
 +===== Scope and rationale =====
 +
 +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
 +  * collect statistics about the number of packets/bytes transferred/received
 +  * any other vendor specific feature: rate limiting, single/double tagging...
 +
 +Such switches can be connected to the controlling CPU using different hardware
 +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
 +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
 +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
 +mechanism was chosen because it allows for all design goals to be met.
 +
 +===== Distributed Switch Architecture vs. swconfig =====
 +
 +The Marvell Distributed Switch Architecture drivers is an existing solution
 +which is a heavy switch driver infrastructure, is 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.
 +
 +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.
 +
 +=====  Switch configuration API ======
 +
 +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)
 +  * a network device pointer it is physically attached to
 +  * a number of physical switch ports (including CPU port)
 +  * a set of configured vlans
 +  * a CPU specific port index
 +
 +A particular switch device is registered/unregistered using the following pair
 +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
 +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:
 +
 +  * get the port list of a VLAN identifier
 +  * set the port list of a VLAN identifier
 +  * get the primary VLAN identifier of a port
 +  * set the primary VLAN identifier of a port
 +  * apply the changed configuration to the switch
 +  * reset the switch
 +  * get a port link status
 +  * get a port statistics counters
 +
 +The switch_dev_ops structure also contains an extensible way of representing and
 +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
 +switch_attr" attributes. This structure must be filed with:
 +
 +  * an unique name for the operation
 +  * a description for the operation
 +  * a setter operation
 +  * a getter operation
 +  * a data type (string, integer, port)
 +  * eventual min/max limits to validate user input data
 +
 +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.
 +
===== References ===== ===== References =====
-  * [[http://inst.eecs.berkeley.edu/~pathorn/ip175c/]] +  * [[http://inst.eecs.berkeley.edu/~pathorn/ip175c/]] FIXME link down 
-  * [[http://inst.eecs.berkeley.edu/~pathorn/ip175c/phylib-swconfig/]]+  * [[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/]]   * [[http://www.debwrt.net/2010/11/07/switch-configuration-command-line-tool-swconfig-ported-2/]]
  * [[http://www.icplus.com.tw/pp-IP175C.html]]   * [[http://www.icplus.com.tw/pp-IP175C.html]]
Line 36: Line 216:
  * [[https://forum.openwrt.org/viewtopic.php?id=28716|switch_port]]   * [[https://forum.openwrt.org/viewtopic.php?id=28716|switch_port]]
  * [[https://forum.openwrt.org/viewtopic.php?id=27485|Is VLAN trunking on WR1034ND with VLAN id higher than 15 possible]]   * [[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}}

Back to top

doc/techref/swconfig.1352220013.txt.bz2 · Last modified: 2012/11/06 17:40 by uvray313