rog-platform 硬件抽象层解析:udev、HID 与 asus-armoury 内核驱动如何驱动 asusctl

原创2026-11-04 14:42:562,245 阅读

rog-platform 硬件抽象层解析:udev、HID 与 asus-armoury 内核驱动如何驱动 asusctl

🖥️ asusctl 是一款为华硕 ROG / TUF 游戏本打造的 Linux 系统控制工具,其核心是 Rust 编写的 rog-platform 硬件抽象层:它基于 udev 枚举设备、通过 HID(hidraw) 与 USB 原始通道 驱动键盘灯效和 Slash 副屏,并读取 asus-nb-wmi 与 asus-armoury 两个内核驱动暴露的 sysfs 属性,最终把风扇曲线、GPU 独显开关、性能模式、电池充电阈值等能力统一封装给 asusd 守护进程,再通过 D-Bus 开放给 asusctl 命令行与 ROG Control Center 图形界面使用。

asusctl 项目自带的 ROG Control Center 硬件控制界面

一、rog-platform 在整个 asusctl 中的位置

asusctl 项目由三大组件构成:守护进程 asusd、图形界面 rog-control-center、命令行客户端 asusctl。所有真正"摸硬件"的动作都被下沉到 rog-platform 这个独立 crate 中,源码位于 rog-platform/src/。

它对外暴露的模块一览:

模块 负责的功能 依赖的内核接口
platform.rs 性能模式、GPU MUX、独显禁用、面板 ODR asus-nb-wmi platform 设备
asus_armoury.rs TDP/PPT 功耗、开机音效、屏幕超频 asus-armoury firmware-attributes
cpu.rs CPU 调度器(governor)与 EPP 性能偏好 cpufreq sysfs
power.rs 电池充电阈值、AC/USB 供电状态 power_supply
backlight.rs / keyboard_led.rs 屏幕亮度、键盘背光亮度和 RGB 模式 backlight / leds 类
hid_raw.rs / usb_raw.rs Aura 键盘逐键灯效、Slash 副屏动画 hidraw 设备文件 / 原始 USB 控制传输
gpu_pci.rs 独显 PCI 检测与电源状态 PCI + sysfs

依赖声明可见 rog-platform/Cargo.toml:核心依赖是 udev(设备枚举)、rusb(原始 USB)、inotify(属性变更监听)和 zbus(D-Bus 数据类型)。

💡 设计要点:任何功能缺失时都"优雅降级"——找不到对应 sysfs 节点就返回错误并跳过,而不是让整个守护进程崩溃。

二、udev:所有设备发现的统一入口

rog-platform 里几乎每个控制器的 new() 都遵循同一个套路:创建 udev::Enumerator → 按 subsystem 过滤 → 按 sysname 精确匹配 → 拿到 sysfs 路径。

以平台设备为例,rog-platform/src/platform.rs 中:

let mut enumerator = udev::Enumerator::new()?;
enumerator.match_subsystem("platform")?;
enumerator.match_sysname("asus-nb-wmi")?;
  • backlight.rs 用同样方式找 intel_backlight(主屏)和 asus_screenpad(副屏背光),见 rog-platform/src/backlight.rs;
  • cpu.rs 枚举 cpu subsystem 的每个核心,读取 scaling_governor 和 energy_performance_preference(EPP),见 rog-platform/src/cpu.rs;
  • power.rs 枚举 power_supply,按 type 属性区分 mains / battery / usb 三个电源,并内置了一套"如何认出华硕电池"的判定策略(厂商名 → 充电阈值属性 → syspath 含 BAT),见 rog-platform/src/power.rs;
  • dmi-id 小 crate 也用 udev 读取 dmi subsystem,拿到机型、BIOS 版本等信息用于日志和兼容判断,见 dmi-id/src/lib.rs。

为什么要走 udev 而不是硬编码路径? 因为 /sys/devices/platform/asus-nb-wmi 这类路径虽稳定,但通过 udev 可以顺带获得设备属性(如 idProduct)、父子设备关系(hidraw → usb_device),并在热插拔场景下重新发现设备。

