From: MD Danish Anwar <danishanwar@ti.com>
To: "David S. Miller" <davem@davemloft.net>,
Eric Dumazet <edumazet@google.com>,
Jakub Kicinski <kuba@kernel.org>, Paolo Abeni <pabeni@redhat.com>,
Simon Horman <horms@kernel.org>, Jonathan Corbet <corbet@lwn.net>,
Andrew Lunn <andrew+netdev@lunn.ch>,
Mengyuan Lou <mengyuanlou@net-swift.com>,
MD Danish Anwar <danishanwar@ti.com>,
Michael Ellerman <mpe@ellerman.id.au>,
Madhavan Srinivasan <maddy@linux.ibm.com>,
Fan Gong <gongfan1@huawei.com>, Lee Trager <lee@trager.us>,
Lorenzo Bianconi <lorenzo@kernel.org>,
Geert Uytterhoeven <geert+renesas@glider.be>,
Lukas Bulwahn <lukas.bulwahn@redhat.com>,
Parthiban Veerasooran <Parthiban.Veerasooran@microchip.com>
Cc: <netdev@vger.kernel.org>, <linux-doc@vger.kernel.org>,
<linux-kernel@vger.kernel.org>
Subject: [PATCH net-next 1/5] net: rpmsg-eth: Add Documentation for RPMSG-ETH Driver
Date: Wed, 23 Jul 2025 13:33:18 +0530 [thread overview]
Message-ID: <20250723080322.3047826-2-danishanwar@ti.com> (raw)
In-Reply-To: <20250723080322.3047826-1-danishanwar@ti.com>
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@ti.com>
---
.../device_drivers/ethernet/index.rst | 1 +
.../device_drivers/ethernet/rpmsg_eth.rst | 339 ++++++++++++++++++
2 files changed, 340 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 40ac552641a3..941f60585ee4 100644
--- a/Documentation/networking/device_drivers/ethernet/index.rst
+++ b/Documentation/networking/device_drivers/ethernet/index.rst
@@ -61,6 +61,7 @@ Contents:
wangxun/txgbevf
wangxun/ngbe
wangxun/ngbevf
+ rpmsg_eth
.. only:: subproject and html
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..70c13deb31ea
--- /dev/null
+++ b/Documentation/networking/device_drivers/ethernet/rpmsg_eth.rst
@@ -0,0 +1,339 @@
+.. 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.
+
+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 remote processor.
+
+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 the host and the
+remote processor. This value is a unique constant (for example,
+``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 Linux
+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 the host and remote processor 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 the host and the remote processor. The shared memory is divided
+into transmit and receive regions, each with its own `head` and `tail` pointers
+to track the buffer state.
+
+Shared Memory Parameters
+------------------------
+
+The following parameters are exchanged between the host 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. **base_addr**:
+
+ - The base address of the shared memory region.
+ - This is the starting point for accessing the shared memory.
+
+4. **tx_offset**:
+
+ - The offset from the `base_addr` where the transmit buffers begin.
+ - This is used by the host to write packets for transmission.
+
+5. **rx_offset**:
+
+ - The offset from the `base_addr` where the receive buffers begin.
+ - This is used by the host to read packets received from the remote
+ processor.
+
+Shared Memory Structure
+-----------------------
+
+The shared memory layout is as follows:
+
+.. code-block:: text
+
+ Shared Memory Layout:
+ ---------------------------
+ | MAGIC_NUM | rpmsg_eth_shm_head
+ | HEAD |
+ ---------------------------
+ | MAGIC_NUM |
+ | PKT_1_LEN |
+ | PKT_1 |
+ ---------------------------
+ | ... |
+ ---------------------------
+ | MAGIC_NUM |
+ | TAIL | 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 Pointer**:
+
+ - Tracks the start of the buffer for packet transmission or reception.
+ - Updated by the producer (host or remote processor) after writing a packet.
+
+3. **TAIL Pointer**:
+
+ - Tracks the end of the buffer for packet transmission or reception.
+ - Updated by the consumer (host or remote processor) 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 host and remote processor use a circular buffer mechanism to manage the shared memory.
+- The `head` and `tail` pointers 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` pointer.
+- The consumer reads packets from the buffer and increments the `tail` pointer.
+
+RPMSG Communication
+===================
+
+The driver uses RPMSG channels to exchange control messages between the host and
+the remote processor. 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 Host to Remote Processor**:
+
+ - `RPMSG_ETH_REQ_SHM_INFO`: Request shared memory information, such as
+ ``num_pkt_bufs``, ``buff_slot_size``, ``base_addr``, ``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 remote
+ processor's filter list.
+ - `RPMSG_ETH_REQ_DEL_MC_ADDR`: Remove a multicast address from the remote
+ processor's filter list.
+
+2. **Responses from Remote Processor to Host**:
+
+ - `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``, ``base_addr``, ``tx_offset``, and
+ ``rx_offset``.
+
+3. **Notifications from Remote Processor to Host**:
+
+ - `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_PORT_READY`: Notify that the Ethernet port is ready for
+ configuration.
+ - `RPMSG_ETH_NOTIFY_REMOTE_READY`: Notify that the remote processor 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`, `base_addr`,
+ `tx_offset`, and `rx_offset`.
+
+2. **Magic Number Requirements**
+
+ - The firmware must write a unique magic number (for example, ``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 host 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.
+
+Configuration
+=============
+
+The driver relies on the device tree for configuration. The shared memory region
+is specified using the `virtual-eth-shm` node in the device tree.
+
+Example Device Tree Node
+------------------------
+
+.. code-block:: dts
+
+ virtual-eth-shm {
+ compatible = "rpmsg,virtual-eth-shm";
+ reg = <0x80000000 0x10000>; /* Base address and size of shared memory */
+ };
+
+Limitations
+===========
+
+- The driver assumes a specific shared memory layout and may not work with other
+ configurations.
+- Multicast address filtering is limited to the capabilities of the underlying
+ RPMSG framework.
+- The driver currently supports only one transmit and one receive queue.
+
+References
+==========
+
+- RPMSG Framework Documentation: https://www.kernel.org/doc/html/latest/rpmsg.html
+- Linux Networking Documentation: https://www.kernel.org/doc/html/latest/networking/index.html
+
+Authors
+=======
+
+- MD Danish Anwar <danishanwar@ti.com>
--
2.34.1
next prev parent reply other threads:[~2025-07-23 8:04 UTC|newest]
Thread overview: 24+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-07-23 8:03 [PATCH net-next 0/5] Add RPMSG Ethernet Driver MD Danish Anwar
2025-07-23 8:03 ` MD Danish Anwar [this message]
2025-07-23 13:49 ` [PATCH net-next 1/5] net: rpmsg-eth: Add Documentation for RPMSG-ETH Driver Jakub Kicinski
2025-07-24 6:54 ` MD Danish Anwar
2025-08-04 12:10 ` [cocci] " Julia Lawall
2025-07-23 16:24 ` Andrew Lunn
2025-07-24 8:24 ` MD Danish Anwar
2025-07-24 16:37 ` Andrew Lunn
2025-07-25 7:04 ` Anwar, Md Danish
2025-08-28 7:08 ` MD Danish Anwar
2025-08-29 0:39 ` Bagas Sanjaya
2025-07-23 8:03 ` [PATCH net-next 2/5] net: rpmsg-eth: Add basic rpmsg skeleton MD Danish Anwar
2025-07-24 19:18 ` Krzysztof Kozlowski
2025-07-28 8:10 ` MD Danish Anwar
2025-07-28 12:40 ` Krzysztof Kozlowski
2025-07-29 9:46 ` MD Danish Anwar
2025-07-29 12:32 ` Krzysztof Kozlowski
2025-07-30 6:01 ` MD Danish Anwar
2025-07-30 6:13 ` Krzysztof Kozlowski
2025-07-30 15:11 ` Anwar, Md Danish
2025-08-28 7:07 ` MD Danish Anwar
2025-07-23 8:03 ` [PATCH net-next 3/5] net: rpmsg-eth: Register device as netdev MD Danish Anwar
2025-07-23 8:03 ` [PATCH net-next 4/5] net: rpmsg-eth: Add netdev ops MD Danish Anwar
2025-07-23 8:03 ` [PATCH net-next 5/5] net: rpmsg-eth: Add support for multicast filtering MD Danish Anwar
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20250723080322.3047826-2-danishanwar@ti.com \
--to=danishanwar@ti.com \
--cc=Parthiban.Veerasooran@microchip.com \
--cc=andrew+netdev@lunn.ch \
--cc=corbet@lwn.net \
--cc=davem@davemloft.net \
--cc=edumazet@google.com \
--cc=geert+renesas@glider.be \
--cc=gongfan1@huawei.com \
--cc=horms@kernel.org \
--cc=kuba@kernel.org \
--cc=lee@trager.us \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=lorenzo@kernel.org \
--cc=lukas.bulwahn@redhat.com \
--cc=maddy@linux.ibm.com \
--cc=mengyuanlou@net-swift.com \
--cc=mpe@ellerman.id.au \
--cc=netdev@vger.kernel.org \
--cc=pabeni@redhat.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®