From: Lei Wei <quic_leiwei@xxxxxxxxxxx>
Add description and high-level diagram for PPE, driver overview and
module enable/debug information.
Signed-off-by: Lei Wei <quic_leiwei@xxxxxxxxxxx>
Signed-off-by: Luo Jie <quic_luoj@xxxxxxxxxxx>
---
.../networking/device_drivers/ethernet/index.rst | 1 +
.../device_drivers/ethernet/qualcomm/ppe/ppe.rst | 197 +++++++++++++++++++++
2 files changed, 198 insertions(+)
diff --git a/Documentation/networking/device_drivers/ethernet/index.rst b/Documentation/networking/device_drivers/ethernet/index.rst
index 6fc1961492b7..978d87edaeb5 100644
--- a/Documentation/networking/device_drivers/ethernet/index.rst
+++ b/Documentation/networking/device_drivers/ethernet/index.rst
@@ -49,6 +49,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..955fc31d740c
--- /dev/null
+++ b/Documentation/networking/device_drivers/ethernet/qualcomm/ppe/ppe.rst
@@ -0,0 +1,197 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============================================
+PPE Ethernet Driver for Qualcomm IPQ SoC Family
+===============================================
+
+Copyright (c) 2025 Qualcomm Innovation Center, Inc. All rights reserved.
+
+Author: Lei Wei <quic_leiwei@xxxxxxxxxxx>
+
+
+Contents
+========
+
+- `PPE Overview`_
+- `PPE Driver Overview`_
+- `PPE Driver Supported SoCs`_
+- `Enabling the Driver`_
+- `Debugging`_
+
+
+PPE Overview
+============
+
+IPQ (Qualcomm Internet Processor) SoC (System-on-Chip) series is Qualcomm's series of
+networking SoC for Wi-Fi access points. The PPE (Packet Process Engine) is the Ethernet
+packet process engine in the IPQ SoC.
+
+Below is a simplified hardware diagram of IPQ9574 SoC which includes the PPE engine and
+other blocks which are in the SoC but outside the PPE engine. These blocks work together
+to enable the Ethernet for the IPQ SoC::
+
+ +------+ +------+ +------+ +------+ +------+ +------+ start +-------+
+ |netdev| |netdev| |netdev| |netdev| |netdev| |netdev|<------|PHYLINK|
+ +------+ +------+ +------+ +------+ +------+ +------+ stop +-+-+-+-+
+ | | | ^
+ +-------+ +-------------------------+--------+----------------------+ | | |
+ | GCC | | | EDMA | | | | |
+ +---+---+ | PPE +---+----+ | | | |
+ | clk | | | | | |
+ +------>| +-----------------------+------+-----+---------------+ | | | |
+ | | Switch Core |Port0 | |Port7(EIP FIFO)| | | | |
+ | | +---+--+ +------+--------+ | | | |
+ | | | | | | | | |
+ +-------+ | | +------+---------------+----+ | | | | |
+ |CMN PLL| | | +---+ +---+ +----+ | +--------+ | | | | | |
+ +---+---+ | | |BM | |QM | |SCH | | | L2/L3 | ....... | | | | | |
+ | | | | +---+ +---+ +----+ | +--------+ | | | | | |
+ | | | | +------+--------------------+ | | | | |
+ | | | | | | | | | |
+ | v | | +-----+-+-----+-+-----+-+-+---+--+-----+-+-----+ | | | | |
+ | +------+ | | |Port1| |Port2| |Port3| |Port4| |Port5| |Port6| | | | | |
+ | |NSSCC | | | +-----+ +-----+ +-----+ +-----+ +-----+ +-----+ | | mac| | |
+ | +-+-+--+ | | |MAC0 | |MAC1 | |MAC2 | |MAC3 | |MAC4 | |MAC5 | | |<---+ | |
+ | ^ | |clk | | +-----+-+-----+-+-----+-+-----+--+-----+-+-----+ | | ops | |
+ | | | +---->| +----|------|-------|-------|---------|--------|-----+ | | |
+ | | | +---------------------------------------------------------+ | |
+ | | | | | | | | | | |
+ | | | MII clk | QSGMII USXGMII USXGMII | |
+ | | +------------->| | | | | | | |
+ | | +-------------------------+ +---------+ +---------+ | |
+ | |125/312.5M clk| (PCS0) | | (PCS1) | | (PCS2) | pcs ops | |
+ | +--------------+ UNIPHY0 | | UNIPHY1 | | UNIPHY2 |<--------+ |
+ +--------------->| | | | | | |
+ | 31.25M ref clk +-------------------------+ +---------+ +---------+ |
+ | | | | | | | |
+ | +-----------------------------------------------------+ |
+ |25/50M ref clk| +-------------------------+ +------+ +------+ | link |
+ +------------->| | QUAD PHY | | PHY4 | | PHY5 | |---------+
+ | +-------------------------+ +------+ +------+ | change
+ | |
+ | MDIO bus |
+ +-----------------------------------------------------+
+
+The CMN (Common) PLL, NSSCC (Networking Sub System Clock Controller) and GCC (Global
+Clock Controller) blocks are in the SoC and act as clock providers.
+
+The UNIPHY block is in the SoC and provides the PCS (Physical Coding Sublayer) and
+XPCS (10-Gigabit Physical Coding Sublayer) functions to support different interface
+modes between the PPE MAC and the external PHY.
+
+This documentation focuses on the descriptions of PPE engine and the PPE driver.
+
+The Ethernet functionality in the PPE (Packet Process Engine) is comprised of three
+components: the switch core, port wrapper and Ethernet DMA.
+
+The Switch core in the IPQ9574 PPE has maximum of 6 front panel ports and two FIFO
+interfaces. One of the two FIFO interfaces is used for Ethernet port to host CPU
+communication using Ethernet DMA. The other is used communicating to the EIP engine
+which is used for IPsec offload. On the IPQ9574, the PPE includes 6 GMAC/XGMACs that
+can be connected with external Ethernet PHY. Switch core also includes BM (Buffer
+Management), QM (Queue Management) and SCH (Scheduler) modules for supporting the
+packet processing.
+
+The port wrapper provides connections from the 6 GMAC/XGMACS to UNIPHY (PCS) supporting
+various modes such as SGMII/QSGMII/PSGMII/USXGMII/10G-BASER. There are 3 UNIPHY (PCS)
+instances supported on the IPQ9574.
+
+Ethernet DMA is used to transmit and receive packets between the Ethernet subsystem
+and ARM host CPU.
+
+The following lists the main blocks in the PPE engine which will be driven by this
+PPE driver:
+
+- BM
+ BM is the hardware buffer manager for the PPE switch ports.
+- QM
+ Queue Manager for managing the egress hardware queues of the PPE switch ports.
+- SCH
+ The scheduler which manages the hardware traffic scheduling for the PPE switch ports.
+- L2
+ The L2 block performs the packet bridging in the switch core. The bridge domain is
+ represented by the VSI (Virtual Switch Instance) domain in PPE. FDB learning can be
+ enabled based on the VSI domain and bridge forwarding occurs within the VSI domain.
+- MAC
+ The PPE in the IPQ9574 supports up to six MACs (MAC0 to MAC5) which are corresponding
+ to six switch ports (port1 to port6). The MAC block is connected with external PHY
+ through the UNIPHY PCS block. Each MAC block includes the GMAC and XGMAC blocks and
+ the switch port can select to use GMAC or XMAC through a MUX selection according to
+ the external PHY's capability.
+- EDMA (Ethernet DMA)
+ The Ethernet DMA is used to transmit and receive Ethernet packets between the PPE
+ ports and the ARM cores.
+
+The received packet on a PPE MAC port can be forwarded to another PPE MAC port. It can
+be also forwarded to internal switch port0 so that the packet can be delivered to the
+ARM cores using the Ethernet DMA (EDMA) engine. The Ethernet DMA driver will deliver the
+packet to the corresponding 'netdevice' interface.
+
+The software instantiations of the PPE MAC (netdevice), PCS and external PHYs interact
+with the Linux PHYLINK framework to manage the connectivity between the PPE ports and
+the connected PHYs, and the port link states. This is also illustrated in above diagram.
+
+
+PPE Driver Overview
+===================
+PPE driver is Ethernet driver for the Qualcomm IPQ SoC. It is a single platform driver
+which includes the PPE part and Ethernet DMA part. The PPE part initializes and drives the
+various blocks in PPE switch core such as BM/QM/L2 blocks and the PPE MACs. The EDMA part
+drives the Ethernet DMA for packet transfer between PPE ports and ARM cores, and enables
+the netdevice driver for the PPE ports.
+
+The PPE driver files in drivers/net/ethernet/qualcomm/ppe/ are listed as below:
+
+- Makefile
+- ppe.c
+- ppe.h
+- ppe_config.c
+- ppe_config.h
+- ppe_debugfs.c
+- ppe_debugfs.h
+- ppe_regs.h
+
+The ppe.c file contains the main PPE platform driver and undertakes the initialization of
+PPE switch core blocks such as QM, BM and L2. The configuration APIs for these hardware
+blocks are provided in the ppe_config.c file.
+
+The ppe.h defines the PPE device data structure which will be used by PPE driver functions.
+
+The ppe_debugfs.c enables the PPE statistics counters such as PPE port Rx and Tx counters,
+CPU code counters and queue counters.
+
+
+PPE Driver Supported SoCs
+=========================
+
+The PPE driver supports the following IPQ SoC:
+
+- IPQ9574
+
+
+Enabling the 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
+
+The PPE driver functionally depends on the CMN PLL and NSSCC clock controller drivers.
+Please make sure the dependent modules are installed before installing the PPE driver
+module.
+
+
+Debugging
+=========
+
+The PPE hardware counters are available in the debugfs and can be checked by the command
+``cat /sys/kernel/debug/ppe/packet_counters``.
--
2.34.1
