# USB mass storage support for B eOS

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:

- memory (flash) keys,
- external HDD/CD/DVD/ZIP/Floppy drives with USB connection,
- digital cameras/camcorders with USBMS protocol,
- MP3 players,
- card readers,
- Jukeboxes
- etc.

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

- Installation and using
- Troubleshooting
- Writing a problem report
- Technical notes

- BeOS USB patches
- USB Device information

- How to obtain USB device information for your hardware
- How USB device information looks like and what does it mean

- Device entries reservation technique
- A couple of words about usb_scsi settings file

- The Module configuration parameters
- Parameters for debugging mode
- Configuring device definitions

- Tweaking device definition
- Overriding device protocol

- Protocol extension modules

- Contact and support information
- Credits
- The History

# 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:

- copies The Module binary to /boot/home/config/add-ons/kernel/busses/scsi/usb directory

- copies settings file to /boot/home/config/settings/kernel/drivers/usb_scsi file
- ask you to reboot your system or edit settings file. More information on settings file is here. If you doesn't reboot from script - you have to do it manually to let The Module work with updated settings.

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?
   - May be. Install this software, plug your device in and try to mount it. Or look for class / subclass / protocol values in usb device description and check against the following lists.
     - Supported class : 8
     - Supported subclasses ( command sets ) : 1, 2, 3, 4, 5, 6
     - Supported protocols: 0, 1, 80
     Any combination of mentioned above class / subclass / protocol is supported.
2. I have installed this software on R5 + USB.patches but my system goes to Kernel Debugger on very early booting stage. Help!
   - Edit settings file and activate the following key:
     - ignore_sysinit2 true
3. I have installed this software and there are still no additional volumes in Tracker's "Mount" menu.
   - Sometimes it is required to open "Mount" menu more than one time to see volumes.
   - You can try open "Mount" menu with "Shift" button pressed and select "Rescan All Devices" menu item to help the system recognize your device.
   - Try to Rescan SCSI in DriveSetup.
4. I still have no volumes to mount!!!
   - Please check the following:
     - [for R5 only. Not required for Dano/Zeta etc. ] your system has USB patches installed;
     - the binary file /boot/home/config/add-ons/kernel/busses/scsi/usb exists on your system;
     - the settings file /boot/home/config/settings/kernel/drivers/usb_scsi exists on your system;
     - check that your device uses standard protocols and should be supported by this module ( see clause 1 of this section )
     - Despite of fact that latest versions of Zeta OS use this module, some of pre-releases of this OS have completely different stuff to support USB storage devices. In some circumstances those Zeta's modules can prevent this USB Support Module from correct working. In this situation you have to disable Zeta's USB Storage support. To do this go to /boot/beos/system/add-ons/kernel/busses/scsi/ diectory and rename or remove the usb and usb_scsi files. After rebooting your system you should have updated USB Storage support.
5. STILL NOTHING TO MOUNT ! ! !
   - Looks like you are in trouble. Write your problem report to developers.
6. I see a lot of empty SCSI devices in DriveSetup and SCSIProbe. What is it?
   - Those "disks" are just reserved device entries - some kind of placeholders for real devices you'll attach to your computer. Read about this technique here.
7. DriveSetup hangs on exit!?!
   - It is known bug. I don't know who is wrong with it. No solution at this time. Just kill this zombie.
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.
   - The mounting in BeOS is broken. Just press "Shift" key before opening Tracker's "Mount" menu than select "Rescan Devices" After some seconds try to mount your device again. Should work now.
9. I have set reserve_devices to maximal value but still no reserved device entries in DriveSetup.
   - Known bug. In some situations reservation doesn't work. It's reproducible with Adaptec SCSI controllers installed on your system. You have to use DriveSetup for first mounting of device in this situation. Nothing is perfect in this World.
10. Does my Canon PowerShot A70 digital camera supported by this software?
    - No. It uses Picture Transfer Protocol (PTP) instead of USB Mass Storage (USBMS) one. You can check your camera information for Interface class. For USBMS it should be 8, for PTP - 6.
11. Help me! No more than 2 devices visible by module at the same time.
    - Read about device entries reservation and increase reserve_devices parameter in settings file.
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?
    - Read about device entries reservation and increase reserve_luns parameter in settings file.
