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 January 27, 2017
  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 iscsi"
  42 .Cd "device ctl"
  43 .Cd "device cfumass"
  44 .Ed
  45 .Pp
  46 The driver module can also be loaded at boot by adding this line to
  47 .Xr loader.conf 5 :
  48 .Bd -literal -offset indent
  49 cfumass_load="YES"
  50 .Ed
  51 .Sh DESCRIPTION
  52 The
  53 .Nm
  54 driver provides device side support for emulating an USB mass storage
  55 device compliant with the USB Mass Storage Class Bulk-Only (BBB) Transport
  56 specification, implemented as a
  57 .Xr ctl 4
  58 frontend driver.
  59 .Pp
  60 To use
  61 .Nm :
  62 .Bl -bullet
  63 .It
  64 .Xr cfumass 4
  65 must be loaded as a module or compiled into the kernel.
  66 .It
  67 The USB Mass Storage template must be chosen by setting the
  68 .Va hw.usb.template
  69 sysctl to 0.
  70 .It
  71 The USB OTG port must be working in USB device-side mode.
  72 This happens automatically upon connection to a USB host.
  73 .It
  74 There must be a
  75 .Xr ctl 4
  76 LUN configured for the
  77 .Pa cfumass
  78 port.
  79 .El
  80 .Pp
  81 Upon loading, the driver creates a
  82 .Xr ctl 4
  83 port named
  84 .Pa cfumass ,
  85 presenting the first LUN mapped for that port - usually LUN 0 - to
  86 the USB host.
  87 See
  88 .Xr ctl.conf 5
  89 and
  90 .Xr ctld 8
  91 for details on configuring the LUN.
  92 .Sh SYSCTL VARIABLES
  93 These variables are available as both
  94 .Xr sysctl 8
  95 variables and
  96 .Xr loader 8
  97 tunables:
  98 .Bl -tag -width indent
  99 .It Va hw.usb.cfumass.debug
 100 Verbosity level for log messages from the
 101 .Nm
 102 driver.
 103 Set to 0 to disable logging or 1 to warn about potential problems.
 104 Larger values enable debugging output.
 105 Defaults to 1.
 106 .It Va hw.usb.cfumass.ignore_stop
 107 Ignore START STOP UNIT SCSI commands with START and LOEJ bits cleared.
 108 Some initiators send that command to stop the target when the user
 109 attempts to gracefully eject the drive, but fail to start it when the
 110 drive is reconnected.
 111 Set to 0 to handle the command in a standards-compliant way,
 112 1 to ignore it and log a warning, or 2 to ignore it silently.
 113 Defaults to 1.
 114 .It Va hw.usb.cfumass.max_lun
 115 Max LUN number to report to the initiator (USB host).
 116 Must be between 0 and 15.
 117 Some initiators incorrectly handle values larger than 0.
 118 Defaults to 0.
 119 .El
 120 .Sh SEE ALSO
 121 .Xr ctl 4 ,
 122 .Xr umass 4 ,
 123 .Xr usb 4 ,
 124 .Xr usb_template 4 ,
 125 .Xr ctl.conf 5 ,
 126 .Xr ctld 8
 127 .Sh HISTORY
 128 The
 129 .Nm
 130 driver first appeared in
 131 .Fx 11.1 .
 132 .Sh AUTHORS
 133 The
 134 .Nm
 135 driver was developed by
 136 .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
 137 under sponsorship from the FreeBSD Foundation.