| blob | 94903e0cbebf36f2d62b405ed1181169690d42de |
1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH SCSA2USB 7D "Jul 28, 2008"
7 .SH NAME
8 scsa2usb \- SCSI to USB bridge driver
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBstorage@unit-address\fR
13 .fi
15 .SH DESCRIPTION
16 .sp
17 .LP
18 The \fBscsa2usb\fR driver is a \fBUSBA\fR (Solaris USB architecture) compliant
19 nexus driver that supports the \fIUSB Mass Storage Bulk Only Transport
20 Specification 1.0\fR and \fIUSB Control/Bulk/Interrupt (CBI) Transport
21 Specification 1.0\fR. The \fBscsa2usb\fR driver also supports USB storage
22 devices that implement CBI Transport without the interrupt completion for
23 status (that is, Control/Bulk (CB) devices.) It supports bus-powered and
24 self-powered USB mass storage devices. This nexus driver is both a USB client
25 driver and a \fBSCSA\fR HBA driver. As such, the \fBscsa2usb\fR driver only
26 supports storage devices that utilize the above two transports.
27 .sp
28 .LP
29 The \fBscsa2usb\fR driver also supports a \fBugen\fR(7D) interface allowing raw
30 access to the device, for example by \fBlibusb\fR(3LIB) applications, bypassing
31 the child \fBsd\fR(7D) or \fBst\fR(7D) driver. Because a libusb application
32 might change the state of the device, you should not access the disk or tape
33 concurrently.
34 .sp
35 .LP
36 The \fBscsa2usb\fR nexus driver maps \fBSCSA\fR target driver requests to
37 \fBUSBA\fR client driver requests.
38 .sp
39 .LP
40 The \fBscsa2usb\fR driver creates a child device info node for each logical
41 unit (LUN) on the mass storage device. The standard Solaris \fBSCSI\fR disk
42 driver or tape driver is attached to those nodes. Refer to \fBsd\fR(7D) or
43 \fBst\fR(7D).
44 .sp
45 .LP
46 This driver supports multiple LUN devices and creates a separate child device
47 info node for each LUN. All child LUN nodes attach to \fBsd\fR(7D) for disks or
48 \fBst\fR(7D) for tapes.
49 .sp
50 .LP
51 In previous releases, all USB disk storage devices were treated as removable
52 media devices and managed by \fBrmformat\fR(1) and volume management software.
53 In the current release, however, only disk storage devices with a removable bit
54 (RMB) value of \fB1\fR are removable. (The RMB is part of the device's SCSI
55 INQUIRY data.) See SCSI specifications T10/995D Revision 11a, T10/1236-D
56 Revision 20 or T10/1416-D Revision 23 for more information. However, for
57 backward compatibility, all USB disk storage devices can still be managed by
58 \fBrmformat\fR(1). With or without a volume manager, you can mount, eject,
59 hot remove and hot insert a 1394 mass storage device as the following sections
60 explain.
61 .sp
62 .LP
63 Some devices may be supported by the USB mass storage driver even though they
64 do not identify themselves as compliant with the USB mass storage class.
65 .sp
66 .LP
67 The \fBscsa2usb.conf\fR file contains an \fBattribute-override-list\fR that
68 lists the vendor ID, product ID, and revision for matching mass storage
69 devices, as well as fields for overriding the default device attributes. The
70 entries in this list are commented out by default and may be uncommented to
71 enable support of particular devices.
72 .sp
73 .LP
74 Follow the information given in the \fBscsa2usb.conf\fR file to see if a
75 particular device can be supported using the override information. Also see
76 http:/\fI/www.sun.com/io\fR. For example, by adding the following to the
77 \fBscsa2usb.conf\fR file, many USB memory sticks and card readers might operate
78 more reliably:
79 .sp
80 .in +2
81 .nf
82 attribute-override-list = "vid=* reduced-cmd-support=true";
83 .fi
84 .in -2
86 .sp
87 .LP
88 Note that this override applies to all USB mass storage devices and might be
89 inappropriate for a USB CD writer. If so, you can add an entry for each device
90 to the attribute override list.
91 .sp
92 .LP
93 If USB mass storage support is considered a security risk, this driver can be
94 disabled in \fB/etc/system\fR as follows:
95 .sp
96 .in +2
97 .nf
98 exclude: scsa2usb
99 .fi
100 .in -2
102 .sp
103 .LP
104 Alternatively, you can disable automatic handling of a device as described in
105 the following subsection.
106 .SS "Using Volume Management"
107 .sp
108 .LP
109 Disk storage devices are managed by Volume Manager. Software that manages
110 removable media creates a device nickname that can be listed with
111 \fBeject\fR(1) or \fBrmmount\fR(1). A device that is not mounted automatically
112 can be mounted using \fBrmmount\fR(1) under \fB/rmdisk/\fIlabel\fR\fR. Note
113 that the \fBmount\fR(1M) and \fBmount\fR(1M) commands do not accept nicknames;
114 you must use explicit device names with these commands.
115 .sp
116 .LP
117 See \fBrmmount\fR(1) to unmount the device and \fBeject\fR(1) to eject the
118 media. If the device is ejected while it is mounted, volume management software
119 unmounts the device before ejecting it. It also might kill any active
120 applications that are accessing the device.
121 .sp
122 .LP
123 Volume management software is hotplug-aware and normally mounts file systems on
124 USB mass storage devices if the file system is recognized. Before hot removing
125 the USB device, use \fBeject\fR(1) to unmount the file system. After the device
126 is removed, a console warning, such as "The disconnected device was busy,
127 please reconnect," might display. The warning is harmless and you can ignore
128 it.
129 .sp
130 .LP
131 You can disable the automatic mounting and unmounting of removable devices by
132 inserting a entry for a removable device in \fB/etc/vfstab\fR. In this entry,
133 you must set the \fBmount at boot\fR field to \fBno\fR. See \fBvfstab\fR(4).
134 See the \fISystem Administration Guide, Volume I\fR and \fISolaris Common
135 Desktop Environment: User's Guide\fR for details on how to manage a removable
136 device with CDE and Removable Media Manager. See \fBdtfile.1X\fR under CDE for
137 information on how to use Removable Media Manager.
138 .SS "Using \fBmount\fR and \fBumount\fR"
139 .sp
140 .LP
141 Use \fBmount\fR(1M) to explicitly mount the device and \fBumount\fR(1M) to
142 unmount the device. Use \fBeject\fR(1) to eject the media. After you have
143 explicitly mounted a removable device, you cannot use a nickname as an argument
144 to \fBeject\fR.
145 .sp
146 .LP
147 Removing the disk device while it is being accessed or mounted fails with a
148 console warning. To hot remove the disk device from the system, unmount the
149 file system, then kill all applications accessing the device. Next, hot remove
150 the device. A storage device can be hot inserted at any time.
151 .sp
152 .LP
153 For a comprehensive listing of (non-bootable) USB mass-storage devices that are
154 compatible with this driver, see \fBwww.sun.com/io\fR.
155 .SH DEVICE SPECIAL FILES
156 .sp
157 .LP
158 Disk block special file names are located in \fB/dev/dsk\fR, while raw file
159 names are located in \fB/dev/rdsk\fR. Tape raw file names are located in
160 \fB/dev/rmt\fR. Input/output requests to the devices must follow the same
161 restrictions as those for SCSI disks or tapes. Refer to \fBsd\fR(7D) or
162 \fBst\fR(7D).
163 .SH IOCTLS
164 .sp
165 .LP
166 Refer to \fBdkio\fR(7I) and \fBcdio\fR(7I).
167 .SH ERRORS
168 .sp
169 .LP
170 Refer to \fBsd\fR(7D) for disks or \fBst\fR(7D) for tapes.
171 .SH FILES
172 .sp
173 .LP
174 The device special files for the USB mass storage device are created like those
175 for a \fBSCSI\fR disk or SCSI tape. Refer to \fBsd\fR(7D) or \fBst\fR(7D).
176 .sp
177 .ne 2
178 .na
179 \fB\fB/dev/dsk/c\fIn\fRt\fIn\fRd\fIn\fRs\fIn\fR\fR\fR
180 .ad
181 .sp .6
182 .RS 4n
183 Block files for disks.
184 .RE
186 .sp
187 .ne 2
188 .na
189 \fB\fB/dev/rdsk/c\fIn\fRt\fIn\fRd\fIn\fRs\fIn\fR\fR\fR
190 .ad
191 .sp .6
192 .RS 4n
193 Raw files for disks.
194 .RE
196 .sp
197 .ne 2
198 .na
199 \fB/dev/usb/*/*/*\fR
200 .ad
201 .sp .6
202 .RS 4n
203 ugen(7D) nodes
204 .RE
206 .sp
207 .ne 2
208 .na
209 \fB\fB/dev/rmt/[0- 127][l,m,h,u,c][b][n]\fR\fR
210 .ad
211 .sp .6
212 .RS 4n
213 Raw files for tapes.
214 .RE
216 .sp
217 .ne 2
218 .na
219 \fB\fB/vol/dev/aliases/zip0\fR\fR
220 .ad
221 .sp .6
222 .RS 4n
223 Symbolic link to the character device for the media in Zip drive 0
224 .RE
226 .sp
227 .ne 2
228 .na
229 \fB\fB/vol/dev/aliases/jaz0\fR\fR
230 .ad
231 .sp .6
232 .RS 4n
233 Symbolic link to the character device for the media in Jaz drive 0.
234 .RE
236 .sp
237 .ne 2
238 .na
239 \fB\fB/vol/dev/aliases/rmdisk0\fR\fR
240 .ad
241 .sp .6
242 .RS 4n
243 Symbolic link to the character device for the media in removable drive 0. This
244 is a generic removable media device.
245 .RE
247 .sp
248 .ne 2
249 .na
250 \fB\fB/kernel/drv/scsa2usb\fR\fR
251 .ad
252 .sp .6
253 .RS 4n
254 32-bit x86 ELF kernel module
255 .RE
257 .sp
258 .ne 2
259 .na
260 \fB\fB/kernel/drv/amd64/scsa2usb\fR\fR
261 .ad
262 .sp .6
263 .RS 4n
264 64-bit x86 ELF kernel module
265 .RE
267 .sp
268 .ne 2
269 .na
270 \fB\fB/kernel/drv/sparcv9/scsa2usb\fR\fR
271 .ad
272 .sp .6
273 .RS 4n
274 64-bit SPARC ELF kernel module
275 .RE
277 .sp
278 .ne 2
279 .na
280 \fB\fB/kernel/drv/scsa2usb.conf\fR\fR
281 .ad
282 .sp .6
283 .RS 4n
284 Can be used to override specific characteristics.
285 .RE
287 .SH ATTRIBUTES
288 .sp
289 .LP
290 See \fBattributes\fR(5) for descriptions of the following attributes:
291 .sp
293 .sp
294 .TS
295 box;
296 c | c
297 l | l .
298 ATTRIBUTE TYPE ATTRIBUTE VALUE
299 _
300 Architecture SPARC, x86, PCI-based systems
301 .TE
303 .SH SEE ALSO
304 .sp
305 .LP
306 \fBcdrw\fR(1), \fBeject\fR(1), \fBrmformat\fR(1), \fBrmmount\fR(1),
307 \fBcfgadm_scsi\fR(1M), \fBcfgadm_usb\fR(1M), \fBfdisk\fR(1M), \fBmount\fR(1M),
308 \fBumount\fR(1M), \fBdtfile.1X\fR (in CDE man pages), \fBlibusb\fR(3LIB),
309 \fBscsi\fR(4), \fBvfstab\fR(4), \fBattributes\fR(5),
310 \fBieee1394\fR(7D)\fBsd\fR(7D), \fBst\fR(7D), \fBugen\fR(7D), \fBusba\fR(7D),
311 \fBpcfs\fR(7FS), \fBcdio\fR(7I), \fBdkio\fR(7I)
312 .sp
313 .LP
314 \fIWriting Device Drivers\fR
315 .sp
316 .LP
317 \fISystem Administration Guide, Volume I\fR
318 .sp
319 .LP
320 \fISolaris Common Desktop Environment: User's Guide\fR
321 .sp
322 .LP
323 \fIUniversal Serial Bus Specification 2.0\fR
324 .sp
325 .LP
326 \fIUniversal Serial Bus Mass Storage Class Specification Overview 1.0\fR
327 .sp
328 .LP
329 \fIUniversal Serial Bus Mass Storage Class Bulk-Only Transport Specification
330 1.0\fR
331 .sp
332 .LP
333 \fIUniversal Serial Bus Mass Storage Class Control/Bulk/Interrupt (CBI)
334 Transport Specification 1.0\fR
335 .sp
336 .LP
337 \fISystem Administration Guide: Basic Administration\fR
338 .sp
339 .LP
340 SCSI Specification \fIT10/995D Revision 11a\fR \(em March 1997
341 .sp
342 .LP
343 SCSI Specification\fIT10/1236-D Revision 20\fR \(em July 2001
344 .sp
345 .LP
346 SCSI Specification\fIT10/1416-D Revision 23\fR\(em May 2005
347 .sp
348 .LP
349 http://\fIwww.sun.com/io\fR
350 .SH DIAGNOSTICS
351 .sp
352 .LP
353 Refer to \fBsd\fR(7D) and \fBst\fR(7D).
354 .sp
355 .LP
356 In addition to being logged, the following messages may appear on the system
357 console. All messages are formatted in the following manner:
358 .sp
359 .in +2
360 .nf
361 Warning: <device path> (scsa2usb<instance number>): Error Message...
362 .fi
363 .in -2
364 .sp
366 .sp
367 .ne 2
368 .na
369 \fBCannot access <device>. Please reconnect.\fR
370 .ad
371 .sp .6
372 .RS 4n
373 There was an error in accessing the mass-storage device during reconnect.
374 Please reconnect the device.
375 .RE
377 .sp
378 .ne 2
379 .na
380 \fBDevice is not identical to the previous one on this port. Please disconnect
381 and reconnect.\fR
382 .ad
383 .sp .6
384 .RS 4n
385 Another USB device has been inserted on a port that was connected to a
386 mass-storage device. Please disconnect the USB device and reconnect the
387 mass-storage device back into that port.
388 .RE
390 .sp
391 .ne 2
392 .na
393 \fBReinserted device is accessible again.\fR
394 .ad
395 .sp .6
396 .RS 4n
397 The mass-storage device that was hot-removed from its USB slot has been
398 re-inserted to the same slot and is available for access.
399 .RE
401 .sp
402 .ne 2
403 .na
404 \fBPlease disconnect and reconnect this device.\fR
405 .ad
406 .sp .6
407 .RS 4n
408 A hotplug of the device is needed before it can be restored.
409 .RE
411 .sp
412 .LP
413 The following messages may be logged into the system log. They are formatted in
414 the following manner:
415 .sp
416 .in +2
417 .nf
418 <device path><scsa2usb<instance number>): message...
419 .fi
420 .in -2
421 .sp
423 .sp
424 .ne 2
425 .na
426 \fBInvalid <record> in scsa2usb.conf file entry.\fR
427 .ad
428 .sp .6
429 .RS 4n
430 An unrecognized record was specified in the \fBscsa2usb.conf\fR file.
431 .RE
433 .sp
434 .ne 2
435 .na
436 \fBPkt submitted with 0 timeout which may cause indefinite hangs.\fR
437 .ad
438 .sp .6
439 .RS 4n
440 An application submitted a request but did not specify a timeout.
441 .RE
443 .sp
444 .ne 2
445 .na
446 \fBSyncing not supported.\fR
447 .ad
448 .sp .6
449 .RS 4n
450 Syncing after a panic is not supported. The filesystem may be corrupted.
451 .RE
453 .sp
454 .ne 2
455 .na
456 \fBscsa2usb.conf override: <record>.\fR
457 .ad
458 .sp .6
459 .RS 4n
460 An override record specified in \fBscsa2usb.conf\fR was applied. Examples of an
461 override record applied to a device with vendor ID 123 and product ID 456 are:
462 .sp
463 .in +2
464 .nf
465 vid=0x123 pid=0x456 reduced-cmd-support=true
467 or
469 vid=* reduced-cmd-support=true
470 .fi
471 .in -2
473 \&...meaning that the override record is applied to this device and all other
474 USB mass storage devices.
475 .RE
477 .SH NOTES
478 .sp
479 .LP
480 The Zip 100 drive does not comply with \fIUniversal Serial Bus Specification
481 1.0\fR and cannot be power managed. Power Management support for Zip 100 has
482 been disabled.
483 .sp
484 .LP
485 If the system panics while a UFS file system is mounted on the mass storage
486 media, no syncing will take place for the disk mass-storage device. (Syncing is
487 not supported by the \fBscsa2usb\fR driver.) As a result, the file system on
488 the media will not be consistent on reboot.
489 .sp
490 .LP
491 If a PCFS file system is mounted, no syncing is needed and the filesystem will
492 be consistent on reboot.
493 .sp
494 .LP
495 If a mass-storage device is busy, system suspend cannot proceed and the system
496 will immediately resume again.
497 .sp
498 .LP
499 Attempts to remove a mass-storage device from the system will fail. The failure
500 will be logged to the console. An attempt to replace the removed device with
501 some other USB device will also fail. To successfully remove a USB mass-storage
502 device you must "close" all references to it.
503 .sp
504 .LP
505 An Iomega Zip 100Mb disk cannot be formatted on an Iomega Zip250 drive. See the
506 Iomega web site at \fIhttp://www.iomega.com\fR for details.
507 .sp
508 .LP
509 Concurrent I/O to devices with multiple LUNs on the same device is not
510 supported.
511 .sp
512 .LP
513 Some USB CD-RW devices may perform inadequately at their advertised speeds. To
514 compensate, use USB CD-RW devices at lower speeds (2X versus 4X). See
515 \fBcdrw(1)\fR for details.
516 .sp
517 .LP
518 This driver also supports CBI devices that do not use USB interrupt pipe for
519 status completion.