Linux内核模块npreal2：串口服务器虚拟串口驱动编译装载与故障排查

简介：npreal2 是 Moxa RealTTY 在 Linux 环境下的驱动程序源码包，面向需要在 4.x/5.x 内核上部署 RealTTY 串口设备的嵌入式开发与系统运维人员，以 C 语言实现，解决设备在 Linux 下的驱动适配问题。包内针对内核版本拆分了 kernel_4.xx 与 kernel_5.xx 两个分支，并汇入了来自 AUR 的驱动补丁，使用时可根据当前内核版本选择合适的补丁与配置。资源共 35 个文件、约 132KB，以 C 源文件（10 个）和头文件（6 个）为核心，另有 Makefile、patch、模块辅助文件及安装/卸载脚本，便于在目标主机上完成驱动的构建、加载与移除；说明文档和版本记录也一并包含，可帮助理解驱动结构与补丁作用。当前已有 311 人学习下载，对于需要为 Moxa 设备定制内核驱动或排查串口通信问题的开发者，这份代码能提供可参考的移植思路与现成补丁基础，节省从零编写驱动的成本。

1. npreal2：给串口服务器装一块本地虚拟串口的底层驱动

在一台工控机上跑老旧的 Modbus 采集程序，程序只认本地/dev/ttyM0，可硬件串口已经占满，现场设备全挂在一台 NPort 串口服务器上。你当然可以用 TCP 直接对接，但老程序的调用代码动不了，socket 改造成本太高。这个场景就是 Moxa RealTTY Linux 驱动的用武之地：它在 Linux 内核里挂上一个虚拟 tty 设备，把对/dev/ttyMx的读写改写成与远端 NPort 的 TCP 交互，应用层的 open/read/write 一行不改。npreal2 就是这套驱动的核心模块。它解决的是「程序只认本地串口、物理口又不够」的迁移问题，适合工控现场运维、嵌入式开发者和做产线改造的人，装好之后还涉及端口分配模式、ips 参数对齐、守护进程状态这些细节，配置错了设备节点起不来是常事。

2. 编译与装载：先搞清楚驱动链路再动手

2.1 RealTTY 的逻辑链路：一个内核模块加一个守护进程

npreal2 并不是单一文件，它包含两部分：内核模块npreal2x.ko和用户态守护进程npreal2d。常见误解是只把.ko拉进去insmod完事，然后发现设备节点根本没有。实际工作链路是：内核模块负责注册 tty 驱动、创建/dev/ttyM*节点，但真正去跟 NPort 建 TCP 连接、维持心跳的是守护进程npreal2d。模块通过 ioctl 把应用层读写转成内部消息，守护进程把这些消息搬到 TCP 通道上。

那安装前先确认什么？第一是内核版本，这直接决定你是否能编译出可装载的模块。第二是目标机上的工具链，工控机上没有 gcc 是常态。我的习惯是先摸一遍现场环境，别急着把源码传上去。

# 查看内核版本、架构、是否缺构建工具 uname -r && uname -m which gcc || echo "no gcc" which make || echo "no make"

这里输出的uname -r是你找内核源码的唯一依据。RealTTY 的模块源码对 2.6.x 到 4.x、5.x 内核都留了兼容路径，但编译时如果你本机没有对应版本的 kernel headers，直接make会报一堆「找不到 generated/autoconf.h」之类的错误。我一般在开发机上把模块编出.ko，再拷到目标机装载，比在工控机上现场编要稳。

2.2 编译的过程与三个必改参数

拿到驱动源码后，目录结构通常包含npreal2.c、Makefile、示例配置npreal2init和说明文档。编译本身不复杂，麻烦的是模块参数。先把源码里的Makefile打开看一眼，确认 SRC 路径指向你实际解压目录。下面是一个典型的内核模块编译循环：

# 假设源码在 /opt/npreal2，且开发机已有对应内核 headers cd /opt/npreal2 make clean make # 编译出 npreal2x.ko 之后先看参数列表 modinfo npreal2x.ko

