4. HPS外设与接口
Agilex 5 的 HPS 侧集成了大量常用外设控制器，它们通过 HPS-FPGA 桥、Pin Mux 与 I/O 复用矩阵连接到外部器件。实际项目中，外设能否稳定工作，往往不取决于控制器本身，而取决于引脚复用、时钟源、设备树配置、驱动匹配与信号完整性这五个环节是否一致。本章围绕 UART、I2C、SPI、SD/MMC、USB 和以太网六类接口，梳理配置思路与调试方法。
一、核心原理：外设从控制器到引脚的完整链路
HPS 外设的访问路径可以概括为：CPU 通过内部总线访问外设控制器寄存器，控制器产生时序信号，经 Pin Mux 选择功能后送到 I/O Bank，再通过外部引脚连接目标器件。任何一环配置错误，都会表现为“控制器存在但通信失败”。
二、方法流程：六类外设的配置与验证步骤
建议按统一流程推进：先确认硬件连接与电压域，再配置 Pin Mux 与时钟，然后修改设备树，最后加载驱动并用用户态工具验证。
- UART：确认 TX/RX 交叉连接，设置波特率、数据位、停止位和校验位。常用
stty或minicom验证。 - I2C：确认上拉电阻和从机地址，使用
i2cdetect扫描总线，再用i2cget/i2cset读写寄存器。 - SPI：确认 CPOL/CPHA、片选和时钟频率，使用
spidev_test回环验证。 - SD/MMC：确认卡检测引脚和供电时序，使用
mmc extcsd read或fdisk -l检查枚举。 - USB：确认 PHY 参考时钟和 VBUS 控制，使用
lsusb、dmesg观察枚举日志。 - 以太网：确认 RGMII 延时、PHY 地址和复位时序，使用
ethtool、ping验证链路。
设备树中一个典型 UART 节点配置如下：
&uart0 {
status = "okay";
pinctrl-names = "default";
pinctrl-0 = &uart0_pins;
clock-frequency = <100000000>;
};
&uart0_pins {
pins = "gpio1_0", "gpio1_1";
function = "uart0";
bias-pull-up;
};三、案例场景：以太网与 SD 卡联合调试
某 Agilex 5 板卡上电后，SD 卡无法识别，同时以太网 PHY 链路不稳定。排查发现两个问题：一是 SD 卡检测引脚被复用为 GPIO 但未配置内部上拉，导致热插拔检测电平漂移；二是 RGMII 接口的 TX 时钟延时未按 PHY 要求设置，造成数据采样窗口偏移。
解决方法是：在设备树中为 SD 检测引脚增加 bias-pull-up，并在以太网节点中配置 tx-internal-delay-ps 与 rx-internal-delay-ps。修改后 SD 卡正常枚举，以太网在千兆模式下稳定传输。
调试外设时，优先查看 dmesg 中的驱动探测日志。若出现 probe failed 或 timeout，通常指向时钟、引脚或供电问题，而不是协议本身。
四、常见误区与复盘清单
| 误区 | 现象 | 正确做法 |
|---|---|---|
| 只改设备树，忽略 Pin Mux | 驱动加载成功但无信号 | 同步检查 pinctrl 与功能号 |
| I2C 缺少上拉电阻 | 扫描不到从机或随机失败 | 按总线速率选择 2.2k～10k 上拉 |
| SPI 模式不匹配 | 读回数据全 0 或全 FF | 核对 CPOL/CPHA 与从机手册 |
| USB VBUS 未使能 | 设备无枚举日志 | 检查 VBUS 控制 GPIO 与供电 |
| RGMII 延时未配置 | 链路时通时断、丢包 | 按 PHY 要求设置内部延时 |
复盘时建议记录“时钟—引脚—设备树—驱动—信号”五要素检查表。多数外设问题并非控制器故障，而是配置链路中某一环缺失或参数不一致。
掌握上述方法后，HPS 外设调试可以从“试错”转为“按链路定位”。下一阶段可结合具体板级原理图，逐项核对引脚分配与电压域，形成可复用的调试记录。