ZMK固件中复合键盘扫描驱动与Charlieplex矩阵的兼容性问题分析

问题背景

在ZMK固件项目中，开发者Scalee报告了一个键盘扫描功能失效的问题。该问题出现在使用kscan_composite复合驱动时，当系统尝试同时使用GPIO矩阵扫描(kscan_matrix)和Charlieplex矩阵扫描(kscan_charlie)两种扫描方式时，键盘输入完全失效。

问题现象

具体表现为：

1. 当直接使用kscan_charlie或kscan_matrix单独作为扫描驱动时，键盘功能正常
2. 当通过kscan_composite组合这两种扫描方式时，虽然设备能正常启动并输出日志，但所有按键输入均无响应
3. 回退到前一个提交版本(0438cb0之前)后，问题消失

技术分析

通过日志对比发现关键差异在于电源管理回调函数的执行情况：

正常工作情况下的日志：

kscan_charlieplex_init
kscan_charlieplex_pm_action
kscan_charlieplex_setup_pins
kscan_charlieplex_init_interrupt

故障情况下的日志：

kscan_charlieplex_init
kscan_charlieplex_configure
kscan_charlieplex_enable
kscan_charlieplex_interrupt_enable
kscan_charlieplex_interrupt_configure

核心问题在于使用复合扫描驱动时，Charlieplex扫描器的电源管理回调函数kscan_charlieplex_pm_action没有被调用。这个回调函数负责关键的初始化步骤，包括引脚设置(kscan_charlieplex_setup_pins)和中断初始化(kscan_charlieplex_init_interrupt)。

问题根源

该问题源于ZMK固件中电源管理子系统与复合扫描驱动的交互方式。在复合扫描场景下：

1. 复合扫描器作为顶层设备被注册到电源管理系统
2. 但底层的Charlieplex扫描器没有被正确注册为子设备
3. 导致Charlieplex扫描器的电源管理回调无法被触发
4. 关键的硬件初始化步骤被跳过
5. 虽然中断配置等后续步骤被执行，但由于基础硬件未正确初始化，扫描功能完全失效

解决方案

项目维护者petejohanson随后提交了修复补丁，主要改进点包括：

1. 确保复合扫描器正确管理其子扫描器的电源状态
2. 在复合扫描器初始化时，显式触发所有子扫描器的电源管理回调
3. 建立正确的设备父子关系，使电源管理事件能正确传播

技术启示

这个案例展示了嵌入式系统中电源管理的重要性，特别是在复合设备场景下：

1. 电源管理回调不仅用于低功耗状态切换，也常用于硬件初始化
2. 复合设备必须妥善管理其子组件的电源状态
3. 设备树中的层次关系需要与实际的硬件依赖关系保持一致
4. 在驱动程序开发中，初始化顺序和依赖关系需要特别关注

对于ZMK固件开发者而言，这个问题的解决也验证了：

1. 日志分析在嵌入式调试中的关键作用
2. 电源管理子系统在复杂外设组合中的重要性
3. 回归测试对固件稳定性的保障价值

该问题的及时修复确保了ZMK固件对复杂键盘矩阵配置的持续支持能力，为使用混合扫描方案(如同时使用普通矩阵和Charlieplex矩阵)的键盘设计提供了可靠基础。