Merge branch 'phy-doc-improvements'

 drivers/net/ethernet/freescale/fsl_pq_mdio.c and an associated DTS file

 for one of the users. (e.g. "git grep fsl,.*-mdio arch/powerpc/boot/dts/")

(RG)MII/electrical interface considerations

 The Reduced Gigabit Medium Independent Interface (RGMII) is a 12-pin

 electrical signal interface using a synchronous 125Mhz clock signal and several

 data lines. Due to this design decision, a 1.5ns to 2ns delay must be added

 between the clock line (RXC or TXC) and the data lines to let the PHY (clock

 sink) have enough setup and hold times to sample the data lines correctly. The

 PHY library offers different types of PHY_INTERFACE_MODE_RGMII* values to let

 the PHY driver and optionally the MAC driver, implement the required delay. The

 values of phy_interface_t must be understood from the perspective of the PHY

 device itself, leading to the following:

 * PHY_INTERFACE_MODE_RGMII: the PHY is not responsible for inserting any

   internal delay by itself, it assumes that either the Ethernet MAC (if capable

   or the PCB traces) insert the correct 1.5-2ns delay

 * PHY_INTERFACE_MODE_RGMII_TXID: the PHY should insert an internal delay

   for the transmit data lines (TXD[3:0]) processed by the PHY device

 * PHY_INTERFACE_MODE_RGMII_RXID: the PHY should insert an internal delay

   for the receive data lines (RXD[3:0]) processed by the PHY device

 * PHY_INTERFACE_MODE_RGMII_ID: the PHY should insert internal delays for

   both transmit AND receive data lines from/to the PHY device

 Whenever possible, use the PHY side RGMII delay for these reasons:

 * PHY devices may offer sub-nanosecond granularity in how they allow a

   receiver/transmitter side delay (e.g: 0.5, 1.0, 1.5ns) to be specified. Such

   precision may be required to account for differences in PCB trace lengths

 * PHY devices are typically qualified for a large range of applications

   (industrial, medical, automotive...), and they provide a constant and

   reliable delay across temperature/pressure/voltage ranges

 * PHY device drivers in PHYLIB being reusable by nature, being able to

   configure correctly a specified delay enables more designs with similar delay

   requirements to be operate correctly

 For cases where the PHY is not capable of providing this delay, but the

 Ethernet MAC driver is capable of doing so, the correct phy_interface_t value

 should be PHY_INTERFACE_MODE_RGMII, and the Ethernet MAC driver should be

 configured correctly in order to provide the required transmit and/or receive

 side delay from the perspective of the PHY device. Conversely, if the Ethernet

 MAC driver looks at the phy_interface_t value, for any other mode but

 PHY_INTERFACE_MODE_RGMII, it should make sure that the MAC-level delays are

 disabled.

 In case neither the Ethernet MAC, nor the PHY are capable of providing the

 required delays, as defined per the RGMII standard, several options may be

 available:

 * Some SoCs may offer a pin pad/mux/controller capable of configuring a given

   set of pins'strength, delays, and voltage; and it may be a suitable

   option to insert the expected 2ns RGMII delay.

 * Modifying the PCB design to include a fixed delay (e.g: using a specifically

   designed serpentine), which may not require software configuration at all.

Common problems with RGMII delay mismatch

 When there is a RGMII delay mismatch between the Ethernet MAC and the PHY, this

 will most likely result in the clock and data line signals to be unstable when

 the PHY or MAC take a snapshot of these signals to translate them into logical

 1 or 0 states and reconstruct the data being transmitted/received. Typical

 symptoms include:

 * Transmission/reception partially works, and there is frequent or occasional

   packet loss observed

 * Ethernet MAC may report some or all packets ingressing with a FCS/CRC error,

   or just discard them all

 * Switching to lower speeds such as 10/100Mbits/sec makes the problem go away

   (since there is enough setup/hold time in that case)

