QNX Technical Articles

Date of this edition: December 10, 2007

Target OS: This patch is compatible with targets that are running QNX^® Neutrino^® 6.3.0 SP3 or 6.3.2.

Host OS: In order to apply this patch, you must have installed QNX Momentics 6.3.0 SP3 or 6.3.2 as a self-hosted QNX^® Neutrino^® system, or on one of the following host OSs:

---

For the most up-to-date version of these notes, go to our website (www.qnx.com), log into your myQNX account, and then go to the Download Center.

---

Contents

• What's in this patch?
• Fixed issues
• Known issues
• Using umass-enum
• Technical support

Throughout this document, you may see reference numbers associated with particular issues, changes, etc. When corresponding with our Technical Support staff about a given issue, please quote the relevant reference number. You might also find the reference numbers useful for tracking issues as they become fixed.

What's in this patch?

This patch updates umass-enum, the USB mass storage enumerator and filesystem-mounting utility, as well as to the <sys/umass-enum.h> system header.

Installed files

The following file is installed in $QNX_TARGET/:

• usr/include/sys/umass-enum.h

The following files are installed under $QNX_TARGET/ in the subdirectories for the supported targets:

• armle/sbin/umass-enum
• ppcbe/sbin/umass-enum
• shle/sbin/umass-enum
• x86/sbin/umass-enum

Fixed issues

