1Broadcom Starfighter 2 Ethernet switch driver
  2=============================================
  3
  4Broadcom's Starfighter 2 Ethernet switch hardware block is commonly found and
  5deployed in the following products:
  6
  7- xDSL gateways such as BCM63138
  8- streaming/multimedia Set Top Box such as BCM7445
  9- Cable Modem/residential gateways such as BCM7145/BCM3390
 10
 11The switch is typically deployed in a configuration involving between 5 to 13
 12ports, offering a range of built-in and customizable interfaces:
 13
 14- single integrated Gigabit PHY
 15- quad integrated Gigabit PHY
 16- quad external Gigabit PHY w/ MDIO multiplexer
 17- integrated MoCA PHY
 18- several external MII/RevMII/GMII/RGMII interfaces
 19
 20The switch also supports specific congestion control features which allow MoCA
 21fail-over not to lose packets during a MoCA role re-election, as well as out of
 22band back-pressure to the host CPU network interface when downstream interfaces
 23are connected at a lower speed.
 24
 25The switch hardware block is typically interfaced using MMIO accesses and
 26contains a bunch of sub-blocks/registers:
 27
 28* SWITCH_CORE: common switch registers
 29* SWITCH_REG: external interfaces switch register
 30* SWITCH_MDIO: external MDIO bus controller (there is another one in SWITCH_CORE,
 31  which is used for indirect PHY accesses)
 32* SWITCH_INDIR_RW: 64-bits wide register helper block
 33* SWITCH_INTRL2_0/1: Level-2 interrupt controllers
 34* SWITCH_ACB: Admission control block
 35* SWITCH_FCB: Fail-over control block
 36
 37Implementation details
 38======================
 39
 40The driver is located in drivers/net/dsa/bcm_sf2.c and is implemented as a DSA
 41driver; see Documentation/networking/dsa/dsa.txt for details on the subsytem
 42and what it provides.
 43
 44The SF2 switch is configured to enable a Broadcom specific 4-bytes switch tag
 45which gets inserted by the switch for every packet forwarded to the CPU
 46interface, conversely, the CPU network interface should insert a similar tag for
 47packets entering the CPU port. The tag format is described in
 48net/dsa/tag_brcm.c.
 49
 50Overall, the SF2 driver is a fairly regular DSA driver; there are a few
 51specifics covered below.
 52
 53Device Tree probing
 54-------------------
 55
 56The DSA platform device driver is probed using a specific compatible string
 57provided in net/dsa/dsa.c. The reason for that is because the DSA subsystem gets
 58registered as a platform device driver currently. DSA will provide the needed
 59device_node pointers which are then accessible by the switch driver setup
 60function to setup resources such as register ranges and interrupts. This
 61currently works very well because none of the of_* functions utilized by the
 62driver require a struct device to be bound to a struct device_node, but things
 63may change in the future.
 64
 65MDIO indirect accesses
 66----------------------
 67
 68Due to a limitation in how Broadcom switches have been designed, external
 69Broadcom switches connected to a SF2 require the use of the DSA slave MDIO bus
 70in order to properly configure them. By default, the SF2 pseudo-PHY address, and
 71an external switch pseudo-PHY address will both be snooping for incoming MDIO
 72transactions, since they are at the same address (30), resulting in some kind of
 73"double" programming. Using DSA, and setting ds->phys_mii_mask accordingly, we
 74selectively divert reads and writes towards external Broadcom switches
 75pseudo-PHY addresses. Newer revisions of the SF2 hardware have introduced a
 76configurable pseudo-PHY address which circumvents the initial design limitation.
 77
 78Multimedia over CoAxial (MoCA) interfaces
 79-----------------------------------------
 80
 81MoCA interfaces are fairly specific and require the use of a firmware blob which
 82gets loaded onto the MoCA processor(s) for packet processing. The switch
 83hardware contains logic which will assert/de-assert link states accordingly for
 84the MoCA interface whenever the MoCA coaxial cable gets disconnected or the
 85firmware gets reloaded. The SF2 driver relies on such events to properly set its
 86MoCA interface carrier state and properly report this to the networking stack.
 87
 88The MoCA interfaces are supported using the PHY library's fixed PHY/emulated PHY
 89device and the switch driver registers a fixed_link_update callback for such
 90PHYs which reflects the link state obtained from the interrupt handler.
 91
 92
 93Power Management
 94----------------
 95
 96Whenever possible, the SF2 driver tries to minimize the overall switch power
 97consumption by applying a combination of:
 98
 99- turning off internal buffers/memories
100- disabling packet processing logic
101- putting integrated PHYs in IDDQ/low-power
102- reducing the switch core clock based on the active port count
103- enabling and advertising EEE
104- turning off RGMII data processing logic when the link goes down
105
106Wake-on-LAN
107-----------
108
109Wake-on-LAN is currently implemented by utilizing the host processor Ethernet
110MAC controller wake-on logic. Whenever Wake-on-LAN is requested, an intersection
111between the user request and the supported host Ethernet interface WoL
112capabilities is done and the intersection result gets configured. During
113system-wide suspend/resume, only ports not participating in Wake-on-LAN are
114disabled.