[RFC PATCH 0/8] xilinx: tsn: Add TSN Endpoint Ethernet MAC driver support

[Srinivas Neeli]

Introduce a new network driver for the AMD LogiCORE 100M/1G TSN
Subsystem IP, also known as the TSN Endpoint Ethernet MAC, which
implements IEEE 802.1 Time-Sensitive Networking (TSN) features for
deterministic and low-latency Ethernet communication in real-time and
industrial automation use cases.

IP Core Overview:
The AMD LogiCORE 100M/1G TSN Subsystem IP solution (named as TSN Endpoint
Ethernet MAC IP in the IP catalog) implements IEEE 802.1 Time Sensitive
Networking (TSN) Standards and provides a low latency Bridged Endpoint or
Endpoint only solutions. The bridged endpoint solution consists of a 3-port
switch that connects to an endpoint including Linux software drivers. For
Bridged Endpoint (Switch Endpoint), two ports connects to the network and
one port connects to an internal Endpoint. It supports the use of
GMII/RGMII interfaces connecting to a physical-side interface (PHY) chip
with full duplex 100 Mb/s and 1 Gb/s operations.

Features:
- IP Customizable to generate TSN Endpoint or Bridged Endpoint solution
- Supports interface to network software stack
- Designed to comply with the following IEEE standards
    - 802.1AS  : Precision Time Protocol (PTP) synchronization
    - 802.1Qav : Credit-Based Shaper for traffic shaping
    - 802.1Qbv : Time-Aware Shaper for scheduled traffic
    - 802.1Qbu : Frame Preemption for ultra-low latency
    - 802.1CB  : Frame Replication and Elimination for redundancy
- IP is customizable to enable various TSN feature-sets
- Supports three priority queues for scheduled, reserved (IEEE 802.1 Qav
  Credit Based Shaper) and best effort traffic classes
- Provides feature rich Ethernet Switch that caters to various network
  needs
	* 3-port Switch (2-external, 1-internal)
	* Programmable cut-through and store-forward operations
	* 4-port Switch (2-external, 2-internal) extension through
          'Endpoint Extension' and 'Endpoint Packet Switching' features
- Solution validated on ZCU102 & ZC702 AMD Evaluation boards.

Sample hardware architecture diagram for Bidge End Point like below:

             +------------------+
             |      MCDMA       |
             +---------+--------+
                    Q0---Q7
                       |
          +------------------------------------------------------------ +
          |            |	 TSN sub system(Bridge End Point)	|
          |            |                                                |
          |     +------+----+  Port 0   +-----------------------+       |
          |     |  EndPoint |<--------->|       TSN Switch      |       |
          |     |    (EP)   |           +----+-------------+----+       |
          |     +-----------+                |             |            |
          |                                  |             |            |
          |                              Port 1         Port 2          |
          |                                  |             |            |
          |                            +-----------+  +-----------+     |
          |                            |  MAC-1    |  |  MAC-2    |     |
          |                            |  (ETH1)   |  |  (ETH2)   |     |
          |                            +-----+-----+  +-----+-----+     |
	  |			             |		    |           |
          |				     |              |           |
          +-------------------------------------------------------------+
                                             |              |           
                                          RGMII           RGMII
                                             |              |
                                      +-----------+  +-----------+
                                      |  PHY1     |  |  PHY2     |
                                      | (Port 0)  |  | (Port 2)  |
                                      +-----------+  +-----------+
									  



Software Driver Overivew:

This patch series targets for Bridge Endpoint design(Two EMAC's ,
one Endpoint and Switch block) with Multi channel DMA.

The TSN driver architecture mirrors the hardware structure by dividing
functionality into multiple sub-blocks(Endpoint, EMACs, Switch, MDIO, DMA).
Each sub-block includes its own init and exit routines, called from the
core probe and remove flow, enabling flexible configurations and clean
error unwind. Please check detailed explanation of each sub-block below.

Core Driver (xilinx_tsn.c):
- Acts as the central entry point for the driver, implementing platform
  probe and remove callbacks.
- Handles device tree parsing to discover configuration parameters such as
  DMA channel counts, queue priorities, and child hardware nodes.
- Manages clock acquisition, enablement, and disablement using the
  kernel bulk clock APIs.
- Maps the top-level register space for the TSN subsystem and prepares it
  for use by sub-blocks.
