USB PHY HAL 接口

1. USB PHY HAL 接口规范

头文件：

#include "hal_usb_phy.h"

1.1 hal_usb_phy_init

void hal_usb_phy_init(void);

功能说明：

通过 CPM 和 PHY 寄存器执行 PHY POR、UTMI reset、默认 IDDIG 配置和基础 PHY 参数初始化。

参数表：

参数	类型	方向	说明
无	-	-	固定操作 USB_PHY 和 CPM。

返回值表：

返回值	说明
无	内部失败只记录日志，不向调用方返回。

当前实现顺序：

1. 写 CPM USBPCR1 = 0x00000000。
2. 写 CPM USBPCR = 0x00400000，置位 POR[22]。
3. 延时 10 us。
4. 写 CPM USBPCR = 0x00000000，释放 POR。
5. 写 CPM USBPCR1 = 0x30000000，置位 DPPD_EN[29] 和 DMPD_EN[28]。
6. 清除 CPM USBRDT.UTMI_RST[27]，assert UTMI reset。
7. 延时 550 us。
8. 置位 USBRDT.UTMI_RST[27]，release UTMI reset。
9. 根据编译期配置选择默认模式：
   • 定义 CONFIG_USB_DUAL_ROLE 或 CONFIG_USB_PERIPHERAL 时为 Peripheral；
   • 否则为 Host。
10. 延时 10 us。
11. 设置 PHY RX_SQUELCH_TRIGGER 为 USB_PHY_RX_SQUELCH_TRIGGER_125MV，字段值 0x8。
12. 置位 OTG_SESSION.IO_HIGH_Z[5]。
13. 清除 PHY_DETECT.LEGACY_CONFIG[3]。
14. 若定义 CONFIG_USB_DISABLE_VBUS，置位 VBUS_CONTROL.DETECT_POWERDOWN[3]。

补充说明：

• 本接口执行 CPM USBPCR/USBPCR1 全寄存器写，不是字段读改写。
• 本接口不显式 ungated USB PHY 参考时钟；通过 MID 使用时，phy_reset 先于 phy_init 执行并完成 refclk ungated。
• 本接口失败时立即返回，前面已经写入的寄存器保持生效，可能留下部分初始化状态。
• 重复调用会重新执行 POR 和 UTMI reset，不能用于运行中无扰调整。
• 本接口不会配置 DWC2 控制器、OTG 门控、USB IRQ 或 VBUS 电源 GPIO。

1.2 hal_usb_phy_reset

void hal_usb_phy_reset(void);

功能说明：

ungated USB PHY 参考时钟、释放 CPM 强制 suspend，并等待 PHY 稳定。

参数表：

参数	类型	方向	说明
无	-	-	固定操作 CPM OPCR.GATE_USBPHY_CLK[23] 和 OPCR.SPENDN0[7]。

返回值表：

返回值	说明
无	失败只记录日志。

当前实现顺序：

1. 清除 OPCR.GATE_USBPHY_CLK[23]，ungated PHY 参考时钟。
2. 置位 OPCR.SPENDN0[7]，释放强制 suspend。
3. 延时 550 ms。

补充说明：

• 函数名中的 “reset” 不表示执行 PHY POR、UTMI reset 或 DWC2 core reset；完整 PHY 初始化动作在 hal_usb_phy_init()。
• 本接口成功后不会重新 gate 参考时钟。
• 若释放 suspend 失败，会尝试重新 gate 参考时钟，然后返回。
• 本接口有 550 ms 阻塞延时，不得在中断上下文调用。

1.3 hal_usb_phy_suspend

void hal_usb_phy_suspend(int suspend, int wakeup);

功能说明：

根据 suspend 进入或退出 PHY 强制 suspend，并同步配置 VBUS detect 和 legacy receiver driver。

参数表：

参数	类型	方向	说明
suspend	int	输入	非 0 进入 suspend；0 恢复。
wakeup	int	输入	保留参数，当前实现完全忽略。

返回值表：

返回值	说明
无	CPM 操作失败时记录 error log。

suspend != 0 时：

