技术

Xbox 无线适配器(045e:02fe)Linux 驱动实录:mt76x2u 误配与 xone 接管

目录
  1. 一、现象:设备在,驱动不在
  2. 二、根因:Wi-Fi 驱动按 USB ID 误匹配
  3. 三、安装:AUR 的两个包,不是 archlinuxcn 那个
  4. 四、黑名单:别让 Wi-Fi 驱动再抢
  5. 五、踩坑:失败的 probe 会把芯片留在坏状态
    1. 软件复位为什么救不回来
    2. 正确恢复方式
  6. 六、正常上电、配对与验证
    1. 冷启动流程
    2. 验证命令
    3. 配对步骤
    4. 其他 sysfs 入口
  7. 七、排查清单
  8. 八、结语
  9. 参考

设备:Xbox Wireless Adapter for Windows(USB 045e:02fe,MT7662,型号 1790,产品串 XBOX ACC)
环境:Arch Linux,linux-zen 7.2.11(发稿时已滚动到 7.2.14),DKMS
目标:让 Xbox 无线手柄通过原装 2.4G 适配器工作
结果:软件侧配置完成——xone-dkms + xone-dongle-firmware 安装、mt76x2u/xpad 黑名单、双内核 DKMS 构建。硬件侧遇到一个关键坑:失败的 probe 会把 MT7662 留在损坏的 USB 状态,软件复位无法恢复,必须 VBUS 断电重插;文末给出复测与配对清单。

一、现象:设备在,驱动不在

插上适配器后,lsusb 能正常识别:

$ lsusb -d 045e:02fe
Bus 005 Device 005: ID 045e:02fe Microsoft Corp. Xbox Wireless Adapter for Windows

描述符信息很明确:这是一个单接口、厂商自定义类(255/255/255)、8 个批量端点的设备,MaxPower 500mA,bcdDevice 1.00,iProduct 为 XBOX ACC,iSerial 为 410408。

但 lsusb -t 里接口没有驱动:

|__ Port 003: Dev 005, If 0, Class=Vendor Specific Class, Driver=[none], 480M

dmesg 给出了第一现场:

mt76x2u 5-1.3:1.0: ASIC revision: 76120044
mt76x2u 5-1.3:1.0: Direct firmware load for mt7662_rom_patch.bin failed with error -2
mt76x2u 5-1.3:1.0: probe with driver mt76x2u failed with error -2

-2 是 -ENOENT:内核拿 mt76x2u 去驱动它,缺 MediaTek 的 Wi-Fi ROM patch 固件,probe 失败,接口就悬空了。

二、根因:Wi-Fi 驱动按 USB ID 误匹配

mt76x2u 的 USB ID 表里确实包含这两个 Xbox 适配器 PID:

$ modinfo mt76x2u | grep 045E
alias:          usb:v045Ep02FEd*dc*dsc*dp*ic*isc*ip*in*
alias:          usb:v045Ep02E6d*dc*dsc*dp*ic*isc*ip*in*

于是 udev 根据 modalias 自动加载 mt76x2u,它按 Wi-Fi 网卡去初始化这颗 MT7662,自然失败。更关键的是:即使把 mt7662_rom_patch.bin 补上,mt76x2u 也只会把它变成一个 Wi-Fi 网卡,不可能产出 Xbox 手柄输入设备。 Xbox 无线适配器跑的是另一套固件和 GIP over RF 协议。

顺带排除几个常见选项:

驱动 适用场景 为什么不是它
xpad Xbox 手柄 USB 有线连接 不处理 2.4G 适配器
xpadneo Xbox 手柄蓝牙连接 只管蓝牙,不管原装 dongle
xow 老的 userspace dongle 方案 已被内核态 xone 取代
xone USB 有线 + 原装无线 dongle 正确选项

xone 的 xone_dongle 传输层基于 mt76x2u 改造,负责给 dongle 加载 xone_dongle_<PID>.bin 固件、初始化 radio;xone_gip 再跑手柄协议。