modinfo会列出ips、devname、maxport、minport等参数，其中ips最容易填错，它是一串用逗号分隔的 IP:port 配置，顺序和数量必须和minport、maxport匹配。举个例子，如果你的目标 NPort 地址是192.168.1.10:4001，想映射 4 个虚拟串口，参数应该写成ips=192.168.1.10:4001,192.168.1.10:4002,192.168.1.10:4003,192.168.1.10:4004，而maxport=4表示本组设备上限。这里常见的翻车是只写一个 IP 不写端口段，守护进程起来后所有虚拟串口全指向同一个 TCP 连接。

装载时我建议用insmod而不是modprobe，因为模块名带x，modprobe有时会去/lib/modules/$(uname -r)里找，找不到就报错，insmod直接指路径更省心：

# 装载模块并指定端口参数，注意 minport/maxport 是从 0 开始计数的段 insmod /opt/npreal2/npreal2x.ko ips=192.168.1.10:4001,192.168.1.10:4002,192.168.1.10:4003,192.168.1.10:4004 maxport=4 # 检查内核日志 dmesg | tail -20

minport=0是默认起始端口号。这里有个边界要留意：如果系统里之前已经装了旧的 RealTTY 驱动，minport不能随便改，它决定 ttyM 节点从哪个序号开始，比如minport=0生成ttyM0到ttyM3，minport=4则生成ttyM4到ttyM7。现场若既有旧驱动又有新驱动，必须先卸载旧模块，否则节点号冲突，应用打开的串口指向的是别台的设备。

2.3 守护进程的启动顺序与一次验证

装完模块还差最后一步：启动npreal2d。这一步新手最容易漏。模块装进去后虽然生成了节点，但守护进程没跑，应用层打开 ttyM 会一直阻塞在读上。更隐蔽的问题是，守护进程参数里的 IP 和模块参数里的 IP 如果不一致，节点在，但连接永远建立不起来。

# 启动守护进程，通常要求指定配置文件或手动指定 IP /usr/local/npreal2/npreal2d -i 192.168.1.10:4001 -p 4 & sleep 2 # 验证连接是否建立 ps -ef | grep npreal2d cat /proc/net/tcp | grep 4001

sleep 2是因为守护进程建立连接需要时间，grep 4001是为了确认 TCP 层已经连上 NPort。如果这一行查不到对应记录，先看 IP 通不通、端口对不对，再看防火墙是不是把 4001 过滤了。我之前处理过一个案例：模块参数、守护进程参数全部正确，最终发现目标机上的 firewalld 开着，过滤了 NPort 的 TCP 端口，ping 能通但连接建立不了。

3. 端口分配机制：devname三种模式与映射规则

3.1 真实端口、固定端口还是自动端口

RealTTY 在 Linux 下的端口分配不是随手定的，devname参数有三套逻辑：真实端口模式（devname=realport）、固定端口模式（devname=fixport）和自动端口模式（devname=autoport）。这是配置里最容易头脑发热的地方，因为文档里三个模式都叫「RealPort」，但行为完全不一样。

realport模式会读取 NPort 设备内部的端口状态，向守护进程报告真实连接情况，适合对状态敏感的应用，但部署最复杂，要求设备固件支持 RealPort 协议，且不能自己随便指定端口号。fixport则是完全本地指定，每台设备的端口号固定映射，比如ips=192.168.1.10:4001永远对应ttyM0，不管 NPort 那边怎么配置。autoport模式不看 NPort 的端口号，只按 IP 自动分配节点，适合多台 NPort 设备统一灌配置的场景。

3.2 固定端口模式的映射规则和参数表

现场改造成本最低的是fixport，因为你能直接预测哪个 IP 对应哪个 tty 节点，写应用白名单也方便。固定端口模式下，ttyM的序号由minport和 IP 在ips参数里的位置决定：第 1 个 IP 从minport开始，第 2 个 IP 接在后面。下面这张表是我自己整理的映射关系，比读源码快得多：

注意fixport模式下maxport也不是摆设，它表示这一组参数里最多容纳多少个端口。如果ips里写了 8 个地址但maxport=4，后面的 4 个会被直接忽略，而且守护进程日志里不一定有报错，只有你打开 ttyM4 发现连不上才能察觉，这是设计上比较坑的地方。

