feat(net): add RTL8111/8168 and RTL8125 Ethernet drivers

Documentation/core-api/drivers.rst

@@ -32,6 +32,10 @@ drivers/ 按 console、tty、video、storage、net、input、usb、sound 等设
      - ``e1000e``
      - Intel 82574L/82574IT、82583V PCIe 千兆网卡；共用单 eth0 服务，
        不替换已有网络 owner。设备范围和验证边界见 :doc:`e1000e`。
+   * - ``R8169``
+     - ``r8169``
+     - Realtek RTL8111/8168 千兆与 RTL8125 2.5GbE PCIe 网卡；共用单 eth0
+       服务。芯片版本、固件来源和验证范围见 :doc:`realtek`。
    * - ``MOUSE_PS2`` / ``USB_UHCI_HCD``
      - ``mouse`` / ``uhci``
      - PS/2、VMware 鼠标与 UHCI HID；键盘基础输入和分发入口内置。

Documentation/core-api/index.rst

@@ -17,5 +17,6 @@
    resource-limits
    drivers
    e1000e
+   realtek
    usb
    svga

Documentation/core-api/realtek.rst

@@ -0,0 +1,113 @@
+==========================
+Realtek PCIe 以太网驱动
+==========================
+
+设备与配置
+==========
+
+``drivers/net/r8169/`` 提供 ReliefNT 原生网卡驱动。``CONFIG_R8169`` 为
+tristate，``make defconfig`` 默认选择 ``y``。选择 ``m`` 生成
+``drivers/net/r8169/r8169.ko``，由普通 ``modprobe`` 根据 PCI 别名加载。
+
+设备表包含 ``10ec:8168`` 和 ``10ec:8125``。驱动进一步读取 TxConfig
+中的硬件版本，分别选择初始化、PHY 和固件流程。
+
+.. list-table:: 已实现的芯片版本路径
+   :header-rows: 1
+   :widths: 30 70
+
+   * - PCI ID
+     - MAC 版本
+   * - ``10ec:8168``
+     - RTL8111/8168 B、C、CP、D、DP、E、E-VL、F、G、GU、H、EP、FP。
+       按 OpenBSD 的版本掩码区分家族与 B/C 的 spin。
+   * - ``10ec:8125``
+     - RTL8125A ``0x60900000``、B ``0x64100000``、D-1 ``0x68800000``、
+       D-2 ``0x68900000``。
+
+未知 MAC 家族返回 ``-ENODEV``。现有网络服务仅提供一个外部 Ethernet
+接口，先注册的网卡拥有 ``eth0``，后来的 owner 收到 ``-EBUSY``。
+驱动复用内部历史名称 ``register_e1000`` 的服务，网络用户程序继续使用
+现有 Linux socket、ioctl、netlink 和 proc 接口。
+
+.. code-block:: sh
+
+   modinfo r8169
+   modprobe r8169
+   ip link show eth0
+   ip addr show dev eth0
+   cat /proc/net/dev
+   rmmod r8169
+
+无网线时接口仍可查询和配置，载波状态来自硬件。PHY 自动协商覆盖
+10/100/1000 Mb/s，RTL8125 另行通告 2500BASE-T 全双工。协商异步完成。
+PHY、EPHY、CSI、固件握手和复位均有界等待，失败返回具体 errno。
+
+硬件初始化中的微秒级稳定等待使用启动时间采样；短于 1 ms 的等待最多
+轮询 4096 次，且采样期间关闭本地中断以避免 CPU 迁移。时钟停滞、回退或
+达到轮询上限时改用 tick 等待；较长等待也使用 tick 等待，并额外加入一整个
+tick，以覆盖请求恰好接近下一个 tick 的情况。等待返回后恢复原中断状态，
+调用方不得持有自旋锁。短等待依赖内核启动时钟的精度；该时钟突然向前跳变
+可能缩短等待。
+
+收发和生命周期
+==============
+
+驱动优先映射 PCI BAR2，再尝试其他有效内存 BAR，支持 64 位地址。
+PCI 电源管理使用常规 capability 链请求 D0。原始 MAC 在复位前读取并保留，
+无效地址导致初始化失败。
+早期 RTL8168 的控制 BAR 可能只有 256 字节，此时可通过该设备的 I/O BAR
+访问同一寄存器组。PCI 内存映射仍要求完整页面位于有效 BAR 内。
+
+RX/TX 各使用 256 个 16 字节经典描述符和 2048 字节缓冲区。RTL8125
+显式选择经典布局。描述符保留物理 DMA 地址，CPU 通过独立映射访问数据。
+所有权交接使用 acquire/release 屏障，发送与接收有独立的短临界区。
+当前使用单队列轮询，MTU 为 1500，IP/传输层校验和由现有网络栈计算。
+
+发送帧补零到最小 Ethernet 长度，再由硬件附加 FCS。队列满返回
+``-EAGAIN``。接收检查错误、缓冲区与调用者容量，移除一个 FCS，并完整
+丢弃跨描述符的异常分片链。接收过滤器接受本站单播、广播和多播，供
+IPv4 ARP、DHCP 与 IPv6 邻居发现使用。
+
+初始化先禁用 PCI bus master 并确认控制器复位，再分配和发布 DMA 队列。
+卸载由模块 owner 关闭回调准入、排空在途调用，随后停止收发和复位。
+停止失败时保留 DMA、MMIO 和模块代码以供重试。释放内存后 PCI bus master
+保持关闭。
+
+固件和许可
+==========
+
+RTL8125 的 MAC/PHY 固件以未经修改的常量寄存器对嵌入内核或模块，启动时
+按芯片版本选择。构建消费仓库内数据。运行时无需网络下载。
+固件在完成写入与握手后才更新版本标记，并回读确认。
+
+硬件初始化改编自 OpenBSD src 提交
+``7779d12194498048b288afda664dd6271a2ec016``。
+RTL8111/8168 派生代码保留 BSD-4-Clause，RTL8125 派生代码保留 ISC，
+固件保留 Realtek 的再分发许可。项目新增的 PCI/DMA/模块连接代码使用
+Apache-2.0。完整声明见 ``NOTICE`` 和 ``LICENSES/realtek/``。
+``modules_install`` 将声明放入版本化模块目录的 ``LICENSES/``，连同
+模块加入安装所有权和校验清单，并随 ReliefOS 的内核载荷分发。
+
+This product includes software developed by Bill Paul.
+
+* `OpenBSD re.c <https://github.com/openbsd/src/blob/7779d12194498048b288afda664dd6271a2ec016/sys/dev/ic/re.c>`_
+* `OpenBSD if_rge.c <https://github.com/openbsd/src/blob/7779d12194498048b288afda664dd6271a2ec016/sys/dev/pci/if_rge.c>`_
+* `Realtek 固件数据与许可 <https://github.com/openbsd/src/blob/7779d12194498048b288afda664dd6271a2ec016/sys/dev/microcode/rge/rgemcode.h>`_
+* `Realtek 提交的 RTL8125 DPDK 寄存器与描述符定义 <https://mails.dpdk.org/archives/dev/2024-June/295259.html>`_
+
+验证范围
+========
+
+``tools/test_r8169.py`` 编译真实驱动对象并模拟 PCI/MMIO/DMA 边界，另行编译
+真实寄存器与等待实现，检查时钟边界、中断状态和不同寄存器访问方式。
+它覆盖 4 GiB 以上地址、收发回绕、长度与错误检查、补零、无载波、资源分配
+失败、owner 冲突、停止失败保留与重试。芯片模型覆盖四个 RTL8125 版本和
+RTL8168 家族路径。真实 PHY 协商、DMA 时序和实体网线收发仍需对应硬件验证。
+
+本次 QEMU 回归覆盖默认内置启动，以及无匹配 Realtek 硬件时三次
+``r8169.ko`` 加载与卸载。既有 e1000 的 IPv4、IPv6 ping 均通过。
+测试使用当前新编译内核和私有 initramfs，BusyBox 来自已有 ReliefOS 构建。
+
+本地 QEMU 只提供 RTL8139 Realtek 模型，真实 RTL8111/8168、RTL8125
+需要实体网卡或正确的 PCI 直通验证。实体网卡验证未完成。VMware 验证未完成。