三、安装:AUR 的两个包,不是 archlinuxcn 那个

Arch 上能搜到 archlinuxcn/xone-dkms-git,但它依赖 xone-dongle-firmware,而后者不在 archlinuxcn 仓库里,直接装会卡在依赖解析:

警告:无法解决 "xone-dongle-firmware","xone-dkms-git" 的一个依赖关系
错误:无法满足依赖 'xone-dongle-firmware'(xone-dkms-git 需要)

AUR 里 xone-dkms 与 xone-dongle-firmware 是一对完整组合,用 makepkg 构建即可:

sudo pacman -S --needed dkms linux-zen-headers
# 如果同时装了 linux 内核,再补 linux-headers

git clone https://aur.archlinux.org/xone-dongle-firmware.git
cd xone-dongle-firmware
makepkg -si --noconfirm

git clone https://aur.archlinux.org/xone-dkms.git
cd xone-dkms
makepkg -si --noconfirm

固件包会从 Microsoft Update Catalog 的 CAB 中提取四个 PID 对应的固件,其中就包括本设备的 xone_dongle_02fe.bin(70620 字节)。

DKMS 会为已安装的内核分别构建:

$ dkms status
xone/0.5.8, 7.2.11-arch1-1, x86_64: installed
xone/0.5.8, 7.2.11-zen1-1-zen, x86_64: installed

模块别名覆盖了 02e6 / 02f9 / 02fe / 091e:

$ modinfo xone_dongle | grep alias
alias:          usb:v045Ep091Ed*dc*dsc*dp*ic*isc*ip*in*
alias:          usb:v045Ep02F9d*dc*dsc*dp*ic*isc*ip*in*
alias:          usb:v045Ep02FEd*dc*dsc*dp*ic*isc*ip*in*
alias:          usb:v045Ep02E6d*dc*dsc*dp*ic*isc*ip*in*

内核升级后 DKMS 会自动重建;这次从 7.2.11 滚到 7.2.14 后,dkms status 里两个内核的 xone/0.5.8 都是 installed。

四、黑名单:别让 Wi-Fi 驱动再抢

xone-dkms 安装时会写入 /usr/lib/modprobe.d/xone-blacklist.conf:

blacklist xpad
blacklist mt76x2u

两条都必要:

  • mt76x2u:与 dongle 的 USB ID 冲突,必须在自动加载层面挡掉,否则每次插拔都可能被 Wi-Fi 驱动先 probe。
  • xpad:传统 Xbox 手柄驱动;xone 用 xone_wired 接管有线手柄,避免两个驱动争同一设备。

代价要说清楚:这是全局屏蔽 mt76x2u。如果机器上还有 MT7662 的 USB Wi-Fi 网卡,它会一起失效;那种场景下应该改成按 USB ID 的精细 quirk,而不是整模块黑名单。本文机器用的是 Intel AX210(iwlwifi),所以没有影响。

热切换并验证绑定:

sudo modprobe -r mt76x2u
sudo modprobe xone_dongle
$ readlink -f /sys/bus/usb/devices/5-1.3:1.0/driver
/sys/bus/usb/drivers/xone-dongle

lsusb -t 里对应接口也会从 Driver=[none] 变成 Driver=xone-dongle。

五、踩坑:失败的 probe 会把芯片留在坏状态

驱动加载成功、接口也绑上了,但初始化日志不对:

xone-dongle 5-1.3:1.0: xone_mt76_read_register: control message failed: -121
xone-dongle 5-1.3:1.0: xone_dongle_fw_load: load firmware failed: -110

拆开看:

  • -121 是 -EREMOTEIO。xone_mt76_read_register() 用 usb_control_msg() 读 4 字节寄存器,返回值不等于 4 就统一记为 -EREMOTEIO,包括短包。
  • -110 是 -ETIMEDOUT,发生在后续轮询 FCE_DMA_ADDR 时。
  • 这不是缺固件:日志里 xone_dongle_02fe.bin 已经 requested successfully,失败在更底层的 USB 控制传输。

