USB host/device使用说明¶

REVISION HISTORY¶

Revision No.	Description	Date
1.0	Initial release	07/07/2023
1.1	Updated kernel/uboot config select	08/07/2024
1.2	文档架构优化与新增	11/20/2025

1. 概述¶

USB（通用串行总线，Universal Serial Bus）是一种广泛使用的接口标准，主要用于连接计算机与外部设备，实现数据传输和设备供电。

IFORD USB规格是包含USB2.0 Host + Device，USB 2.0 Host和Device各一个，Host和device共用一个UTMI，故Host和Device只能存在一个。不支持USB3.0。

2. 关键词说明¶

Device

通过USB接口连接至计算机或其他设备以实现数据传输、供电或扩展功能的外部硬件，如U盘、键盘、移动硬盘等。
Host

USB Host是控制USB总线并管理连接设备的主控端（如电脑、手机），负责供电、数据传输协调及驱动加载，使外部设备（如U盘、鼠标）得以正常工作。
EHCI

Enhanced Host Controller Interface, 增强型主机控制器接口规范定义了一个通用串行总线（USB）2.0主机控制器的寄存器级接口。
UTMI

USB2.0 Transceiver Macrocell Interface，此协议是针对USB2.0的信号特点进行定义的，分为8位或16位数据接口。

3. 功能描述¶

USB HOST可以支持键盘、鼠标、U盘、USB网卡、USB摄像头、USB耳机等多种设备接入，也支持usb hub接入扩展usb接口数量
USB device可以配置成USB摄像头、USB音频采集播放、RNDIS等设备

3.1. IFORD¶

支持1个USB2.0 port
每个USB2.0 port都支持host mode和device mode
USB2.0 Device EP资源

EP0 EP1 EP2 EP3 EP4 EP5 EP6

64 8192 1024 64 512 512 64

4. Uboot用法介绍¶

4.1 USB2.0 Host Driver使用¶

4.1.1 USB 2.0 Host menuconfig配置¶

    -> Device Drivers
        -> [*] USB support --->
            -> [*] Enable driver model for USB Gadget
            -> [*] EHCI HCD (USB 2.0) support

    -> [*] SigmaStar drivers  --->
        -> -*-   SigmaStar USB2.0 Host Controller
        -> [*] Sgs USB Reset Control

4.2. USB2.0 Device Driver使用¶

4.2.1. USB 2.0 Device menuconfig配置¶

    -> Device Drivers
        -> [*] USB support --->
            -> [*] Enable driver model for USB Gadget
            -> [*] USB Gadget Support --->

    -> [*] SigmaStar drivers  --->
        -> [*] SigmaStar USB 2.0 Device Controller
        -> [*] Sgs USB Reset Control

4.3. ufu使用¶

Uboot CONFIG要开启CMD_SSTAR_UFU, 如果需要编译空片升级的uboot,还需要额外开启CONFIG_SSTAR_AUTOBOOT_RUN_UFU_ALWAYS

使用方法：Uboot下输入ufu, 就会进入ufu升级模式，等待PC工具启动升级

4.4. usbstar使用¶

Uboot CONFIG要开启CONFIG_CMD_SSTAR_USBSTAR

使用方法：project下执行./image/makefiletools/script/make_usb_upgrade_sigmastar.sh，将生成的image bin放入Fat32格式的U盘，将U盘插入USB Host口，Uboot下输入usbstar，就可以开始升级

5. Kernel用法介绍¶

5.1 USB2.0 Host Driver使用¶

5.1.1 USB 2.0 Host menuconfig配置¶

-> Device Drivers

    -> [M] USB support --->

        -> <M> EHCI HCD (USB 2.0) support

            -> [*] Root Hub Transaction Translators

            -> [*] Improved Transaction Translator scheduling

选择上述选项，编译出USB 2.0 Host driver：usb-common.ko usbcore.ko ehci-hcd.ko

-> Device Drivers

    -> [*] SStar SoC platform drivers --->

         -> <*>   SStar USB2 PHY Driver

选择上述选项，编译出：sstar-usb2-phy.ko。

按如下顺序加载ko:

    #USB2.0 host normal ko
    usb-common.ko
    usbcore.ko
    sstar-usb2-phy.ko
    ehci-hcd.ko

5.1.2 DTS节点配置¶

