ASR_BASE
Change-Id: Icf3719cc0afe3eeb3edc7fa80a2eb5199ca9dda1
diff --git a/target/linux/generic/files/Documentation/networking/adm6996.txt b/target/linux/generic/files/Documentation/networking/adm6996.txt
new file mode 100644
index 0000000..ab59f1d
--- /dev/null
+++ b/target/linux/generic/files/Documentation/networking/adm6996.txt
@@ -0,0 +1,110 @@
+-------
+
+ADM6996FC / ADM6996M switch chip driver
+
+
+1. General information
+
+ This driver supports the FC and M models only. The ADM6996F and L are
+ completely different chips.
+
+ Support for the FC model is extremely limited at the moment. There is no VLAN
+ support as of yet. The driver will not offer an swconfig interface for the FC
+ chip.
+
+1.1 VLAN IDs
+
+ It is possible to define 16 different VLANs. Every VLAN has an identifier, its
+ VLAN ID. It is easiest if you use at most VLAN IDs 0-15. In that case, the
+ swconfig based configuration is very straightforward. To define two VLANs with
+ IDs 4 and 5, you can invoke, for example:
+
+ # swconfig dev ethX vlan 4 set ports '0 1t 2 5t'
+ # swconfig dev ethX vlan 5 set ports '0t 1t 5t'
+
+ The swconfig framework will automatically invoke 'port Y set pvid Z' for every
+ port that is an untagged member of VLAN Y, setting its Primary VLAN ID. In
+ this example, ports 0 and 2 would get "pvid 4". The Primary VLAN ID of a port
+ is the VLAN ID associated with untagged packets coming in on that port.
+
+ But if you wish to use VLAN IDs outside the range 0-15, this automatic
+ behaviour of the swconfig framework becomes a problem. The 16 VLANs that
+ swconfig can configure on the ADM6996 also have a "vid" setting. By default,
+ this is the same as the number of the VLAN entry, to make the simple behaviour
+ above possible. To still support a VLAN with a VLAN ID higher than 15
+ (presumably because you are in a network where such VLAN IDs are already in
+ use), you can change the "vid" setting of the VLAN to anything in the range
+ 0-1023. But suppose you did the following:
+
+ # swconfig dev ethX vlan 0 set vid 998
+ # swconfig dev ethX vlan 0 set ports '0 2 5t'
+
+ Now the swconfig framework will issue 'port 0 set pvid 0' and 'port 2 set pvid
+ 0'. But the "pvid" should be set to 998, so you are responsible for manually
+ fixing this!
+
+1.2 VLAN filtering
+
+ The switch is configured to apply source port filtering. This means that
+ packets are only accepted when the port the packets came in on is a member of
+ the VLAN the packet should go to.
+
+ Only membership of a VLAN is tested, it does not matter whether it is a tagged
+ or untagged membership.
+
+ For untagged packets, the destination VLAN is the Primary VLAN ID of the
+ incoming port. So if the PVID of a port is 0, but that port is not a member of
+ the VLAN with ID 0, this means that untagged packets on that port are dropped.
+ This can be used as a roundabout way of dropping untagged packets from a port,
+ a mode often referred to as "Admit only tagged packets".
+
+1.3 Reset
+
+ The two supported chip models do not have a sofware-initiated reset. When the
+ driver is initialised, as well as when the 'reset' swconfig option is invoked,
+ the driver will set those registers it knows about and supports to the correct
+ default value. But there are a lot of registers in the chip that the driver
+ does not support. If something changed those registers, invoking 'reset' or
+ performing a warm reboot might still leave the chip in a "broken" state. Only
+ a hardware reset will bring it back in the default state.
+
+2. Technical details on PHYs and the ADM6996
+
+ From the viewpoint of the Linux kernel, it is common that an Ethernet adapter
+ can be seen as a separate MAC entity and a separate PHY entity. The PHY entity
+ can be queried and set through registers accessible via an MDIO bus. A PHY
+ normally has a single address on that bus, in the range 0 through 31.
+
+ The ADM6996 has special-purpose registers in the range of PHYs 0 through 10.
+ Even though all these registers control a single ADM6996 chip, the Linux
+ kernel treats this as 11 separate PHYs. The driver will bind to these
+ addresses to prevent a different PHY driver from binding and corrupting these
+ registers.
+
+ What Linux sees as the PHY on address 0 is meant for the Ethernet MAC
+ connected to the CPU port of the ADM6996 switch chip (port 5). This is the
+ Ethernet MAC you will use to send and receive data through the switch.
+
+ The PHYs at addresses 16 through 20 map to the PHYs on ports 0 through 4 of
+ the switch chip. These can be accessed with the Generic PHY driver, as the
+ registers have the common layout.
+
+ If a second Ethernet MAC on your board is wired to the port 4 PHY, that MAC
+ needs to bind to PHY address 20 for the port to work correctly.
+
+ The ADM6996 switch driver will reset the ports 0 through 3 on startup and when
+ 'reset' is invoked. This could clash with a different PHY driver if the kernel
+ binds a PHY driver to address 16 through 19.
+
+ If Linux binds a PHY on addresses 1 through 10 to an Ethernet MAC, the ADM6996
+ driver will simply always report a connected 100 Mbit/s full-duplex link for
+ that PHY, and provide no other functionality. This is most likely not what you
+ want. So if you see a message in your log
+
+ ethX: PHY overlaps ADM6996, providing fixed PHY yy.
+
+ This is most likely an indication that ethX will not work properly, and your
+ kernel needs to be configured to attach a different PHY to that Ethernet MAC.
+
+ Controlling the mapping between MACs and PHYs is usually done in platform- or
+ board-specific fixup code. The ADM6996 driver has no influence over this.