1. 若未定义 CONFIG_USB_DISABLE_VBUS，置位 VBUS_CONTROL.DETECT_POWERDOWN[3]。
2. 清除 PLL_CONTROL0.LEGACY_RECEIVER_DRIVER[6]。
3. 清除 CPM OPCR.SPENDN0[7]，强制 PHY suspend。

suspend == 0 时：

1. 置位 CPM OPCR.SPENDN0[7]，释放强制 suspend。
2. 若该步骤失败，立即返回，不恢复 receiver/VBUS detect。
3. 置位 PLL_CONTROL0.LEGACY_RECEIVER_DRIVER[6]。
4. 若未定义 CONFIG_USB_DISABLE_VBUS，清除 VBUS_CONTROL.DETECT_POWERDOWN[3]。

补充说明：

• wakeup 当前不改变硬件行为。
• 调用方应确保 USB Core 已停止或准备好停止总线活动。
• 本接口不管理 OTG 控制器门控；MID 在调用本接口后还会关闭/开启 OTG 时钟门。

1.4 hal_usb_phy_resume_status

int hal_usb_phy_resume_status(void);

功能说明：

兼容 MID 的 PHY resume 状态查询回调。

参数表：无。

返回值表：

返回值	说明
0	当前实现始终返回 0。

补充说明：

• 当前实现不读取 PHY、CPM 或 DWC2 的 resume 状态寄存器。
• 应用不能使用该接口判断 USB 是否完成 resume；应使用 DWC2 WKUPINT、DSTS 或 USB MID 状态。
• 函数可在中断相关 MID 路径调用，因为当前仅返回常量。

1.5 hal_usb_phy_set_mode

int hal_usb_phy_set_mode(enum otg_phy_mode mode);

功能说明：

通过 CPM IDDIG override 选择 Peripheral、Host 或硬件 OTG 模式。

参数表：

参数	类型	方向	说明
mode	enum otg_phy_mode	输入	OTG_PHY_MODE_PERIPHERAL、OTG_PHY_MODE_HOST 或 OTG_PHY_MODE_OTG。

返回值表：

返回值	说明
0	设置成功。
-1	mode 非法或 CPM 辅助函数返回错误。

模式映射：

模式	CPM 操作
Peripheral	置位 IDDIG_EN[1]，设置 IDDIG_REG[0]=1（mini-B）。
Host	置位 IDDIG_EN[1]，设置 IDDIG_REG[0]=0（mini-A）。
OTG	清除 IDDIG_EN[1]，由 PHY UTMI IDDIG 信号决定。

补充说明：

• 返回 -1 不等同于某个标准 errno。
• 本接口只控制 IDDIG；DWC2 角色切换仍由控制器或 MID 完成。
• 不要在传输中调用。切换后应由上层等待实际模式生效。

1.6 hal_usb_phy_power_detect

enum usb_device_power hal_usb_phy_power_detect(void);

功能说明：

使用 PHY BC1.1 detect 控制执行 data contact、Primary 和 Secondary 检测。

参数表：无。

返回值表：

返回值	判定条件
USB_POWER_UNKNOWN	20 ms 后未检测到 data contact。
USB_POWER_SDP	data contact 成功，Primary 失败。
USB_POWER_DCP	data contact、Primary、Secondary 全部成功。
USB_POWER_CDP	data contact、Primary 成功，Secondary 失败。

当前实现顺序：

1. 写 PLL_CONTROL1 = USB_PHY_BC_DETECT_CONTROL_DATA_CONTACT (0x60)。
2. 延时 20 ms，读取 VBUS_VALID_CONTROL.BC_DATA_CONTACT_STATUS[5]。
3. 数据接触成立后写 PLL_CONTROL1 = USB_PHY_BC_DETECT_CONTROL_PRIMARY (0x90)。
4. 延时 20 ms，读取 SESSION_VALID_CONTROL.BC_PRIMARY_STATUS[1]。
5. Primary 成立后写 PLL_CONTROL1 = USB_PHY_BC_DETECT_CONTROL_SECONDARY (0x0C)。
6. 延时 20 ms，读取 SESSION_VALID_CONTROL.BC_SECONDARY_STATUS[0]。
7. 无论结果如何，最后写 PLL_CONTROL1 = USB_PHY_BC_DETECT_CONTROL_IDLE (0x00)。