usb2phy1_utmi: utmi@0x1f284200 {
    compatible="syscon";
    reg = <0x1f284200 0x200>;
    reg-io-width = <2>;
};

usb2phy1_bc: bc@0x1f284400 {
    compatible="syscon";
    reg = <0x1f284400 0x200>;
    reg-io-width = <2>;
};

usb2phy1_usbc: usbc@0x1f284600 {
    compatible="syscon";
    reg = <0x1f284600 0x200>;
    reg-io-width = <2>;
};

usb2phy1_uhc: uhc@0x1f284800 {
    compatible="syscon";
    reg = <0x1f284800 0x200>;
    reg-io-width = <2>;
};

sstar_u2phy: sstar-usb2-phy {
    compatible = "sstar,u2phy";
    #address-cells = <1>;
    #size-cells = <1>;
    ranges;
    status = "ok";

    sstar_u2phy1: u2phy1 {
        syscon-utmi = <&usb2phy1_utmi>;
        syscon-uhc = <&usb2phy1_uhc>;
        syscon-usbc = <&usb2phy1_usbc>;
        syscon-bc = <&usb2phy1_bc>;
        //utmi_dp_dm_swap = <0>;
        #phy-cells = <0>;
        status = "ok";
    };
};
sstar-ehci-1 {
    compatible = "sstar-ehci-1";
    reg-names = "ehc_base";
    reg = <0x1f284800 0x200>;
    syscon-utmi = <&usb2phy1_utmi>;
    syscon-usbc = <&usb2phy1_usbc>;
    syscon-bc = <&usb2phy1_bc>;
    //clocks = <&CLK_upll_480m>;
    interrupts = <GIC_SPI INT_IRQ_UHC IRQ_TYPE_LEVEL_HIGH>;
    phys = <&sstar_u2phy1>;
    phy-names = "usb";
    support_high_2g_access_patch;
    //power-enable-pad = <PAD_GPIO8>;
    status = "ok";
};

5.1.3 DTS参数说明¶

5.1.3.1 EHCI dts参数说明¶

属性值	描述	备注
compatible	用于匹配驱动进行驱动的注册	禁止修改
syscon-utmi	用于指定utmi bank的syscon节点，便于使用regmap访问寄存器	不需要改
syscon-uhc	用于指定ehci bank的syscon节点，便于使用regmap访问寄存器，与reg属性相同	不需要改
syscon-usbc	用于指定usbc bank的syncon节点，便于使用regmap访问寄存器	不需要改
syscon-bc	用于指定bc bank的syncon节点，便于使用regmap访问寄存器	不需要改
interrupts	用于指定ehci的中断及触发方式	禁止修改
phys	用于指定ehci所使用的phy列表	不需要改
phy-names	用于指定phys属性所支持phy列表的名称，与phy列表对应	不需要改
clocks	用于开启ehci时钟	禁止修改
status	选择是否使能驱动	根据需要修改

5.1.3.2 phy dts参数说明¶

属性值	描述	备注
compatible	用于匹配驱动进行驱动的注册	禁止修改
#address-cells	用于指定子节点reg属性地址信息所占用的字长（32bit）	禁止修改
#size-cells	用于指定子节点reg属性地址范围信息所占的字长（32bit）	禁止修改
ranges	用于表示子节点继承#address-cells和#size-cells属性	不需要改
status	选择是否使能驱动	根据需要修改

5.1.3.3 phy子节点dts参数说明¶

属性值	描述	备注
syscon-utmi	用于指定utmi bank的syscon节点，便于使用regmap访问寄存器	不需要改
syscon-uhc	用于指定ehci bank的syscon节点，便于使用regmap访问寄存器，与reg属性相同	不需要改
syscon-usbc	用于指定usbc bank的syncon节点，便于使用regmap访问寄存器	不需要改
syscon-bc	用于指定bc bank的syncon节点，便于使用regmap访问寄存器	不需要改
syscon-utmi2	用于指定utmi2 bank的syncon节点，便于使用regmap访问寄存器	不需要改
status	选择是否使能驱动	根据需要修改

5.2 USB2.0 Device Driver使用¶

5.2.1 USB 2.0 Device menuconfig配置¶

-> Device Drivers

    ->[*] USB support --->

        -><*> USB Gadget Support --->

            -> USB Peripheral Controller --->

                -> <M> Sstar USB 2.0 Device Controller