服务也是靠 udev 规则拉起的

安装 asusctl 时部署的 data/asusd.rules 做两件事:

  1. 用 DMI_VENDOR / DMI_FAMILY 匹配 ROG、TUF、Zephyrus、ProArt 等机型;
  2. 当驱动 asus-nb-wmi 出现 add|change 事件时,打上 systemd 标签并写入 SYSTEMD_WANTS,自动启动 asusd.service 和 asus-shutdown.service。

这就是为什么插上电源后守护进程"自己就起来了"——udev 是整个链路的触发器。

三、asus-armoury:新一代 TDP 控制内核驱动

华硕笔记本的控制能力分两代内核接口:

  • asus-nb-wmi(老驱动):设备挂在 /sys/devices/platform/asus-nb-wmi/ 下,提供 dgpu_disable、gpu_mux_mode、panel_od 等直接属性;
  • asus-armoury(新驱动,6.19+ 主线):通过标准的 firmware-attributes 框架暴露,所有属性位于统一目录:
/sys/class/firmware-attributes/asus-armoury/attributes/
├── boot_sound/        # 开机音效
├── nv_tgp/            # 独显功耗
├── ppt_pl1_spl/       # CPU PL1/PL2 功耗
└── ...
    ├── current_value      # 当前值(读写)
    ├── default_value      # 默认值
    ├── min_value / max_value / scalar_increment
    └── possible_values    # 枚举列表

rog-platform/src/asus_armoury.rs 中直接把这个根路径写成常量 BASE_DIR(注释说明该路径由内核保证稳定,无需 udev 查找)。启动时 FirmwareAttributes::new() 遍历该目录,把每个子目录解析成 Attribute 结构体:名称、帮助文本、当前值、默认值、取值范围一应俱全。

每个属性还通过 define_attribute_getters! 宏(rog-platform/src/asus_armoury.rs)生成了类型化的 getter,例如 attr.nv_tgp()、attr.gpu_mux_mode(),并用 FirmwareAttributeType 标记它的行为类别:

  • Ppt:功耗类属性,重启后需重新应用;
  • Gpu:GPU 相关,如 gpu_mux_mode、dgpu_disable;
  • Bios:写入后需重启才生效(如开机音效);
  • ReadOnly:只读,绝不允许 asusd 写入(如 nv_base_tgp、charge_mode)。

另外,Attribute::get_watcher() 基于 inotify 监视属性目录的 MODIFY 事件(asus_armoury.rs),使 asusd 能实时感知硬件侧变化。

在 GPU 状态读取上,rog-platform/src/gpu_pci.rs 同时兼容新旧两个驱动路径:优先读 firmware-attributes,回退到已废弃的 asus-nb-wmi 属性——这正是"内核接口迁移期"的典型双路径兼容写法。

四、HID 与 USB 原始通道:驱动灯效动画

灯效和动画不走 sysfs,而是直接对话 USB 控制器。rog-platform 提供了两条通道:

4.1 HidRaw —— 逐键 RGB 键盘

rog-platform/src/hid_raw.rs 的 HidRaw::new(id_product) 流程:

  1. udev 枚举 hidraw subsystem;
  2. 向上找到父级 usb_device,比对 idProduct(华硕 Aura 键盘有固定的产品 ID);
  3. 打开对应的 /dev/hidrawX 设备文件,write_bytes() 直接把原始字节包写进去。

asusd 的灯效管理正是建立其上:asusd/src/aura_types.rs、aura_anime、aura_slash 等多个模块都 use rog_platform::hid_raw::HidRaw,配合 rog-aura/data/layouts/ 中按机型定义的键盘布局(.ron 文件),实现逐键配色和呼吸、波浪等内置效果。

4.2 USBRaw —— Slash 副屏动画

rog-platform/src/usb_raw.rs 走的是更底层的 libusb(rusb) 控制传输:

  • 按 0x0b05(ASUSTek vendor ID)+ 指定 product ID 找到设备;
  • reset() 后 claim_interface(0) 独占接口;
  • 用固定的控制请求参数(request_type=0x21, request=0x09)发送帧数据。

