IoTGateway/BSP/Android/Gettingstarted/How to use USB DISK

USB DISK

The USB (Universal Serial Bus) standard specifies two roles USB host and USB peripheral (also known as USB function, USB peripheral device or sometimes just USB device). The bus can only have one USB host connected all other devices need to be in USB peripheral mode. Most PCs support USB host mode exclusively. However, embedded systems often have multiple USB controller supporting host or peripheral roles or supporting both roles on a single controller (dual-role controller). The dual-role controllers often also support the OTG (On-The-Go) specification which defines a host negotiation protocol allowing two devices to negotiate for the role of the host.

On Colibri modules the client port (USBC) is usually connected to a dual-role capable controller. By default the port is in peripheral mode. If a USB Micro-B OTG cable is used (which connects the ID pin to ground) the circuit on the carrier board automatically enables driving +5V onto VBUS in order to provide power to USB devices as required by a host. On the other hand VBUS is also connected to the Colibri USBC_DET signal (usually via a diode) allowing driver software to monitor and subsequently change the role. On Apalis modules a full OTG port (USBO1) is provided which makes use of the OTG ID pin using the USBO1_ID signal to determine its role and additionally the VBUS pin using the USBO1_VBUS signal to determine the actual connection status thereof allowing suspending the USB complex if not connected.

On Linux USB peripheral mode is supported through the Gadget API. This API abstracts the USB peripheral controller hardware as well as offers hardware neutral routines which allow to implement USB functions (e.g. USB CDC ACM or RNDIS). Traditionally the USB function had to be chosen at Kernel compile time (e.g. g_ether). The Linux USB gadget drivers received increasingly more attention and have evolved over time, especially since Android appeared. The Android variant of the Linux kernel added functionality allowing easy switching between USB functions using sysfs. Later in Linux 3.10 a similar functionality also landed in the upstream kernel which now allows configuring USB gadgets through configfs (the USB Gadget ConfigFS). Depending on the Linux kernel version provided by our BSP a different level of USB peripheral functionality and API is available.

USB peripheral devices need a vendor and product identification. Toradex has its own vendor ID (0x1b67) and assigns a product ID for each Colibri and Apalis product which you as a customer can use too. The USB Product ID is the sum of an offset of 0x4000 and the hexadecimal representation of the product identifier, e.g. 0x4000 + 14 = 0x400e (the product identifier is the first 4 digits of the Toradex Product Number, e.g. 0014 for Colibri VF61 256MB IT).

Some platforms need device dependent and certified drivers (e.g. CDC ACM for Microsoft Windows) even for standard USB classes. While it is possible to use the driver delivered with Windows a custom inf file still needs to be provided. For better out-of-the-box experience the standard images typically use the default Linux USB product/vendor ID (e.g. 1d6b:0104 Linux Foundation Multifunction Composite Gadget)

Kernel USB Gadget Configfs Interface

The i.MX6 BSP (since V2.5 Beta 2) use the USB Gadget ConfigFS to configure the USB peripheral port.

The USB Gadget ConfigFS is a file system which allows to configure USB functions by using file system commands such as mkdir and creating/writing files. Typically the file system is mounted under /sys/kernel/config/. The official Linux kernel documentation has more information in Documentation/usb/gadget_configfs.txt on how to use the file system to enable USB functions. Matt Porter held a talk at ELC 2014 titled Kernel USB Gadget Configfs Interface cover the Gadget ConfigFS a bit more in depth.

The library libusbg allows to use the USB Gadget ConfigFS through a C API. This can be useful if embedded software needs to dynamically control USB functions provided by a device. The library also provides two utilities called gadget-import and gadget-export. This utilities allow to export a hand-crafted USB Gadget to a schema file and reimport it. The BSP provides a default schema specifying two configurations (USB functions), RNDIS and CDC ACM, under /etc/usbg/g1.schema. A systemd service called usbg.service uses gadget-import to import this schema on startup (see libusbg: add updated version of USB gadget library).

The Gadget testing documentation located at Documentation/usb/gadget-testing.txt of the Linux kernel also contains some valuable information how to use the USB Gadget functions.

To enable this configuration write the name of the USB controller to the UDC file (see /sys/class/udc/ for available USB Device Controllers). You need to disable the old configuration first before enabling the new one:

cd /sys/kernel/config/usb_gadget/
echo "" > g1/UDC
echo "ci_hdrc.0" > g2/UDC

Don't forget to store the configuration using gadget-export:

gadget-export g2 /etc/usbg/g2.schema

To make sure the g2 Gadget configuration gets loaded automatically, alter the systemd service located at /lib/systemd/system/usbg.service or name the schema g1.schema.

USB Disk Status

Log

root@dmssr09:~#
[ 1012.178981] android_work: sent uevent USB_STATE=DISCONNECTED
[ 1012.239487] android_work: sent uevent USB_STATE=CONNECTED
[ 1012.251323] android_work: sent uevent USB_STATE=DISCONNECTED
[ 1012.321347] android_work: sent uevent USB_STATE=CONNECTED
[ 1012.343418] android_usb gadget: high speed config #1: android
[ 1012.352025] android_work: sent uevent USB_STATE=CONFIGURED

U-Disk Path

~/storage/udisk

U-Disk mounted status