From nobody Thu Oct 2 21:41:27 2025 Received: from fllvem-ot03.ext.ti.com (fllvem-ot03.ext.ti.com [198.47.19.245]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 7D84E320380; Thu, 11 Sep 2025 11:37:05 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=198.47.19.245 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757590628; cv=none; b=M39nvJp88MVyTZ1sndqv4ZZ084iDfPz/MLuvbVTllchm/XnSg4E9sldFctWbZ1ESY4ob8HBwNPSTalzocgeudoMMI+5gN9+vMCq7sevognrDCLRFma/djpi0WlicSmrmLwV62DSr89AhZujG6qq2ynQ3Ui5RWPRsUjCuoatMgIs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757590628; c=relaxed/simple; bh=3/IXwQYdzrb+8+Wl8ttL6K2OCageb+uA5sMyf5P3l0U=; h=From:To:CC:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=jp31rAAUHRkNfsve2+irSt+vPPd2z/wDye8F6GGMFqOkOoMHZ7SAt/nKM2y+PmrBldU4NKg3PaeryeKnaMfyD93TbDY+5clU5mVG/wc0CW3Ph4fsnjlHBr6W72yK8iB6YzQeW1VFuviLdCmPchpF6Jkj6G+CKnnTus/Wc+H7agg= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=ti.com; spf=pass smtp.mailfrom=ti.com; dkim=pass (1024-bit key) header.d=ti.com header.i=@ti.com header.b=ped4xet8; arc=none smtp.client-ip=198.47.19.245 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=ti.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=ti.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=ti.com header.i=@ti.com header.b="ped4xet8" Received: from lelvem-sh02.itg.ti.com ([10.180.78.226]) by fllvem-ot03.ext.ti.com (8.15.2/8.15.2) with ESMTP id 58BBaJqJ282478; Thu, 11 Sep 2025 06:36:19 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ti.com; s=ti-com-17Q1; t=1757590579; bh=oFCiZfEq7zIHjgLX3tsUwQj/pkDFixFCQPlJyAkDwDQ=; h=From:To:CC:Subject:Date:In-Reply-To:References; b=ped4xet8FJRNV2jYqgJzx9ZFhpf9i/K81xUgQrLIJOGw7ea0RnyIOl6D2o+C/gYH4 p+Bpxl5Bp8auJcC8guGuwDYGk/hHVeq+vu2BbHrdiaJa9qNxfIQllCbLYNgBC2FWWv DFkQPwHNdXJI0qe1oJTNLol/50IgoG2UPVK9FYMA= Received: from DLEE105.ent.ti.com (dlee105.ent.ti.com [157.170.170.35]) by lelvem-sh02.itg.ti.com (8.18.1/8.18.1) with ESMTPS id 58BBaJ7R1027159 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA256 bits=128 verify=FAIL); Thu, 11 Sep 2025 06:36:19 -0500 Received: from DLEE215.ent.ti.com (157.170.170.118) by DLEE105.ent.ti.com (157.170.170.35) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256_P256) id 15.1.2507.55; Thu, 11 Sep 2025 06:36:18 -0500 Received: from lelvem-mr06.itg.ti.com (10.180.75.8) by DLEE215.ent.ti.com (157.170.170.118) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.2562.20 via Frontend Transport; Thu, 11 Sep 2025 06:36:18 -0500 Received: from lelv0854.itg.ti.com (lelv0854.itg.ti.com [10.181.64.140]) by lelvem-mr06.itg.ti.com (8.18.1/8.18.1) with ESMTP id 58BBaIJL1766152; Thu, 11 Sep 2025 06:36:18 -0500 Received: from localhost (danish-tpc.dhcp.ti.com [172.24.231.152]) by lelv0854.itg.ti.com (8.14.7/8.14.7) with ESMTP id 58BBaHiF007143; Thu, 11 Sep 2025 06:36:18 -0500 From: MD Danish Anwar To: "David S. Miller" , Eric Dumazet , Jakub Kicinski , Paolo Abeni , Simon Horman , Jonathan Corbet , Nishanth Menon , Vignesh Raghavendra , Tero Kristo , Rob Herring , Krzysztof Kozlowski , Conor Dooley , Andrew Lunn , MD Danish Anwar , Mengyuan Lou , Lei Wei , Xin Guo , Michael Ellerman , Fan Gong , Lorenzo Bianconi , Parthiban Veerasooran , Lukas Bulwahn , Geert Uytterhoeven CC: , , , , Subject: [PATCH net-next v4 1/7] net: rpmsg-eth: Add Documentation for RPMSG-ETH Driver Date: Thu, 11 Sep 2025 17:06:06 +0530 Message-ID: <20250911113612.2598643-2-danishanwar@ti.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20250911113612.2598643-1-danishanwar@ti.com> References: <20250911113612.2598643-1-danishanwar@ti.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-C2ProcessedOrg: 333ef613-75bf-4e12-a4b1-8e3623f5dcea Content-Type: text/plain; charset="utf-8" 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 --- .../device_drivers/ethernet/index.rst | 1 + .../device_drivers/ethernet/rpmsg_eth.rst | 424 ++++++++++++++++++ 2 files changed, 425 insertions(+) create mode 100644 Documentation/networking/device_drivers/ethernet/rpmsg_= eth.rst diff --git a/Documentation/networking/device_drivers/ethernet/index.rst b/D= ocumentation/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..7a9d94291de4 --- /dev/null +++ b/Documentation/networking/device_drivers/ethernet/rpmsg_eth.rst @@ -0,0 +1,424 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +RPMSG Based Virtual Ethernet Driver +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Overview +=3D=3D=3D=3D=3D=3D=3D=3D + +The RPMSG Based Virtual Ethernet Driver provides a virtual Ethernet interf= ace for +communication between a host processor and a remote processor using the RP= MSG +framework. This driver enables Ethernet-like packet transmission and recep= tion +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 d= ata +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 driv= er. +The firmware must adhere to the shared memory layout, RPMSG communication +protocol, and data exchange requirements described in this documentation. + +Naming Convention +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Throughout this documentation and in the driver implementation, the follow= ing naming +convention is used to describe the direction of communication: + +- **Firmware**: The firmware / RTOS binary running on the remote core. Thi= s takes the primary role. +- **Driver**: The Linux driver running on the host core. This takes the se= condary role. + +This convention is important for understanding the data flow and the respo= nsibilities +of each side in the communication channel. + +Key Features +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +- 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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 t= he +firmware. This value is a unique constant ``0xABCDABCD`` that is written to +specific locations (such as the head and tail structures) in the shared me= mory +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 nu= mber + value, which helps detect mismatches in memory layout or protocol versio= n. +- **Error Detection:** If the driver detects an incorrect magic number dur= ing + initialization or runtime, it can abort the handshake and report an erro= r, + 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 hea= d and + tail structures in the shared memory region. +- During the handshake, the Linux driver reads these fields and compares t= hem 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 t= o the +appropriate locations in shared memory before the Linux driver attempts to +initialize the interface. + +Shared Memory Layout +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The RPMSG Based Virtual Ethernet Driver uses a shared memory region to exc= hange +data between driver and firmware. The shared memory is divided into transm= it +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 ` 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 t= he + 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 p= acket + 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 accessibl= e. + +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 packe= t. + - **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 sh= ared + memory. +- The `head` and `tail` indices are used to determine the number of packets + available for processing: + + .. code-block:: c + + num_pkts =3D head - tail; + num_pkts =3D num_pkts >=3D 0 ? num_pkts : (num_pkts + max_buffers= ); + +- The producer writes packets to the buffer and increments the `head` inde= x. +- The consumer reads packets from the buffer and increments the `tail` ind= ex. + +RPMSG Communication +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The driver uses RPMSG channels to exchange control messages with the firmw= are. +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 configurat= ion. + - `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 suc= h 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 r= eady + 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 packe= ts, + errors, and dropped packets. + - **Error Notifications**: Notifications about errors like buffer overf= lows + or invalid packets. + - **Configuration Updates**: Notifications about changes in configurati= on, + such as updated MTU or VLAN settings. + +How-To Guide for Vendors +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +This section provides a guide for vendors to develop firmware for the remo= te +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_off= set`, + 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 sh= ared + 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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The driver relies on the device tree for configuration. The shared memory +region need to be specified in the remote processor device's "memory-regio= n". + +Example Device Tree Node +------------------------ +Here is an example of how the device tree node might look: + +.. code-block:: dts + + { + compatible =3D "shared-dma-pool"; + reg =3D ; + }; + + { + memory-region =3D <&>; + }; + +In this example, ```` is the remote processor device node, a= nd +```` is the shared memory region node. The remote processor +device references the shared memory region node using the ``memory-region`` +property. + +Vendors can create their own ```` and add it to their remo= te +processor device node i.e. ```` + +Driver Configuration +-------------------- + +Vendors need to configure the driver as well by adding a new entry of type +:c:type:`rpmsg_device_id` in the array ``rpmsg_eth_id_table``. + +The :c:type:`rpmsg_device_id` structure contains two members: + +* :c:member:`name` - a string that identifies the RPMsg device +* :c:member:`driver_data` - a pointer to a :c:type:`rpmsg_eth_data` struct= ure + +Overview of rpmsg_eth_data +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``rpmsg_eth_data`` structure is a vendor-specific configuration struct= ure +that provides customization options for the RPMsg Ethernet driver. + +.. code-block:: c + + /** + * struct rpmsg_eth_data - RPMSG ETH device data + * @shm_region_index: Shared memory region index + */ + struct rpmsg_eth_data { + u8 shm_region_index; + }; + +Currently, the structure contains a single field, but it is designed to be +extensible for future enhancements. + +The shm_region_index Field +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``shm_region_index`` field is an 8-bit unsigned integer within the +``rpmsg_eth_data`` structure that specifies which memory-region phandle to= use +from the device tree for the RPMsg Ethernet shared memory. + +This field is used in the ``rpmsg_eth_get_shm_info`` function to retrieve = the +correct shared memory region from the device tree using the +``of_parse_phandle`` function: + +.. code-block:: c + + rmem_np =3D of_parse_phandle(np, "memory-region", common->data.shm_reg= ion_index); + +The ``shm_region_index`` indicates which memory region to use when multiple +memory regions are defined in the remote processor device tree node. + +Example +~~~~~~~ + +The following example shows how to create a custom RPMsg device ID: + +.. code-block:: c + + static const struct rpmsg_eth_data my_rpmsg_eth_data =3D { + .shm_region_index =3D 2, + }; + + static struct rpmsg_device_id my_rpmsg_eth_id_table[] =3D { + { .name =3D "my.shm-eth", .driver_data =3D (kernel_ulong_t)&my_rpm= sg_eth_data }, + {}, + }; + +Limitations +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +- 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 "ho= st" + core as secondary and firmware running on the "remote" core as primary. = It + does not support Linux-to-Linux communication where Linux driver would r= un on + both ends. + +References +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +- :doc:`RPMSG Framework documentation ` +- :doc:`Network device documentation ` + +Authors +=3D=3D=3D=3D=3D=3D=3D + +- MD Danish Anwar --=20 2.34.1