Supporting USB Gadgets in i.MX RT uClinux BSP Print

 

This application note explains how to configure the i.MX RT1170 as the composite USB Gadget providing the USB Ethernet and the Mass storage functions over the USB OTG High-Speed link.

In practical embedded applications, the Ethernet Gadget can be used for organizing TCP/IP-based communications with the i.MX RT1170 over the USB physical link. The Mass Storage Gadget can to used to share data on physical or virtual storage of the IMXRT1170 board to a PC, for example provide access to its SD card.


Configuration and Build

To enable USB Gadgets functionality in the rootfs project, do the following:

  1. Activate the cross development environment:

    2. $ . ./ACTIVATE.sh
    $ cd projects/rootfs

  2. Select the appropriate USB Gadget in the Linux configuration menu (go to the Device Drivers -> USB support -> USB Gadget Support -> USB Gadget functions configurable through configfs menu, and select the RNDIS and Mass storage options):

    3. $ make kmenuconfig

  3. Build the project:

    4. $ make

  4. Run the resultant rootfs.uImage on the target.
  5. Configure the USB Gadgets in the Linux console on the target board:
  6. Mount the configfs File System:

    7. / # mount -t configfs configfs /sys/kernel/config/

  7. Create new composite USB gadget:

    8. / # mkdir /sys/kernel/config/usb_gadget/g1

  8. Add description for new device:

    9. / # cd /sys/kernel/config/usb_gadget/g1
    /sys/kernel/config/usb_gadget/g1 # echo 0x525 > idVendor
    /sys/kernel/config/usb_gadget/g1 # echo 0xa4a7 > idProduct
    /sys/kernel/config/usb_gadget/g1 # mkdir strings/0x409
    /sys/kernel/config/usb_gadget/g1 # echo 00001 > strings/0x409/serialnumber
    /sys/kernel/config/usb_gadget/g1 # echo user > strings/0x409/manufacturer
    /sys/kernel/config/usb_gadget/g1 # echo mygadget > strings/0x409/product

  9. Create configuration for the composite device:

    10. /sys/kernel/config/usb_gadget/g1 # mkdir configs/c.1
    /sys/kernel/config/usb_gadget/g1 # mkdir configs/c.1/strings/0x409
    /sys/kernel/config/usb_gadget/g1 # echo composite > configs/c.1/strings/0x409/configuration
    /sys/kernel/config/usb_gadget/g1 # echo 120 > configs/c.1/MaxPower

  10. Define the mass storage function:

    11. /sys/kernel/config/usb_gadget/g1 # mkdir functions/mass_storage.0
    Mass Storage Function, version: 2009/09/11
    LUN: removable file: (no medium)

  11. Provide whole SD card to mass storage:

    12. /sys/kernel/config/usb_gadget/g1 # echo /dev/mmcblk0 > functions/mass_storage.0/lun.0/file

  12. Define the Ethernet Gadget (RNDIS) function:

    13. /sys/kernel/config/usb_gadget/g1 # mkdir functions/rndis.usb0
    using random self ethernet address
    using random host ethernet address

  13. Link the Gadget functions to the composite device:

    14. /sys/kernel/config/usb_gadget/g1 # ln -s functions/mass_storage.0/ configs/c.1/
    /sys/kernel/config/usb_gadget/g1 # ln -s functions/rndis.usb0 configs/c.1

  14. Enable the USB Gadget on either USB1 (ci_hdrc.0) or USB2 (ci_hdrc.1) port:

    15. /sys/kernel/config/usb_gadget/g1 # echo ci_hdrc.1 > UDC


Connect to the Linux Host

The host PC will detect the i.MX RT1170 as 2 devices: RNDIS Ethernet and USB Mass Storage:

$ dmesg | tail
[81641.785983] usb 3-3.1.2: new high-speed USB device number 20 using xhci_hcd
[81641.888722] usb 3-3.1.2: New USB device found, idVendor=0525, idProduct=a4a7, bcdDevice= 5.15
[81641.888729] usb 3-3.1.2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[81641.888731] usb 3-3.1.2: Product: mygadget
[81641.888732] usb 3-3.1.2: Manufacturer: user
[81641.888734] usb 3-3.1.2: SerialNumber: 00001
[81641.945525] usb-storage 3-3.1.2:1.0: USB Mass Storage device detected
[81641.945761] scsi host10: usb-storage 3-3.1.2:1.0
[81641.949113] rndis_host 3-3.1.2:1.1 usb0: register 'rndis_host' at usb-0000:2f:00.3-3.1.2, RNDIS device, fe:bc:a0:60:1b:d5
[81641.954094] rndis_host 3-3.1.2:1.1 enxfebca0601bd5: renamed from usb0
[81642.958387] scsi 10:0:0:0: Direct-Access Linux File-Stor Gadget 0515 PQ: 0 ANSI: 2
[81642.958655] sd 10:0:0:0: Attached scsi generic sg9 type 0
[81642.958903] sd 10:0:0:0: Power-on or device reset occurred
[81642.959298] sd 10:0:0:0: [sdi] 62521344 512-byte logical blocks: (32.0 GB/29.8 GiB)
[81642.959546] sd 10:0:0:0: [sdi] Write Protect is off
[81642.959549] sd 10:0:0:0: [sdi] Mode Sense: 0f 00 00 00
[81642.959807] sd 10:0:0:0: [sdi] Write cache: enabled, read cache: enabled, doesn't support DPO or FUA
[81642.961618] sdi: sdi1
[81642.961847] sd 10:0:0:0: [sdi] Attached SCSI removable disk


