[PATCH net-next 01/20] Documentation: networking: qcom PPE driver documentation
From: Luo Jie
Date: Wed Jan 10 2024 - 06:42:57 EST
From: Lei Wei <quic_leiwei@xxxxxxxxxxx>
Add Qualcomm PPE driver documentation
Signed-off-by: Lei Wei <quic_leiwei@xxxxxxxxxxx>
Signed-off-by: Luo Jie <quic_luoj@xxxxxxxxxxx>
---
.../device_drivers/ethernet/index.rst | 1 +
.../ethernet/qualcomm/ppe/ppe.rst | 305 ++++++++++++++++++
2 files changed, 306 insertions(+)
create mode 100644 Documentation/networking/device_drivers/ethernet/qualcomm/ppe/ppe.rst
diff --git a/Documentation/networking/device_drivers/ethernet/index.rst b/Documentation/networking/device_drivers/ethernet/index.rst
index 43de285b8a92..fff37383f995 100644
--- a/Documentation/networking/device_drivers/ethernet/index.rst
+++ b/Documentation/networking/device_drivers/ethernet/index.rst
@@ -47,6 +47,7 @@ Contents:
neterion/s2io
netronome/nfp
pensando/ionic
+ qualcomm/ppe/ppe
smsc/smc9
stmicro/stmmac
ti/cpsw
diff --git a/Documentation/networking/device_drivers/ethernet/qualcomm/ppe/ppe.rst b/Documentation/networking/device_drivers/ethernet/qualcomm/ppe/ppe.rst
new file mode 100644
index 000000000000..0f728a178ee7
--- /dev/null
+++ b/Documentation/networking/device_drivers/ethernet/qualcomm/ppe/ppe.rst
@@ -0,0 +1,305 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===================================================
+PPE Driver for Qualcomm PPE Ethernet Network Family
+===================================================
+
+Copyright (c) 2024 Qualcomm Innovation Center, Inc. All rights reserved.
+
+Author: Lei Wei <quic_leiwei@xxxxxxxxxxx>
+
+
+Contents
+========
+
+- `Overview`_
+- `PPE Driver Supported SoCs`_
+- `Enabling the Driver`_
+- `Supported Features`_
+- `PPE MAC and UNIPHY Interface`_
+- `Debugging`_
+- `APIs used by PPE EDMA driver`_
+- `Exported PPE Device Operations`_
+
+
+Overview
+========
+
+This file describes the Qualcomm PPE (Packet Process Engine) driver.
+
+PPE Architecture
+----------------
+
+PPE supports maximum 6 MACs (GMACs or XGMACs) which are connected with 6 PHYs through 3 UNIPHYs,
+the 6 PHYs correspond to 6 Panel ethernet ports from port1 to port6. Some IPQ platforms will have
+less than 6 MACs and 3 UNIPHYs.
+
+PPE supports to forward the ingress packets to EDMA network driver through intenal cpu port0. It
+also supports to forward packets between the PPE ports.
+
+A simplified example view of the PPE interfaces with PHYs and net devices::
+
+ +--------+ +--------+ +--------+ +--------+ +--------+ +--------+ start/stop +---------+
+ | netdev | | netdev | | netdev | | netdev | | netdev | | netdev | <-------------- | |
+ +--------+ +--------+ +--------+ +--------+ +--------+ +--------+ | |
+ | | |
+ P0 | |
+ | | |
+ +-------------------------------------------------------------------------+ | |
+ | | | |
+ | PPE(packet process engine) | | |
+ | | | |
+ | | | |
+ | +------+ +------+ +------+ +------+ +------+ +------+ | mac ops | phylink |
+ | | MAC0 | | MAC1 | | MAC2 | | MAC3 | | MAC4 | | MAC5 | | <-------- | |
+ | +------+ +------+ +------+ +------+ +------+ +------+ | | |
+ | | | | | | | | | |
+ +-------------------------------------------------------------------------+ | |
+ | | | | | | | |
+ +-------------------------------+ +-------------+ +-------------+ | |
+ | [ QSGMII ] | | [ USXGMII ] | | [ USXGMII ] | pcs ops | |
+ | UNIPHY0 | | UNIPHY1 | | UNIPHY2 | <------------ | |
+ | | | | | | | |
+ +-------------------------------+ +-------------+ +-------------+ | |
+ | | | | | | | |
+ +----------------------------------------------------------------------+ | |
+ | +------+ +------+ +------+ +------+ +------+ +------+ | link change | |
+ | | PHY0 | | PHY1 | | PHY2 | | PHY3 | | PHY4 | | PHY5 | | ----------> | |
+ | +------+ +------+ +------+ +------+ +------+ +------+ | | |
+ | | | | | | | MDIO bus | | |
+ +----------------------------------------------------------------------+ +---------+
+ | | | | | |
+ P1 P2 P3 P4 P5 P6
+
+
+PPE Driver Overview
+-------------------
+
+PPE driver is the PPE platform driver which executes the initialization of the PPE
+hardware including the PPE clock, Queue management, Buffer management, TDM,
+scheduler, RSS, MAC and UNIPHY.
+
+PPE driver provides PPE MAC and UNIPHY PCS operations for PHYLINK. It also exports
+a set of PPE operations. These operations can be used by network driver to drive
+PPE.
+
+PPE driver exports functions to get the PPE device and PPE device operations. Other
+network drivers such as PPE EDMA network driver can use the exported functions to
+get the PPE device and PPE device operations.
+
+PPE driver provides debugfs file to get the PPE packet counters. These packet counters
+include port Rx and Tx counters, CPU code counters and queue counters.
+
+
+PPE Driver Supported SoCs
+=========================
+
+The PPE drivers enable the PPE engine present on the following SoCs:
+
+- IPQ9574
+- IPQ5332
+
+
+Enabling the Driver
+===================
+
+The driver is enabled automatically by the network driver which depends on it such as
+Qualcomm EDMA driver.
+
+The driver is located in the menu structure at:
+
+ -> Device Drivers
+ -> Network device support (NETDEVICES [=y])
+ -> Ethernet driver support
+ -> Qualcomm devices
+ -> Qualcomm Technologies, Inc. PPE Ethernet support
+
+If this driver is built as a module, we can use below commands to install and remove
+it:
+
+- insmod qcom-ppe.ko
+- rmmod qcom-ppe.ko
+
+Please note that this driver should be installed before the Qualcomm EDMA driver
+and removed after the Qualcomm EDMA driver if it is built as a module.
+
+
+Supported Features
+==================
+
+PPE Interface mode - SGMII, 2500BASEX, USXGMII, 10GBASER, QSGMII and QUSGMII.
+
+PPE port link speed from 10Mbps to 10000Mbps.
+
+PPE Packets forwarding and offloading.
+
+PPE RSS.
+
+PPE Buffer Manager.
+
+PPE Queues Manager and Scheduler.
+
+
+PPE MAC and UNIPHY Interface
+============================
+
+PPE MAC and UNIPHY supports various interface mode including SGMII, 2500BASEX, USXGMII,
+10GBASER, QSGMII and QUSGMII. A various link including external PHY mode, 2.5G fixed
+link mode and 10G SFP mode are also supported.
+
+PPE driver provides two phylink ops functions to PPE EDMA network driver to setup and
+destroy phylink for each PPE ports. EDMA neworking driver will setup the phylink when
+each net device created and destroy the phylink when each net device removed.
+
+ - .phylink_setup() will lookup the PPE port device tree for PHYLINK-compatible of
+ binding (phy-handle) and create and return a PHYLINK instance associated with the
+ received net device for each port.
+
+ - .phylink_destroy() will disconnect and destroy the PHYLINK instance for each port.
+
+The PPE phylink MAC ops and UNIPHY PCS ops functions are implemented in the PPE driver
+to drive PPE MAC and UNIPHY to interact with PHYLINK framework.
+
+
+Debugging
+=========
+
+PPE packet counters can be checked by debugfs file ``/sys/kernel/debug/ppe/packet_counter``.
+
+PPE MAC statistics can be checked by ``ethtool -S ethX``.
+
+PPE UNIPHY clock and PPE port clock rate can be checked by the clock debugfs file
+in ``/sys/kernel/debug/clk/``.
+
+PPE port link state and PHY features can be also checked by ``ethtool ethX``.
+
+The SFP module state can be checked by the debugfs file in ``/sys/kernel/debug/@sfp/state``,
+where the ``@sfp`` is the SFP DTS node name.
+
+
+APIs used by PPE EDMA driver
+============================
+
+PPE driver also exports a set of APIs. Whether PPE driver have been probed can be
+checked by below API, the PPE EDMA driver uses it to query and ascertain that the
+PPE driver is installed and probed before going ahead with its initialization.
+::
+
+ bool ppe_is_probed(struct platform_device *pdev);
+
+PPE driver private PPE device structure can be got by below API::
+
+ struct ppe_device *ppe_dev_get(struct platform_device *pdev);
+
+PPE device operations pointer can be got by below API::
+
+ struct ppe_device_ops *ppe_ops_get(struct platform_device *pdev);
+
+Above APIs are exported and also declared in the common ppe header file in
+"include/linux/soc/qcom/ppe.h". The network driver which wants to drive PPE
+can include this header file and get the PPE device structure by exported
+"ppe_dev_get" API, and get the PPE device operations by exported
+"ppe_ops_get" API.
+
+PPE queue configuration operations pointer can be got by below API::
+
+ const struct ppe_queue_ops *ppe_queue_config_ops_get(void);
+
+This API is exported and is only used by PPE EDMA driver.
+
+
+Exported PPE Device Operations
+==============================
+
+PPE driver provides a set of PPE device operations to drive the PPE. Higher level
+network drivers such as PPE EDMA ethernet driver or a PPE DSA driver can use these
+operations to drive the PPE. The definitions of these PPE device operations can be
+found in "include/linux/soc/qcom/ppe.h". Below lists these PPE device operations.
+
+phylink_setup::
+
+ .phylink_setup(struct ppe_device *ppe_dev, struct net_device *netdev, int port);
+
+The phylink_setup operation is used by the network driver such as PPE EDMA driver to
+create PHYLINK when creating net device. This operation takes net device and the PPE
+port id as input parameters, PPE driver will create and return a PHYLINK instance
+associated with the net device and port.
+
+phylink_destroy::
+
+ .phylink_destroy(struct ppe_device *ppe_dev, int port);
+
+The phylink_destroy operation is used by the network driver such as PPE EDMA driver
+to destroy the PHYLINK.
+
+phylink_mac_config::
+
+ .phylink_mac_config(struct ppe_device *ppe_dev, int port, unsigned int mode,
+ const struct phylink_link_state *state);
+
+phylink_mac_link_up::
+
+ .phylink_mac_link_up(struct ppe_device *ppe_dev, int port, struct phy_device *phy,
+ unsigned int mode, phy_interface_t interface, int speed, int duplex,
+ bool tx_pause, bool rx_pause);
+
+phylink_mac_link_down::
+
+ .phylink_mac_link_down(struct ppe_device *ppe_dev, int port, unsigned int mode,
+ phy_interface_t interface);
+
+phylink_mac_select_pcs::
+
+ .phylink_mac_select_pcs(struct ppe_device *ppe_dev, int port,
+ phy_interface_t interface);
+
+Above PHYLINK MAC operations are used by the network driver which creates the PHYLINK and
+provides the PHYLINK MAC ops such as PPE DSA driver. In the network driver PHYLINK MAC ops,
+it can use above PPE PHYLINK MAC operations to drive the PPE MAC for PHYLINK.
+
+get_stats64::
+
+ .get_stats64(struct ppe_device *ppe_dev, int port, struct rtnl_link_stats64 *s);
+
+This operation is used by PPE network driver to get the PPE MAC statistics, for example
+used in network driver net device ops.
+
+get_strings::
+
+ .get_strings(struct ppe_device *ppe_dev, int port, u32 stringset, u8 *data);
+
+get_sset_count::
+
+ .get_sset_count(struct ppe_device *ppe_dev, int port, int sset);
+
+get_ethtool_stats::
+
+ .get_ethtool_stats(struct ppe_device *ppe_dev, int port, u64 *data);
+
+Above operations are used by PPE network driver to show PPE MAC statistics, for example
+used in network driver ethtool ops.
+
+set_mac_address::
+
+ .set_mac_address(struct ppe_device *ppe_dev, int port, u8 *macaddr);
+
+This operation is used by PPE network driver to set the PPE MAC address, for example
+used in network driver net device ops.
+
+set_mac_eee::
+
+ .set_mac_eee(struct ppe_device *ppe_dev, int port, struct ethtool_eee *eee);
+
+get_mac_eee::
+
+ .get_mac_eee(struct ppe_device *ppe_dev, int port, struct ethtool_eee *eee);
+
+Above operations are used by PPE network driver to set and get the PPE MAC eee, for example
+used in network driver ethtool ops.
+
+set_maxframe::
+
+ .set_maxframe(struct ppe_device *ppe_dev, int port, int maxframe_size);
+
+This operation is used by PPE network driver to set the PPE port maximum frame size, for
+example used in network net device ops.
--
2.42.0