share/man/man4/cfumass.4

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