- Establishes initialization sequencing, ensuring that the endpoint is
  initialized first, followed by EMACs and MDIO, and finally the switch
  block.
- Provides a central driver context (struct tsn_priv), containing locks,
  statistics counters, configuration parameters, and references to
  instantiated functional components.

EndPoint(xilinx_tsn_ep.c):
- Implements the primary host-facing net_device interface (tsn_ep), which
  acts as the main application access point to the TSN subsystem.
- Manages multi-queue TX and RX descriptor rings using the dmaengine
  framework for high-performance packet transfer.
- Handles DMA submission and completion callbacks (tsn_dma_tx_cb /
  tsn_dma_rx_cb) to ensure efficient packet flow and completion tracking.
- Includes a VLAN PCP-to-queue mapping mechanism, enabling priority-based
  traffic classification and scheduling.
- Implements standard net_device operations including open, stop,
  start_xmit, set_mac_address, and select_queue for seamless integration
  with the Linux networking stack.

EMAC & MDIO (xilinx_tsn_emac.c and xilinx_tsn_mdio.c):
- Discovers and initializes individual Ethernet MAC instances by parsing
  child "ethernet-mac" nodes from the device tree.
- Allocates and registers a dedicated net_device for each MAC port,
  enabling independent interface management.
- Maps and configures register space for each MAC instance, including MAC
  address programming through UAW0/UAW1 registers.
- Establishes PHY connectivity using of_phy_connect() and manages link
  state changes. 
- Updates MAC control registers dynamically based on PHY state transitions
  to ensure correct operational parameters.
- Optionally sets up an integrated MDIO bus if a "mdio" child node is
  present under the MAC node, enabling PHY access and management through
  the standard PHY framewor.

Switch (xilinx_tsn_switch.c):
- Handles initialization of the optional TSN switch block by mapping the
  "switch" child node from the device tree.
- Provides per-port state control (Disabled,Forwarding) via a hardware
  change-bit handshake mechanism with polling and timeout handling.
- Adds frame filter configuration support based on unicast source and
  destination MAC addresses.
- During driver initialization, all switch ports (Endpoint, MAC1, MAC2)
  are configured into the Forwarding state to enable data flow across the
  fabric.
- On driver removal, all ports are transitioned to the disabled state to
  ensure clean shutdown and traffic isolation.

xilinx_tsn_ptp_clock.c:
- Implements PTP Hardware Clock (PHC) support for the TSN subsystem's
  RTC/timer block.
- Provides ptp_clock_info operations (gettime64, settime64, adjtime,
  adjfine) for time synchronization.
- Handles RTC offset and increment register programming for clock
  adjustments.
- Implements PPS (Pulse Per Second) generation via timer interrupt
  handler, generating events at 128 pulses/second and delivering them
  to userspace.
- Registers PHC using ptp_clock_register() and exposes PHC index via
  ethtool for use by PTP daemons (ptp4l, phc2sys).
- Initialization is performed only for EMAC1 (MAC ID 1), as the PTP timer
  is shared globally across all MAC instances.
- Calculates RTC increment value based on fixed 125 MHz GTX clock
  frequency as specified in TSN IP core documentation.

xilinx_tsn_ptp_xmit.c:

- Implements dedicated PTP packet transmission and timestamping path
  using hardware PTP buffers.
- Manages 8 TX buffers and 16 RX buffers in hardware for PTP packet handling.
- Provides 32-bit aligned memory-mapped I/O helpers
  (memcpy_toio_32, memcpy_fromio_32) for efficient buffer access.
- Implements TX path (tsn_ptp_xmit) that copies PTP packets to hardware
  TX buffers and queues skbs for timestamp retrieval.
- Handles RX path using circular buffer mechanism with ptp_rx_hw_pointer
  (hardware write position) and ptp_rx_sw_pointer (software read position)
  for synchronized buffer access.
- Delivers hardware timestamps only for PTP event messages (Sync,
  Delay_Req, Pdelay_Req, Pdelay_Resp) by checking message type field.
- Uses interrupt-driven approach: RX ISR calls tsn_ptp_recv() directly,
  TX ISR schedules work queue (tsn_ptp_tx_tstamp) for timestamp delivery.
