Documentation/networking/adm6996.txt - kernel/windcharger - Git at Google

 -------

 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.
	-------

	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.