freebsd-nq/share/man/man4/umass.4

.\" Copyright (c) 1999
.\"	Nick Hibma <n_hibma@FreeBSD.org>. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd January 27, 2020
.Dt UMASS 4
.Os
.Sh NAME
.Nm umass
.Nd USB Mass Storage Devices driver
.Sh SYNOPSIS
To compile this driver into the kernel,
place the following line in your
kernel configuration file:
.Bd -ragged -offset indent
.Cd "device scbus"
.Cd "device usb"
.Cd "device umass"
.Ed
.Pp
Alternatively, to load the driver as a
module at boot time, place the following line in
.Xr loader.conf 5 :
.Bd -literal -offset indent
umass_load="YES"
.Ed
.Sh DESCRIPTION
The
.Nm
driver provides support for Mass Storage devices that attach to the USB
port.
.Pp
To use the
.Nm
driver,
.Xr usb 4
and one of
.Xr uhci 4
or
.Xr ohci 4
or
.Xr ehci 4
or
.Xr xhci 4
must be configured in the kernel.
Additionally, since
.Nm
uses the SCSI subsystem and sometimes acts as a SCSI device, it
requires
.Xr da 4
and
.Xr scbus 4
to be included in the kernel.
.Sh EXAMPLES
.Bd -literal -offset indent
device umass
device scbus
device da
device pass
.Ed
.Pp
Add the
.Nm
driver to the kernel.
.Pp
.Bd -literal -offset indent
camcontrol rescan 0:0:0
camcontrol rescan 0:0:1
camcontrol rescan 0:0:2
camcontrol rescan 0:0:3
.Ed
.Pp
Rescan all slots on a multi-slot flash reader, where the slots map to separate
LUNs on a single SCSI ID.
Typically only the first slot will be enabled at boot time.
This assumes that the flash reader is the first SCSI bus in the system and has 4 slots.
.Sh SEE ALSO
.Xr cfumass 4 ,
.Xr ehci 4 ,
.Xr ohci 4 ,
.Xr uhci 4 ,
.Xr usb 4 ,
.Xr xhci 4 ,
.Xr camcontrol 8
.\".Sh HISTORY
.Sh AUTHORS
.An -nosplit
The
.Nm
driver was written by
.An MAEKAWA Masahide Aq Mt bishop@rr.iij4u.or.jp
and
.An Nick Hibma Aq Mt n_hibma@FreeBSD.org .
.Pp
This manual page was written by
.An Nick Hibma Aq Mt n_hibma@FreeBSD.org .
Add the USB Mass Storage manual page 1999-05-09 19:35:51 +00:00			`.\" Copyright (c) 1999`
Update @freebsd.org email addresses to @FreeBSD.org as is the precedent. 2000-10-26 15:30:44 +00:00			`.\" Nick Hibma <n_hibma@FreeBSD.org>. All rights reserved.`
Add the USB Mass Storage manual page 1999-05-09 19:35:51 +00:00			`.\"`
			`.\" Redistribution and use in source and binary forms, with or without`
			`.\" modification, are permitted provided that the following conditions`
			`.\" are met:`
			`.\" 1. Redistributions of source code must retain the above copyright`
			`.\" notice, this list of conditions and the following disclaimer.`
			`.\" 2. Redistributions in binary form must reproduce the above copyright`
			`.\" notice, this list of conditions and the following disclaimer in the`
			`.\" documentation and/or other materials provided with the distribution.`
			`.\"`
Use our preferred license text (no more "voices in his head"). While here, also move to a 2-clause license. From n_hibma@: "The 3rd clause was originally there for a reason, but I guess that it is safe to assume that no one can assume endorsement by me or anyone else without prior consent on anything really, so we might as well remove that clause." Approved by: n_hibma 2010-03-04 22:06:57 +00:00			.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
Add the USB Mass Storage manual page 1999-05-09 19:35:51 +00:00			`.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE`
			`.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE`
Use our preferred license text (no more "voices in his head"). While here, also move to a 2-clause license. From n_hibma@: "The 3rd clause was originally there for a reason, but I guess that it is safe to assume that no one can assume endorsement by me or anyone else without prior consent on anything really, so we might as well remove that clause." Approved by: n_hibma 2010-03-04 22:06:57 +00:00			`.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE`
			`.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL`
			`.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS`
			`.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)`
			`.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT`
			`.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY`
			`.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF`
			`.\" SUCH DAMAGE.`
Add the USB Mass Storage manual page 1999-05-09 19:35:51 +00:00			`.\"`
Fixed the misplaced $FreeBSD$. 2005-02-09 18:07:17 +00:00			`.\" $FreeBSD$`
Add the USB Mass Storage manual page 1999-05-09 19:35:51 +00:00			`.\"`
Remove old device list The device list hasn't aged well. All these devices are over a decade old. umass supports thunb drives almost universally, and the list is too long to try to list here. Remove some obsolete advice as well. This isn't the place to talk about how to create FAT filesystems, nor now to mount them. The only advice that's still useful is the rescanning of a multi-slot flash adapater. MFC After: 3 days 2020-01-28 00:36:46 +00:00			`.Dd January 27, 2020`
* remove i386 specific mark * some style and syntax fixes * some duplicated $FreeBSD$ tags removed 1999-11-15 23:14:32 +00:00			`.Dt UMASS 4`
mdoc(7) police: removed HISTORY info from the .Os call. 2001-07-10 15:31:11 +00:00			`.Os`
Add the USB Mass Storage manual page 1999-05-09 19:35:51 +00:00			`.Sh NAME`
			`.Nm umass`