LICENSES/realtek/OpenBSD-BSD-4-Clause.txt

@@ -0,0 +1,37 @@
+The RTL8168 initialization and PHY register sequences are adapted from
+OpenBSD re.c, rtl81x9reg.h and rgephy.c, at commit
+7779d12194498048b288afda664dd6271a2ec016.
+
+Copyright (c) 1997, 1998-2003
+    Bill Paul <wpaul@windriver.com>.  All rights reserved.
+Copyright (c) 1997, 1998
+    Bill Paul <wpaul@ctr.columbia.edu>.  All rights reserved.
+Copyright (c) 2003
+    Bill Paul <wpaul@windriver.com>.  All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+3. All advertising materials mentioning features or use of this software
+   must display the following acknowledgement:
+   This product includes software developed by Bill Paul.
+4. Neither the name of the author nor the names of any co-contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY Bill Paul AND CONTRIBUTORS ``AS IS'' AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL Bill Paul OR THE VOICES IN HIS HEAD
+BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+THE POSSIBILITY OF SUCH DAMAGE.

LICENSES/realtek/OpenBSD-ISC.txt

@@ -0,0 +1,14 @@
+Copyright (c) 2019, 2020, 2023-2026
+     Kevin Lo <kevlo@openbsd.org>
+
+Permission to use, copy, modify, and distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