选择上述选项，编译出USB 2.0 Device driver：usb-common.ko usbcore.ko udc-core.ko udc-msb250x.ko

使用configfs脚本开启gadget配置, 红色箭头指向为配置具体的device function(生成libcomposite.ko, 以及具体function的ko(usb_f_xxx.ko))

    [*]USB support  --->
        [M]USB Gadget Support  --->
            [M]USB functions configurable through configfs

也可通过leagacy方式加载对应的g_xxx.ko来配置gadget:

    [*]USB support  --->
        [M]USB Gadget Support  --->
               USB Gadget precomposed configurations

5.2.2 DTS节点配置¶

msb250x-udc-p0 {
    compatible = "sstar,msb250x-udc";
    reg = <0x1f284200 0x200>, <0x1f284600 0x200>, <0x1f284a00 0x400>, <0x1f203c00 0x200>;
    reg-names = "utmi", "usb0", "otg", "chiptop";
    interrupts = <GIC_SPI INT_IRQ_OTG IRQ_TYPE_LEVEL_HIGH>;
    interrupt-names = "msb250x_udc_p0";
    maximum-speed = "high-speed";
    ep_name = "ep0", "ep1" , "ep2", "ep3", "ep4", "ep5", "ep6";
    ep_maxpkt_limit = <64>, <1024>, <1024>, <64>, <512>, <512>, <64>;
    ep_fifo_size =  <64>, <8192>, <1024>, <64>, <512>, <512>, <64>;
    dma_channel_num = <7>;
    status = "okay";
};

5.2.3 DTS参数说明¶

属性值	描述	备注
compatible	用于匹配驱动进行驱动的注册	禁止修改
reg	用于指定ehci所占用4个bank寄存器地址范围	不需要改
reg-names	用于指定上个选项reg中的name	不需要改
interrupts	用于指定msb250x udc的中断及触发方式	禁止修改
interrupt-names	用于指定msb250x udc的中断名字	禁止修改
maximum-speed	USB 2.0未使用	不需要改
ep_name	USB 2.0 EP的名字，获取ep有几个	禁止修改
ep_maxpkt_limit	指定各个ep的支持的最大包长度	根据需要修改
ep_fifo_size	每个ep的HE FIFO支持的最大长度	不需要改
dma_channel_num	USB HW DMA有几路	禁止修改
status	选择是否使能usb device驱动	根据需要修改

5.2.4 USB 2.0 Device模块使用¶

按照下列顺序加载（如果有模块选择builtin，请忽略）：

insmod usb-common.ko
insmod udc-core.ko
insmod udc-msb250x.ko
libcomposite.ko
#device function ko
例如adb需要加载usb_f_fs.ko
#如果是leagacy配置方式，还需要加载g_xxx.ko

5.3. UVC host配置¶

首先参考章节: 5.1 USB2.0 Host Driver使用

5.3.1. kernel config配置¶

开启Multimedia配置(生成的ko:mc.ko、videodev.ko、videobuf2-common.ko、videobuf2-v4l2.ko、videobuf2-memops.ko、videobuf2-vmalloc.ko、videobuf2-dma-sg.ko、uvcvideo.ko)

    Device Drivers  --->
        [*]Multimedia support  --->
            Media drivers  --->
                [*]Media USB Adapters  --->
                    [M]USB Vide Class (UVC)
            Media device types  --->
                [*]Cameras and video grabbers
            Media core support  --->
                [*]Media Controller API

5.3.2. ko加载¶

    sstar-usb2-phy.ko         # for USB2.0 only
    ehci-hcd.ko             # for USB2.0 only

    #multimedia ko
    mc.ko
    videodev.ko
    videobuf2-common.ko
    videobuf2-v4l2.ko
    videobuf2-memops.ko
    videobuf2-vmalloc.ko
    videobuf2-dma-sg.ko
    uvcvideo.ko

ko加载成功之后，板子USB host口用USB线连接到uvc device设备，可以看到/dev/videoX节点

5.4. UVC device配置¶

首先参考章节 5.2 USB2.0 Device Driver使用

5.4.1. kernel config配置¶

开启UVC device function配置(生成ko:libcomposite.ko、usb_f_uvc.ko、g_sgs_gadget.ko)

    Device Drivers  --->
        [*]USB support  --->
            [M]USB Gadget Support  --->
                [M]USB functions configurable through configfs
                USB Gadget precomposed configurations  --->
                    [M]USB SigmaStar Gadget
                    [*]Include configuration with UVC (Video)

