Table of Contents


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

Make sure you can safemode or TTL before changing network/switch settings

Supported hardware

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

Driver Ethernet switches models Hardware wiring
adm6996 Infineon/ADMTek 6996M/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


Example switch port on/off per port (ex: on/off port 4)

disable: ssh > swconfig dev switch0 port 4 set disable 1
enable:  ssh > swconfig dev switch0 port 4 set disable 0


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

Design and rationale

Generic Netlink Switch configuration API


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:

Such switches can be connected to the controlling CPU using different hardware busses, but most commonly:

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:

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:

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 (DSA) 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.

* More info e.g. at 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).

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:

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:

The switch_dev_ops structure also contains an extensible way of representing and querying switch specific features, 3 different types of attributes are available:

Each of these 3 categories must be represented using an array of "struct switch_attr" attributes. This structure must be filed with:

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.