mdoc(7) police: normalize .Nd. 2001-04-18 15:54:10 +00:00			`.Nd USB Mass Storage Devices driver`
Add the USB Mass Storage manual page 1999-05-09 19:35:51 +00:00			`.Sh SYNOPSIS`
Use our standard section 4 SYNOPSIS. MFC after: 3 days 2006-11-22 21:30:02 +00:00			`To compile this driver into the kernel,`
			`place the following line in your`
			`kernel configuration file:`
			`.Bd -ragged -offset indent`
List more dependencies for these drivers. While here, convert atapicam(4) to use our standard section 4 SYNOPSIS layout. PR: 132525 Submitted by: gcooper MFC after: 3 days 2009-10-22 11:35:12 +00:00			`.Cd "device scbus"`
			`.Cd "device usb"`
Second round of config related changes to the manpages. device blah0 -> device blah for PCI devices and busses. 2000-01-23 16:13:26 +00:00			`.Cd "device umass"`
Use our standard section 4 SYNOPSIS. MFC after: 3 days 2006-11-22 21:30:02 +00:00			`.Ed`
			`.Pp`
			`Alternatively, to load the driver as a`
			`module at boot time, place the following line in`
			`.Xr loader.conf 5 :`
			`.Bd -literal -offset indent`
			`umass_load="YES"`
			`.Ed`
Add the USB Mass Storage manual page 1999-05-09 19:35:51 +00:00			`.Sh DESCRIPTION`
			`The`
			`.Nm`
			`driver provides support for Mass Storage devices that attach to the USB`
Remove single-space hard sentence breaks. These degrade the quality of the typeset output, tend to make diffs harder to read and provide bad examples for new-comers to mdoc. 2000-03-01 14:50:24 +00:00			`port.`
Reflect the fact that we supported the Y-E Data floppy as well. 2000-03-18 17:59:27 +00:00			`.Pp`
- add a HARDWARE section based on the hardware notes and the devices already listed in the manpage - reword some DESCRIPTION sentences - Xref ehci(4) - bump .Dd MFC after: 3 days 2004-12-17 18:35:38 +00:00			`To use the`
			`.Nm`
			`driver,`
			`.Xr usb 4`
			`and one of`
			`.Xr uhci 4`
			`or`
			`.Xr ohci 4`
Update UMASS manual page to mention newer host controller drivers. Submitted by: Aseem Jolly <aseem.jolly@gmail.com> 2014-04-19 06:32:51 +00:00			`or`
			`.Xr ehci 4`
Remove EOL whitespace. Found with: mandoc -Tlint 2014-12-21 10:04:26 +00:00			`or`
Update UMASS manual page to mention newer host controller drivers. Submitted by: Aseem Jolly <aseem.jolly@gmail.com> 2014-04-19 06:32:51 +00:00			`.Xr xhci 4`
- add a HARDWARE section based on the hardware notes and the devices already listed in the manpage - reword some DESCRIPTION sentences - Xref ehci(4) - bump .Dd MFC after: 3 days 2004-12-17 18:35:38 +00:00			`must be configured in the kernel.`
Synchronize with notes in GENERIC and note the kernel dependency on scbus(4). MFC after: 7 days 2005-01-18 20:23:47 +00:00			`Additionally, since`
			`.Nm`
			`uses the SCSI subsystem and sometimes acts as a SCSI device, it`
			`requires`
- add a HARDWARE section based on the hardware notes and the devices already listed in the manpage - reword some DESCRIPTION sentences - Xref ehci(4) - bump .Dd MFC after: 3 days 2004-12-17 18:35:38 +00:00			`.Xr da 4`
Synchronize with notes in GENERIC and note the kernel dependency on scbus(4). MFC after: 7 days 2005-01-18 20:23:47 +00:00			`and`
			`.Xr scbus 4`
			`to be included in the kernel.`
mdoc(7) police: use certified section headers wherever possible. 2000-11-17 11:44:16 +00:00			`.Sh EXAMPLES`
For multi-line blocks of literal text, please use -literal displays. 2003-05-20 22:08:51 +00:00			`.Bd -literal -offset indent`
			`device umass`
			`device scbus`
			`device da`
			`device pass`
			`.Ed`
Add the USB Mass Storage manual page 1999-05-09 19:35:51 +00:00			`.Pp`
			`Add the`
mdoc(7) police: use the new features of the Nm macro. 2000-11-20 18:41:33 +00:00			`.Nm`
Add the USB Mass Storage manual page 1999-05-09 19:35:51 +00:00			`driver to the kernel.`
			`.Pp`