阻塞时间：

路径	最大阻塞时间
data contact 失败	20 ms
Primary 失败	40 ms
执行完整 Secondary 检测	60 ms

补充说明：

• 本接口对 PLL_CONTROL1 做全寄存器写。
• PHY 必须已上电、参考时钟有效并连接到可执行 BC1.1 检测的下游端口。
• 本接口不改变 USB 数据角色，也不判断主机是否开始枚举。
• 不应与 ll_usb_phy_write_bc_detect_control() 或其他 BC detect 用户并发执行。

1.7 hal_usb_phy_regs_dump

error_code_t hal_usb_phy_regs_dump(void);

功能说明：

以 INFO 日志打印 USB PHY 地址和全部已命名寄存器。

参数表：无。

返回值表：

返回值	说明
IM_OK	已输出寄存器。
IM_ERR_UNSUPPORTED	两个 debug helper 开关未同时开启。

输出寄存器顺序：

0x030 TX_PRE_EMPHASIS
0x040 TX_HS_PRE_EMPHASIS
0x044 RX_CLOCK_PHASE
0x048 TX_CLOCK_PHASE
0x060 DISCONNECT_TRIGGER
0x064 RX_SQUELCH_TRIGGER
0x068 DISCONNECT_TRIGGER_EXT
0x070 PHY_DETECT
0x078 OTG_SESSION
0x0A0 BG_CONTROL
0x100 PLL_CONTROL0
0x104 PLL_CONTROL1
0x108 VBUS_CONTROL
0x10C SESSION_VALID_CONTROL
0x110 VBUS_VALID_CONTROL
0x114 CLOCK_ENABLE
0x11C HS_ODT_FSLS_STRENGTH
0x120 SQUELCH_SLEW_TUNING
0x124 HS_EYE_HEIGHT
0x1C0 DPDM_PULLDOWN_CONTROL
0x1C4 PLL_WAVE_FILTER
0x1CC SOF_DISCONNECT_CONTROL

补充说明：

• 需要同时定义非 0 的 CONFIG_SDK_ENABLE_DEBUG_HELPERS 和 CONFIG_USB_PHY_ENABLE_DEBUG_HELPERS。
• 本接口只读寄存器，不读取 FIFO 或修改硬件状态。
• 本接口是阻塞日志接口，不得在中断上下文调用。

2. CPM USB HAL 接口规范

头文件：

#include "hal_cpm_usb.h"

这些接口是 USB PHY 驱动的一部分，不是通用 CPM HAL 的全部接口。

2.1 参考时钟控制

2.1.1 hal_cpm_usb_phy_enable_refclk

error_code_t hal_cpm_usb_phy_enable_refclk(void);

功能说明：

清除 CPM OPCR.GATE_USBPHY_CLK[23]，使能 24 MHz USB PHY 参考时钟。

参数表：无。

返回值表：

返回值	说明
IM_OK	当前实现始终返回。

补充说明：该接口不等待时钟稳定，也不确认硬件门控状态。

2.1.2 hal_cpm_usb_phy_disable_refclk

error_code_t hal_cpm_usb_phy_disable_refclk(void);

功能说明：

置位 CPM OPCR.GATE_USBPHY_CLK[23]，关闭 USB PHY 参考时钟。

参数表：无。

返回值表：

返回值	说明
IM_OK	当前实现始终返回。

补充说明：PHY 寄存器访问期间或 PHY 仍需工作时不得 gate 参考时钟。

2.2 PHY 强制挂起

2.2.1 hal_cpm_usb_phy_set_suspend

error_code_t hal_cpm_usb_phy_set_suspend(bool suspend);

功能说明：

通过 CPM OPCR.SPENDN0[7] 强制或释放 USB PHY suspend。

参数表：

参数	类型	方向	说明
suspend	bool	输入	true 强制 suspend；false 释放。

返回值表：

返回值	说明
IM_OK	当前实现始终返回。

硬件电平：

参数	SPENDN0[7]	含义
true	0	USB PHY 被强制进入 suspend。
false	1	USB PHY 不处于强制 suspend。

