Subject: Re: [PATCH net-next 4/4] net: documentation: add docs for MAC/PHY support in DPAA2

From: Russell King - ARM Linux admin <[email-masked]>
Date: Tue, 22 Oct 2019 10:49:46 +0100

On Tue, Oct 22, 2019 at 09:41:45AM +0000, Ioana Ciornei wrote:
> > Subject: Re: [PATCH net-next 4/4] net: documentation: add docs for MAC/PHY
> > support in DPAA2
> > 
> > This mentions phylink, but I never got the other patches of the series which
> > presumably implement this idea.
> 
> Hi Russell,
> 
> I copied you to the entire series. Anyhow, here is a link to the entire patch set - https://www.spinics.net/lists/netdev/msg606466.html.

Please avoid using [email-masked] for patches.  dspam doesn't
know about Linux stuff there, and so files emails that contain
patches into spam.  Please use [email-masked] for all kernel
related work, as per my addresses in the MAINTAINERS file.

I now need to manually transfer all those emails...

> > Please also note that I gave up waiting for another set, and as I now have
> > LX2160A hardware, I ended up writing my own version, which can be found in
> > my cex7 branch at:
> 
> I looked through the branch and it seems that the approach you are going for is similar (if not exactly the same) as the one from my previous patch set that was shut down.
> Also, sorry for the delay on sending another set but it takes a bit of time to consider all the implications of changing the entire architecture of the solution to better fit the upstream model.
> 
> Ioana
> 
> > 
> >  git://git.armlinux.org.uk/~rmk/linux-arm.git cex7
> > 
> > 
> > http://git.armlinux.org.uk/cgit/linux-arm.git/log/?h=cex7
> > 
> > On Tue, Oct 22, 2019 at 01:50:28AM +0300, Ioana Ciornei wrote:
> > > Add documentation file for the MAC/PHY support in the DPAA2
> > > architecture. This describes the architecture and implementation of
> > > the interface between phylink and a DPAA2 network driver.
> > >
> > > Signed-off-by: Ioana Ciornei <[email-masked]>
> > > ---
> > >  .../device_drivers/freescale/dpaa2/index.rst       |   1 +
> > >  .../freescale/dpaa2/mac-phy-support.rst            | 191
> > +++++++++++++++++++++
> > >  MAINTAINERS                                        |   2 +
> > >  3 files changed, 194 insertions(+)
> > >  create mode 100644
> > > Documentation/networking/device_drivers/freescale/dpaa2/mac-phy-suppor
> > > t.rst
> > >
> > > diff --git
> > > a/Documentation/networking/device_drivers/freescale/dpaa2/index.rst
> > > b/Documentation/networking/device_drivers/freescale/dpaa2/index.rst
> > > index 67bd87fe6c53..ee40fcc5ddff 100644
> > > ---
> > > a/Documentation/networking/device_drivers/freescale/dpaa2/index.rst
> > > +++ b/Documentation/networking/device_drivers/freescale/dpaa2/index.rs
> > > +++ t
> > > @@ -8,3 +8,4 @@ DPAA2 Documentation
> > >     overview
> > >     dpio-driver
> > >     ethernet-driver
> > > +   mac-phy-support
> > > diff --git
> > > a/Documentation/networking/device_drivers/freescale/dpaa2/mac-phy-supp
> > > ort.rst
> > > b/Documentation/networking/device_drivers/freescale/dpaa2/mac-phy-supp
> > > ort.rst
> > > new file mode 100644
> > > index 000000000000..51e6624fb774
> > > --- /dev/null
> > > +++ b/Documentation/networking/device_drivers/freescale/dpaa2/mac-phy-
> > > +++ support.rst
> > > @@ -0,0 +1,191 @@
> > > +.. SPDX-License-Identifier: GPL-2.0
> > > +.. include:: <isonum.txt>
> > > +
> > > +=======================
> > > +DPAA2 MAC / PHY support
> > > +=======================
> > > +
> > > +:Copyright: |copy| 2019 NXP
> > > +
> > > +Overview
> > > +--------
> > > +
> > > +The DPAA2 MAC / PHY support consists of a set of APIs that help DPAA2
> > > +network drivers (dpaa2-eth, dpaa2-ethsw) interract with the PHY library.
> > > +
> > > +DPAA2 Software Architecture
> > > +---------------------------
> > > +
> > > +Among other DPAA2 objects, the fsl-mc bus exports DPNI objects
> > > +(abstracting a network interface) and DPMAC objects (abstracting a
> > > +MAC). The dpaa2-eth driver probes on the DPNI object and connects to
> > > +and configures a DPMAC object with the help of phylink.
> > > +
> > > +Data connections may be established between a DPNI and a DPMAC, or
> > > +between two DPNIs. Depending on the connection type, the
> > > +netif_carrier_[on/off] is handled directly by the dpaa2-eth driver or by
> > phylink.
> > > +
> > > +.. code-block:: none
> > > +
> > > +  Sources of abstracted link state information presented by the MC
> > > + firmware
> > > +
> > > +                                               +--------------------------------------+
> > > +  +------------+                  +---------+  |                           xgmac_mdio |
> > > +  | net_device |                  | phylink |--|  +-----+  +-----+  +-----+  +-----+  |
> > > +  +------------+                  +---------+  |  | PHY |  | PHY |  | PHY |  | PHY |  |
> > > +        |                             |        |  +-----+  +-----+  +-----+  +-----+  |
> > > +      +------------------------------------+   |                    External MDIO bus |
> > > +      |            dpaa2-eth               |   +--------------------------------------+
> > > +      +------------------------------------+
> > > +        |                             |                                           Linux
> > > +
> > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > ~~~~~~~~~~~~~~~~~~~~
> > > +        |                             |                                     MC firmware
> > > +        |              /|             V
> > > +  +----------+        / |       +----------+
> > > +  |          |       /  |       |          |
> > > +  |          |       |  |       |          |
> > > +  |   DPNI   |<------|  |<------|   DPMAC  |
> > > +  |          |       |  |       |          |
> > > +  |          |       \  |<---+  |          |
> > > +  +----------+        \ |    |  +----------+
> > > +                       \|    |
> > > +                             |
> > > +           +--------------------------------------+
> > > +           | MC firmware polling MAC PCS for link |
> > > +           |  +-----+  +-----+  +-----+  +-----+  |
> > > +           |  | PCS |  | PCS |  | PCS |  | PCS |  |
> > > +           |  +-----+  +-----+  +-----+  +-----+  |
> > > +           |                    Internal MDIO bus |
> > > +           +--------------------------------------+
> > > +
> > > +
> > > +Depending on an MC firmware configuration setting, each MAC may be in
> > one of two modes:
> > > +
> > > +- DPMAC_LINK_TYPE_FIXED: the link state management is handled
> > > +exclusively by
> > > +  the MC firmware by polling the MAC PCS. Without the need to
> > > +register a
> > > +  phylink instance, the dpaa2-eth driver will not bind to the
> > > +connected dpmac
> > > +  object at all.
> > > +
> > > +- DPMAC_LINK_TYPE_PHY: The MC firmware is left waiting for link state
> > > +update
> > > +  events, but those are in fact passed strictly between the dpaa2-mac
> > > +(based on
> > > +  phylink) and its attached net_device driver (dpaa2-eth,
> > > +dpaa2-ethsw),
> > > +  effectively bypassing the firmware.
> > > +
> > > +Implementation
> > > +--------------
> > > +
> > > +At probe time or when a DPNI's endpoint is dynamically changed, the
> > > +dpaa2-eth is responsible to find out if the peer object is a DPMAC
> > > +and if this is the case, to integrate it with PHYLINK using the
> > > +dpaa2_mac_connect() API, which will do the following:
> > > +
> > > + - look up the device tree for PHYLINK-compatible of binding
> > > + (phy-handle)
> > > + - will create a PHYLINK instance associated with the received
> > > + net_device
> > > + - connect to the PHY using phylink_of_phy_connect()
> > > +
> > > +The following phylink_mac_ops callback are implemented:
> > > +
> > > + - .validate() will populate the supported linkmodes with the MAC capabilities
> > > +   only when the phy_interface_t is RGMII_* (at the moment, this is the only
> > > +   link type supported by the driver).
> > > +
> > > + - .mac_config() will configure the MAC in the new configuration using the
> > > +   dpmac_set_link_state() MC firmware API.
> > > +
> > > + - .mac_link_up() / .mac_link_down() will update the MAC link using the same
> > > +   API described above.
> > > +
> > > +At driver unbind() or when the DPNI object is disconnected from the
> > > +DPMAC, the dpaa2-eth driver calls dpaa2_mac_disconnect() which will,
> > > +in turn, disconnect from the PHY and destroy the PHYLINK instance.
> > > +
> > > +In case of a DPNI-DPMAC connection, an 'ip link set dev eth0 up'
> > > +would start the following sequence of operations:
> > > +
> > > +(1) phylink_start() called from .dev_open().
> > > +(2) The .mac_config() and .mac_link_up() callbacks are called by PHYLINK.
> > > +(3) In order to configure the HW MAC, the MC Firmware API
> > > +    dpmac_set_link_state() is called.
> > > +(4) The firmware will eventually setup the HW MAC in the new configuration.
> > > +(5) A netif_carrier_on() call is made directly from PHYLINK on the associated
> > > +    net_device.
> > > +(6) The dpaa2-eth driver handles the LINK_STATE_CHANGE irq in order to
> > > +    enable/disable Rx taildrop based on the pause frame settings.
> > > +
> > > +.. code-block:: none
> > > +
> > > +  +---------+               +---------+
> > > +  | PHYLINK |-------------->|  eth0   |
> > > +  +---------+           (5) +---------+
> > > +  (1) ^  |
> > > +      |  |
> > > +      |  v (2)
> > > +  +-----------------------------------+
> > > +  |             dpaa2-eth             |
> > > +  +-----------------------------------+
> > > +         |                    ^ (6)
> > > +         |                    |
> > > +         v (3)                |
> > > +  +---------+---------------+---------+
> > > +  |  DPMAC  |               |  DPNI   |
> > > +  +---------+               +---------+
> > > +  |            MC Firmware            |
> > > +  +-----------------------------------+
> > > +         |
> > > +         |
> > > +         v (4)
> > > +  +-----------------------------------+
> > > +  |             HW MAC                |
> > > +  +-----------------------------------+
> > > +
> > > +In case of a DPNI-DPNI connection, a usual sequence of operations
> > > +looks like the following:
> > > +
> > > +(1) ip link set dev eth0 up
> > > +(2) The dpni_enable() MC API called on the associated fsl_mc_device.
> > > +(3) ip link set dev eth1 up
> > > +(4) The dpni_enable() MC API called on the associated fsl_mc_device.
> > > +(5) The LINK_STATE_CHANGED irq is received by both instances of the dpaa2-
> > eth
> > > +    driver because now the operational link state is up.
> > > +(6) The netif_carrier_on() is called on the exported net_device from
> > > +    link_state_update().
> > > +
> > > +.. code-block:: none
> > > +
> > > +  +---------+               +---------+
> > > +  |  eth0   |               |  eth1   |
> > > +  +---------+               +---------+
> > > +      |  ^                     ^  |
> > > +      |  |                     |  |
> > > +  (1) v  | (6)             (6) |  v (3)
> > > +  +---------+               +---------+
> > > +  |dpaa2-eth|               |dpaa2-eth|
> > > +  +---------+               +---------+
> > > +      |  ^                     ^  |
> > > +      |  |                     |  |
> > > +  (2) v  | (5)             (5) |  v (4)
> > > +  +---------+---------------+---------+
> > > +  |  DPNI   |               |  DPNI   |
> > > +  +---------+               +---------+
> > > +  |            MC Firmware            |
> > > +  +-----------------------------------+
> > > +
> > > +
> > > +Exported API
> > > +------------
> > > +
> > > +Any DPAA2 driver that drivers endpoints of DPMAC objects should
> > > +service its _EVENT_ENDPOINT_CHANGED irq and connect/disconnect from
> > > +the associated DPMAC when necessary using the below listed API::
> > > +
> > > + - int dpaa2_mac_connect(struct dpaa2_mac *mac);
> > > + - void dpaa2_mac_disconnect(struct dpaa2_mac *mac);
> > > +
> > > +A phylink integration is necessary only when the partner DPMAC is not of
> > TYPE_FIXED.
> > > +One can check for this condition using the below API::
> > > +
> > > + - bool dpaa2_mac_is_type_fixed(struct fsl_mc_device
> > > + *dpmac_dev,struct fsl_mc_io *mc_io);
> > > +
> > > +Before connection to a MAC, the caller must allocate and populate the
> > > +dpaa2_mac structure with the associated net_device, a pointer to the
> > > +MC portal to be used and the actual fsl_mc_device structure of the DPMAC.
> > > diff --git a/MAINTAINERS b/MAINTAINERS index
> > > d0e562d3ce5b..fdc3c89a4a6d 100644
> > > --- a/MAINTAINERS
> > > +++ b/MAINTAINERS
> > > @@ -5052,6 +5052,8 @@ F:	drivers/net/ethernet/freescale/dpaa2/dpmac*
> > >  F:	drivers/net/ethernet/freescale/dpaa2/dpkg.h
> > >  F:	drivers/net/ethernet/freescale/dpaa2/Makefile
> > >  F:	drivers/net/ethernet/freescale/dpaa2/Kconfig
> > > +F:	Documentation/networking/device_drivers/freescale/dpaa2/ethernet-
> > driver.rst
> > > +F:	Documentation/networking/device_drivers/freescale/dpaa2/mac-phy-
> > support.rst
> > >
> > >  DPAA2 ETHERNET SWITCH DRIVER
> > >  M:	Ioana Radulescu <[email-masked]>
> > > --
> > > 1.9.1
> > >
> > >
> > >
> > >
> > 
> > --
> > RMK's Patch system:
> > https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.ar
> > mlinux.org.uk%2Fdeveloper%2Fpatches%2F&amp;data=02%7C01%7Cioana.cior
> > nei%40nxp.com%7C3d68212cba5c486cd92208d756c7d35d%7C686ea1d3bc2b4c
> > 6fa92cd99c5c301635%7C0%7C0%7C637073288560452478&amp;sdata=JOi4zc4
> > WROKWPD085JMZw4mo8a6pyVZa4JXo6wiaD%2BI%3D&amp;reserved=0
> > FTTC broadband for 0.8mile line in suburbia: sync at 12.1Mbps down 622kbps up
> > According to speedtest.net: 11.9Mbps down 500kbps up
> 

-- 
RMK's Patch system: https://www.armlinux.org.uk/developer/patches/
FTTC broadband for 0.8mile line in suburbia: sync at 12.1Mbps down 622kbps up
According to speedtest.net: 11.9Mbps down 500kbps up