Message-ID: <20250902090746.3221225-4-danishanwar@ti.com>
Date: Tue, 2 Sep 2025 14:37:41 +0530
From: MD Danish Anwar <danishanwar@...com>
To: Andrew Lunn <andrew+netdev@...n.ch>,
        "David S. Miller"
	<davem@...emloft.net>,
        Eric Dumazet <edumazet@...gle.com>, Jakub Kicinski
	<kuba@...nel.org>,
        Paolo Abeni <pabeni@...hat.com>, Rob Herring
	<robh@...nel.org>,
        Krzysztof Kozlowski <krzk+dt@...nel.org>,
        Conor Dooley
	<conor+dt@...nel.org>,
        Bjorn Andersson <andersson@...nel.org>,
        Mathieu
 Poirier <mathieu.poirier@...aro.org>,
        Simon Horman <horms@...nel.org>, Jonathan Corbet <corbet@....net>,
        Nishanth Menon <nm@...com>, Vignesh
 Raghavendra <vigneshr@...com>,
        Mengyuan Lou <mengyuanlou@...-swift.com>,
        MD
 Danish Anwar <danishanwar@...com>, Xin Guo <guoxin09@...wei.com>,
        Lei Wei
	<quic_leiwei@...cinc.com>, Lee Trager <lee@...ger.us>,
        Michael Ellerman
	<mpe@...erman.id.au>, Fan Gong <gongfan1@...wei.com>,
        Lorenzo Bianconi
	<lorenzo@...nel.org>,
        Geert Uytterhoeven <geert+renesas@...der.be>,
        Lukas
 Bulwahn <lukas.bulwahn@...hat.com>,
        Parthiban Veerasooran
	<Parthiban.Veerasooran@...rochip.com>,
        Suman Anna <s-anna@...com>
CC: Tero Kristo <kristo@...nel.org>, <netdev@...r.kernel.org>,
        <devicetree@...r.kernel.org>, <linux-kernel@...r.kernel.org>,
        <linux-remoteproc@...r.kernel.org>, <linux-doc@...r.kernel.org>,
        <linux-arm-kernel@...ts.infradead.org>, <srk@...com>,
        Roger Quadros
	<rogerq@...nel.org>
Subject: [PATCH net-next v2 3/8] net: rpmsg-eth: Add Documentation for RPMSG-ETH Driver

Add documentation for the RPMSG Based Virtual Ethernet Driver (rpmsg-eth).
The documentation describes the driver's architecture, shared memory
layout, RPMSG communication protocol, and requirements for vendor firmware
to interoperate with the driver. It details the use of a magic number for
shared memory validation, outlines the information exchanged between the
host and remote processor, and provides a how-to guide for vendors to
implement compatible firmware.

Signed-off-by: MD Danish Anwar <danishanwar@...com>
---
 .../device_drivers/ethernet/index.rst         |   1 +
 .../device_drivers/ethernet/rpmsg_eth.rst     | 368 ++++++++++++++++++
 2 files changed, 369 insertions(+)
 create mode 100644 Documentation/networking/device_drivers/ethernet/rpmsg_eth.rst

diff --git a/Documentation/networking/device_drivers/ethernet/index.rst b/Documentation/networking/device_drivers/ethernet/index.rst
index 0b0a3eef6aae..20513a595af1 100644
--- a/Documentation/networking/device_drivers/ethernet/index.rst
+++ b/Documentation/networking/device_drivers/ethernet/index.rst
@@ -51,6 +51,7 @@ Contents:
    netronome/nfp
    pensando/ionic
    qualcomm/ppe/ppe
+   rpmsg_eth
    smsc/smc9
    stmicro/stmmac
    ti/cpsw
