USB mass storage support for BeOS

by Siarzhuk Zharski
This is yet another piece of hardware support for BeOS/Dano/Zeta operating systems. This USB Storage Module (The Module) is designed to support a wide variety of standard USB mass storage devices. Those devices are:

In other (more special and technical) words this Module works with standard USB class 8 devices, both Bulk-Only and CB[I] ones, with all standard command sets used in such devices.

Table of Contents

1. Installation and using

(!!!) FIRST EMERGENCY TIP: If your system crashes with this Module - reboot and press "Space" during load. In boot menu select "Disable user add-ons" and continue booting. Uninstall and reboot again into normal mode. Please, inform the developer about this problem.

  1. Please check, that you have supported version of BeOS. Minimal system requirement is R5 + BeOS.USB-patches. No support for "plain" R5! More information about USB-patches you can find in corresponding clause of this document. Note that Dan0, all it's successors and Zeta already have compatible USB stack - no patches are required.
  2. Contents of distribution archive: 
        ReadMe.html      <--- file you are reading now
    install.sh       <--- installation script
    uninstall.sh     <--- uninstallation script
    usb              <--- The Module binary
    usb_scsi.sample  <--- settings file sample
    usb_scsi_logging <--- logging daemon
    usb_scsi.devices <--- definitions for "non-standard" devices
    usb_dev_info     <--- the tool to obtain device inforamtion
  3. Run ./install.sh to install The Module on your system. This script do the following:
  4. After system rebooted, plug in your USB device into USB slot and try to open Tracker's "Mount" menu some times. In case if all goes OK - you'll see some additional volumes available for mounting. Mount that one you think is your USB mass storage and use it as usual "real" drives.
  5. It is highly recommended to unmount your USB volume before unplugging device from USB slot. Some pending read/write operations can be still active in background. If you break this process - YOU CAN LOOSE YOUR DATA. Unmount it and wait until your USB volume icon is disappeared from desktop and led on your device ( in case this led exists, of course ) turns off. To be sure you can run "sync" command from the Terminal.
  6. [optional] To uninstall The Module from your system - run uninstall.sh from distribution archive or delete files mentioned in clause 3 of this section manually.
Table of Contents

2. Troubleshooting

  1. Is my USB device supported?
  2. I have installed this software on R5 + USB.patches but my system goes to Kernel Debugger on very early booting stage. Help!
  3. I have installed this software and there are still no additional volumes in Tracker's "Mount" menu.
  4. I still have no volumes to mount!!!
  5. STILL NOTHING TO MOUNT ! ! !
  6. I see a lot of empty SCSI devices in DriveSetup and SCSIProbe. What is it?
  7. DriveSetup hangs on exit!?!
  8. I have found a bug! I have unmounted my USB floppy, unplug it than plug in another device but still see the "floppy" volume in the mount list.
  9. I have set reserve_devices to maximal value but still no reserved device entries in DriveSetup.
  10. Does my Canon PowerShot A70 digital camera supported by this software?
  11. Help me! No more than 2 devices visible by module at the same time.
  12. My 9-in-1 card reader works only with media in first 4 slots! No reaction on media in 5th - 9th slots! Is it a trial version of a driver? Where can I buy full version?
  13. "Mount" menu hangs for a time
  14. I see the Generic OS Error message any time I want to mount my device.

    In most of such situations your hardware is OK. The problem is that standard filesystem addon doesn't recognize the filesystem on volume as correct. Unfortunatley BeOS is "to close to standard" to be compatible with all bugs of Windows. Do not forget to backup your data before trying to solve this problem!

    First of all try to reformat your media.

    If formatting doesn't help or doesn't work with your hardware - open DriveSetup and [re]create partition on your device. Rescan SCSI bus if required. Note that you have to make your partition a bit smaller as physical size of your device. Try to initialize and reformat your media with new size.

  15. Your software sucks!!!
Table of Contents

3. Writing a problem report

Either something goes wrong with this software or nothing goes right you have to write a bug report about it.
  1. Obtain your USB device information and save it in safe place
  2. now investigate device information for interface class. If it is not equal to 8 go to step 12
  3. open your settings file ( /boot/home/config/settings/kernel/drivers/usb_scsi ) in editor you prefer to use
  4. activate following keys if they are still not activated
    5.     debug_output true
    debug_output_in_file true
    debug_output_file_rewrite true
    debug_trace_protocol true
    debug_trace_sense_data true
  5. save your changes and close your editor
  6. reboot your system keeping your devices switched off from your computer
  7. after reboot run usb_scsi_logging application from distribution pack
  8. plug your device in free USB slot
  9. try to mount it again.
  10. unplug your device from computer
  11. copy the /var/log/usb_scsi.log file into same place as in step 1.
  12. Get the information, obtained on step 1 and step 12 and let developer know about your problem