调试日志显示,第一次读 MT_FCE_DMA_ADDR 返回了非零值,驱动因此误判为「固件已在运行」,走了 xone_mt76_reset_firmware() 热重置路径;紧接着读 XONE_MT_RF_PATCH 就短包失败。芯片被之前的 mt76x2u 失败 probe 留在了半初始化状态。

软件复位为什么救不回来

先试 authorized 重授权:

echo 0 | sudo tee /sys/bus/usb/devices/5-1.3/authorized
echo 1 | sudo tee /sys/bus/usb/devices/5-1.3/authorized

结果:

usb 5-1.3: can't set config #1, error -32

-32 是 -EPIPE,设备在 SET_CONFIGURATION 阶段直接 STALL,接口消失。

再试 USBDEVFS_RESET(ioctl 0x5514):

usb 5-1.3: reset high-speed USB device number 5 using xhci_hcd
usb 5-1.3: device reset changed ep0 maxpacket size!
usb 5-1.3: USB disconnect, device number 5
usb 5-1.3: new high-speed USB device number 6 using xhci_hcd
usb 5-1.3: Invalid ep0 maxpacket: 9
usb 5-1.3: new high-speed USB device number 7 using xhci_hcd
usb 5-1.3: Invalid ep0 maxpacket: 9
usb 5-1-port3: attempt power cycle
usb 5-1.3: new high-speed USB device number 8 using xhci_hcd
usb 5-1.3: Invalid ep0 maxpacket: 9
usb 5-1-port3: unable to enumerate USB device

设备直接从总线消失。hub 自己尝试了 power cycle,也没救回来。

驱动源码在 xone_dongle_probe() 里特意留了一段注释,解释为什么 probe 阶段不能做 USB reset:

Do not call usb_reset_device() here. On cold boot the MT76 chip disconnects from USB as a normal part of its firmware startup sequence (inside xone_mt76_load_ivb). A preceding USB reset leaves the XHCI port in a state where it cannot cleanly handle that subsequent disconnect/reconnect cycle, causing the chip to permanently disappear from the USB bus until a physical replug.

翻译过来:冷启动时,MT76 在固件启动序列里会主动断开再重连 USB;如果之前先做了一次 USB reset,XHCI 端口无法干净地处理这次断连/重连,芯片就会从总线上「永久」消失,只有物理重插能恢复。

这不是孤例,上游已有多个 issue 记录同类现象:

  • #215:冷启动 radio init 失败(-71),只有物理重插能恢复;模块重载后变成 -121 / 固件加载失败。
  • #188:045e:02e6 在 0.5.8 上冷启动初始化失败(-108),重插恢复。
  • #227:带着已连接手柄重启会破坏 dongle 初始化,出现 -108/-110 或 ADD/REMOVE_CLIENT 死循环。

正确恢复方式

  1. 拔下适配器;
  2. 等 5 秒,让 VBUS 彻底掉电;
  3. 直接插到机箱后置 USB 2.0 口,不要经过 hub。

原因有两个:一是失败 probe 后芯片只有断电才能清掉内部状态,USB reset 不够;二是这次设备挂在一个 Terminus 1a40:0801 的四口 hub 上,hub 是 ganged 供电、和键盘共享 500mA 预算,自动 power cycle 也没能恢复。直插后置口能同时避开供电和 hub 状态两个变量。

上游 #215 里还有一个 udev workaround:在设备 add 后 3 秒重新写 authorized 0/1。它在部分冷启动失败场景有效,但本文这台机器上芯片已经进入更深的坏状态,重授权直接 can't set config #1。因此只能作为备用手段,不能替代物理断电。

六、正常上电、配对与验证

冷启动流程