diff --git a/Documentation/networking/device_drivers/ethernet/rpmsg_eth.rst b/Documentation/networking/device_drivers/ethernet/rpmsg_eth.rst
new file mode 100644
index 000000000000..f39363645df3
--- /dev/null
+++ b/Documentation/networking/device_drivers/ethernet/rpmsg_eth.rst
@@ -0,0 +1,368 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===================================
+RPMSG Based Virtual Ethernet Driver
+===================================
+
+Overview
+========
+
+The RPMSG Based Virtual Ethernet Driver provides a virtual Ethernet interface for
+communication between a host processor and a remote processor using the RPMSG
+framework. This driver enables Ethernet-like packet transmission and reception
+over shared memory, facilitating inter-core communication in systems with
+heterogeneous processors.
+
+The driver is designed to work with the RPMSG framework, which is part of the
+Linux Remote Processor (remoteproc) subsystem. It uses shared memory for data
+exchange and supports features like multicast address management, dynamic MAC
+address assignment, and efficient packet processing using NAPI.
+
+This driver is generic and can be used by any vendor. Vendors can develop their
+own firmware for the remote processor to make it compatible with this driver.
+The firmware must adhere to the shared memory layout, RPMSG communication
+protocol, and data exchange requirements described in this documentation.
+
+Naming Convention
+=================
+
+Throughout this documentation and in the driver implementation, the following naming
+convention is used to describe the direction of communication:
+
+- **Firmware**: The firmware / RTOS binary running on the remote core. This takes the primary role.
+- **Driver**: The Linux driver running on the host core. This takes the secondary role.
+
+This convention is important for understanding the data flow and the responsibilities
+of each side in the communication channel.
+
+Key Features
+============
+
+- Virtual Ethernet interface using RPMSG.
+- Shared memory-based packet transmission and reception.
+- Support for multicast address management.
+- Dynamic MAC address assignment.
+- NAPI (New API) support for efficient packet processing.
+- State machine for managing interface states.
+- Workqueue-based asynchronous operations.
+- Support for notifications and responses from the firmware.
+
+Magic Number
+============
+
+A **magic number** is used in the shared memory layout to validate that the
+memory region is correctly initialized and accessible by both driver and the
+firmware. This value is a unique constant ``0xABCDABCD`` that is written to
+specific locations (such as the head and tail structures) in the shared memory
+by the firmware and checked by the driver during the handshake process.
+
+Purpose of the Magic Number
+---------------------------
+
+- **Validation:** Ensures that the shared memory region has been properly set up
+  and is not corrupted or uninitialized.
+- **Synchronization:** Both driver and firmware must agree on the magic number
+  value, which helps detect mismatches in memory layout or protocol version.
+- **Error Detection:** If the driver detects an incorrect magic number during
+  initialization or runtime, it can abort the handshake and report an error,
+  preventing undefined behavior.
+
+Implementation Details
+----------------------
+
+- The magic number is defined as a macro in the driver source (e.g.,
+  ``#define RPMSG_ETH_SHM_MAGIC_NUM 0xABCDABCD``).
+- The firmware must write this value to the ``magic_num`` field of the head and
+  tail structures in the shared memory region.
+- During the handshake, the Linux driver reads these fields and compares them to
+  the expected value. If any mismatch is detected, the driver will log an error
+  and refuse to proceed.
+
+Example Usage in Shared Memory
+------------------------------
+
+.. code-block:: text
+
+      Shared Memory Layout:
+      ---------------------------
+      |   MAGIC_NUM (0xABCDABCD) |   <-- rpmsg_eth_shm_head
+      |          HEAD            |
+      ---------------------------
+      |   MAGIC_NUM (0xABCDABCD) |   <-- rpmsg_eth_shm_tail
+      |          TAIL            |
+      ---------------------------
+
+The magic number must be present in both the head and tail structures for the
+handshake to succeed.
+
+Firmware developers must ensure that the correct magic number is written to the
+appropriate locations in shared memory before the Linux driver attempts to
+initialize the interface.
+
+Shared Memory Layout
+====================
+
+The RPMSG Based Virtual Ethernet Driver uses a shared memory region to exchange
+data between driver and firmware. The shared memory is divided into transmit
+and receive regions, each with its own `head` and `tail` indices to track the
+buffer state. The base address of this shared memory is configured in the
+device tree. See :ref:`Configuration <rpmsg_config>` for details.
+
+Shared Memory Parameters
+------------------------
+
+The following parameters are exchanged between the driver and the firmware to
+configure the shared memory layout:
+
+1. **num_pkt_bufs**:
+
+   - The total number of packet buffers available in the shared memory.
+   - This determines the maximum number of packets that can be stored in the
+     shared memory at any given time.
+
+2. **buff_slot_size**:
+
+   - The size of each buffer slot in the shared memory.
+   - This includes space for the packet length, metadata, and the actual packet
+     data.
+
+3. **tx_offset**:
+
+   - The offset from the `base_addr` where the transmit buffers begin.
+   - This is used by driver to write packets for transmission.
+
+4. **rx_offset**:
+
+   - The offset from the `base_addr` where the receive buffers begin.
+   - This is used by driver to read packets received from the firmware.
+
+Shared Memory Structure
+-----------------------
+
+The shared memory layout is as follows:
+
+.. code-block:: text
+
+      Shared Memory Layout:
+      ---------------------------
+      |        MAGIC_NUM        |   rpmsg_eth_shm_head
+      |        HEAD_IDX         |
+      ---------------------------
+      |        MAGIC_NUM        |
+      |        PKT_1_LEN        |
+      |          PKT_1          |
+      ---------------------------
+      |           ...           |
+      ---------------------------
+      |        MAGIC_NUM        |
+      |        TAIL_IDX         |   rpmsg_eth_shm_tail
+      ---------------------------
+
+1. **MAGIC_NUM**:
+
+   - A unique identifier used to validate the shared memory region.
+   - Ensures that the memory region is correctly initialized and accessible.
+
+2. **HEAD Index**:
+
+   - Tracks the start of the buffer for packet transmission or reception.
+   - Updated by the producer (Driver or firmware) after writing a packet.
+
+3. **TAIL Index**:
+
+   - Tracks the end of the buffer for packet transmission or reception.
+   - Updated by the consumer (Driver or firmware) after reading a packet.
+
+4. **Packet Buffers**:
+
+   - Each packet buffer contains:
+
+      - **Packet Length**: A 4-byte field indicating the size of the packet.
+      - **Packet Data**: The actual Ethernet frame data.
+
+5. **Buffer Size**:
+
+   - Each buffer has a fixed size defined by `RPMSG_ETH_BUFFER_SIZE`, which
+     includes space for the packet length and data.
+
+Buffer Management
+-----------------
+
+- The driver and firmware use a circular buffer mechanism to manage the shared
+  memory.
+- The `head` and `tail` indices are used to determine the number of packets
+  available for processing:
+
+   .. code-block:: c
+
+         num_pkts = head - tail;
+         num_pkts = num_pkts >= 0 ? num_pkts : (num_pkts + max_buffers);
+
+- The producer writes packets to the buffer and increments the `head` index.
+- The consumer reads packets from the buffer and increments the `tail` index.
+
+RPMSG Communication
+===================
+
+The driver uses RPMSG channels to exchange control messages with the firmware.
+These messages are used to manage the state of the Ethernet interface,
+configure settings, notify events, and exchange runtime information.
+
+Information Exchanged Between RPMSG Channels
+--------------------------------------------
+
+1. **Requests from Driver to Firmware**:
+
+   - `RPMSG_ETH_REQ_SHM_INFO`: Request shared memory information, such as
+     ``num_pkt_bufs``, ``buff_slot_size``, ``tx_offset``, and
+     ``rx_offset``.
+   - `RPMSG_ETH_REQ_SET_MAC_ADDR`: Set the MAC address of the Ethernet
+     interface.
+   - `RPMSG_ETH_REQ_ADD_MC_ADDR`: Add a multicast address to the firmware's
+     filter list.
+   - `RPMSG_ETH_REQ_DEL_MC_ADDR`: Remove a multicast address from firmware's
+     filter list.
+
+2. **Responses from Firmware to Driver**:
+
+   - `RPMSG_ETH_RESP_SET_MAC_ADDR`: Acknowledge the MAC address configuration.
+   - `RPMSG_ETH_RESP_ADD_MC_ADDR`: Acknowledge the addition of a multicast
+     address.
+   - `RPMSG_ETH_RESP_DEL_MC_ADDR`: Acknowledge the removal of a multicast
+     address.
+   - `RPMSG_ETH_RESP_SHM_INFO`: Respond with shared memory information such as
+     ``num_pkt_bufs``, ``buff_slot_size``, ``tx_offset``, and
+     ``rx_offset``.
+
+3. **Notifications from Firmware to Driver**:
+
+   - `RPMSG_ETH_NOTIFY_PORT_UP`: Notify that the Ethernet port is up and ready
+     for communication.
+   - `RPMSG_ETH_NOTIFY_PORT_DOWN`: Notify that the Ethernet port is down.
+   - `RPMSG_ETH_NOTIFY_REMOTE_READY`: Notify that the firmware is ready for
+     communication.
+
+4. **Runtime Information Exchanged**:
+
+   - **Link State**: Notifications about link state changes (e.g., link up or
+     link down).
+   - **Statistics**: Runtime statistics such as transmitted/received packets,
+     errors, and dropped packets.
+   - **Error Notifications**: Notifications about errors like buffer overflows
+     or invalid packets.
+   - **Configuration Updates**: Notifications about changes in configuration,
+     such as updated MTU or VLAN settings.
+
+How-To Guide for Vendors
+========================
+
+This section provides a guide for vendors to develop firmware for the remote
+processor that is compatible with the RPMSG Based Virtual Ethernet Driver.
+
+1. **Implement Shared Memory Layout**:
+
+   - Allocate a shared memory region for packet transmission and reception.
+   - Initialize the `MAGIC_NUM`, `num_pkt_bufs`, `buff_slot_size`, `tx_offset`,
+     and `rx_offset`.
+
+2. **Magic Number Requirements**
+
+   - The firmware must write a unique magic number ``0xABCDABCD`` to the
+     `magic_num` field of both the head and tail structures in the shared
+     memory region.
+   - This magic number is used by the Linux driver to validate that the shared
+     memory region is correctly initialized and accessible.
+   - If the driver detects an incorrect magic number during the handshake, it
+     will abort initialization and report an error.
+   - Vendors must ensure the magic number matches the value expected by the
+     Linux driver, see the `RPMSG_ETH_SHM_MAGIC_NUM` macro in the driver
+     source.
+
+3. **Handle RPMSG Requests**:
+
+   - Implement handlers for the following RPMSG requests:
+
+      - `RPMSG_ETH_REQ_SHM_INFO`
+      - `RPMSG_ETH_REQ_SET_MAC_ADDR`
+      - `RPMSG_ETH_REQ_ADD_MC_ADDR`
+      - `RPMSG_ETH_REQ_DEL_MC_ADDR`
+
+4. **Send RPMSG Notifications**:
+
+   - Notify the Driver about the state of the Ethernet interface using the
+     notifications described above.
+
+5. **Send Runtime Information**:
+
+   - Implement mechanisms to send runtime information such as link state
+     changes, statistics, and error notifications.
+
+6. **Implement Packet Processing**:
+
+   - Process packets in the shared memory transmit and receive buffers.
+
+7. **Test the Firmware**:
+
+   - Use the RPMSG Based Virtual Ethernet Driver on the host to test packet
+     transmission and reception.
+
+.. _rpmsg_config:
+
+Configuration
+=============
+
+The driver relies on the device tree for configuration. The RPMsg Ethernet device
+is specified as a child node of the remote processor device, and it references a
+shared memory region.
+
+Example Device Tree Node
+------------------------
+The RPMsg Ethernet device is represented by the ``rpmsg-eth`` node, which is a
+child of the remote processor device. The shared memory region is specified
+using the ``memory-region`` property, which references a ``shared-dma-pool`` node.
+
+Here is an example of how the device tree node might look:
+
+.. code-block:: dts
+
+    <memory_region> {
+        compatible = "shared-dma-pool";
+        reg = <base_address size>;
+    };
+
+    <rproc_device> {
+        rpmsg-eth {
+            memory-region = <&<memory_region>>;
+        };
+    };
+
+In this example, ``<rproc_device>`` is the remote processor device node, and
+``<memory_region>`` is the shared memory region node. The ``rpmsg-eth`` node is
+a child of the remote processor device node, and it references the shared memory
+region node using the ``memory-region`` property.
+
+Vendors can create their own RPMsg Ethernet device node by replacing
+``<rproc_device>`` with their remote processor device node, and
+``<memory_region>`` with their shared memory region node.
+
+Limitations
+===========
+
+- The driver assumes a specific shared memory layout and may not work with other
+  configurations.
+- The driver currently supports only one transmit and one receive queue.
+- The current implementation only supports Linux driver running on the "host"
+  core as secondary and firmware running on the "remote" core as primary. It
+  does not support Linux-to-Linux communication where Linux driver would run on
+  both ends.
+
+References
+==========
+
+- :doc:`RPMSG Framework documentation </staging/rpmsg>`
+- :doc:`Network device documentation </networking/index>`
+
+Authors
+=======
+
+- MD Danish Anwar <danishanwar@...com>
-- 
2.34.1

Powered by blists - more mailing lists