G14/M16 屏幕下方的 Slash 显示屏动画就是按这个通道一帧帧推下去的;rog-anime crate 负责把 GIF/PNG 转换成适配分辨率的帧序列。

五、宏魔法:一行声明,四组方法

rog-platform 最精巧的部分是 rog-platform/src/macros.rs 里的 attr_*! 系列宏。以 backlight.rs 中的用法为例:

attr_num!("brightness", path, i32);

这一行会展开生成 has_brightness()(是否存在)、get_brightness()、set_brightness(value)、monitor_brightness()(inotify 监视)四个方法。attr_string、attr_u8_array、attr_bool 同理。

这让每个硬件模块的代码风格高度一致:声明属性 → 宏生成读写接口 → 守护进程调用 → 结果经 D-Bus 广播。keyboard_led.rs 里对 kbd_rgb_mode 的注释也揭示了内核细节——某些属性"只能写、不能回读",宏机制让这种差异无需额外处理。

六、asusd 如何消费这一抽象层

守护进程启动时(asusd/src/daemon.rs)的初始化顺序清晰地展示了抽象层如何被组装:

start_daemon()
 ├─ RogPlatform::new()        # 平台设备
 ├─ AsusPower::new()          # 电源
 ├─ FirmwareAttributes::new() # asus-armoury 属性
 ├─ CtrlFanCurveZbus::new()   # 风扇曲线
 ├─ CtrlBacklight::new()      # 亮度
 └─ CtrlPlatform::new()       # 性能模式 / GPU

每个控制器成功后都会 add_to_server() 注册到 zbus(D-Bus)服务树上,失败则记录日志并跳过——抽象层错误被 rog-platform/src/error.rs 中细分的 PlatformError 枚举精确分类(AttrNotFound、MissingFunction、Udev、USB……),方便上层给出可操作的提示。

ROG Control Center 风扇曲线设置页面,可自定义温度与转速

用户最终不接触这些细节:asusctl platform --profile performance、asusctl battery --charge-stop 80 或 Control Center 界面上的一次点击,都会经 D-Bus 落到 rog-platform,再由 udev 发现的 sysfs 节点、hidraw 设备文件或 USB 控制传输送达硬件。

七、常见问题速查

现象 原因 排查方向
找不到风扇曲线 / 性能模式 内核缺少 asus-nb-wmi 驱动 检查 ls /sys/devices/platform/ 下有无 asus-nb-wmi
TDP 调节不可用 内核版本低于 6.19,无 asus-armoury 升级内核至主线最新稳定版
键盘灯效无反应 未匹配到 hidraw 设备 lsusb 查看是否有 0b05:1866 等 ASUSTek 设备
服务没有自启 udev 规则未匹配机型 查看 data/asusd.rules 中是否包含你的 DMI_FAMILY
EPP 设置失败 部分 CPU 无 energy_performance_preference 属性 仅告警不致命,属预期行为

总结

rog-platform 是 asusctl 的"地基":

  1. udev 统一解决了"设备在哪里"的问题——从 DMI 识别、platform 设备到电源与 LED,全部枚举而来;
  2. sysfs 属性 + 宏解决了"怎么读写"的问题——asus-nb-wmi 与 asus-armoury 两代驱动被封装成同构的 get_/set_/monitor_ 接口;
  3. HID 与原始 USB 解决了 sysfs 覆盖不到的灯效通道,让 Aura 键盘与 Slash 副屏动画得以落地;
  4. 所有结果通过 D-Bus 暴露,用户无需 root 也能安全地控制自己的 ROG 笔记本。

如果你想继续深入,推荐阅读顺序:rog-platform/src/lib.rs → rog-platform/src/platform.rs → rog-platform/src/asus_armoury.rs → asusd/src/daemon.rs,即可完整走通从"内核驱动"到"桌面按钮"的全链路。🚀

登录后查看全文
asusctl