Table of Contents

4. Technical notes

4.1. BeOS USB patches

To work with this software on original BeOS R5 Pro/PE versions and it's successors your system need to be improved to newer version of USB. This version is available on well-known BeOS file-sharing network as BeOS.USB-patches.zip. Get it, unpack and install it as required in corresponding readme. Note that, there are 3 patches in this archive:
  1. beos-usb-patch
  2. beos-usb.modem-patch
  3. beos-usb.modem-patch.sm

At least first one should be installed on your system to make using of The USB Support Module possible. Note that Dan0, all it's successors and Zeta don't require this patches.

Table of Contents

4.2. USB Device information

4.2.1. How to obtain USB device information for your hardware

There is an usb_dev_info tool inside of distribution archive. It can be used to obtain this information. Someone prefers USBCommander.
  1. Unplug all USB devices and hubs from your PC.
  2. Go into Terminal and run the following command: ls -alR /dev/bus/usb You should see something like this: 
        $ ls -alR /dev/bus/usb/
    /dev/bus/usb:
    total 0
    drw-r--r--   1 walther  users           0 May 31 23:16 .
    drw-r--r--   1 walther  users           0 Jun  1  2003 ..
    drw-r--r--   1 walther  users           0 May 31 23:16 0
    drw-r--r--   1 walther  users           0 May 31 23:16 1
    crw-r--r--   1 walther  users      0,   0 May 31 23:16 unload
    
    /dev/bus/usb/0:
    total 0
    drw-r--r--   1 walther  users           0 May 31 23:16 .
    drw-r--r--   1 walther  users           0 May 31 23:16 ..
    crw-r--r--   1 walther  users      0,   0 May 31 23:16 hub
    
    /dev/bus/usb/1:
    total 0
    drw-r--r--   1 walther  users           0 May 31 23:16 .
    drw-r--r--   1 walther  users           0 May 31 23:16 ..
    crw-r--r--   1 walther  users      0,   0 May 31 23:16 hub
  3. Note this information.
  4. Now plug your USB device into PC and run ls -alR /dev/bus/usb/ again. You'll get something slightly different: 
        $ ls -alR /dev/bus/usb/
    /dev/bus/usb:
    total 0
    drw-r--r--   1 walther  users           0 May 31 23:16 .
    drw-r--r--   1 walther  users           0 Jun  1  2003 ..
    drw-r--r--   1 walther  users           0 May 31 23:16 0
    drw-r--r--   1 walther  users           0 May 31 23:16 1
    crw-r--r--   1 walther  users      0,   0 May 31 23:16 unload
    
    /dev/bus/usb/0:
    total 0
    drw-r--r--   1 walther  users           0 May 31 23:16 .
    drw-r--r--   1 walther  users           0 May 31 23:16 ..
    crw-r--r--   1 walther  users      0,   0 May 31 23:17 1
    crw-r--r--   1 walther  users      0,   0 May 31 23:16 hub
    
    /dev/bus/usb/1:
    total 0
    drw-r--r--   1 walther  users           0 May 31 23:16 .
    drw-r--r--   1 walther  users           0 May 31 23:16 ..
    crw-r--r--   1 walther  users      0,   0 May 31 23:16 hub
  5. Compare this results with previous one and look for file, that appeared (is selected for our sample case). This file is your "unknown" USB device (in our sample it is /dev/bus/usb/0/1).
  6. Now you can run usb_dev_info tool to obtain device information: 
    $ usb_dev_info /dev/bus/usb/0/1
Table of Contents

4.2.2. How USB device information looks like and what does it mean

After performing tasks, described in previous clause you'll receive something like the following. Note that some details can be different for your hardware 

    $ usb_dev_info /dev/bus/usb/0/1
    [Device]
    Class .................. 0
    Subclass ............... 0
    Protocol ............... 0
    Vendor ID .............. 0x08ec   <---------- Vendor ID of your hardware manufacturer
    Product ID ............. 0x0011   <---------- unique Product ID of your hardware
    Version ................ 0x0200
    Manufacturer String .... "      "
    Product String ......... "      "
    Serial Number .......... "      "
      [Configuration 0]               <---------- begin of configuration description 
        [Interface 0]                 <---------- begin of interface description
        Class .............. 8        <---------- this interface class. 
        Subclass ........... 6        <---------- this interface subclass
        Protocol ........... 80       <---------- protocol used by this interface
          [Endpoint 0]
          MaxPacketSize .... 64
          Interval ......... 0
          Type ............. Bulk
          Direction ........ Input
          [Endpoint 1]
          MaxPacketSize .... 64
          Interval ......... 0
          Type ............. Bulk
          Direction ........ Output