- Implements proper error handling including NULL checks for skb
  allocation, TX buffer overflow detection with netdev statistics updates,
  and cleanup paths for interrupt unregistration.

Future work:
- Plan to add hardware statistics support for EMACs.
- Plan to add support for PTP(1 step), QBV, preemption, FRER features.
- Adopting switch dev frame work for switch configurations.

Test information:
- Performed ping,iperf3 and 2 step ptp tests on the ZYNQMP platform.

NOTE:
- The changes depend on a few patches in the Xilinx DMA driver
  (xilinx_dma.c). Some of these patches are already posted, while
  others are still under review. The corresponding lore links are listed
  below, and links for the remaining patches will be added once they are
  submitted.

https://lore.kernel.org/all/DDB5J5V1IM0E.34WP32K550WIU@xxxxxxxxxxxxxxxxxxxxx/
https://lore.kernel.org/all/DDB5IRSNB09F.3HRTZZOZQ7J6@xxxxxxxxxxxxxxxxxxxxx/
https://lore.kernel.org/all/DDB5IDDEOVBT.NHJF03FYW2BN@xxxxxxxxxxxxxxxxxxxxx/


This RFC is the initial submission of the driver and aims to gather
feedback on design, structure, and subsystem integration before
further upstreamization work.

Srinivas Neeli (8):
  dt-bindings: net: Add TSN Endpoint Ethernet MAC support
  net: xilinx: tsn: Introduce TSN core driver skeleton
  net: xilinx: tsn: Add TSN endpoint and MCDMA support
  xilinx: tsn: Add Ethernet MAC (EMAC) and MDIO support to the TSN
    driver
  net: xilinx: tsn: Add TSN switch support with port state and frame
    filter control
  dt-bindings: net: Add PTP interrupt support
  net: xilinx: tsn: Add PTP hardware clock (PHC) and timer support
  net: xilinx: tsn: Add PTP packet transmission support

 .../net/xlnx,tsn-endpoint-ethernet-mac.yaml   | 362 ++++++++
 drivers/net/ethernet/xilinx/Kconfig           |   1 +
 drivers/net/ethernet/xilinx/Makefile          |   1 +
 drivers/net/ethernet/xilinx/tsn/Kconfig       |  14 +
 drivers/net/ethernet/xilinx/tsn/Makefile      |   2 +
 drivers/net/ethernet/xilinx/tsn/xilinx_tsn.h  | 430 ++++++++++
 .../net/ethernet/xilinx/tsn/xilinx_tsn_emac.c | 547 ++++++++++++
 .../net/ethernet/xilinx/tsn/xilinx_tsn_ep.c   | 211 +++++
 .../net/ethernet/xilinx/tsn/xilinx_tsn_main.c | 794 ++++++++++++++++++
 .../net/ethernet/xilinx/tsn/xilinx_tsn_mdio.c | 308 +++++++
 .../xilinx/tsn/xilinx_tsn_ptp_clock.c         | 386 +++++++++
 .../ethernet/xilinx/tsn/xilinx_tsn_ptp_xmit.c | 451 ++++++++++
 .../ethernet/xilinx/tsn/xilinx_tsn_switch.c   | 546 ++++++++++++
 13 files changed, 4053 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/net/xlnx,tsn-endpoint-ethernet-mac.yaml
 create mode 100644 drivers/net/ethernet/xilinx/tsn/Kconfig
 create mode 100644 drivers/net/ethernet/xilinx/tsn/Makefile
 create mode 100644 drivers/net/ethernet/xilinx/tsn/xilinx_tsn.h
 create mode 100644 drivers/net/ethernet/xilinx/tsn/xilinx_tsn_emac.c
 create mode 100644 drivers/net/ethernet/xilinx/tsn/xilinx_tsn_ep.c
 create mode 100644 drivers/net/ethernet/xilinx/tsn/xilinx_tsn_main.c
 create mode 100644 drivers/net/ethernet/xilinx/tsn/xilinx_tsn_mdio.c
 create mode 100644 drivers/net/ethernet/xilinx/tsn/xilinx_tsn_ptp_clock.c
 create mode 100644 drivers/net/ethernet/xilinx/tsn/xilinx_tsn_ptp_xmit.c
 create mode 100644 drivers/net/ethernet/xilinx/tsn/xilinx_tsn_switch.c

-- 
2.25.1