开启Multimedia配置(生成的ko:mc.ko、videodev.ko、videobuf2-common.ko、videobuf2-v4l2.ko、videobuf2-memops.ko、videobuf2-vmalloc.ko、videobuf2-dma-sg.ko、uvcvideo.ko)

    Device Drivers  --->
        [*]Multimedia support  --->
            Media drivers  --->
                [*]Media USB Adapters  --->
                    [M]USB Vide Class (UVC)
            Media device types  --->
                [*]Cameras and video grabbers
            Media core support  --->
                [*]Media Controller API

5.4.2. ko加载¶

按如下顺序加载ko:

    usb-common.ko
    udc-core.ko
    udc-msb250x.ko          # for USB2.0 UDC
    libcomposite.ko

    mc.ko
    videodev.ko
    videobuf2-common.ko
    videobuf2-v4l2.ko
    videobuf2-memops.ko
    videobuf2-vmalloc.ko
    videobuf2-dma-sg.ko
    uvcvideo.ko

    usb_f_uvc.ko
    g_sgs_gadget.ko

ko加载成功之后将生成/dev/video0节点，板子USB device口用USB线连接到PC端，运行UVC demo使用PotPlayer等播放器打开摄像头设备将出现UVC Camera设备.

6. USB 2.0 模拟参数调整¶

以下情况需要考虑调节驱动能力

1、眼图的模板测试不通过，或者不够漂亮，修改驱动能力以期更好的测试结果。

2、遇到部分USB2不连接，通信中断，或其他诸如概率性的USB2的相关问题，想用修改驱动能力的方式，试试看，测测看，此种情形，本质上应当回归到第一点。但迫于有些没有眼图测试能力的，只能进行黑盒测试

6.1. Tx swing trim（此参数OTP有trim过，修改时需要找HWRD确认）¶

位于UTMI bank offset 0x44[9:4] ，调整值范围：0~63。

1) 查看当前值: cat /sys/kernel/debug/usb/phy-soc\:sstar-usb2-phy.0/swing_trim

2) 设置: echo value > /sys/kernel/debug/usb/phy-soc\:sstar-usb2-phy.0/swing_trim

6.2. pre_emphasis¶

位于UTMI bank offset 0x43[9:8] ，调整值范围：0~3，值越大pre-emphasis越强。

1) 查看当前值: cat /sys/kernel/debug/usb/phy-soc\:sstar-usb2-phy.0/pre_emphasis

2) 设置: echo value > /sys/kernel/debug/usb/phy-soc\:sstar-usb2-phy.0/pre_emphasis

6.3. 眼图测试¶

1）开机进入kernel，执行下列命令之后可以接示波器查看眼图

2）眼图测试波形不符合要求时，可以调整上述5个参数，直到波形完美为止

测试highspeed眼图，执行：echo “hs” > /sys/kernel/debug/usb/phy-soc\:sstar-usb2-phy.0/eye_diagram_switch

测试fullspeed眼图，执行：echo “fs” > /sys/kernel/debug/usb/phy-soc\:sstar-usb2-phy.0/eye_diagram_switch

6.4. Tx swing和pre_emphasis参数含义¶

1、TX swing：如上图，指的是黄色Mark的的这部分，主要是针对眼高的调整（DM DP差分信号的Level的调整，与USB2驱动能力的提法最为贴近），如果测试结果眼高部分不合要求，可以给出对应的修改方式/方法（开的强度越高，对应的眼高张得越开）

2、De-emphasis Current：如上图，指蓝色Mark部分，主要针对波形上升/下降速度的修改（高速信号传输中的去加重设计），如有上升/下降波形压眼图的情形，可以尝试调整此部分（开的强度越高，对应的波形越陡）

7. Debug & FAQ¶

Q1：Kernel下USB Host接入Device无法识别

检查是否有将vbus拉高
检查DTS 节点的status是否为ok
检查kernel config是否配置

Q2：Kernel下high speed device识别成full speed

检查device上级是否有接full speed hub

Q3：Uboot下U盘升级失败

检查是否有将vbus拉高
检查DTS 节点的status是否为ok
检查U盘是否是Fat32格式

Q4：USB空片升级失败

检查是否处于空片升级状态，空片升级状态串口会打印Start USB Mode
检查打包的usb image是否和板子匹配