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 | 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 ` 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 + + { + compatible = "shared-dma-pool"; + reg = ; + }; + + { + rpmsg-eth { + memory-region = <&>; + }; + }; + +In this example, ```` is the remote processor device node, and +```` 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 +```` with their remote processor device node, and +```` 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 ` +- :doc:`Network device documentation ` + +Authors +======= + +- MD Danish Anwar -- 2.34.1