Table of Contents

4.3. Device entries reservation technique

Some tricks are required to implement simple and natural ( "one-click" ) volumes mounting in Tracker. Current versions of BeOS don't fully conform to SCSI Common Access Model specifications. Particularly that is mean, that there are no possibility to tell system about mass storage devices, attached after system boot. If you already used usb mass storage driver from Dano you should know this problem - you have to go to DriveSetup than Rescan SCSI bus and only after this mount your volume from DriveSetup.

This Module introduces a workaround for such problem - it just let system to know, that "device is here, but not ready at the moment, keep trying". This allows to simulate some kind of plug and play in mounting from Tracker. You can see those reserved device entries in DriveSetup -a lot of SCSI "drives" without media and with ZIP cartridge icon left of it. This reservation can be configured in settings file.

Table of Contents

4.4. A couple of words about usb_scsi settings file

You can configure some aspects of this software behavior through editing it's settings file. This file is placed by installation script into /boot/home/config/settings/kernel/drivers/ directory and has the name usb_scsi. It is usual text file and can be edited by any text editor you like. Note that improper using of this settings file can crash your system - please be accurate.

Typically the parameters in settings file can be inactive (commented ) or active. For example the following quote from settings file contains two parameters: first one ( reserve_devices ) is inactive ( commented by '#'-sign at the begin of line ) and second one ( reserve_luns ) is active and set to 4: 

#reserve_devices 2 <----------------- inactive
reserve_luns    4 <----------------- active
Please use this notation during editing of settings file.

4.4.1 The Module configuration parameters

This set of parameters is loaded by Module during system boot and is used on permanent basis. To apply changes, made by you in any of this parameter you have to restart your system Table of Contents

4.4.2. Parameters for debugging mode

Table of Contents

4.4.3 Configuring device definitions

Device definition allows to override your hardware parameters and tweak it's functionality. This parameters are device-specific and reloaded on physical device attach. You not need to reboot your system to apply your changes in device descriptions. All you need to use changed device definitions - unplug your USB hardware from computer and plug it in again.

Typical "non-standard" devices definition looks like this: 

vendor <<vendor id>> {
  device <<product id 1>> {
    <<parameter 1>> 
    <<parameter 2>>
         ...
    <<parameter N>>
  }
    ....
  device <<product id N>> {
    <<parameter 1>> 
    <<parameter 2>>
         ...
    <<parameter N>>
  }
}

The real vendor ID and product ID for your hardware you can obtain from USB Device information. Note that you can define many devices inside of single vendor definition. More real samples of device overrides you can find in usb_scsi.devices file inside of distribution archive. Just copy the content of corresponding device description into settings file and re-plug your hardware.

Table of Contents

4.4.3.1.Tweaking device definition

Every parameter of device definition is like switch. It affects on Module behavior only if exists in device definition and is not commented out.

4.4.3.2. Overriding device protocol

There are two special parameters allow to override protocol and command set used to communicate with device Table of Contents

4.5. Protocol extension modules

The BeOS USB Support Module was designed with extensibility in mind. It means, that you can add support of vendor-specific, non-standard protocols/commandsets without changing the main Module. All you need is protocol extention module, that implements all specifics of the data and commands flow.

Currently available modules:

To install protocol extention module obtain it's distribution archive and read instructions inside of it.

For development questions refer to of already existing protocol extention modules or the Author of UBS Support Module.

Table of Contents

4.Contact and support information

The BeOS USB Support Module project is hosted on SourceForge and uses some it's powerful development services. There are some ways to inform developer about problems or put feature requests for next version
  1. Use Bug Tracker to put problem reports.
  2. Use Forum to ask simple support question, discuss any problems. Do not put your problem reports here - use Bug Tracker!
  3. Use Mailing-list to be informed with latest news, ask questions etc. This is also not right place for your problem reports - use Bug Tracker instead.
  4. If you want to share any ideas, that can be good to implement in future versions - use Feature Request Submit form.
  5. If you doesn't like any way, mentioned above you can contact me personally by e-mail but remember, that I don't like this way!(Joke!) =-) In my opinion such Community Knowledges like Forums and mail-lists must be public and available for everyone.
Table of Contents

5.Credits

I want to say my "Thanks" to:

... Sergei Dolgov ("fyysik") for pushing me to develop this software and help in testing,

... Valery Rybin for testing a really lot of those USB gadgets he has at his hands,

... them who have spend some time to trying all those "-dev-" versions in work.

Table of Contents

6. The History

Date: Version: What's new:
06 June 2004 0.1.0-alpha-1 first public release.

Table of Contents
< End of document >