src/kernel/linux/v4.19/Documentation/networking/adm6996.txt

------- 

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.