真实端口模式和自动端口模式则对 IP 的排列也有讲究。autoport下节点号不随ips里的顺序走，而是按 NPort 返回的设备信息自动排列。如果你现场有多台不同型号的 NPort，自动排列的结果可能跟预期不一致，排查起来更费时间。所以我一般会建议：能用fixport就别碰autoport，少一个黑匣子。

3.3 节点权限和设备名称的连带问题

devname决定完之后还有两个连带问题：节点权限和已有设备命名冲突。RealTTY 生成的设备节点权限默认是 root:root，普通用户程序打不开。你可以手动chmod 666，但它会在重启后失效，所以更靠谱的写法是写一个 udev 规则固定权限：

# 新建 /etc/udev/rules.d/99-npreal2.rules # 遇到 ttyM 设备就改属组为 dialout 并设 0660 权限 KERNEL=="ttyM*", MODE="0660", GROUP="dialout"

这块写完后要udevadm control --reload再udevadm trigger，否则规则不会立刻生效。曾经有个现场，应用怎么都打不开 ttyM0，排查到最后就是权限问题——驱动日志一切正常，TCP 连接也建立着，但应用本身是普通用户起的，open 直接返回 EPERM。另外要注意，如果你系统里本来有别的 ttyM 设备，RealTTY 的模块加载会尝试抢占同名节点，此时要把其他驱动的别名禁用掉，避免开机时两个驱动抢同一个ttyM主次设备号。

4. 避坑：装载到 NPort 映射的三个高频排查场景

4.1 模块装载成功但连不上 NPort

现象：insmod没有报错，ttyM0节点也生成了，但cat /dev/ttyM0没有任何数据回显，strace看应用阻塞在open或者read。

原因：90% 是守护进程没启动，或者守护进程参数与模块参数不一致。还有一部分是 TCP 413 端口不通，比如目标 NPort 的 RealPort 端口不是 4001，而是 4002，这类错误 dmesg 不报，只有抓包才能看到 SYN 重传。

解决：确认ps -ef | grep npreal2d有进程；确认模块参数里的ips端口是 NPort 的 RealPort 端口而不是数据中心端口；再不行就在目标机上tcpdump -i eth0 host <NPort_IP>，看有没有 TCP 握手包。最常见的坑是把 NPort 的网页配置端口当成了 RealPort 端口，两者差了 4000 多，看起来填的没毛病，实际上完全不是一回事。

4.2 节点存在但应用打开就报参数错误

现象：应用调用open("/dev/ttyM0", O_RDWR)返回成功，随后ioctl(TCGETS)报错，或者termios设置无效。

原因：内核模块分配的 tty 驱动和标准串口驱动的 ioctl 行为不同，部分驱动没实现TIOCMGET这类调制解调器控制查询，而老程序初始化串口时会先做一轮完整的termios查询加设置。驱动没实现就直接返回错误，应用程序就认为端口初始化失败。

解决：先用stty -F /dev/ttyM0 -a试着读一遍参数，确认驱动对 termios 的基本支持。如果stty本身都报错，考虑换devname=realport模式，它在 ioctl 兼容层面做得更完整。如果旧程序还调用了tiocmget系列操作，只能在应用侧把这段初始化逻辑去掉或者改成忽略错误，这是最省事的路径。

4.3 重启后节点消失，映射关系跟配置文件对不上

现象：系统重启后，/dev/ttyM*全部不见，但/var/log/messages里没有任何报错；或者节点在，但ttyM0对应的是另一台 NPort 设备。

原因：RealTTY 驱动的默认安装脚本没有把模块加载命令放进开机启动流程，或者放进了但加载顺序在网卡就绪之前。模块一加载就要跟 NPort 建立连接，网卡还没拿到 IP，守护进程只能重试，部分版本不会自动重试就退出了。

解决：把模块加载和守护进程启动写成独立的 systemd service，并且设置After=network-online.target。同时建议在 service 里加个循环重试逻辑，等网络真正就绪后再启动守护进程。参考配置如下：

# /etc/systemd/system/npreal2d.service [Unit] Description=Start npreal2d after network ready After=network-online.target Wants=network-online.target [Service] Type=forking ExecStart=/usr/local/npreal2/npreal2d Restart=on-failure RestartSec=5 [Install] WantedBy=multi-user.target

