xref: /freebsd/share/man/man4/cfumass.4 (revision 84943d6f38e936ac3b7a3947ca26eeb27a39f938)
1.\" Copyright (c) 2017 The FreeBSD Foundation
2.\"
3.\" This software was developed by Edward Tomasz Napierala under sponsorship
4.\" from the FreeBSD Foundation.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25.\" SUCH DAMAGE.
26.Dd April 21, 2018
27.Dt CFUMASS 4
28.Os
29.Sh NAME
30.Nm cfumass
31.Nd USB device side support for Mass Storage Class Transport
32.Sh SYNOPSIS
33This driver can be compiled into the kernel by placing these lines in
34the kernel configuration file:
35.Bd -ragged -offset indent
36.Cd "device usb"
37.Cd "device usb_template"
38.Cd "device ctl"
39.Cd "device cfumass"
40.Ed
41.Pp
42The driver module can also be loaded at boot by adding this line to
43.Xr loader.conf 5 :
44.Bd -literal -offset indent
45cfumass_load="YES"
46.Ed
47.Sh DESCRIPTION
48The
49.Nm
50driver provides device side support for emulating an USB mass storage
51device compliant with the USB Mass Storage Class Bulk-Only (BBB) Transport
52specification, implemented as a
53.Xr ctl 4
54frontend driver.
55.Pp
56To use
57.Nm :
58.Bl -bullet
59.It
60.Nm cfumass
61must be loaded as a module or compiled into the kernel.
62.It
63The USB Mass Storage template must be chosen by setting the
64.Va hw.usb.template
65sysctl to 0.
66.It
67The USB OTG port must be working in USB device-side mode.
68This happens automatically upon connection to a USB host.
69.It
70There must be a
71.Xr ctl 4
72LUN configured for the
73.Pa cfumass
74port.
75.El
76.Pp
77Upon loading, the driver creates a
78.Xr ctl 4
79port named
80.Pa cfumass ,
81presenting the first LUN mapped for that port - usually LUN 0 - to
82the USB host.
83See
84.Xr ctl.conf 5
85and
86.Xr ctld 8
87for details on configuring the LUN.
88See the
89.Cm cfumass_enable
90and
91.Cm cfumass_dir
92.Xr rc 8
93variables in
94.Xr rc.conf 5
95for an automated way to configure it at boot.
96.Sh SYSCTL VARIABLES
97These variables are available as both
98.Xr sysctl 8
99variables and
100.Xr loader 8
101tunables:
102.Bl -tag -width indent
103.It Va hw.usb.cfumass.debug
104Verbosity level for log messages from the
105.Nm
106driver.
107Set to 0 to disable logging or 1 to warn about potential problems.
108Larger values enable debugging output.
109Defaults to 1.
110.It Va hw.usb.cfumass.ignore_stop
111Ignore START STOP UNIT SCSI commands with START and LOEJ bits cleared.
112Some initiators send that command to stop the target when the user
113attempts to gracefully eject the drive, but fail to start it when the
114drive is reconnected.
115Set to 0 to handle the command in a standards-compliant way,
1161 to ignore it and log a warning, or 2 to ignore it silently.
117Defaults to 1.
118.It Va hw.usb.cfumass.max_lun
119Max LUN number to report to the initiator (USB host).
120Must be between 0 and 15.
121Some initiators incorrectly handle values larger than 0.
122Defaults to 0.
123.El
124.Sh SEE ALSO
125.Xr ctl 4 ,
126.Xr umass 4 ,
127.Xr usb 4 ,
128.Xr usb_template 4 ,
129.Xr ctl.conf 5 ,
130.Xr ctld 8
131.Sh HISTORY
132The
133.Nm
134driver first appeared in
135.Fx 11.1 .
136.Sh AUTHORS
137The
138.Nm
139driver was developed by
140.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
141under sponsorship from the FreeBSD Foundation.
142