2.3 USBPCR/USBPCR1 参数控制

2.3.1 hal_cpm_usb_phy_write_parameter_control

error_code_t hal_cpm_usb_phy_write_parameter_control(uint32_t value);

功能说明：

将 value 完整写入 CPM USBPCR (0x03C)。

参数表：

参数	类型	方向	说明
value	uint32_t	输入	USBPCR 原始值。

返回值表：IM_OK。

补充说明：全寄存器写。除非明确知道全部字段值，否则应使用 CPM LL 的单 bit 接口。

2.3.2 hal_cpm_usb_phy_read_parameter_control

error_code_t hal_cpm_usb_phy_read_parameter_control(uint32_t *value_out);

功能说明：

读取 CPM USBPCR。

参数表：

参数	类型	方向	说明
value_out	uint32_t *	输出	原始值输出，不能为 NULL。

返回值表：

返回值	说明
IM_OK	读取成功。
IM_ERR_INVALID_PARAM	value_out == NULL。

2.3.3 hal_cpm_usb_phy_write_parameter_control1

error_code_t hal_cpm_usb_phy_write_parameter_control1(uint32_t value);

功能说明：

将 value 完整写入 CPM USBPCR1 (0x048)。

参数表：

参数	类型	方向	说明
value	uint32_t	输入	USBPCR1 原始值。

返回值表：IM_OK。

补充说明：全寄存器写；hal_usb_phy_init() 使用该接口写入 0x30000000 和 0x00000000。

2.3.4 hal_cpm_usb_phy_read_parameter_control1

error_code_t hal_cpm_usb_phy_read_parameter_control1(uint32_t *value_out);

功能说明：

读取 CPM USBPCR1。

参数表：

参数	类型	方向	说明
value_out	uint32_t *	输出	原始值输出，不能为 NULL。

返回值表：

返回值	说明
IM_OK	读取成功。
IM_ERR_INVALID_PARAM	value_out == NULL。

2.4 UTMI 复位

2.4.1 hal_cpm_usb_phy_assert_utmi_reset

error_code_t hal_cpm_usb_phy_assert_utmi_reset(void);

功能说明：

清除 CPM USBRDT.UTMI_RST[27]，assert UTMI reset。

参数表：无。

返回值表：IM_OK。

2.4.2 hal_cpm_usb_phy_release_utmi_reset

error_code_t hal_cpm_usb_phy_release_utmi_reset(void);

功能说明：

置位 CPM USBRDT.UTMI_RST[27]，release UTMI reset。

参数表：无。

返回值表：IM_OK。

补充说明：UTMI_RST 为 0 时保持 reset，为 1 时释放 reset。调用方负责 assert/release 之间的 PHY 时序延时。

2.5 IDDIG 模式控制

2.5.1 hal_cpm_usb_phy_force_iddig

error_code_t hal_cpm_usb_phy_force_iddig(bool peripheral);

功能说明：

使能 CPM IDDIG override 并设置 IDDIG 电平。

参数表：

参数	类型	方向	说明
peripheral	bool	输入	true 为 mini-B/peripheral；false 为 mini-A/host。

返回值表：IM_OK。

peripheral	IDDIG_EN[1]	IDDIG_REG[0]
true	1	1
false	1	0

2.5.2 hal_cpm_usb_phy_release_iddig

error_code_t hal_cpm_usb_phy_release_iddig(void);

功能说明：

清除 CPM USBRDT.IDDIG_EN[1]，释放 software override，使用 PHY UTMI IDDIG。

参数表：无。

返回值表：IM_OK。

2.6 CPM 寄存器调试输出

2.6.1 hal_cpm_usb_phy_regs_dump

error_code_t hal_cpm_usb_phy_regs_dump(void);

功能说明：

打印 USB PHY 控制相关的四个 CPM 寄存器。

参数表：无。

返回值表：

返回值	说明
IM_OK	已输出寄存器。
IM_ERR_UNSUPPORTED	Debug helper 未同时开启。

输出内容：

地址	寄存器
0x024	OPCR
0x03C	USBPCR
0x040	USBRDT
0x048	USBPCR1