Swconfig

The program swconfig allows you to configure configurable Ethernet network switches.

Supported hardware

swconfig supports the following hardware switches using the mentioned swconfig driver;

Driver Ethernet switches models Hardware wiring
adm6696 Infineon/ADMTek 66996M/L/FC MDIO / GPIO
ar8216 Qualcomm/Atheros AR8216/8236/8316/8327/8337 MDIO
b53 Broadcom BCM5325/5365/5395/5398/53115/53125/53128/53010/53011/53012/53018/53019/63xx MDIO / SPI / MMIO
ip17xx IC+ IP178C IP175A/C/D MDIO
psb6970 Lantiq PSB6970 MDIO
rtl8306 Realtek RTL8306S/SD/SDM MDIO
rtl8366s Realtek RTL8366S MDIO GPIO/SMI
rtl8366rb Realtek RTL8366RB MDIO GPIO/SMI
rtl8367 Realtek RTL8367 MDIO
rtl8367b Realtek RTL8367B MDIO

Usage examples

Show

  • swconfig list
  • swconfig dev switch0 show
  • Show current configuration
    swconfig dev rtl8366rb show
    
    and you will obtain:
    VLAN 1:
            info: VLAN 1: Ports: '12345t', members=003e, untag=001e, fid=0
            fid: 0
            ports: 1 2 3 4 5t
    VLAN 2:
            info: VLAN 2: Ports: '05t', members=0021, untag=0001, fid=0
            fid: 0
            ports: 0 5t
    
  • Show available features
    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)
    
    or
    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)
    

Change

Note: Make sure to apply any changes made previously with the "set" command.

  • LEDs:
    swconfig dev rtl8366s port 0 set led 2
    wconfig dev rtl8366rb set apply
  • Disable VLANs:
    swconfig dev switch0 set enable_vlan 0
    swconfig dev switch0 set apply

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

Tags

Back to top

doc/techref/swconfig.txt · Last modified: 2014/08/06 05:05 by phip