User Tools

Site Tools


doc:techref:swconfig

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
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.gin the [[toh/tp-link/tl-wr1043nd|WR1043ND]]. + 
-  ​* ​[[http://www.realtek.com.tw/press/newsViewOne.aspx?​NewsID=182|RealTek RTL8366S]], e.gin the [[toh/d-link/DIR-825]] +==== Supported hardware ===== 
-  * Atheros AR8316, e.gin 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}}
doc/techref/swconfig.1352220013.txt.bz2 · Last modified: 2012/11/06 17:40 by uvray313