Command line for USB launcher (usblauncher_otg)

Start usblauncher_otg device enumerator and publisher

Synopsis

usblauncher_otg [-0] [-b] [-C] [-c config] [-d dll [opts]] [-E] [-e]  
                [-L] [-l] [-M mnt_rules] [-m pps_path] [-n name] [-P]
                [-p seconds] [-r] [-S stackno] [-s dll_path] [-t] 
                [-v[v]...]

Options

-0
(“zero”) Enable host events, including insertions and removals, on bus 0. Bus 0 refers to the first DLL listed in the io-usb-otg command line. This option allows usblauncher_otg to be used in systems where it manages a host-only port, such as when it is used in a virtual machine.
-b
Run usblauncher_otg in the foreground (not background). This option is handy for debugging because you can press CtrlC to terminate the publisher. By default, usblauncher_otg runs in the background.
-C
Always select a configuration when a device is attached. By default, usblauncher_otg selects a configuration only for devices with multiple configurations, based on the first driver that matches the device.
You should use this option alongside the io-usb-otg -C option, which tells the USB stack never to set the device configuration at enumeration time. Note that this stack option doesn't affect hubs—their configurations are always set by the stack.
We recommend using the -C option for usblauncher_otg and io-usb-otg when supporting MirrorLink devices, because it makes usblauncher_otg set the configuration after sending the NCM request.
-c config
Use the specified configuration file. At startup, usblauncher_otg reads this file to learn the USB matching rules, which specify how to process devices when they're attached.
If you don't specify a configuration file, usblauncher_otg looks for the default file, /etc/usblauncher/rules.lua. In this case, this file must exist or usblauncher_otg won't run.
The main configuration file named with this option can include other Lua files by using the dofile() command. For example, if you use separate files to define descriptors to use when running in USB device mode, you can include these descriptor files in the main file.
-d dll [opts]
Load this DLL and pass it the specified options.
-E
Publish USB hub information. This option requires the -e option. By default, usblauncher_otg doesn't report whether a device is connected directly to the target system or through a USB hub.

You must set -E to publish device objects for USB hubs as well as information about the upstream hub for other devices connected to a hub. You can use this information to decide whether to allow role-swapping of the USB stack, based on which type of hub and which hub port a device is connected to.

-e
Enable detection of extra events; specifically, bad device attachments and detachments as well as device resets. By default, usblauncher_otg doesn't detect and publish information about these extra events.
-L
Run in local mode, even when the Qnet networking protocol is running (see Local mode, below).
-l
Log messages to slog2info instead of to standard out (which is the default behavior). This option increases the verbosity level to -vvv, unless you use the -v option to set a different verbosity level.
-M mnt_rules
The mount-rules file, which tells usblauncher_otg where to mount the filesystems of devices represented by particular /dev entries. Any file named with this option must be in the same format as the default USB launcher mount rules found in /etc/usblauncher/rules.mnt. In this file, you can name not only mountpoints but also the mount options provided to the filesystem library, such as codepage mapping or long-filename handling in fs-dos.
Use this option if you want to assign nondefault mountpoints to devices. You can also name an empty file or /dev/null to prevent usblauncher_otg from auto-mounting USB devices.
-m pps_path
Use the specified PPS directory path. The subdirectories for storing the device, device control, driver, and mount objects are located in this directory. The default is /pps/qnx/.
-n name
The server name of the USB stack. The default is /dev/usb/io-usb-otg. Use this option only if the stack is stored in a nondefault location.
-P
Probe the media to get the partition count only if the device is ready. By default, usblauncher_otg doesn't wait until the device is ready to try to obtain the partition count.
-p seconds
The polling interval, in seconds, that determines how often usblauncher_otg checks for changes to the mountpoints associated with the active drivers. Default is 0. Note that polling can be CPU-intensive and result in a significant amount of logging.
-r
Treat a device suspension event as a cable removal event. Some devices don't generate removal events, so you can set this option to make usblauncher_otg terminate the USB device stack after receiving a suspension event following a configuration event.
-S stackno
Use the specified USB stack number. The usblauncher_otg service stores this value in the information for each USB device that it monitors, to differentiate the device from others that have the same bus number and device number but are managed by other instances of the io-usb-otg stack.
-s dll_path
Use the specified plugin path. At startup, usblauncher_otg looks in this path for plugins that it can load and use to provide more device details (for more information, see Plugins).
If this option isn't specified, no plugins are loaded.
-t
Terminate launched drivers when exiting. By default, usblauncher_otg doesn't terminate driver processes while deleting device and driver objects during shutdown.
-v[v]...
Override the output verbosity level. Setting one v logs USB device attachments and detachments. Setting two v's adds the logging of PPS object creation and deletion. Setting three or four v's logs more detailed events as well as errors that are less severe.
Increasing the output verbosity is handy when you're trying to understand the operation of usblauncher_otg. However, when lots of -v arguments are used, the logging becomes quite significant. A higher verbosity setting is good for systems under development but probably shouldn't be used in production systems or during performance testing.

Description

Note: You should start usblauncher_otg with an explicit command only if the process terminates unexpectedly. Before trying to start usblauncher_otg manually, always confirm that the service isn't already running by checking the list of active processes with pidin or ps.

The usblauncher_otg command starts a multipurpose service that responds to USB device attachments and detachments, launches drivers for communicating with the devices, and publishes their information through PPS. The service can also force a re-enumeration of a device, by resetting it or by requesting that it change its personality.

On the command line, you can name a nondefault configuration file to make usblauncher_otg use a custom set of rules for configuring various device types. You can also name your own mount-rules file to mount filesystems to nondefault locations, and configure how errors and events are logged.

To reconfigure usblauncher_otg, you must restart it with new command-line options. For a production environment, we highly recommend putting the usblauncher_otg command line in a startup script to automatically launch the service during bootup.

Local mode

The local mode option (-L) can help simplify configuration for standalone systems. You should use it only when Qnet is running (for instance, for debugging). When usblauncher_otg runs in local mode, it:
  • doesn't add the network prefix to paths it generates
  • expects all paths it receives to already have the network prefix

Examples

Use /etc/enum.lua as the configuration file and look for plugins in /lib/dll/pubs:

usblauncher_otg -c /etc/enum.lua -s /lib/dll/pubs

Store PPS objects in /ramdisk/pps, get the partition count only if the device is ready, and direct output to standard out:

usblauncher_otg -m /ramdisk/pps -P -vv

Abilities

The usblauncher_otg service may require the following abilities:

Use secpolmonitor to determine which abilities usblauncher_otg is using on your system.

For more information on abilities, see procmgr_ability() in the C Library Reference.