io-usb-otg

Updated: October 26, 2022

USB On-The-Go (OTG) server

Syntax:

io-usb-otg [-CcIVv] [-d dll [opts]]* [-E priority] [-e priority] 
           [-n name] [-O string] [-o dll [opts]]* [-P priority]
           [-r num] [-T num] [-t memory=name] [-U priority]

Runs on:

QNX Neutrino

Options:

-C
Don't configure a device, even if it has only one configuration.
-c
Don't select a device configuration if the device has more than one configuration. See Device configuration below.
-d dll [opts]
Load this DLL, pass it the specified options, and start it. You can specify multiple -d options.
-E priority
Set the priority of the transaction-timeout thread for the host bus; the default is 10.
-e priority
Set the priority of the enumeration thread; the default is 10.
-I
Run without I/O privilege.
Note:

The -I option isn't supported on x86 and x86_64 platforms.

-n name
Set the server name; the default is /dev/usb/io-usb-otg.
-O string
(“Oh”; QNX Neutrino 7.1 or later) Once running, run as the specified user, so that the program doesn't need to run as root. The string can be in one of these forms:
  • uid[:gid[,sup_gid]*]
  • user_name[,sup_gid]*

In the second form, the primary group is the one specified for user_name in /etc/passwd.

-o dll [opts]
Load this DLL and pass it the specified options, but don't start the DLL. You can specify multiple -o options.
-P priority
Set the priority of the server; the default is 21.
-r num
Set the number of enumeration retries; the default is 3.
-s smmu=[0 | 1 | off | on]
Use the QNX System Memory Management Unit Manager (SMMUMAN).

If the smmuman service is running, you can specify 1 or on to configure io-usb-otg to interface with smmuman to manage ("cage") access for non-CPU initiated reads and writes (i.e., DMA devices). If you specify 1 or on but smmuman isn't running, the io-usb-otg server fails to start.

The default setting is 0 or off. An invalid setting is treated as off.

-t memory=name
Set the typed-memory name. This option tells the server to allocate memory from the specified typed-memory region, such as the memory used for usbd_alloc(), and from other internal memory that's needed to transfer data from the USB chip. The default is /memory/below4G.
-T num
Set the default control transfer timeout, in milliseconds; the default is 2000.
-U priority
Set the priority of the usbmgr thread; the default is 10.
-V
Display the server version, then exit.
-v
Be verbose.

Description:

The io-usb-otg server manages the USB bus and USB protocols through hardware controller drivers (which are DLLs). The -d and -o options let you load the DLLs when you start io-usb-otg; to load more than one DLL, use multiple -d or -o options.

The server provides USB On-The-Go (OTG) service because it supports both USB host mode and USB device mode. The name of the hardware controller driver passed to a -d or -o option determines whether it's a host-mode DLL (devu-hcd-*) or device-mode DLL (devu-dcd-*).

The -o option is useful for a dual-mode system, because it lets you load pairs of DLLs that perform operations that must be mutually exclusive. Typically, you use -o in conjunction with an external process such as the USB launcher service (usblauncher_otg), which can automatically start and stop the appropriate DLLs when the server switches between modes. See the USB launcher chapter in the Device Publishers Developer's Guide for more information about this service.

Note: If you're using the USB launcher service to support mode-switching, the device-mode DLLs should appear on the io-usb-otg command line before the host-mode DLLs.

Note that mounting and unmounting DLLs isn't supported in this release. For information on host-mode DLLs and their syntax, see the devu-hcd-* entries. For information on device-mode DLLs and their syntax, see the devu-dcd-* information in your BSP documentation.

The io-usb-otg server handles all data transfers to and from devices connected to the USB bus. Drivers that are clients to the server are responsible for implementing class- or function-specific protocols (for instance, devb-ustor implements mass storage, and devnp-usbdnet.so implements a USB device network driver). To communicate with connected devices, class drivers use the host client library to talk to the server, which then talks to the device over the bus. Function drivers use the device client library to talk to the server.

The USB subsystem can detect incompatible (i.e., mismatched) binary versions between the:
  • Class driver and host client library
  • Function driver and device client library
  • Host or device client library and io-usb-otg server

When a binary mismatch is detected, a warning is logged to slogger2.

The server uses the loaded hardware controller (devu-*) drivers to do data transfers with USB hardware. If a driver is found to be incompatible with the server, the driver isn't started, a warning is logged to slogger2, and the hardware remains inaccessible.

Device configuration

You should use the -c option in conjunction with a launcher application such as usblauncher_otg, which chooses a device's configuration before launching the driver to manage a device's interfaces.

A launcher application must choose a default configuration for any device with more than one configuration, or the device won't function:

Note: Some devices might not be able to switch the configuration once an initial configuration is selected.

Examples:

Start the server and USB drivers on a PCI-based system:

io-usb-otg -dehci -dohci -duhci -dxhci

Start the server and the EHCI (high speed) USB driver:

io-usb-otg -dehci ioport=0x02184000, irq=75