## X5 USB 使用手册

### 介绍
- x5 usb 有两个控制器
- 都支持 drd 主从双角色模式
- 其中一个接了 usb2.0 phy, 一个接了 usb3.0 phy
- 故一个控制器只支持 usb2.0, 另一个支持 usb3.0

### 主从切换
- 如何进行主从模式切换 ?
    1. 如果支持 otg 的接口 , 插入 otg 线 , 通过 usb id 管脚状态 , Linux 系统会切换 usb 模式到主机模式。

    2. 其余可以通过设备树 dr_mode 进行静态配置。
    ```bash
    dr_mode = "otg"; // peripheral/host/otg
    ```

    3. 可以通过文件节点进行主从控制
    ```bash
    # usb3.0 口切换到从模式
    echo device > /sys/class/usb_role/35100000.usb-role-switch/role

    # usb3.0 口切换到主机模式
    echo host > /sys/class/usb_role/35100000.usb-role-switch/role

    # usb2.0 口切换到从模式
    echo device > /sys/class/usb_role/35300000.usb-role-switch/role

    # usb2.0 口切换到主机模式
    echo host > /sys/class/usb_role/35300000.usb-role-switch/role
    ```

### 主机模式
- 默认支持 U 盘 , 鼠标 , 键盘 , uvc, 以及常见 usb 转串口 , usb 转网口等外设。
- 如果有其他设备支持需求 , 可自行打开对应 config 配置和移植相关设备驱动。


### 设备模式
- 请参考上文主从切换 , 确保 usb 控制器工作在设备模式。
- 通常和开发板接口形态有关。可参考对应硬件设计。
- 提供了 usb-gadget.sh 和 usb3.0-gadget.sh 脚本作为 usb 装置启动的参考脚本。
- 可利用该脚本启动常见如 adb, rndis 等形态设备。
- 如客户有定制的设备形态 , 可参考或自行开发。

#### 常见形态装置命令
- adb 设备
    ```bash
    # 启动 usb2.0 port adb 装置 , 其实默认启动就是 usb2.0 port adb 形态。
    /etc/init.d/usb-gadget.sh stop
    /etc/init.d/usb-gadget.sh start adb

    # 关闭 usb2.0 设备 , 启动 usb3.0 adb 装置
    /etc/init.d/usb-gadget.sh stop
    /etc/init.d/usb3.0-gadget.sh stop
    /etc/init.d/usb3.0-gadget.sh start adb

    ```
- rndis 虚拟网卡 # win10 建议用 rndis 虚拟网卡
    ```bash
    # 开启 usb2.0 port rndis 虚拟网口设备
    /etc/init.d/usb-gadget.sh stop
    /etc/init.d/usb-gadget.sh start rndis

    # 启动 usb3.0 port rndis 虚拟网卡装置
    /etc/init.d/usb3.0-gadget.sh stop
    /etc/init.d/usb3.0-gadget.sh start rndis
    ```

- ecm 虚拟网卡 # ubuntu/linux 系统建议用 ecm 等虚拟网卡
    ```bash
    # 开启 usb2.0 port ecm 虚拟网口设备
    /etc/init.d/usb-gadget.sh stop
    /etc/init.d/usb-gadget.sh start ecm

    # 启动 usb3.0 port ecm 虚拟网卡装置
    /etc/init.d/usb3.0-gadget.sh stop
    /etc/init.d/usb3.0-gadget.sh start ecm
    ```

- 备注 :
1. 目前 usb2.0 和 usb3.0 port 口分别 / 同时起装置的一些限制
    目前有些设备 , 例如 adb, 有用户态的 adbd deamon 程序 , 故暂不支持同时起两路 adb 通路。
    需要关闭一路设备后 , 再启动另一路设备。
    其余不冲突的 , 例如两路 rndis, 或者一路 adb + 一路 rndis, 理论上是可以同时启动的。
    以实际使用情况为准。

2. 关于 rndis, ecm, ncm 等各类 usb 虚拟网卡协议
    windows 主机建议使用 rndis 虚拟网卡设备 , 其他如 ecm 等 win10 驱动还没做 , 得去网上搜索并制作合适的驱动
    ubuntu 或类 linux 主机可使用 ecm 等虚拟网卡装置


### USB 一致性测试

USB 一致性测试是为了确保 USB 设备在设计、制造和功能上严格遵循USB标准协议（由 USB-IF 协会制定），从而保障设备间的兼容性和稳定性。该测试主要围绕物理层（信号质量、电气特性）和协议层（数据传输规范）展开，是设备获得USB认证标志（如SuperSpeed USB）的必要条件。

#### USB 2.0

##### 硬件连接

![USB2_test_hardware_connect.jpg](./_static/_images/43-USB_Usage_Guide/USB2_test_hardware_connect.jpg)


##### 软件配置

**原理说明**

X5 USB 2.0 Host 通过配置 portpmsc 寄存器进入 Test Packet Mode。

**操作示例**

X5 USB 2.0 通过拉低 USB ID 管脚，即`AON_USB2_ID` 管脚来进入 Host 模式。可以通过接入 USB OTG 线实现。USB OTG 线定义如下:

![USB_OTG.png](./_static/_images/43-USB_Usage_Guide/USB_OTG.png)


配置 Test Packet Mode

```
# usbcmd bit[1] reset assert
devmem 0x35300020 32 0x7

# 等待 1 秒
sleep 1

# usbcmd bit[1] reset de-assert
devmem 0x35300020 32 0x5

# usb2.0 portpmsc disable test mode
devmem 0x35300024 32 0x0

# usb2.0 portpmsc enable test packet mode
devmem 0x35300024 32 0x40000000

```

**验证端口状态**

```
cat /sys/kernel/debug/usb/xhci/xhci-hcd.4.auto/ports/port01/portsc
Powered Connected Enable Link:Test mode PortSpeed:3 Change: CSC Wake:
```
通过打印信息得到: USB2.0 Host 进入 Test Packet Mode




#### USB 3.0

##### 硬件连接

![USB3_test_hardware_connect.jpg](./_static/_images/43-USB_Usage_Guide/USB3_test_hardware_connect.jpg)

##### 软件配置

**原理说明**

USB3.0 Host 通过配置 portpmsc 寄存器进入 Compliance 模式


**操作示例**

USB3.0 启动后自动工作在 Host 模式


配置 Compliance 模式

```
# usbcmd bit[1] reset assert
devmem 0x35100020 32 0x7

# 等待 1 秒
sleep 1

# usbcmd bit[1] reset de-assert
devmem 0x35100020 32 0x5

# portpmsc set to compliance mode
devmem 0x3510c2c0 32 0x140

# pipectrl host reset
devmem 0x3510c2c0 32 0x410c0102

```

**验证端口状态**

```
cat /sys/kernel/debug/usb/xhci/xhci-hcd.3.auto/ports/port02/portsc
Powered-off Not-connected Disabled Link:Compliance mode PortSpeed:0 Change: Wake:
```
通过打印信息得到: USB3.0 Host 进入 Test Compliance Mode


#### USB 眼图测试

USB 眼图测试结果如下

![USB_compliance_test.jpg](./_static/_images/43-USB_Usage_Guide/USB_compliance_test.jpg)

