USB file sharing in Archos Angstrom

The Archos A5/7 has USB device support as well as host support. So as well as support for USB peripherals such as keyboards, it is also possible to connect the A5/7 to a host computer and have it behave as a device rather than a host. In the stock AVOS firmware this support is used for exchanging files with a host, with the A5/7 acting as a device that implements the USB mass storage protocol, or some Microsoft-specific protocol that I don't understand. This file sharing feature is sadly lacking from the stock Angstrom (as it is from most Linux implementations). To be sure, the low-level support is present in the kernel -- the omission is a way for an end user to make use of it in a straightforward and safe way.

Design considerations

The AVOS approach to file sharing is perhaps not entirely suitable for a more general-purpose Linux implementation, for a number of reasons.

• When sharing files, all normal operations are suspended. The USB cable must be physically unplugged to recover control. This is fine for a media player, but might be a nuisance for what is effectively a small computer
• In AVOS, connecting the USB shuts down all applications that might have data files open on the shared filesystem. This, again, is fine if we know in advance exactly which applications might be running, and that it is safe to shut them down.
• The shut-down of applications is for a good reason -- it allows the whole of the disk partition to be exported for sharing. In Angstrom there is almost no possibility of exporting the whole disk partition, because most likely that's where the root and home filesystem images are. Therefore mass application suicide is unnecessary. However, we do have to go to some trouble to ensure that the same file area is not being used locally and exported over USB -- this will almost certainly eventually corrupt the filesystem.

The system adopted for Angstrom at present is to use a separate filesystem image, usually stored alongside the root and filesystem images, exclusively for sharing files over USB. By default, this filesystem is created in vfat format, to make it easy to share with Windows and Mac systems. The default filesystem size is 100Mb. Both the size and type can be configured by the administrator using an rc file.

At any time, the shared area will (we hope) be in one three states.

• Mounted locally. By default, the mount point is `/usbshare'. A symlink to this area is created in the default user's home directory as well.
• Exported over USB
• Idle

We hope that there is no fourth state

• Exported over USB and mounted locally

The command-line utility provided to manage the USB share, /bin/a5usb.sh, goes to some trouble to prevent this dangerous state being entered. This utility also handles switching the USB controller from host mode to device mode, as the hardware only supports one mode of operation at a time (note that the Archos docks enforce this mechanically -- you can only plug one USB cable in at a time). However, it is impossible completely to prevent the user fiddling about with the system at the command prompt and breaking something. In particular, there is absolutely nothing to prevent the user exporting the shared filesystem over USB, and then issuing a mount command to mount it locally. So far as the Linux USB drivers are concerned, this is a perfectly legitimate thing to do. All we can do is recommend that users only use the built-in utilities for getting access to the USB shared area, which will always (we hope) disconnect the USB driver before mounting locally.

The shared filesystem image is created automatically at boot time if it does not exist. This will add about five seconds to the time taken for the first boot.

User interface

There is a graphical user interface implemented in archos-helper-gui. Press the power button, then select the 'USB' tab.

The UI will show the current state of the share -- exported, mounted locally, or stopped -- and allow it to be changed. If a USB host is connected, the user interface will warn the user when clicking the 'Stop' or 'Mount locally' buttons. But the A5/7 has no way of knowing (so far as I can tell) whether the host actually has the A5 mounted as a drive. So there's no way to prevent the user disconnecting when the host thinks the A5 is mounted. But there's no way to stop the user pulling the cable out, either.

Note that the GUI does not provide a way to delete, resize, or change the format of the shared filesystem, but the command-line does. Note also that the GUI does all its operations via archos-helper; it has no USB support of its own.

Command-line interface

Configuration settings are in /etc/a5usb.rc. At present, it's best not to change any of these except the size and type, as archos-helper does not (yet) read the configuration file, and makes certain assumptions about where things are mounted.

The command-line utility /bin/a5usb.sh will almost certainly have to be run as root. It takes one of five arguments.

• a5usb.sh stop -- unmount and stop exporting
• a5usb.sh mount -- mount the shared area locally, disconnecting USB first if necessary
• a5usb.sh export -- export the shared area over USB, umounting locally first if necessary. If the local filesystem can't be unmounted, the whole oepration fails with an error code. This is absolutely necessary, because the most obvious reason for failing is that the user has one or more files open on the shared filesystem, and exporting in that state would be catastrophic
• a5usb.sh delete -- deletes the shared filesystem image, if it is not in use
• a5usb.sh create -- creates the shared filesytem image, if it does not already exist, using the parameters in /etc/a5usb.rc.
• a5usb.sh status -- returns a short string indicating the current status of the USB share

If an operation fails, a5usb.sh will give a numerical error code and a brief message. The error code is intended to be read by archos-helper, not by the user.

archos-helper interface

The following commands get be issued on the archos-helper daemon:

• setUSBShareMode N where N is 0 (stopped), 1 (mounted), and 2 (exported)
• getUSBShareMode returns a number 0-2 as above

archos-helper implements both these operations by running sudo a5usb.sh so sudo will need to be configured to allow this.