cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

mac-phy-support.rst (7798B)


      1.. SPDX-License-Identifier: GPL-2.0
      2.. include:: <isonum.txt>
      3
      4=======================
      5DPAA2 MAC / PHY support
      6=======================
      7
      8:Copyright: |copy| 2019 NXP
      9
     10Overview
     11--------
     12
     13The DPAA2 MAC / PHY support consists of a set of APIs that help DPAA2 network
     14drivers (dpaa2-eth, dpaa2-ethsw) interract with the PHY library.
     15
     16DPAA2 Software Architecture
     17---------------------------
     18
     19Among other DPAA2 objects, the fsl-mc bus exports DPNI objects (abstracting a
     20network interface) and DPMAC objects (abstracting a MAC). The dpaa2-eth driver
     21probes on the DPNI object and connects to and configures a DPMAC object with
     22the help of phylink.
     23
     24Data connections may be established between a DPNI and a DPMAC, or between two
     25DPNIs. Depending on the connection type, the netif_carrier_[on/off] is handled
     26directly by the dpaa2-eth driver or by phylink.
     27
     28.. code-block:: none
     29
     30  Sources of abstracted link state information presented by the MC firmware
     31
     32                                               +--------------------------------------+
     33  +------------+                  +---------+  |                           xgmac_mdio |
     34  | net_device |                  | phylink |--|  +-----+  +-----+  +-----+  +-----+  |
     35  +------------+                  +---------+  |  | PHY |  | PHY |  | PHY |  | PHY |  |
     36        |                             |        |  +-----+  +-----+  +-----+  +-----+  |
     37      +------------------------------------+   |                    External MDIO bus |
     38      |            dpaa2-eth               |   +--------------------------------------+
     39      +------------------------------------+
     40        |                             |                                           Linux
     41  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     42        |                             |                                     MC firmware
     43        |              /|             V
     44  +----------+        / |       +----------+
     45  |          |       /  |       |          |
     46  |          |       |  |       |          |
     47  |   DPNI   |<------|  |<------|   DPMAC  |
     48  |          |       |  |       |          |
     49  |          |       \  |<---+  |          |
     50  +----------+        \ |    |  +----------+
     51                       \|    |
     52                             |
     53           +--------------------------------------+
     54           | MC firmware polling MAC PCS for link |
     55           |  +-----+  +-----+  +-----+  +-----+  |
     56           |  | PCS |  | PCS |  | PCS |  | PCS |  |
     57           |  +-----+  +-----+  +-----+  +-----+  |
     58           |                    Internal MDIO bus |
     59           +--------------------------------------+
     60
     61
     62Depending on an MC firmware configuration setting, each MAC may be in one of two modes:
     63
     64- DPMAC_LINK_TYPE_FIXED: the link state management is handled exclusively by
     65  the MC firmware by polling the MAC PCS. Without the need to register a
     66  phylink instance, the dpaa2-eth driver will not bind to the connected dpmac
     67  object at all.
     68
     69- DPMAC_LINK_TYPE_PHY: The MC firmware is left waiting for link state update
     70  events, but those are in fact passed strictly between the dpaa2-mac (based on
     71  phylink) and its attached net_device driver (dpaa2-eth, dpaa2-ethsw),
     72  effectively bypassing the firmware.
     73
     74Implementation
     75--------------
     76
     77At probe time or when a DPNI's endpoint is dynamically changed, the dpaa2-eth
     78is responsible to find out if the peer object is a DPMAC and if this is the
     79case, to integrate it with PHYLINK using the dpaa2_mac_connect() API, which
     80will do the following:
     81
     82 - look up the device tree for PHYLINK-compatible of binding (phy-handle)
     83 - will create a PHYLINK instance associated with the received net_device
     84 - connect to the PHY using phylink_of_phy_connect()
     85
     86The following phylink_mac_ops callback are implemented:
     87
     88 - .validate() will populate the supported linkmodes with the MAC capabilities
     89   only when the phy_interface_t is RGMII_* (at the moment, this is the only
     90   link type supported by the driver).
     91
     92 - .mac_config() will configure the MAC in the new configuration using the
     93   dpmac_set_link_state() MC firmware API.
     94
     95 - .mac_link_up() / .mac_link_down() will update the MAC link using the same
     96   API described above.
     97
     98At driver unbind() or when the DPNI object is disconnected from the DPMAC, the
     99dpaa2-eth driver calls dpaa2_mac_disconnect() which will, in turn, disconnect
    100from the PHY and destroy the PHYLINK instance.
    101
    102In case of a DPNI-DPMAC connection, an 'ip link set dev eth0 up' would start
    103the following sequence of operations:
    104
    105(1) phylink_start() called from .dev_open().
    106(2) The .mac_config() and .mac_link_up() callbacks are called by PHYLINK.
    107(3) In order to configure the HW MAC, the MC Firmware API
    108    dpmac_set_link_state() is called.
    109(4) The firmware will eventually setup the HW MAC in the new configuration.
    110(5) A netif_carrier_on() call is made directly from PHYLINK on the associated
    111    net_device.
    112(6) The dpaa2-eth driver handles the LINK_STATE_CHANGE irq in order to
    113    enable/disable Rx taildrop based on the pause frame settings.
    114
    115.. code-block:: none
    116
    117  +---------+               +---------+
    118  | PHYLINK |-------------->|  eth0   |
    119  +---------+           (5) +---------+
    120  (1) ^  |
    121      |  |
    122      |  v (2)
    123  +-----------------------------------+
    124  |             dpaa2-eth             |
    125  +-----------------------------------+
    126         |                    ^ (6)
    127         |                    |
    128         v (3)                |
    129  +---------+---------------+---------+
    130  |  DPMAC  |               |  DPNI   |
    131  +---------+               +---------+
    132  |            MC Firmware            |
    133  +-----------------------------------+
    134         |
    135         |
    136         v (4)
    137  +-----------------------------------+
    138  |             HW MAC                |
    139  +-----------------------------------+
    140
    141In case of a DPNI-DPNI connection, a usual sequence of operations looks like
    142the following:
    143
    144(1) ip link set dev eth0 up
    145(2) The dpni_enable() MC API called on the associated fsl_mc_device.
    146(3) ip link set dev eth1 up
    147(4) The dpni_enable() MC API called on the associated fsl_mc_device.
    148(5) The LINK_STATE_CHANGED irq is received by both instances of the dpaa2-eth
    149    driver because now the operational link state is up.
    150(6) The netif_carrier_on() is called on the exported net_device from
    151    link_state_update().
    152
    153.. code-block:: none
    154
    155  +---------+               +---------+
    156  |  eth0   |               |  eth1   |
    157  +---------+               +---------+
    158      |  ^                     ^  |
    159      |  |                     |  |
    160  (1) v  | (6)             (6) |  v (3)
    161  +---------+               +---------+
    162  |dpaa2-eth|               |dpaa2-eth|
    163  +---------+               +---------+
    164      |  ^                     ^  |
    165      |  |                     |  |
    166  (2) v  | (5)             (5) |  v (4)
    167  +---------+---------------+---------+
    168  |  DPNI   |               |  DPNI   |
    169  +---------+               +---------+
    170  |            MC Firmware            |
    171  +-----------------------------------+
    172
    173
    174Exported API
    175------------
    176
    177Any DPAA2 driver that drivers endpoints of DPMAC objects should service its
    178_EVENT_ENDPOINT_CHANGED irq and connect/disconnect from the associated DPMAC
    179when necessary using the below listed API::
    180
    181 - int dpaa2_mac_connect(struct dpaa2_mac *mac);
    182 - void dpaa2_mac_disconnect(struct dpaa2_mac *mac);
    183
    184A phylink integration is necessary only when the partner DPMAC is not of TYPE_FIXED.
    185One can check for this condition using the below API::
    186
    187 - bool dpaa2_mac_is_type_fixed(struct fsl_mc_device *dpmac_dev,struct fsl_mc_io *mc_io);
    188
    189Before connection to a MAC, the caller must allocate and populate the
    190dpaa2_mac structure with the associated net_device, a pointer to the MC portal
    191to be used and the actual fsl_mc_device structure of the DPMAC.