这次故障最容易误判的地方，是 BurnTool 已经完成写入，设备却黑屏。若只看下载结果，很容易继续怀疑 USB 线、显示屏排线、ST7789 驱动或包格式；但真实根因落在更靠前的板级初始化：试验固件把 GPIO14 当成中键候选进行配置，而这块 WS63 V1 板上 GPIO14 属于PWR_ON电源保持/显示供电相关保留脚。
本文依据仍保留在本地的黑屏包、恢复包、历史故障记录和当前board_config.h、key_config.c复盘。当前主线仍是 OpenHarmony mini 与 LiteOS-M；黑屏包与恢复包的字节数、SHA-256 都重新计算过。当前源码已经把按键限定在 P11、P12、P13，并增加编译期禁止映射到 P14 的保护。本轮没有为了写文章再次烧入危险包，也不会提供“请复现黑屏”的操作步骤。
先把写入成功和业务启动分开
BurnTool 能写完.fwpkg，说明下载握手、Loader 和镜像写入流程已经完成；屏幕点亮还需要电源保持、背光、SPI、LCD 复位、显示初始化和 UI 任务全部成立。一个包可以在写入层成功，却在任何业务初始化步骤失败。这个项目的 GPIO14 故障就是直接证据：工具完成写入，但代码在启动阶段改动了不该占用的引脚。
因此黑屏后的第一张检查表不应只有“是否烧录成功”，而要分为：本次选中包的哈希；BurnTool 完成状态；启动串口是否出现；早期背光是否点亮；恢复包能否恢复。恢复包可以点亮，而试验包稳定黑屏时，硬件突然损坏的可能性会显著下降，调查应优先转向两个包之间的板级差异。
两个真实包先用大小和哈希锁定
危险包保留在DO_NOT_BURN_black_screen_p14_probe隔离目录，文件名为xiaohong_ws63_sch_key_probe_p12_p13_p14_20260708_1626.fwpkg.Hi3863BurnTool.bad，大小 1,908,008 字节，SHA-256 为88E02500B00BAF21A1ED5AFF35F259A5A7FB464A78A931409321FDB7AB788608。
已知屏幕恢复包为000_FLASH_THIS_NOW_RECOVER_SCREEN_GOOD_WS63.fwpkg，大小 1,908,264 字节，SHA-256 为F8D7B52914723A07A6D3BC2C5FE4E000B6AA0445F02E1726F6A9C775AC05F1D3。两者相差 256 字节，但不能根据这 256 字节直接推导哪条指令或哪个分区不同；.fwpkg是容器，必须结合构建时源码和镜像表解释。
black-screen package 1,908,008 bytes 88E02500B00BAF21A1ED5AFF35F259A5A7FB464A78A931409321FDB7AB788608 screen-good recovery package 1,908,264 bytes F8D7B52914723A07A6D3BC2C5FE4E000B6AA0445F02E1726F6A9C775AC05F1D3正确按键映射来自当前板级头文件
当前xiaohong/xiaohong/src/boards/board_config.h明确给出三键映射：音量加 P13、音量减 P12、功能键 P11。紧跟其后的PWR_ON_RESERVED_PIN是 P14。它不是可供轮询扫描随意尝试的第四个按键脚，而是必须从按键子系统中排除的板级所有权。
#define KEY_VOLUP_PIN (13) // Volume Up key #define KEY_VOLDW_PIN (12) // Volume Down key #define KEY_WAKEUP_PIN (11) // Function key #define PWR_ON_RESERVED_PIN (14) // Power hold/display supply; never configure as a key这里的注释不是唯一证据。历史故障中，KEY_WAKEUP_PIN曾被改为 14，扫描范围也曾扩大到 P11～P14；随后初始化代码对 P14 执行复用、上下拉、GPIO 方向、输出状态和中断注册。恢复 P11 并停止配置 P14 后，屏幕恢复到已知可工作路径。这形成“错误改动—黑屏—撤销改动—恢复”的因果链。
为什么普通输入初始化也可能影响供电
GPIO 初始化不是只读操作。uapi_pin_set_mode会改复用，uapi_pin_set_pull会改变上下拉，uapi_gpio_set_dir会切换输入输出，设置输出值会驱动电平，注册中断还会改变触发与中断控制状态。当这个脚连接到 PWR_ON 或显示供电相关链路时，即使业务代码只是“想看看按键有没有变化”，也可能破坏电源保持条件。
黑屏包的问题并不是某个if分支把屏幕隐藏，而是按键探测跨越了硬件所有权边界。它发生在显示 UI 之前，因此 LVGL 页面、字体和 Agent 状态机都没有机会补救。只有先恢复保留脚状态，显示初始化才有继续运行的条件。
当前 key_init 只初始化三个确认过的按键
当前key_config.c的真实初始化片段只对三个宏代表的引脚操作。音量键使用下拉，功能键使用上拉；每个引脚设置为输入并注册双边沿中断。只要KEY_WAKEUP_PIN保持为 11，这段代码就不会触碰 P14。
step = uapi_pin_set_mode(KEY_WAKEUP_PIN, 0); ret |= step; step = uapi_pin_set_pull(KEY_WAKEUP_PIN, PIN_PULL_TYPE_UP); ret |= step; step = uapi_gpio_set_dir(KEY_WAKEUP_PIN, GPIO_DIRECTION_INPUT); ret |= step; step = uapi_gpio_register_isr_func( KEY_WAKEUP_PIN, GPIO_INTERRUPT_DEDGE, wakeup_key_event_cb); ret |= step;但仅靠“当前正好写的是 11”仍然脆弱。下一次调板时，如果有人只改宏值，初始化代码会自动跟着走到新引脚。真正防回归需要把 P14 禁止条件变成编译器能够检查的约束。
编译期保护比运行后黑屏更便宜
当前头文件已经加入三个比较：任意按键宏等于PWR_ON_RESERVED_PIN时立即#error。这样错误不会等到打包、烧录和黑屏才暴露，而是在预处理阶段停止。错误信息直接写出 GPIO14 与 PWR_ON 的关系，能让后续维护者知道这不是普通引脚冲突。
#if (KEY_VOLUP_PIN == PWR_ON_RESERVED_PIN) || \ (KEY_VOLDW_PIN == PWR_ON_RESERVED_PIN) || \ (KEY_WAKEUP_PIN == PWR_ON_RESERVED_PIN) #error "GPIO14 is PWR_ON and must not be initialized by key_config" #endif编译期保护覆盖的是静态宏映射，仍需防止循环扫描把 14 包含进去。因此当前扫描边界单独定义为 11～13，轮询任务的日志也写明scan pins[11-13]。一个检查守住宏映射，一个检查守住通用扫描范围，两者不能互相替代。
扫描边界必须由常量和数据表共同约束
当前按键轮询数组只由KEY_VOLUP_PIN、KEY_VOLDW_PIN、KEY_WAKEUP_PIN三项组成，额外探测数组也以KEY_SCAN_FIRST_PIN 11U和KEY_SCAN_LAST_PIN 13U为边界。这样不会出现一个显式数组是安全的、另一个“为方便诊断”从 11 循环到 14 的旁路。
#define KEY_SCAN_FIRST_PIN 11U #define KEY_SCAN_LAST_PIN 13U key_poll_state_t keys[] = { {.pin = KEY_VOLUP_PIN, .id = KEY_VOLUP_PIN, .short_event = eKey_VolUp_ShortPressed, .long_event = eKey_VolUp_LongPressed, .long5_event = KEY_EVENT_NONE, .name = "VolUp"}, {.pin = KEY_VOLDW_PIN, .id = KEY_VOLDW_PIN, .short_event = eKey_VolDw_ShortPressed, .long_event = eKey_VolDw_LongPressed, .long5_event = KEY_EVENT_NONE, .name = "VolDw"}, {.pin = KEY_WAKEUP_PIN, .id = KEY_WAKEUP_PIN, .short_event = eKey_Wakeup_ShortPressed, .long_event = eKey_Wakeup_LongPressed, .long5_event = eKey_Wakeup_LongPressed_5S, .name = "Wakeup"}, };代码摘录保留了当前真实数据表的事件字段。短按、长按和 5 秒长按分别绑定到对应项；对保留脚的安全要求应同样覆盖诊断代码、产测代码和临时 probe，不能因为“只读电平”就放松。
恢复屏幕后还要逐层确认不是偶然
恢复包点亮屏幕只能证明已知基线重新工作。要确认修复进入新包，还应重新构建并保存产物哈希，烧入后读取启动串口，观察早期显示日志，再检查三键。音量加减短按应更新音量，长按应改变背光；中键短按负责会话控制，普通长按切换语音打断，5 秒长按进入清除 Wi-Fi 配置与重启流程。
如果只测试“屏幕亮了”，仍可能漏掉按键电平、上拉下拉或事件重复问题。反过来，如果串口能打印按键中断，也不能推导 P14 一定安全；必须从源码确认初始化目标和扫描范围。静态检查、构建保护、烧录、启动和功能测试要各自留证据。
黑屏后的排查顺序应该从板级差异开始
遇到“新包黑屏、旧包正常”时，先固定两个包的哈希，再比较board_config.h、板级初始化、LCD/背光引脚、SPI 片选和早期启动顺序。不要先改 LVGL 颜色，也不要用不断重烧不同包代替差异定位。已知恢复包应随时可用，危险包必须隔离并在名称中标明禁止烧录。
其次检查是否有开发期间加入的 GPIO 扫描、强制输出、全范围中断注册。调试代码往往比正式逻辑更容易越过所有权，因为它倾向于“先扫一遍看看”。对于 PWR_ON、复位、Flash 片选、LCD 片选和背光等关键脚，应建立保留表，并让编译期或静态脚本拒绝通用扫描覆盖。
本次复盘能够确认和仍待验证的部分
已经确认的事实包括：黑屏包仍以隔离扩展名保存，大小和 SHA-256 可复算；恢复包大小和 SHA-256 可复算；历史故障记录把黑屏定位到 P14 的模式、上下拉、方向、输出与中断初始化；当前源码恢复 P11/P12/P13，定义 P14 为保留脚，并同时加入宏映射检查和 11～13 扫描边界。
本轮没有重新烧入黑屏包，也没有再次用当前源码构建后完成三键、显示、Wi-Fi 与 Agent 的整机回归。因此本文的结论是“根因和源码防线已经核对”，不是“今天又完成了一轮破坏性复现”。这也是固件故障文章应保持的证据边界：能够从已有包、改动记录和恢复结果建立因果链时，不需要为了截图再次把设备置于已知危险状态。