写完后systemctl enable npreal2d，注意Type=forking是守护进程自身的默认行为，如果你的 npreal2d 前端不 fork，需要改成Type=simple，否则 systemd 会误判启动失败。这块是玄学重灾区，我见过好几回 systemd 显示 active，但进程一直重启，就是 Type 写错了。

4.4 系统有多个网卡时 NPort 连到了错误网口

现象：目标机有两个网口，一个连内网 NPort，一个连外网。驱动能起来，但访问 NPort 的流量总是走外网口出去，导致连接失败或超时。

原因：守护进程默认按路由表选源地址，ips参数里如果写的是 NPort 的 IP，而系统路由把该网段指向了外网口，TCP 连接就发错地方。

解决：在守护进程参数里显式指定源地址，或者加一条到 NPort 网段的静态路由ip route add 192.168.1.0/24 dev eth1。如果驱动版本允许，给守护进程加-s参数指定源 IP 最直接。这个问题现场容易忽略，因为ping NPort_IP是通的，ping不走 TCP 连接端口，也不绑定源地址，看起来一切正常，但就是连不上。

4.5 守护进程活着但连接反复断开重连

现象：ps看守护进程一直在，dmesg里有 TCP 连接重置记录，应用周期性报「设备无响应」。

原因：通常是 NPort 设备侧的 TCP keepalive 时间短于应用的空闲时间，而 RealTTY 驱动方没有启用 keepalive，导致设备侧因为超时主动断开。另外网线或交换机端口的协商问题也会带来类似现象，表现为 5 分钟到 30 分钟周期性的断开。

解决：给 NPort 设备调整 RealPort 超时配置，把连接超时拉长；同时在驱动侧用setsockopt层的 keepalive 参数，不过这个驱动不一定暴露配置入口。更省事的做法是让应用定期发一个空查询，保持链路活跃。待调试时可以用ss -tnp | grep 4001观察断连时间间隔，判断是设备侧超时还是网络问题。这类间歇性故障最难查，建议先做 24 小时连续日志观察，别凭感觉改参数。

5. 给迁移项目留一个后悔药：切换映射前先做链路自检

每次改现场映射，我都有一个强制顺序：先停应用，再停守护进程，然后卸载模块，最后才改配置。这个顺序看起来繁琐，但能避开绝大多数「配置改坏了想回滚」的尴尬。

# 1. 停应用（按实际进程名） systemctl stop my_app # 2. 停守护进程并确认退出 killall npreal2d sleep 1 ps -ef | grep npreal2d || echo "npreal2d stopped" # 3. 卸载内核模块，确认节点消失 rmmod npreal2x ls /dev/ttyM* 2>/dev/null || echo "ttyM nodes removed" # 4. 更新配置文件，重新装载 insmod /opt/npreal2/npreal2x.ko ips=192.168.1.10:4001,192.168.1.10:4002 maxport=2 /usr/local/npreal2/npreal2d &

关键在第 3 步——很多人改配置时只停守护进程不卸模块，然后重新insmod时报错说模块已存在，只能rmmod再装。但更隐蔽的坑是旧模块还持有连接状态，重新装载后ttyM0指向的还是缓存里的旧设备信息，应用读写全指向旧目标。主动把节点清掉再装载，就等于把整个链路重置一遍，避免黑匣子里的脏状态。

卸完之后顺手做一轮快速验证，别急着把应用恢复。我的习惯是写一个 10 行的 C 小程序，打开 ttyM0 发一个AT\r\n或者任意启动帧，看有没有返回。如果设备不支持回显，就用tcpdump在网口上抓包，确认应用打开 ttyM0 的瞬间，TCP 通道上有对应的数据流出。这比看驱动日志靠谱，因为日志只告诉你连接建立了，不告诉你数据有没有真的发出去。

还有一点是注意备份：旧的ips参数、守护进程命令行、之前能用的配置文件，改之前全部拷贝到一个目录，别只改文件不留副本。后来有一次我在现场误把fixport改成了autoport，整个节点号全乱，一堆应用的串口号白名单作废，幸好留了旧配置，两分钟就回滚了。从那以后我每次动 RealTTY 配置都强制走一遍「停应用、停守护、卸模块、改动、验证」五步流程，也建议你把这套顺序写成自己的检查单，希望帮到你。

本文还有配套的精品资源，点击获取