• We've updated umass-enum to support the latest devices, and we've addressed some minor problems. (Ref# 47614, 43001)
• We previously shipped umass-enum for x86 systems only. This patch adds support for other targets. (Ref# 47614)
• This utility now ignores PlaysForSure devices that also identify themselves as USB Mass Storage devices. These devices are enumerated by another driver; if umass-enum were also to enumerate them, a race condition could arise, leading to instability. (Ref# 43001)

Known issues

• If the system is in a certain state (which we haven't yet clearly identified, but seems to occur rarely), unplugging a device may cause the driver to halt operations. (Ref# 43914)

  Workaround: If this happens, slay the USB stack (io-usb) and then umass-enum. Then start io-usb and umass-enum again (in this order).

• The umass-enum utility may insert error messages into the system log that are inconsistent with the actual behavior. If you remove a device, you'll see entries such as “Error unmounting filesystem /fs/hdumass10-dos-1”, but the operation actually succeeded. You can ignore these messages. (Ref# 52164)

Using umass-enum

umass_enum [-aAbkMrv] [-d location] [-f cfg]
           [-h hd[,cd] name] [-m hd[,cd] name]
           [-p priority] [-P priority] [-s stack]
           [-S perm] [-T period] [-w sec] &

Options:

-a

Don't automount partitions; just start the driver.

-A

Enable autorun, which by default, runs the mount_point/autorun script (or mount_point/autorun.exe for DOS partitions). For more information, see “Autorun,” below.

-b

Boost the priority of an unknown device to a known priority once it's successfully mounted.

-d location

The location of the device entry. The default is /dev/umass.

-f cfg

The path to an ASCII configuration file containing a list of devices to manage. The default is /etc/config/umass-enum.cfg. For more information, see “Configuration file format,” below.

-h hd[,cd] name

Specify raw device name disks. The default is hdumass,cdumass.

-k

Mount only the devices listed in the configuration file (known devices).

-m hd[,cd] name

Specify the mountpoint name. The default is /fs/hdumass, /fs/cdumass.

-M

Ignore devices advertising themselves as MTP.

-p priority

The priority to run the devb-umass driver at.

-P priority

The priority to run the devb-umass driver at for devices that aren't found in the configuration file.

-r

Enable the resource-manager notification thread; see “Resource manager interface,” below.

-s stack

The name of the stack to attach to. The default is /dev/io-usb/io-usb.

-S perm

The default access permissions for mountpoints. This can be a combination of the characters r, w, and x. The default is rwx.

-T period

The polling period for removable media, in milliseconds. The default is 1000 ms.

-v

Be verbose.

-w sec

Wait sec seconds for the USB stack (default 60 seconds).

Description:

The umass-enum utility manages USB mass-storage-compliant devices and filesystems.

---

Make sure the USB stack is running before you start umass-enum. For example: io-usb -dehci -duhci -dohci umass-enum &

---

The umass-enum utility reads, parses, and stores the contents of a configuration file (/etc/config/umass-enum.cfg by default), which may contain a list devices and options on how to start devb-umass and mount filesystems on the device. If you specify the -k option, then devb-umass is only started, and filesystems are mounted for devices listed in the configuration file.

---

The configuration file accepts wildcards for the vendor and device IDs, so you can apply arguments globally or for specific vendors.

---

When a mass storage device is plugged in and is an acceptable device (i.e. it's in the list or matches a wildcard) or you haven't specified -k, umass-enum launches devb-umass to manage the device. All valid/supported partitions are then mounted automatically as well, including all standard QNX partitions and some FAT partitions. When the mass storage device is removed, the filesystems are unmounted and the devb-umass driver managing the device is terminated. If a device is matches an entry in the configuration file, the options specified in the configuration file are applied against that particular device. Otherwise the default actions are taken. You can use the options to umass-enum to override some of the default actions.

By default, all raw device entries and partitions are created under /dev/umass with names of hdumass and cdumass. Each instance of device is assigned a unique LUN number by the devb-umass driver. This number is used when mounting the partitions. The driver is coded to scan and mount partitions for a maximum of three LUNs per device that's plugged in. (Most devices are single-LUN.)

For example, umass-enum creates these entries for a single-LUN device:

For a multiple-LUN device, umass-enum creates multiple HD entries. For example:

Here's an example of multiple devices:

---

If a device has no partitions, umass-enum tries to mount the raw device entry as a FAT partition. You may or may not want to allow this. If there really isn't a valid partition there, or the device simply has never been formatted, you'll likely get I/O errors when attempting to read from or write to the device.

---

Autorun

To enable the autorun feature, specify the -A option.

If a shell script called autorun (QNX 4) or autorun.exe (DOS) exists in the root of the mounted device, it's run after the filesystem is mounted. This feature can be useful for launching applications, automatically updating files to and from the device, etc.

Here's a sample autorun script that generates a playlist from available MP3 files on the device and launches a player to play them:

# Get the mountpoint of the USB device:
bname=`dirname $0`
cd $bname

# Create a playlist from the available MP3 files:
find $PWD -name *.mp3 > playlist.m3u

# Launch qnxplayer with the playlist:
qnxplayer -u $bname/playlist.m3u &

# Start the mixer:
mixer &

Resource manager interface

To enable the resource manager interface, specify the -r option.

Currently the resource manager uses simple devctl() commands that applications can use to get information about devices that umass-enum knows about.

When you enable the resource manager interface, umass-enum registers the path /dev/umass-enum. Applications can then open /dev/umass-enum and use the devctl() commands that umass-enum supports. The main devctl() commands are:

UMASS_DEVCTL_DEVICE_CHANGE

This is a blocking call that returns whenever there's a change to the devices managed by umass-enum. It fills in a struct _umass_devctl_change_data that includes the following members:

• int device_state — one of the following:
  • UMASS_DEVICE_STATE_REMOVED
  • UMASS_DEVICE_STATE_INSERTED
  • UMASS_DEVICE_STATE_MEDIA_CHANGED
  • UMASS_DEVICE_STATE_DRIVER_DIED
• uint32_t busno, uint32_t devno — used as identifiers to get further information about the device (on insertion).

UMASS_DEVCTL_GET_DEVICE_INFO

Get information about the device, including the string identifier, speed, and so on.

UMASS_DEVCTL_GET_MOUNT_INFO

Get information about the filesystems that have been mounted by umass-enum.

See <sys/umass-enum.h> for complete details.

Here's some pseudo-code that illustrates how to use these commands:

open /dev/umass-enum

while( 1 ) {
   send blocking UMASS_DEVCTL_DEVICE_CHANGE.
   switch ( device_state ) {
      case INSERTED :
         Get string information using UMASS_DEVCTL_GET_DEVICE_INFO
         and mount information UMASS_DEVCTL_GET_MOUNT_INFO.
         Do something useful with this information.
         break;

      case REMOVED :    
         Remove from internal list.
         break;

      case DRIVER_DIED :
         Inform user a problem occurred while using this device.
         break;
   }
}

Configuration file format

---

If the configuration file doesn't exist, umass-enum supports all devices.

---

Here are the rules that apply to the configuration file, umass-enum.cfg:

• Lines beginning with a # character are ignored and can be used for adding comments.
• Blank lines are ignored.
• Each device to be supported must be listed on a single line, and the entry must not be longer than 1024 characters.
• Each tag must be separated by a comma.
• A value of 0xffff acts as a wildcard. You typically use this as device_id=0xffff.
• You should use wildcards after any specific devices for which you want to apply arguments. For example, if you have:

   vendor=0xffff,device=0xffff
    

  as the first line, all devices would match this line, so the utility would stop searching for a match in the configuration file.

Here's an example of a configuration file:

# Support for an Unknown device ( Comment) 
vendor=0x0a17,device=0x0001
  
# Another example ( turn verbosity off for cam layer )
vendor=0x0a18,device=0x0002,cam=quiet

# Support all devices for a particular vendor
vendor=0x0a19,device=0xffff,cam=quiet

# This would also work - support all devices for a particular vendor
# as device_id defaults to 0xffff
vendor=0x0a19,cam=quiet

# Mount a specific device at a specific mount point.
vendor=0x0781,device=0x7112,serial_num=0000762108,mount=0:t6:/sandisk:dos

The configuration file supports the following tags:

• Vendor/device tags:

  vendor=vendor_id

  The vendor ID, as reported by the usb utility.

  device=device_id

  The device ID as reported by the usb utility.

  subclass=subclass

  The subclass as reported by the usb utility.

  protocol=protocol

  The protocol as reported by the usb utility.

  serial_num=serial_num

  The serial number as reported by the usb utility.

  perm=[rwx]

  Specify the access permission for the mountpoint.

• Block and filesystems tags support; these tags define overrides for the corresponding driver options:
  • blk=blk_options
  • cam=cam_options
  • disk=disk_options
  • umass=umass_options
  • qnx4=qnx_options
  • dos=dos_options
  • cd=cd_options
• Miscellaneous tags:

  mount=lun:partition:mount_point:fstype[:perm]

  Mount the device to the specified mountpoint (e.g. mount=0:t77:/umass_part:qnx4).

  The perm can be a combination of the r, w and x characters, which you can use to specify access permissions. If you omit it, then the device's perm is used (if specified). Otherwise, umass-enum uses a default of rwx.

  comment=comment

  Specify a comment to be stored with the device entry.

Technical support

If you have any questions, comments, or problems with a QNX product, please contact Technical Support. For more information, see the How to Get Help chapter of the Welcome to QNX Momentics guide or visit our website, www.qnx.com.