0001 =============================================
0002 Broadcom Starfighter 2 Ethernet switch driver
0003 =============================================
0004
0005 Broadcom's Starfighter 2 Ethernet switch hardware block is commonly found and
0006 deployed in the following products:
0007
0008 - xDSL gateways such as BCM63138
0009 - streaming/multimedia Set Top Box such as BCM7445
0010 - Cable Modem/residential gateways such as BCM7145/BCM3390
0011
0012 The switch is typically deployed in a configuration involving between 5 to 13
0013 ports, offering a range of built-in and customizable interfaces:
0014
0015 - single integrated Gigabit PHY
0016 - quad integrated Gigabit PHY
0017 - quad external Gigabit PHY w/ MDIO multiplexer
0018 - integrated MoCA PHY
0019 - several external MII/RevMII/GMII/RGMII interfaces
0020
0021 The switch also supports specific congestion control features which allow MoCA
0022 fail-over not to lose packets during a MoCA role re-election, as well as out of
0023 band back-pressure to the host CPU network interface when downstream interfaces
0024 are connected at a lower speed.
0025
0026 The switch hardware block is typically interfaced using MMIO accesses and
0027 contains a bunch of sub-blocks/registers:
0028
0029 - ``SWITCH_CORE``: common switch registers
0030 - ``SWITCH_REG``: external interfaces switch register
0031 - ``SWITCH_MDIO``: external MDIO bus controller (there is another one in SWITCH_CORE,
0032 which is used for indirect PHY accesses)
0033 - ``SWITCH_INDIR_RW``: 64-bits wide register helper block
0034 - ``SWITCH_INTRL2_0/1``: Level-2 interrupt controllers
0035 - ``SWITCH_ACB``: Admission control block
0036 - ``SWITCH_FCB``: Fail-over control block
0037
0038 Implementation details
0039 ======================
0040
0041 The driver is located in ``drivers/net/dsa/bcm_sf2.c`` and is implemented as a DSA
0042 driver; see ``Documentation/networking/dsa/dsa.rst`` for details on the subsystem
0043 and what it provides.
0044
0045 The SF2 switch is configured to enable a Broadcom specific 4-bytes switch tag
0046 which gets inserted by the switch for every packet forwarded to the CPU
0047 interface, conversely, the CPU network interface should insert a similar tag for
0048 packets entering the CPU port. The tag format is described in
0049 ``net/dsa/tag_brcm.c``.
0050
0051 Overall, the SF2 driver is a fairly regular DSA driver; there are a few
0052 specifics covered below.
0053
0054 Device Tree probing
0055 -------------------
0056
0057 The DSA platform device driver is probed using a specific compatible string
0058 provided in ``net/dsa/dsa.c``. The reason for that is because the DSA subsystem gets
0059 registered as a platform device driver currently. DSA will provide the needed
0060 device_node pointers which are then accessible by the switch driver setup
0061 function to setup resources such as register ranges and interrupts. This
0062 currently works very well because none of the of_* functions utilized by the
0063 driver require a struct device to be bound to a struct device_node, but things
0064 may change in the future.
0065
0066 MDIO indirect accesses
0067 ----------------------
0068
0069 Due to a limitation in how Broadcom switches have been designed, external
0070 Broadcom switches connected to a SF2 require the use of the DSA slave MDIO bus
0071 in order to properly configure them. By default, the SF2 pseudo-PHY address, and
0072 an external switch pseudo-PHY address will both be snooping for incoming MDIO
0073 transactions, since they are at the same address (30), resulting in some kind of
0074 "double" programming. Using DSA, and setting ``ds->phys_mii_mask`` accordingly, we
0075 selectively divert reads and writes towards external Broadcom switches
0076 pseudo-PHY addresses. Newer revisions of the SF2 hardware have introduced a
0077 configurable pseudo-PHY address which circumvents the initial design limitation.
0078
0079 Multimedia over CoAxial (MoCA) interfaces
0080 -----------------------------------------
0081
0082 MoCA interfaces are fairly specific and require the use of a firmware blob which
0083 gets loaded onto the MoCA processor(s) for packet processing. The switch
0084 hardware contains logic which will assert/de-assert link states accordingly for
0085 the MoCA interface whenever the MoCA coaxial cable gets disconnected or the
0086 firmware gets reloaded. The SF2 driver relies on such events to properly set its
0087 MoCA interface carrier state and properly report this to the networking stack.
0088
0089 The MoCA interfaces are supported using the PHY library's fixed PHY/emulated PHY
0090 device and the switch driver registers a ``fixed_link_update`` callback for such
0091 PHYs which reflects the link state obtained from the interrupt handler.
0092
0093
0094 Power Management
0095 ----------------
0096
0097 Whenever possible, the SF2 driver tries to minimize the overall switch power
0098 consumption by applying a combination of:
0099
0100 - turning off internal buffers/memories
0101 - disabling packet processing logic
0102 - putting integrated PHYs in IDDQ/low-power
0103 - reducing the switch core clock based on the active port count
0104 - enabling and advertising EEE
0105 - turning off RGMII data processing logic when the link goes down
0106
0107 Wake-on-LAN
0108 -----------
0109
0110 Wake-on-LAN is currently implemented by utilizing the host processor Ethernet
0111 MAC controller wake-on logic. Whenever Wake-on-LAN is requested, an intersection
0112 between the user request and the supported host Ethernet interface WoL
0113 capabilities is done and the intersection result gets configured. During
0114 system-wide suspend/resume, only ports not participating in Wake-on-LAN are
0115 disabled.
