1b3d94504SStephan Aßmus<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2b3d94504SStephan Aßmus<!--
3b3d94504SStephan Aßmus 
4b3d94504SStephan Aßmus This file is a part of BeOS USB SCSI interface module project.
5b3d94504SStephan Aßmus Copyright (c) 2003-2004 by Siarzhuk Zharski <imker@gmx.li>
6b3d94504SStephan Aßmus 
7b3d94504SStephan Aßmus This file may be used under the terms of the BSD License
8b3d94504SStephan Aßmus See the file "License" for details.
9b3d94504SStephan Aßmus 
10b3d94504SStephan Aßmus $Source: /cvsroot/sis4be/usb_scsi/ReadMe.html,v $
11b3d94504SStephan Aßmus $Author: zharik $
12b3d94504SStephan Aßmus $Revision: 1.23 $
13b3d94504SStephan Aßmus $Date: 2005/04/09 20:53:25 $
14b3d94504SStephan Aßmus
15b3d94504SStephan Aßmus-->
16b3d94504SStephan Aßmus<html>
17b3d94504SStephan Aßmus<head>
18b3d94504SStephan Aßmus  <title>USB mass storage support for BeOS</title>
19b3d94504SStephan Aßmus</head>
20b3d94504SStephan Aßmus<body bgcolor="#f0f0e0">
21b3d94504SStephan Aßmus<h1>USB mass storage support for 
22b3d94504SStephan Aßmus       <font color="#000066">B</font><font color="#cc0000">e</font>OS</h1>
23b3d94504SStephan Aßmus<div align="right">
24b3d94504SStephan Aßmus<address><a href="mailto:imker@gmx.li">by Siarzhuk Zharski</a></address>
25b3d94504SStephan Aßmus</div>
26b3d94504SStephan AßmusThis is yet another piece of hardware support for BeOS/Dano/Zeta operating systems.
27b3d94504SStephan AßmusThis USB Storage Module (<strong>The Module</strong>) is designed to support a wide variety
28b3d94504SStephan Aßmusof standard USB mass storage devices. Those devices are: 
29b3d94504SStephan Aßmus<ul>
30b3d94504SStephan Aßmus  <li>memory (flash) keys,</li> 
31b3d94504SStephan Aßmus  <li>external HDD/CD/DVD/ZIP/Floppy drives with USB connection,</li> 
32b3d94504SStephan Aßmus  <li>digital cameras/camcorders with USBMS protocol,</li> 
33b3d94504SStephan Aßmus  <li>MP3 players,</li> 
34b3d94504SStephan Aßmus  <li>card readers,</li>
35b3d94504SStephan Aßmus  <li>Jukeboxes</li> 
36b3d94504SStephan Aßmus  <li>etc.</li>
37b3d94504SStephan Aßmus</ul> 
38b3d94504SStephan Aßmus<p>In other (more special and technical) words this Module
39b3d94504SStephan Aßmusworks with standard USB class 8 devices, both Bulk-Only and CB[I] ones,
40b3d94504SStephan Aßmuswith all standard command sets used in such devices. 
41b3d94504SStephan Aßmus</p>
42b3d94504SStephan Aßmus<h1><a name="Contents"></a>Table of Contents</h1>
43b3d94504SStephan Aßmus<ul>
44b3d94504SStephan Aßmus  <li><a href="#1._Installation_and_using_">Installation and using </a></li>
45b3d94504SStephan Aßmus  <li><a href="#2._Troubleshooting">Troubleshooting</a></li>
46b3d94504SStephan Aßmus  <li><a href="#3.5.Writing_a_problem_report">Writing a problem report</a></li>
47b3d94504SStephan Aßmus  <li><a href="#3._Technical_notes_">Technical notes</a></li>
48b3d94504SStephan Aßmus  <ul>
49b3d94504SStephan Aßmus    <li><a href="#3.1._BeOS_USB_patches">BeOS USB patches</a></li>
50b3d94504SStephan Aßmus    <li><a href="#3.2._USB_Device_information">USB Device information</a></li>
51b3d94504SStephan Aßmus    <ul>
52b3d94504SStephan Aßmus      <li><a href="#3.2.1._How_to_obtain_USB_device">How to obtain USB device information for your hardware</a></li>
53b3d94504SStephan Aßmus      <li><a href="#3.2.2._How_it_looks_like_and_what_does_">How USB device information looks like and what does it mean</a>
54b3d94504SStephan Aßmus      </li>
55b3d94504SStephan Aßmus    </ul>
56b3d94504SStephan Aßmus    <li><a href="#3.3._Device_entries_reservation">Device entries reservation technique</a></li>
57b3d94504SStephan Aßmus    <li><a href="#3.4._A_couple_of_words_about_usb_scsi">A couple of words about usb_scsi settings file</a></li>
58b3d94504SStephan Aßmus    <ul>
59b3d94504SStephan Aßmus      <li><a href="#3.4.1_General_Module_settings">The Module configuration parameters</a></li>
60b3d94504SStephan Aßmus      <li><a href="#3.4.2._Module_settings_for_debugging_">Parameters for debugging mode</a></li>
61b3d94504SStephan Aßmus      <li><a href="#3.4.3_Device_settings">Configuring device definitions</a></li>
62b3d94504SStephan Aßmus      <ul>
63b3d94504SStephan Aßmus        <li><a href="#3.4.3.1._Parameters_of_Device_settings">Tweaking device definition</a></li>
64b3d94504SStephan Aßmus        <li><a href="#3.4.3.2._Protocol_override_parameters">Overriding device protocol</a>
65b3d94504SStephan Aßmus        </li>
66b3d94504SStephan Aßmus      </ul>
67b3d94504SStephan Aßmus    </ul>
68b3d94504SStephan Aßmus    <li><a href="#3.6._Protocol_extension_modules">Protocol extension modules</a></li>
69b3d94504SStephan Aßmus  </ul>
70b3d94504SStephan Aßmus  <li><a href="#6.Contact_information">Contact and support information</a></li>
71b3d94504SStephan Aßmus  <li><a href="#5.Credits">Credits</a></li>
72b3d94504SStephan Aßmus  <li><a href="#4._Versions_History_">The History</a></li>
73b3d94504SStephan Aßmus</ul>
74b3d94504SStephan Aßmus
75b3d94504SStephan Aßmus<h1><a name="1._Installation_and_using_"></a>1. Installation and using</h1>
76b3d94504SStephan Aßmus<p><font color="#cc0000"><b>(!!!) FIRST EMERGENCY TIP:</b></font> If your system
77b3d94504SStephan Aßmuscrashes with this Module - reboot and press "Space"
78b3d94504SStephan Aßmusduring load. In boot menu select "Disable user add-ons" and continue
79b3d94504SStephan Aßmusbooting. Uninstall and reboot again into normal mode. Please, <a
80b3d94504SStephan Aßmus href="#6.Contact_information">inform the developer</a> about this problem.
81b3d94504SStephan Aßmus</p>
82b3d94504SStephan Aßmus<ol> 
83b3d94504SStephan Aßmus  <li>Please check, that you have supported version of BeOS. Minimal system
84b3d94504SStephan Aßmusrequirement is R5 + BeOS.USB-patches. No support for "plain" R5! More
85b3d94504SStephan Aßmusinformation about USB-patches you can find in 
86b3d94504SStephan Aßmus<a href="#3.1._BeOS_USB_patches">corresponding clause of this document</a>.
87b3d94504SStephan AßmusNote that Dan0, all it's successors and Zeta already have compatible USB stack - no patches
88b3d94504SStephan Aßmusare required.</li>
89b3d94504SStephan Aßmus  <li>Contents of distribution archive:
90b3d94504SStephan Aßmus<pre>    ReadMe.html      &lt;--- file you are reading now
91b3d94504SStephan Aßmus    <a href="install.sh">install.sh</a>       &lt;--- installation script
92b3d94504SStephan Aßmus    <a href="uninstall.sh">uninstall.sh</a>     &lt;--- uninstallation script
93b3d94504SStephan Aßmus    usb              &lt;--- The Module binary
94b3d94504SStephan Aßmus    <a href="usb_scsi.sample">usb_scsi.sample</a>  &lt;--- settings file sample
95b3d94504SStephan Aßmus    usb_scsi_logging &lt;--- logging daemon
96b3d94504SStephan Aßmus    <a href="usb_scsi.devices">usb_scsi.devices</a> &lt;--- definitions for "non-standard" devices
97b3d94504SStephan Aßmus    usb_dev_info     &lt;--- the tool to obtain device inforamtion</pre>
98b3d94504SStephan Aßmus  </li>
99b3d94504SStephan Aßmus  <li>Run <a href="install.sh"><strong>./install.sh</strong></a> to install The Module on your system.
100b3d94504SStephan AßmusThis script do the following:</li>
101b3d94504SStephan Aßmus  <ul>
102b3d94504SStephan Aßmus    <li>copies The Module binary to 
103b3d94504SStephan Aßmus          <strong>/boot/home/config/add-ons/kernel/busses/scsi/usb</strong>
104b3d94504SStephan Aßmus              directory</li>
105b3d94504SStephan Aßmus  </ul>
106b3d94504SStephan Aßmus  <ul>
107b3d94504SStephan Aßmus    <li>copies settings file to 
108b3d94504SStephan Aßmus          <strong>/boot/home/config/settings/kernel/drivers/usb_scsi</strong>
109b3d94504SStephan Aßmus              file</li>
110b3d94504SStephan Aßmus    <li>ask you to reboot your system or edit settings file. More
111b3d94504SStephan Aßmusinformation on settings file <a href="#3.4._A_couple_of_words_about_usb_scsi">is here</a>.
112b3d94504SStephan AßmusIf you doesn't reboot from script - you
113b3d94504SStephan Aßmushave to do it manually to let The Module work with updated settings.
114b3d94504SStephan Aßmus    </li>
115b3d94504SStephan Aßmus  </ul>
116b3d94504SStephan Aßmus  <li>After system rebooted, plug in your USB device into USB slot and
117b3d94504SStephan Aßmustry to open Tracker's "Mount" menu some times. In case if all goes OK -
118b3d94504SStephan Aßmusyou'll see some additional volumes available for mounting. Mount that
119b3d94504SStephan Aßmusone you
120b3d94504SStephan Aßmusthink is your USB mass storage and use it as usual "real" drives.</li>
121b3d94504SStephan Aßmus  <li>It is highly recommended to unmount your USB volume before
122b3d94504SStephan Aßmusunplugging device from USB slot. Some pending read/write operations can
123b3d94504SStephan Aßmusbe still active in background. If you break this process - 
124b3d94504SStephan Aßmus<font color="#cc0000"><b>YOU CAN LOOSE YOUR DATA</b></font>. Unmount
125b3d94504SStephan Aßmusit and wait until your USB volume icon is
126b3d94504SStephan Aßmusdisappeared from desktop and led on your device ( in case this led
127b3d94504SStephan Aßmusexists, of course ) turns off. To be sure you can run "sync" command from the Terminal.</li>
128b3d94504SStephan Aßmus  <li>[optional] To uninstall The Module from your system - run <a href="uninstall.sh"><strong>uninstall.sh</strong></a>
129b3d94504SStephan Aßmusfrom distribution archive or delete files mentioned in
130b3d94504SStephan Aßmusclause 3 of this section manually.</li>
131b3d94504SStephan Aßmus</ol>
132b3d94504SStephan Aßmus<a href="#Contents">Table
133b3d94504SStephan Aßmusof Contents</a>
134b3d94504SStephan Aßmus<h1><a name="2._Troubleshooting"></a>2. Troubleshooting</h1>
135b3d94504SStephan Aßmus<ol>
136b3d94504SStephan Aßmus  <li><strong>Is my USB device supported?</strong>
137b3d94504SStephan Aßmus    <ul>
138b3d94504SStephan Aßmus      <li>May be. Install this software, plug your device in and
139b3d94504SStephan Aßmustry to mount it. Or look for class / subclass / protocol values
140b3d94504SStephan Aßmusin usb device description and check against the following lists.
141b3d94504SStephan Aßmus        <ul>
142b3d94504SStephan Aßmus          <li>Supported class : 8</li>
143b3d94504SStephan Aßmus          <li>Supported subclasses ( command sets ) : 1, 2, 3, 4, 5, 6</li>
144b3d94504SStephan Aßmus          <li>Supported protocols: 0, 1, 80</li>
145b3d94504SStephan Aßmus        </ul>
146b3d94504SStephan AßmusAny combination of mentioned above class / subclass / protocol is supported.
147b3d94504SStephan Aßmus      </li>
148b3d94504SStephan Aßmus    </ul>
149b3d94504SStephan Aßmus  </li>
150b3d94504SStephan Aßmus  <li>I have installed this software on R5 + USB.patches but my <strong>system
151b3d94504SStephan Aßmusgoes to Kernel Debugger on very early booting stage</strong>. Help!
152b3d94504SStephan Aßmus    <ul>
153b3d94504SStephan Aßmus      <li>Edit <a href="#3.4._A_couple_of_words_about_usb_scsi">settings
154b3d94504SStephan Aßmusfile</a> and activate the following key:
155b3d94504SStephan Aßmus        <ul>
156b3d94504SStephan Aßmus          <li>ignore_sysinit2 true</li>
157b3d94504SStephan Aßmus        </ul>
158b3d94504SStephan Aßmus      </li>
159b3d94504SStephan Aßmus    </ul>
160b3d94504SStephan Aßmus  </li>
161b3d94504SStephan Aßmus  <li>I have installed this software and <strong>there are still no additional
162b3d94504SStephan Aßmusvolumes</strong> in Tracker's "Mount" menu.
163b3d94504SStephan Aßmus    <ul>
164b3d94504SStephan Aßmus      <li>Sometimes it is required to open "Mount" menu more than
165b3d94504SStephan Aßmusone time to see volumes.
166b3d94504SStephan Aßmus      </li>
167b3d94504SStephan Aßmus      <li>You can try open "Mount" menu with "Shift" button pressed and
168b3d94504SStephan Aßmusselect "Rescan All Devices" menu item to help the system recognize your device.
169b3d94504SStephan Aßmus      </li>
170b3d94504SStephan Aßmus      <li>Try to Rescan SCSI in DriveSetup.
171b3d94504SStephan Aßmus      </li>
172b3d94504SStephan Aßmus    </ul>
173b3d94504SStephan Aßmus  </li>
174b3d94504SStephan Aßmus  <li><strong>I still have no volumes to mount!!!</strong>
175b3d94504SStephan Aßmus    <ul>
176b3d94504SStephan Aßmus      <li>Please check the following:
177b3d94504SStephan Aßmus        <ul>
178b3d94504SStephan Aßmus          <li>[for R5 only. Not required for Dano/Zeta etc. ] your system
179b3d94504SStephan Aßmushas USB patches installed;</li>
180b3d94504SStephan Aßmus          <li>the binary file <strong>/boot/home/config/add-ons/kernel/busses/scsi/usb</strong>
181b3d94504SStephan Aßmusexists on your system;
182b3d94504SStephan Aßmus          </li>
183b3d94504SStephan Aßmus          <li>the settings file <strong>/boot/home/config/settings/kernel/drivers/usb_scsi</strong>
184b3d94504SStephan Aßmusexists on your system;</li>
185b3d94504SStephan Aßmus          <li>check that your device uses standard protocols and should be supported by
186b3d94504SStephan Aßmusthis module ( see clause 1 of this section )
187b3d94504SStephan Aßmus          </li>
188b3d94504SStephan Aßmus          <li>Despite of fact that latest <strong>versions of Zeta OS</strong> use this module, some of
189b3d94504SStephan Aßmuspre-releases of this OS have completely different stuff to support USB storage devices.
190b3d94504SStephan AßmusIn some circumstances those Zeta's modules can prevent this USB Support Module from correct working.
191b3d94504SStephan AßmusIn this situation you have to disable Zeta's USB Storage support. To do this go to
192b3d94504SStephan Aßmus/boot/beos/system/add-ons/kernel/busses/scsi/ diectory and rename or remove the
193b3d94504SStephan Aßmus<strong>usb</strong> and <strong>usb_scsi</strong> files. After rebooting your system
194b3d94504SStephan Aßmusyou should have updated USB Storage support. 
195b3d94504SStephan Aßmus          </li>
196b3d94504SStephan Aßmus        </ul>
197b3d94504SStephan Aßmus      </li>
198b3d94504SStephan Aßmus    </ul>
199b3d94504SStephan Aßmus  </li>
200b3d94504SStephan Aßmus  <li>STILL <strong>NOTHING TO MOUNT ! ! !</strong>
201b3d94504SStephan Aßmus    <ul>
202b3d94504SStephan Aßmus      <li>Looks like you are in trouble. <a href="#6.Contact_information">
203b3d94504SStephan Aßmus               Write your problem report</a> to developers.
204b3d94504SStephan Aßmus      </li>
205b3d94504SStephan Aßmus    </ul>
206b3d94504SStephan Aßmus  </li>
207b3d94504SStephan Aßmus  <li>I see <strong>a lot of empty SCSI devices in DriveSetup</strong> and SCSIProbe.
208b3d94504SStephan AßmusWhat is it?
209b3d94504SStephan Aßmus    <ul>
210b3d94504SStephan Aßmus      <li>Those "disks" are just reserved device entries - some kind of
211b3d94504SStephan Aßmusplaceholders for real devices you'll attach to your computer. Read
212b3d94504SStephan Aßmusabout this technique <a href="#3.3._Device_entries_reservation">here</a>.
213b3d94504SStephan Aßmus      </li>
214b3d94504SStephan Aßmus    </ul>
215b3d94504SStephan Aßmus  </li>
216b3d94504SStephan Aßmus  <li><strong>DriveSetup hangs on exit</strong>!?!
217b3d94504SStephan Aßmus    <ul>
218b3d94504SStephan Aßmus      <li>It is known bug. I don't know who is wrong with it. No
219b3d94504SStephan Aßmussolution at this time. Just kill this zombie.
220b3d94504SStephan Aßmus      </li>
221b3d94504SStephan Aßmus    </ul>
222b3d94504SStephan Aßmus  </li>
223b3d94504SStephan Aßmus  <li>I have found a bug! I have <strong>unmounted my USB floppy</strong>, unplug it
224b3d94504SStephan Aßmusthan plug in another device<strong> but still see the "floppy" volume</strong> in the mount
225b3d94504SStephan Aßmuslist.
226b3d94504SStephan Aßmus    <ul>
227b3d94504SStephan Aßmus      <li>The mounting in BeOS is broken. Just press "Shift" key before
228b3d94504SStephan Aßmusopening Tracker's "Mount" menu than select "Rescan Devices"
229b3d94504SStephan AßmusAfter some seconds try to mount your device again. Should work now.
230b3d94504SStephan Aßmus      </li>
231b3d94504SStephan Aßmus    </ul>
232b3d94504SStephan Aßmus  </li>
233b3d94504SStephan Aßmus  <li>I have set reserve_devices to maximal value but still <strong>no reserved device
234b3d94504SStephan Aßmusentries in DriveSetup</strong>.
235b3d94504SStephan Aßmus    <ul>
236b3d94504SStephan Aßmus      <li>Known bug. In some situations reservation doesn't work.
237b3d94504SStephan AßmusIt's reproducible with Adaptec SCSI controllers installed on your
238b3d94504SStephan Aßmussystem. You have to use DriveSetup for first mounting of device in this
239b3d94504SStephan Aßmussituation. Nothing is perfect in this World.
240b3d94504SStephan Aßmus      </li>
241b3d94504SStephan Aßmus    </ul>
242b3d94504SStephan Aßmus  </li>
243b3d94504SStephan Aßmus  <li>Does my Canon PowerShot A70 <strong>digital camera supported by this software?</strong>
244b3d94504SStephan Aßmus    <ul>
245b3d94504SStephan Aßmus      <li>No. It uses Picture Transfer Protocol (PTP) instead of USB Mass Storage (USBMS)
246b3d94504SStephan Aßmusone. You can check your camera information for Interface class. For USBMS it should
247b3d94504SStephan Aßmusbe 8, for PTP - 6.
248b3d94504SStephan Aßmus      </li>
249b3d94504SStephan Aßmus    </ul>
250