xref: /linux/Documentation/networking/device_drivers/ethernet/qualcomm/ppe/ppe.rst (revision 8804d970fab45726b3c7cd7f240b31122aa94219) 
1.. SPDX-License-Identifier: GPL-2.0
2
3===============================================
4PPE Ethernet Driver for Qualcomm IPQ SoC Family
5===============================================
6
7Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries.
8
9Author: Lei Wei <quic_leiwei@quicinc.com>
10
11
12Contents
13========
14
15- `PPE Overview`_
16- `PPE Driver Overview`_
17- `PPE Driver Supported SoCs`_
18- `Enabling the Driver`_
19- `Debugging`_
20
21
22PPE Overview
23============
24
25IPQ (Qualcomm Internet Processor) SoC (System-on-Chip) series is Qualcomm's series of
26networking SoC for Wi-Fi access points. The PPE (Packet Process Engine) is the Ethernet
27packet process engine in the IPQ SoC.
28
29Below is a simplified hardware diagram of IPQ9574 SoC which includes the PPE engine and
30other blocks which are in the SoC but outside the PPE engine. These blocks work together
31to enable the Ethernet for the IPQ SoC::
32
33               +------+ +------+ +------+ +------+ +------+  +------+ start +-------+
34               |netdev| |netdev| |netdev| |netdev| |netdev|  |netdev|<------|PHYLINK|
35               +------+ +------+ +------+ +------+ +------+  +------+ stop  +-+-+-+-+
36                                             |                                | | ^
37 +-------+     +-------------------------+--------+----------------------+    | | |
38 | GCC   |     |                         |  EDMA  |                      |    | | |
39 +---+---+     |  PPE                    +---+----+                      |    | | |
40     | clk     |                             |                           |    | | |
41     +-------->| +-----------------------+------+-----+---------------+  |    | | |
42               | |   Switch Core         |Port0 |     |Port7(EIP FIFO)|  |    | | |
43               | |                       +---+--+     +------+--------+  |    | | |
44               | |                           |               |        |  |    | | |
45 +-------+     | |                    +------+---------------+----+   |  |    | | |
46 |CMN PLL|     | | +---+ +---+ +----+ | +--------+                |   |  |    | | |
47 +---+---+     | | |BM | |QM | |SCH | | | L2/L3  |  .......       |   |  |    | | |
48 |   |         | | +---+ +---+ +----+ | +--------+                |   |  |    | | |
49 |   |         | |                    +------+--------------------+   |  |    | | |
50 |   |         | |                           |                        |  |    | | |
51 |   v         | | +-----+-+-----+-+-----+-+-+---+--+-----+-+-----+   |  |    | | |
52 | +------+    | | |Port1| |Port2| |Port3| |Port4|  |Port5| |Port6|   |  |    | | |
53 | |NSSCC |    | | +-----+ +-----+ +-----+ +-----+  +-----+ +-----+   |  | mac| | |
54 | +-+-+--+    | | |MAC0 | |MAC1 | |MAC2 | |MAC3 |  |MAC4 | |MAC5 |   |  |<---+ | |
55 | ^ | |clk    | | +-----+-+-----+-+-----+-+-----+--+-----+-+-----+   |  | ops  | |
56 | | | +------>| +----|------|-------|-------|---------|--------|-----+  |      | |
57 | | |         +---------------------------------------------------------+      | |
58 | | |                |      |       |       |         |        |               | |
59 | | |   MII clk      |      QSGMII               USXGMII   USXGMII             | |
60 | | +--------------->|      |       |       |         |        |               | |
61 | |                +-------------------------+ +---------+ +---------+         | |
62 | |125/312.5MHz clk|       (PCS0)            | | (PCS1)  | | (PCS2)  | pcs ops | |
63 | +----------------+       UNIPHY0           | | UNIPHY1 | | UNIPHY2 |<--------+ |
64 +----------------->|                         | |         | |         |           |
65 | 31.25MHz ref clk +-------------------------+ +---------+ +---------+           |
66 |                     |     |      |      |          |          |                |
67 |                +-----------------------------------------------------+         |
68 |25/50MHz ref clk| +-------------------------+    +------+   +------+  | link    |
69 +--------------->| |      QUAD PHY           |    | PHY4 |   | PHY5 |  |---------+
70                  | +-------------------------+    +------+   +------+  | change
71                  |                                                     |
72                  |                       MDIO bus                      |
73                  +-----------------------------------------------------+
74
75The CMN (Common) PLL, NSSCC (Networking Sub System Clock Controller) and GCC (Global
76Clock Controller) blocks are in the SoC and act as clock providers.
77
78The UNIPHY block is in the SoC and provides the PCS (Physical Coding Sublayer) and
79XPCS (10-Gigabit Physical Coding Sublayer) functions to support different interface
80modes between the PPE MAC and the external PHY.
81
82This documentation focuses on the descriptions of PPE engine and the PPE driver.
83
84The Ethernet functionality in the PPE (Packet Process Engine) is comprised of three
85components: the switch core, port wrapper and Ethernet DMA.
86
87The Switch core in the IPQ9574 PPE has maximum of 6 front panel ports and two FIFO
88interfaces. One of the two FIFO interfaces is used for Ethernet port to host CPU
89communication using Ethernet DMA. The other one is used to communicate to the EIP
90engine which is used for IPsec offload. On the IPQ9574, the PPE includes 6 GMAC/XGMACs
91that can be connected with external Ethernet PHY. Switch core also includes BM (Buffer
92Management), QM (Queue Management) and SCH (Scheduler) modules for supporting the
93packet processing.
94
95The port wrapper provides connections from the 6 GMAC/XGMACS to UNIPHY (PCS) supporting
96various modes such as SGMII/QSGMII/PSGMII/USXGMII/10G-BASER. There are 3 UNIPHY (PCS)
97instances supported on the IPQ9574.
98
99Ethernet DMA is used to transmit and receive packets between the Ethernet subsystem
100and ARM host CPU.
101
102The following lists the main blocks in the PPE engine which will be driven by this
103PPE driver:
104
105- BM
106    BM is the hardware buffer manager for the PPE switch ports.
107- QM
108    Queue Manager for managing the egress hardware queues of the PPE switch ports.
109- SCH
110    The scheduler which manages the hardware traffic scheduling for the PPE switch ports.
111- L2
112    The L2 block performs the packet bridging in the switch core. The bridge domain is
113    represented by the VSI (Virtual Switch Instance) domain in PPE. FDB learning can be
114    enabled based on the VSI domain and bridge forwarding occurs within the VSI domain.
115- MAC
116    The PPE in the IPQ9574 supports up to six MACs (MAC0 to MAC5) which are corresponding
117    to six switch ports (port1 to port6). The MAC block is connected with external PHY
118    through the UNIPHY PCS block. Each MAC block includes the GMAC and XGMAC blocks and
119    the switch port can select to use GMAC or XMAC through a MUX selection according to
120    the external PHY's capability.
121- EDMA (Ethernet DMA)
122    The Ethernet DMA is used to transmit and receive Ethernet packets between the PPE
123    ports and the ARM cores.
124
125The received packet on a PPE MAC port can be forwarded to another PPE MAC port. It can
126be also forwarded to internal switch port0 so that the packet can be delivered to the
127ARM cores using the Ethernet DMA (EDMA) engine. The Ethernet DMA driver will deliver the
128packet to the corresponding 'netdevice' interface.
129
130The software instantiations of the PPE MAC (netdevice), PCS and external PHYs interact
131with the Linux PHYLINK framework to manage the connectivity between the PPE ports and
132the connected PHYs, and the port link states. This is also illustrated in above diagram.
133
134
135PPE Driver Overview
136===================
137PPE driver is Ethernet driver for the Qualcomm IPQ SoC. It is a single platform driver
138which includes the PPE part and Ethernet DMA part. The PPE part initializes and drives the
139various blocks in PPE switch core such as BM/QM/L2 blocks and the PPE MACs. The EDMA part
140drives the Ethernet DMA for packet transfer between PPE ports and ARM cores, and enables
141the netdevice driver for the PPE ports.
142
143The PPE driver files in drivers/net/ethernet/qualcomm/ppe/ are listed as below:
144
145- Makefile
146- ppe.c
147- ppe.h
148- ppe_config.c
149- ppe_config.h
150- ppe_debugfs.c
151- ppe_debugfs.h
152- ppe_regs.h
153
154The ppe.c file contains the main PPE platform driver and undertakes the initialization of
155PPE switch core blocks such as QM, BM and L2. The configuration APIs for these hardware
156blocks are provided in the ppe_config.c file.
157
158The ppe.h defines the PPE device data structure which will be used by PPE driver functions.
159
160The ppe_debugfs.c enables the PPE statistics counters such as PPE port Rx and Tx counters,
161CPU code counters and queue counters.
162
163
164PPE Driver Supported SoCs
165=========================
166
167The PPE driver supports the following IPQ SoC:
168
169- IPQ9574
170
171
172Enabling the Driver
173===================
174
175The driver is located in the menu structure at::
176
177  -> Device Drivers
178    -> Network device support (NETDEVICES [=y])
179      -> Ethernet driver support
180        -> Qualcomm devices
181          -> Qualcomm Technologies, Inc. PPE Ethernet support
182
183If the driver is built as a module, the module will be called qcom-ppe.
184
185The PPE driver functionally depends on the CMN PLL and NSSCC clock controller drivers.
186Please make sure the dependent modules are installed before installing the PPE driver
187module.
188
189
190Debugging
191=========
192
193The PPE hardware counters can be accessed using debugfs interface from the
194``/sys/kernel/debug/ppe/`` directory.
195