Using the Ethernet Function of the Composite USB Gadget

  1. Setup an IP address of the USB Ethernet interface on the USB Device (i.MX RT1170) side. Select an address that will not conflict with the other network sub nets in the system (if present):

    2. / # ifconfig usb0 192.168.2.2

  2. Setup an IP address of the USB Ethernet interface on the USB host (PC) side (obviously, select the address from the same sub-net as the Gadget):

    Linux host example:

    $ sudo ifconfig enxfebca0601bd5 192.168.2.1

  3. Check communication between i.MX RT1170 and the host over USB with ping:
    • on i.MX RT1170:

      • / # ping 192.168.2.1 -c 3
      PING 192.168.2.1 (192.168.2.1): 56 data bytes
      64 bytes from 192.168.2.1: seq=0 ttl=64 time=0.798 ms
      64 bytes from 192.168.2.1: seq=1 ttl=64 time=0.428 ms
      64 bytes from 192.168.2.1: seq=2 ttl=64 time=0.389 ms

      --- 192.168.2.1 ping statistics ---
      3 packets transmitted, 3 packets received, 0% packet loss
      round-trip min/avg/max = 0.389/0.538/0.798 ms
      / #

    • on PC:

      • $ ping 192.168.2.2 -c 3
      PING 192.168.2.2 (192.168.2.2) 56(84) bytes of data.
      64 bytes from 192.168.2.2: icmp_seq=1 ttl=64 time=0.339 ms
      64 bytes from 192.168.2.2: icmp_seq=2 ttl=64 time=0.280 ms
      64 bytes from 192.168.2.2: icmp_seq=3 ttl=64 time=0.292 ms

      --- 192.168.2.2 ping statistics ---
      3 packets transmitted, 3 received, 0% packet loss, time 2030ms
      rtt min/avg/max/mdev = 0.280/0.303/0.339/0.025 ms


Using the Mass Storage Function of the Composite USB Gadget

  1. On the Linux host check the Mass Storage Gadget is automatically mounted:

    2. $ mount | grep "/dev/sd"
    dev/sdb1 on /media/sasha/987E-02F8 type vfat (rw,nosuid,nodev,relatime,uid=1001,gid=1001,fmask=0022,dmask=0022,
    codepage=437,iocharset=iso8859-1,shortname=mixed,showexec,utf8,flush,
    errors=remount-ro,uhelper=udisks2)

  2. Verify that the mounted media contains the boot image:

    3. $ ls /media/sasha/987E-02F8
    rootfs.uImage 'System Volume Information'


Configuration USB Multifunction Composite Gadget via a Script

For convenience the usb_gadget.sh script is included into the rootfs project.

To configure USB Gadget as a mass storage device the following command can be used on the target board:

/ # usb_gadget.sh -m -p 0
Mass Storage Function, version: 2009/09/11
LUN: removable file: (no medium)
USB Gadet config done
/ #

To configure USB Gadget as a network device the following command can be used on the target board:

/ # usb_gadget.sh -r -p 0
using random self ethernet address
using random host ethernet address
usb0: HOST MAC 5a:32:a9:e7:72:85
usb0: MAC 22:ff:72:5f:e5:64
USB Gadet config done
/ #

To configure USB Gadget as a mass storage and a network devices the following command can be used on the target board:

/ # usb_gadget.sh -m -r -p 0
Mass Storage Function, version: 2009/09/11
LUN: removable file: (no medium)
using random self ethernet address
using random host ethernet address
usb0: HOST MAC 06:b2:3f:33:72:e8
usb0: MAC a6:b2:16:ae:fa:e1
USB Gadet config done
/ #

To deactivate configured USB composite gadget the following command can be used on the target board:

/ # usb_gadget.sh -d
USB gadgets deactivated
/ #

Note: For configuring USB port 2 as USB gadget use the <-p 1> option.