[RFC PATCH net-next 12/13] Documentation: networking: dsa: Add details about NXP SJA1105 driver

[Vladimir Oltean <olteanv@gmail.com>]

Signed-off-by: Vladimir Oltean <olteanv@gmail.com>
---
 Documentation/networking/dsa/sja1105.txt | 83 ++++++++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 Documentation/networking/dsa/sja1105.txt

diff --git a/Documentation/networking/dsa/sja1105.txt b/Documentation/networking/dsa/sja1105.txt
new file mode 100644
index 000000000000..b6f2c1bedd02
--- /dev/null
+++ b/Documentation/networking/dsa/sja1105.txt
@@ -0,0 +1,83 @@
+NXP SJA1105 switch driver
+=========================
+
+The NXP SJA1105 is a family of 6 devices:
+* SJA1105E: First generation, no TTEthernet
+* SJA1105T: First generation, TTEthernet
+* SJA1105P: Second generation, no TTEthernet, no SGMII
+* SJA1105Q: Second generation, TTEthernet, no SGMII
+* SJA1105R: Second generation, no TTEthernet, SGMII
+* SJA1105S: Second generation, TTEthernet, SGMII
+
+These are SPI-managed automotive switches, with all ports being gigabit
+capable, and supporting MII/RMII/RGMII and optionally SGMII on one port.
+
+The switches do not have an MDIO bus of their own and do not support
+in-band autonegotiation, so for proper PHY management, the host's MDIO
+bus controller needs to be used.
+
+Being automotive parts, their configuration interface is geared towards
+set-and-forget use, with minimal dynamic interaction at runtime. They
+require a static configuration to be composed by software and packed
+with CRC and table headers, and sent over SPI.
+
+The static configuration is composed of several configuration tables. Each
+table takes a number of entries. Some configuration tables can be (partially)
+reconfigured at runtime, some not. Some tables are mandatory, some not.
+
+Table                        | Mandatory        | Reconfigurable
+-----------------------------+------------------+-----------------------------
+Schedule                     | no               | no
+Schedule entry points        | if Scheduling    | no
+VL Lookup                    | no               | no
+VL Policing                  | if VL Lookup     | no
+VL Forwarding                | if VL Lookup     | no
+L2 Lookup                    | no               | no
+L2 Policing                  | yes              | no
+VLAN Lookup                  | yes              | yes
+L2 Forwarding                | yes              | partially (fully on P/Q/R/S)
+MAC Config                   | yes              | partially (fully on P/Q/R/S)
+Schedule Params              | if Scheduling    | no
+Schedule Entry Points Params | if Scheduling    | no
+VL Forwarding Params         | if VL Forwarding | no
+L2 Lookup Params             | no               | partially (fully on P/Q/R/S)
+L2 Forwarding Params         | yes              | no
+Clock Sync Params            | no               | no
+AVB Params                   | no               | no
+General Params               | yes              | partially
+Retagging                    | no               | yes
+xMII Params                  | yes              | no
+SGMII                        | no               | yes
+
+Also the configuration is write-only (software cannot read it back from the
+switch except for very few exceptions).
+
+So the driver creates the static configuration at probe time, and keeps it at
+all times in memory, as a shadow for the hardware state. When required to
+change a hardware setting, the static configuration is also updated.
+If that changed setting can be transmitted to the switch through the dynamic
+reconfiguration interface, it is; otherwise the switch is reset and
+reprogrammed with the updated static configuration.
+
+The switches do not support switch tagging in hardware. But they do support
+customizing the TPID by which VLAN traffic is identified as such. The switch
+driver is leveraging CONFIG_NET_DSA_TAG_8021Q by requesting that special VLANs
+(with a custom TPID of ETH_P_EDSA instead of ETH_P_8021Q) are installed on its
+ports when not in vlan_filtering mode. This does not interfere with the
+reception and transmission of real 802.1Q-tagged traffic, because the switch
+does no longer parse those packets as VLAN after the TPID change.
+The TPID is restored when vlan_filtering is requested, and IP termination
+becomes no longer possible through the switch netdevices in this mode.
+
+The switches have two programmable filters for link-local destination MACs.
+These are used to trap BPDUs and PTP traffic to the master netdevice, and are
+further used to support STP and 1588 ordinary clock/boundary clock
+functionality.
+
+Among other notable features, the switches have a PTP Hardware Clock that can
+be steered through SPI and used for timestamping on ingress and egress.
+Also, the T, Q and S devices support TTEthernet (an implementation of
+SAE AS6802 from TTTech), which is a set of Ethernet QoS enhancements similar in
+behavior to IEEE TSN. Configuring these features is currently not supported in
+the driver.
+
-- 
2.17.1