For multi-line blocks of literal text, please use -literal displays. 2003-05-20 22:08:51 +00:00			`.Bd -literal -offset indent`
			`camcontrol rescan 0:0:0`
			`camcontrol rescan 0:0:1`
			`camcontrol rescan 0:0:2`
			`camcontrol rescan 0:0:3`
			`.Ed`
Note that Sitecom CN-300 MultiFlash works with FreeBSD and provide example of utilizing multiple slots on a multi-slot card reader. PR: docs/49036 Submitted by: Scott Mitchell <scott+freebsd@fishballoon.org> MFC after: 3 days 2003-04-07 11:26:54 +00:00			`.Pp`
			`Rescan all slots on a multi-slot flash reader, where the slots map to separate`
For multi-line blocks of literal text, please use -literal displays. 2003-05-20 22:08:51 +00:00			`LUNs on a single SCSI ID.`
			`Typically only the first slot will be enabled at boot time.`
Remove old device list The device list hasn't aged well. All these devices are over a decade old. umass supports thunb drives almost universally, and the list is too long to try to list here. Remove some obsolete advice as well. This isn't the place to talk about how to create FAT filesystems, nor now to mount them. The only advice that's still useful is the rescanning of a multi-slot flash adapater. MFC After: 3 days 2020-01-28 00:36:46 +00:00			`This assumes that the flash reader is the first SCSI bus in the system and has 4 slots.`
Add the USB Mass Storage manual page 1999-05-09 19:35:51 +00:00			`.Sh SEE ALSO`
Add USB Mass Storage CTL frontend. This makes it possible for USB OTG-capable hardware to implement device side of USB Mass Storage, ie pretend it's a flash drive. It's configured in the same way as other CTL frontends, using ctladm(8) or ctld(8). Differently from usfs(4), all the configuration can be done without rebuilding the kernel. Testing and review is welcome. Right now I'm still moving, and I don't have access to my test environment, so I'm somewhat reluctant to making larger changes to this code; on the other hand I don't want to let it sit on Phab until my testing setup is back, because I want to get it into 11.1-RELEASE. Reviewed by: emaste (cursory), wblock (man page) MFC after: 2 weeks Relnotes: yes Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D8787 2017-02-19 17:47:43 +00:00			`.Xr cfumass 4 ,`
- add a HARDWARE section based on the hardware notes and the devices already listed in the manpage - reword some DESCRIPTION sentences - Xref ehci(4) - bump .Dd MFC after: 3 days 2004-12-17 18:35:38 +00:00			`.Xr ehci 4 ,`
Add the USB Mass Storage manual page 1999-05-09 19:35:51 +00:00			`.Xr ohci 4 ,`
			`.Xr uhci 4 ,`
			`.Xr usb 4 ,`
Sort SEE ALSO 2014-12-26 22:30:18 +00:00			`.Xr xhci 4 ,`
Assorted markup, spelling, and grammar fixes. 2004-06-16 08:33:57 +00:00			`.Xr camcontrol 8`
Add the USB Mass Storage manual page 1999-05-09 19:35:51 +00:00			`.\".Sh HISTORY`
Various man page cleanup: - Sort xrefs - FreeBSD.ORG -> FreeBSD.org - Be consistent with section names as outlined in mdoc(7). - Other misc mdoc cleanup. PR: doc/13144 Submitted by: Alexey M. Zelkin <phantom@cris.net> 1999-08-15 10:48:36 +00:00			`.Sh AUTHORS`
mdoc(7) police: do not split author names in the AUTHORS section. 2000-11-22 09:35:58 +00:00			`.An -nosplit`
Add the USB Mass Storage manual page 1999-05-09 19:35:51 +00:00			`The`
mdoc(7) police: use the new features of the Nm macro. 2000-11-20 18:41:33 +00:00			`.Nm`
Add the USB Mass Storage manual page 1999-05-09 19:35:51 +00:00			`driver was written by`
use .Mt to mark up email addresses consistently (final part) PR: 191174 Submitted by: Franco Fichtner <franco at lastsummer.de> 2014-06-26 21:46:14 +00:00			`.An MAEKAWA Masahide Aq Mt bishop@rr.iij4u.or.jp`
Add the USB Mass Storage manual page 1999-05-09 19:35:51 +00:00			`and`
use .Mt to mark up email addresses consistently (final part) PR: 191174 Submitted by: Franco Fichtner <franco at lastsummer.de> 2014-06-26 21:46:14 +00:00			`.An Nick Hibma Aq Mt n_hibma@FreeBSD.org .`
Add the USB Mass Storage manual page 1999-05-09 19:35:51 +00:00			`.Pp`
			`This manual page was written by`
use .Mt to mark up email addresses consistently (final part) PR: 191174 Submitted by: Franco Fichtner <franco at lastsummer.de> 2014-06-26 21:46:14 +00:00			`.An Nick Hibma Aq Mt n_hibma@FreeBSD.org .`