Connecting to a PHY

 Sometime during startup, the network driver needs to establish a connection

 values pruned from them which don't make sense for your controller (a 10/100

 controller may be connected to a gigabit capable PHY, so you would need to

 mask off SUPPORTED_1000baseT*).  See include/linux/ethtool.h for definitions

 for these bitfields. Note that you should not SET any bits, or the PHY may

 get put into an unsupported state.

 for these bitfields. Note that you should not SET any bits, except the

 SUPPORTED_Pause and SUPPORTED_AsymPause bits (see below), or the PHY may get

 put into an unsupported state.

 Lastly, once the controller is ready to handle network traffic, you call

 phy_start(phydev).  This tells the PAL that you are ready, and configures the

 When you want to disconnect from the network (even if just briefly), you call

 phy_stop(phydev).

Pause frames / flow control

 The PHY does not participate directly in flow control/pause frames except by

 making sure that the SUPPORTED_Pause and SUPPORTED_AsymPause bits are set in

 MII_ADVERTISE to indicate towards the link partner that the Ethernet MAC

 controller supports such a thing. Since flow control/pause frames generation

 involves the Ethernet MAC driver, it is recommended that this driver takes care

 of properly indicating advertisement and support for such features by setting

 the SUPPORTED_Pause and SUPPORTED_AsymPause bits accordingly. This can be done

 either before or after phy_connect() and/or as a result of implementing the

 ethtool::set_pauseparam feature.

Keeping Close Tabs on the PAL

 It is possible that the PAL's built-in state machine needs a little help to

 PHY_BASIC_FEATURES, but you can look in include/mii.h for other

 features.

 Each driver consists of a number of function pointers:

   soft_reset: perform a PHY software reset

   config_init: configures PHY into a sane state after a reset.

     For instance, a Davicom PHY requires descrambling disabled.

   probe: Allocate phy->priv, optionally refuse to bind.

   PHY may not have been reset or had fixups run yet.

   suspend/resume: power management

   config_aneg: Changes the speed/duplex/negotiation settings

   aneg_done: Determines the auto-negotiation result

   read_status: Reads the current speed/duplex/negotiation settings

   ack_interrupt: Clear a pending interrupt

   did_interrupt: Checks if the PHY generated an interrupt

   config_intr: Enable or disable interrupts

   remove: Does any driver take-down

   ts_info: Queries about the HW timestamping status

   match_phy_device: used for Clause 45 capable PHYs to match devices

   in package and ensure they are compatible

   hwtstamp: Set the PHY HW timestamping configuration

   rxtstamp: Requests a receive timestamp at the PHY level for a 'skb'

   txtsamp: Requests a transmit timestamp at the PHY level for a 'skb'

   set_wol: Enable Wake-on-LAN at the PHY level

   get_wol: Get the Wake-on-LAN status at the PHY level

   link_change_notify: called to inform the core is about to change the

   link state, can be used to work around bogus PHY between state changes

   read_mmd_indirect: Read PHY MMD indirect register

   write_mmd_indirect: Write PHY MMD indirect register

   module_info: Get the size and type of an EEPROM contained in an plug-in

   module

   module_eeprom: Get EEPROM information of a plug-in module

   get_sset_count: Get number of strings sets that get_strings will count

   get_strings: Get strings from requested objects (statistics)

   get_stats: Get the extended statistics from the PHY device

 Each driver consists of a number of function pointers, documented

 in include/linux/phy.h under the phy_driver structure.

 Of these, only config_aneg and read_status are required to be

 assigned by the driver code.  The rest are optional.  Also, it is

 The stubs set one of the two matching criteria, and set the other one to

 match anything.

Standards

 IEEE Standard 802.3: CSMA/CD Access Method and Physical Layer Specifications, Section Two:

 http://standards.ieee.org/getieee802/download/802.3-2008_section2.pdf

 RGMII v1.3:

 http://web.archive.org/web/20160303212629/http://www.hp.com/rnd/pdfs/RGMIIv1_3.pdf

 RGMII v2.0:

 http://web.archive.org/web/20160303171328/http://www.hp.com/rnd/pdfs/RGMIIv2_0_final_hp.pdf