重插后,xone-dongle 会重新走完整的冷启动:

  1. USB 枚举,接口绑定 xone-dongle;
  2. 请求 xone_dongle_02fe.bin;
  3. 发送 ILM/DLM 固件段;
  4. 芯片按固件启动序列断开/重连一次;
  5. 轮询 FCE_DMA_ADDR == 0x01;
  6. 初始化 radio;
  7. 自动开启 60 秒配对窗口(这个 fork 的行为,方便已配对手柄开机自动回连)。

验证命令

cat /sys/bus/usb/drivers/xone-dongle/*/pairing
cat /sys/bus/usb/drivers/xone-dongle/*/active_clients
grep -i xbox /proc/bus/input/devices
ls -l /dev/input/js*

正常状态下:

  • 刚初始化完 pairing=1(60 秒窗口);
  • 手柄连上后 active_clients 对应槽位变为非零;
  • /proc/bus/input/devices 出现 Xbox Wireless Controller;
  • /dev/input/js* 新增对应节点。

配对步骤

  1. 手柄关机;
  2. 按住 Xbox 键开机;
  3. 再按住顶部配对键(LB 右上方的小圆键),直到 Xbox 键快速闪烁;
  4. 等待 dongle 与手柄完成配对。

如果这个手柄之前就配过这个 dongle,直接按 Xbox 键开机即可自动回连。如果上次是通过蓝牙或 USB 连到别的主机,它不会自动连 dongle,必须重新进配对模式——这是 Xbox 手柄的 host 记忆机制,不是驱动问题。

其他 sysfs 入口

# 主动开启配对
echo 1 | sudo tee /sys/bus/usb/drivers/xone-dongle/*/pairing

# 断开单个客户端(0-15),-1 表示全部
echo -1 | sudo tee /sys/bus/usb/drivers/xone-dongle/*/poweroff

# 查看当前客户端
cat /sys/bus/usb/drivers/xone-dongle/*/active_clients

权限方面,/dev/input/js* 是 root:input 0660 并带 ACL;当前用户在 input 组,steam-devices 也已安装,Steam 能正常看到手柄。

七、排查清单

现象 根因 处理
045e:02fe 接口 Driver=[none],mt76x2u 报 mt7662_rom_patch.bin -2 Wi-Fi 驱动按 USB ID 误匹配 装 xone + 黑名单 mt76x2u
xone_mt76_read_register: -121,随后 load firmware failed: -110 失败 probe 残留状态 / 芯片未干净上电 拔下等 5 秒,直插后置 USB 2.0
重授权后 can't set config #1, error -32 芯片 USB 控制器已卡死 物理断电重插,不要再软复位
Invalid ep0 maxpacket: 9,设备从总线消失 USB reset 破坏了 ep0 状态 物理断电重插
pairing=0,没有 js 设备 未配对,或手柄还记着别的主机 进配对模式重新配对
重启后 dongle 初始化失败 已知 #227 / #215 重启时保持手柄关机;必要时重插
装有线手柄时 xpad 与 xone 冲突 两个驱动争设备 确认黑名单里有 xpad

八、结语

这块适配器的软件配置本身不复杂:xone-dkms + 对应 PID 的固件 + 黑名单 mt76x2u/xpad。真正浪费时间的是失败 probe 之后的硬件状态——内核 Wi-Fi 驱动先摸了一把 MT7662,留下半初始化的寄存器;此时任何 authorized 重授权或 USBDEVFS_RESET 都可能把设备推入更深的坏状态,最后只能物理断电。

所以这类 dongle 的排障顺序应该是:

  1. 先确认 VID:PID 和接口驱动状态;
  2. 确认没有内核自带的同 ID 驱动在抢(modinfo 查 alias);
  3. 装对驱动后,一次干净的冷启动比任何软件复位都重要;
  4. 冷启动失败时,直接拔插,不要反复 usb_reset_device()。

截至本文发布,软件侧(驱动、固件、黑名单、双内核 DKMS)已经就绪;适配器已从总线拔出,等待按上面的流程物理重插复测。复测通过后的正常标志就是 Driver=xone-dongle、pairing=1,以及 /dev/input/js* 下出现手柄节点。

参考