LICENSES/realtek/Realtek-firmware.txt

@@ -0,0 +1,15 @@
+Copyright (c) 2026 Realtek Semiconductor Corporation
+
+Permission is hereby granted for the distribution of this firmware
+data in hexadecimal or equivalent format, provided this copyright
+notice is accompanying it.
+
+Copyright (c) 2011-2013, Realtek Semiconductor Corporation
+
+Permission is hereby granted for the distribution of this firmware
+data in hexadecimal or equivalent format, provided this copyright
+notice is accompanying it.
+
+Embedded, unchanged register-pair data for RTL8125 A/B/D-1/D-2.
+Source: OpenBSD src sys/dev/microcode/rge/rgemcode.h
+Revision: 7779d12194498048b288afda664dd6271a2ec016

NOTICE

@@ -32,6 +32,20 @@ Third-party components in this repository
   drivers/video/framebuffer/framebuffer.c (see the ReliefNT rules in Kbuild).
 * zlib 1.3.2 puff (third_party/zlib/contrib/puff/puff.c): zlib License. See
   third_party/zlib/LICENSE. Copyright (C) 2002-2013 Mark Adler.
+* Realtek PCIe Ethernet hardware support in drivers/net/r8169/:
+  RTL8111/8168 register/PHY sequences are adapted from OpenBSD re.c,
+  rtl81x9reg.h and rgephy.c under Bill Paul's BSD-4-Clause terms.
+  This product includes software developed by Bill Paul.
+  RTL8125 initialization is adapted from OpenBSD if_rge.c and if_rgereg.h
+  under Kevin Lo's ISC terms. The pinned OpenBSD src revision is
+  7779d12194498048b288afda664dd6271a2ec016.
+  Complete notices and conditions are in LICENSES/realtek/OpenBSD-ISC.txt
+  and LICENSES/realtek/OpenBSD-BSD-4-Clause.txt and in the derived source.
+  Embedded RTL8125 firmware register pairs are unchanged data from
+  sys/dev/microcode/rge/rgemcode.h at that revision, copyright (c) 2026
+  Realtek Semiconductor Corporation, under its accompanying firmware
+  redistribution permission. See LICENSES/realtek/Realtek-firmware.txt.
+  The firmware data and derived files retain their respective terms.
 * Linux kernel 6.12 build and configuration infrastructure (selected files in
   scripts/basic/, scripts/include/, scripts/kconfig/, scripts/Makefile.*,
   scripts/Kbuild.include, and scripts/subarch.include): sourced from the

drivers/net/Kbuild

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
 # Objects are owned by this directory; child modules own their own lists.
-obj-y := e1000/ e1000e/
+obj-y := e1000/ e1000e/ r8169/
 
 include $(srctree)/scripts/Makefile.module

drivers/net/Kconfig

@@ -2,4 +2,5 @@
 menu "Network device drivers"
 source "drivers/net/e1000/Kconfig"
 source "drivers/net/e1000e/Kconfig"
+source "drivers/net/r8169/Kconfig"
 endmenu

drivers/net/r8169/Kbuild

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: Apache-2.0
+obj-$(CONFIG_R8169) += r8169.o
+r8169-y := main.o hardware.o io.o rings.o rtl8168.o rtl8125.o firmware_8125.o module.o
+
+include $(srctree)/scripts/Makefile.module

drivers/net/r8169/Kconfig

@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: Apache-2.0
+config R8169
+	tristate "Realtek RTL8111/8168 and RTL8125 PCIe Ethernet"
+	default y
+	help
+	  Native driver for supported Realtek RTL8111/8168 Gigabit and RTL8125
+	  2.5 Gigabit PCIe Ethernet MAC revisions. Supports coherent DMA and
+	  standard copper autonegotiation, with software protocol checksums.
+	  Select M to build r8169.ko. The default configuration builds it in.