13. "Mount" menu hangs for a time
    - System requires some time to ask all available volumes for media availability, filesystem data format etc. This check is performed any time you opening "Mount" menu. In case you have many devices reserved in your configuration - you can be in such trouble. Read about device entries reservation and optimize your settings to more reasonable values.
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!!!
    - Please write your problem report to developer first.

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

        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

- reserve_devices
  - Amount of device entries to be reserved by The Module. If you plan to use more than 2 devices simultaneously than increase this parameter. Note that if you set this parameter to 0 - device entry reservation will be "switched off" and you have to use DriveSetup for first mounting.
  - default value: 2
  - maximal value: 7
- reserve_luns
  - Amount of logical unit numbers (LUN) to be reserved by The Module for every device entry defined in reserve_devices parameter. If you plan to use devices with more than 4 LUNs than increase this parameter.
  - default value: 4
  - maximal value: 8
- ignore_sysinit2

- If you have R5 with USB patches and your system goes in kernel debugger on booting with this software - this parameter is for you. Set it to true and reboot to avoid such crashing behavior.
- default value: false

Table of Contents

### 4.4.2. Parameters for debugging mode

- debug_output

- This parameter activates / deactivates debug output.
- default value: false

- debug_output_in_file

- This parameter handles redirection of tracing information to private log file (/var/log/usb_scsi.log). If this parameter is false - all debuging information goes to system log.
- default value: false

- debug_output_file_rewrite

- Forces private log file to be truncated on every system restart
- default value: false

- debug_trace_commands

- Activate this to dump SCSI commands to debug output
- default value: false

- debug_trace_protocol

- Activate this to see mass storage protocols work information in debug output
- default value: false

- debug_trace_data_io
- debug_trace_sense_data
- debug_trace_bulk_callback
- debug_trace_time
- debug_trace_threadid
- debug_trace_thread_name
- debug_trace_capacity

- Mean this stuff as undocumented because it is rarely used.
- default values: false

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.

- fake_inquiry

- do not send INQUIRY SCSI command to USB device but handle it in Module.

- use_6byte_cmd

- use 6 byte length SCSI READ/WRITE/MODE SENSE/SELECT SENSE commands instead of 10 byte ones. Typically BeOS uses 6-byte commands but many USB mass storage devices doesn't like this. To avoid massive device redefinitions this Module automatically translates such commands to 10-byte counterparts. If this default translation doesn't work for you - set use_6byte_cmd to avoid it.

- trans_test_unit

- translate TEST UNIT SCSI command to START STOP one.

- no_test_unit

- do not send TEST UNIT SCSI command to device. At all.

- no_get_max_lun

- do not ask for maximal number of supported Logical Unit Numbers

- no_prevent_media

- do not send to device PREVENT ALLOW MEDIA REMOVAL SCSI command.

- use_mode_sense_10

- force module to use 10-byte MODE SENSE command. Typically this Module detects automatically the supported MODE SENSE command and you don't need to set it manually.

- force_read_only

- force drive to be read-only. It is not 100% guaranteed - but in many cases works. If you need "true" read-only volumes - than mount it with corresponding flags from command line.

#### 4.4.3.2. Overriding device protocol

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

- commandset

- forces The Module to use specific command set when communicating with device. The following command sets are supported

- SCSI - transparent SCSI command set. USB subclass 6
- UFI - USB subclass 4
- ATAPI - USB subclasses 5,2
- RBC - USB subclass 1
- QIC157 - USB subclass 3. Used for tape drives so, probably is not be anytime usable... but supported. =-)
- <Vendor> - any vendor-specific, non-standard commands set. Note that to work with it a corresponding protocol extension module is required.

- protocol

- forces The Module to use specific protocol when communicating with device. The following protocols are supported

- BULK - bulk-only. USB protocol 80
- CB - Control/Bulk/Interrupt protocol (with command completion interrupt). USB protocol 1
- CBI - Control/Bulk/Interrupt protocol (with no command completion interrupt) USB protocol 0
- <Vendor> - any vendor-specific, non-standard protocol. Note that to work with it a corresponding protocol extension module is required.

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:

- freecom - FREECOM USB-IDE Bridge (ATAPI devices only).

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 >