SDK debug 口修改说明

文档说明

本文档说明如何修改 U-Boot 和 Kernel 的 debug uart 口，覆盖配置位置、关键参数、注意事项和修改检查清单，适用于需要切换板级串口打印输出的场景。

debug uart 口修改分为两部分：

U-Boot uart debug：影响 SPL/U-Boot 阶段的串口打印。
Kernel uart debug：影响 Kernel 启动后的 console 打印。

两部分需要分别确认。U-Boot 能正常输出，只能说明 U-Boot 阶段的 uart 配置有效；Kernel 启动后会接管 U-Boot 初始化后的 uart，Kernel 是否继续输出还取决于 kernel cmdline 和 DTS 中的 uart 配置。

1. U-Boot uart debug 配置

U-Boot uart debug 配置通常位于：

SDK/u-boot/include/configs/xxx_xxx.h

修改前需要确认实际参与编译的是哪个板级头文件，尤其注意该文件是否被 overlay 覆盖。如果修改的不是最终生效文件，重新编译后串口配置不会变化。

常用 uart 相关配置包括：

#define CONFIG_SYS_UART_INDEX 0
#define CONFIG_BAUDRATE 115200
#define CONFIG_SYS_UART0_PE_2PIN

其中：

CONFIG_SYS_UART_INDEX 表示 U-Boot debug uart 编号，支持 0 ~ 5。
CONFIG_BAUDRATE 表示串口波特率，需要和 PC 端串口工具保持一致。
CONFIG_SYS_UART*_... 表示对应 uart 的引脚复用配置。

当前支持的 CONFIG_SYS_UART*_... 配置包括：

CONFIG_SYS_UART0_PE_2PIN
CONFIG_SYS_UART1_PC
CONFIG_SYS_UART3_PC
CONFIG_SYS_UART4_PC
CONFIG_SYS_UART5_PC

这些配置对应的 GPIO 初始化代码位于：

SDK/u-boot/drivers/gpio/jz_gpio/x2600_gpio.c

例如将 U-Boot debug 口切换到 uart5，可以按实际板级配置调整为：

#define CONFIG_SYS_UART_INDEX 5
#define CONFIG_BAUDRATE 115200
#define CONFIG_SYS_UART5_PC

修改后需要重新编译 U-Boot，并使用新生成的 U-Boot 镜像启动设备。若配置正确，U-Boot 阶段应能通过目标 uart 正常输出打印。

2. Kernel uart debug 配置

Kernel 启动后会接管 U-Boot 初始化后的 uart。Kernel debug uart 使用哪个串口，主要取决于 kernel config 中 cmdline 的来源配置。

2.1 使用 U-Boot 传入的 bootargs

当 kernel config 使用 MIPS_CMDLINE_FROM_BOOTLOADER，并且未启用 CMDLINE_OVERRIDE 时，Kernel 使用 U-Boot 传入的 bootargs。

此时需要修改 U-Boot 板级头文件中的 BOOTARGS_COMMON：

SDK/u-boot/include/configs/xxx_xxx.h

例如原配置为：

#define BOOTARGS_COMMON "console=ttyS0,115200 ..."

console=ttyS0,115200 表示 Kernel console 使用 uart0，波特率为 115200。

如果要切换到 uart5，需要改为：

#define BOOTARGS_COMMON "console=ttyS5,115200 ..."

修改后需要重新编译 U-Boot，使新的 bootargs 生效。

2.2 使用 DTS 中的 bootargs

当 kernel config 使用 MIPS_CMDLINE_DTB_EXTEND 时，Kernel 使用设备树中的 bootargs。

此时需要在对应板级 DTS/DTSI 中修改 bootargs 里的 console= 参数，例如：

chosen {
    bootargs = "console=ttyS5,115200 ...";
};

实际节点路径以当前 SDK 的板级 DTS 为准。修改 DTS 后，需要重新编译 kernel 或 dtb。

2.3 使用 Kernel 内置 cmdline

如果启用了 CMDLINE_OVERRIDE，Kernel 会优先使用 kernel config 中配置的内置 cmdline。此时需要同步检查并修改 kernel config 中的 CONFIG_CMDLINE，确认其中的 console=ttySx,baud 与目标 debug uart 一致。

3. DTS 中的 uart 使能

Kernel 阶段还需要确认目标 debug uart 在 DTS 中已经使能。如果 U-Boot 已经能打印，但进入 Kernel 后没有打印，需要重点检查：

目标 uart 节点是否存在。
目标 uart 节点是否配置为 status = "okay"。
目标 uart 的 pinctrl、clock 等配置是否完整。
console=ttySx,baud 中的 ttySx 是否与目标 uart 编号一致。

示例：

&uart5 {
    status = "okay";
};

节点名称和附加属性以实际 SDK 的 DTS 配置为准。

4. 修改示例：切换到 uart5

U-Boot 阶段：

#define CONFIG_SYS_UART_INDEX 5
#define CONFIG_BAUDRATE 115200
#define CONFIG_SYS_UART5_PC

Kernel 使用 U-Boot bootargs 时：

#define BOOTARGS_COMMON "console=ttyS5,115200 ..."

Kernel 使用 DTS bootargs 时：

chosen {
    bootargs = "console=ttyS5,115200 ...";
};

同时确认 DTS 中 uart5 已使能。完成修改后，按实际改动范围重新编译 U-Boot、kernel 或 dtb，并烧录/更新到设备。

5. 常见现象与排查方向

U-Boot 没有打印：优先检查 CONFIG_SYS_UART_INDEX、CONFIG_BAUDRATE、CONFIG_SYS_UART*_...、硬件连接和板级头文件是否实际生效。
U-Boot 有打印，Kernel 没有打印：优先检查 kernel cmdline 来源、console=ttySx,baud 和 DTS 中目标 uart 是否使能。
打印乱码：优先检查 CONFIG_BAUDRATE、console=ttySx,baud 和 PC 端串口工具波特率是否一致。
切换后仍从旧串口输出：优先检查是否修改了被 overlay 覆盖的文件，或是否没有烧录/更新新编译出的 U-Boot、kernel、dtb。

6. 修改检查清单

[ ] 确认实际生效的 U-Boot 板级头文件为 SDK/u-boot/include/configs/xxx_xxx.h 中的目标文件。
[ ] 确认该板级头文件没有被 overlay 覆盖，或已同步修改最终生效的 overlay 文件。
[ ] 确认 CONFIG_SYS_UART_INDEX 已设置为目标 uart 编号，且编号范围为 0 ~ 5。
[ ] 确认 CONFIG_BAUDRATE 与 PC 端串口工具波特率一致。
[ ] 确认已选择目标 uart 对应的 CONFIG_SYS_UART*_... 引脚复用配置。
[ ] 确认 SDK/u-boot/drivers/gpio/jz_gpio/x2600_gpio.c 中支持目标 uart 的 GPIO 初始化。
[ ] 确认已重新编译并更新 U-Boot。
[ ] 确认 kernel cmdline 来源：MIPS_CMDLINE_FROM_BOOTLOADER、MIPS_CMDLINE_DTB_EXTEND 或 CMDLINE_OVERRIDE。
[ ] 确认 Kernel 使用的 console=ttySx,baud 已改为目标 uart。
[ ] 确认 DTS 中目标 debug uart 已使能。
[ ] 如果修改了 DTS，确认已重新编译并更新 kernel 或 dtb。
[ ] 启动设备后，确认 U-Boot 阶段和 Kernel 阶段都能通过目标 uart 正常输出 debug 打印。