share/man/man4/mpr.4

   1 .\"
   2 .\" Copyright (c) 2010 Spectra Logic Corporation
   3 .\" Copyright (c) 2014 LSI Corp
   4 .\" Copyright (c) 2016 Avago Technologies
   5 .\" Copyright (c) 2016 Broadcom Ltd.
   6 .\" All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions, and the following disclaimer,
  13 .\"    without modification.
  14 .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer
  15 .\"    substantially similar to the "NO WARRANTY" disclaimer below
  16 .\"    ("Disclaimer") and any redistribution must be conditioned upon
  17 .\"    including a substantially similar Disclaimer requirement for further
  18 .\"    binary redistribution.
  19 .\"
  20 .\" NO WARRANTY
  21 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
  24 .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25 .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  29 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  30 .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  31 .\" POSSIBILITY OF SUCH DAMAGES.
  32 .\"
  33 .\" mpr driver man page.
  34 .\"
  35 .\" Author: Ken Merry <ken@FreeBSD.org>
  36 .\" Author: Stephen McConnell <slm@FreeBSD.org>
  37 .\"
  38 .\" $Id$
  39 .\" $FreeBSD$
  40 .\"
  41 .Dd April 29, 2016
  42 .Dt MPR 4
  43 .Os
  44 .Sh NAME
  45 .Nm mpr
  46 .Nd "LSI Fusion-MPT 3 IT/IR 12Gb/s Serial Attached SCSI/SATA driver"
  47 .Sh SYNOPSIS
  48 To compile this driver into the kernel, place these lines in the kernel
  49 configuration file:
  50 .Bd -ragged -offset indent
  51 .Cd "device pci"
  52 .Cd "device scbus"
  53 .Cd "device mpr"
  54 .Ed
  55 .Pp
  56 The driver can be loaded as a module at boot time by placing this line in
  57 .Xr loader.conf 5 :
  58 .Bd -literal -offset indent
  59 mpr_load="YES"
  60 .Ed
  61 .Sh DESCRIPTION
  62 The
  63 .Nm
  64 driver provides support for Broadcom Ltd./Avago Tech (LSI)
  65 Fusion-MPT 3 IT/IR
  66 .Tn SAS
  67 controllers.
  68 .Sh HARDWARE
  69 These controllers are supported by the
  70 .Nm
  71 driver:
  72 .Pp
  73 .Bl -bullet -compact
  74 .It
  75 Broadcom Ltd./Avago Tech (LSI) SAS 3004 (4 Port SAS)
  76 .It
  77 Broadcom Ltd./Avago Tech (LSI) SAS 3008 (8 Port SAS)
  78 .It
  79 Broadcom Ltd./Avago Tech (LSI) SAS 3108 (8 Port SAS)
  80 .It
  81 Broadcom Ltd./Avago Tech (LSI) SAS 3216 (16 Port SAS)
  82 .It
  83 Broadcom Ltd./Avago Tech (LSI) SAS 3224 (24 Port SAS)
  84 .El
  85 .Sh CONFIGURATION
  86 .Pp
  87 In all tunable descriptions below, X represents the adapter number.
  88 .Pp
  89 To disable MSI interrupts for all
  90 .Nm
  91 driver instances, set this tunable value in
  92 .Xr loader.conf 5 :
  93 .Bd -literal -offset indent
  94 hw.mpr.disable_msi=1
  95 .Ed
  96 .Pp
  97 To disable MSI interrupts for a specific
  98 .Nm
  99 driver instance, set this tunable value in
 100 .Xr loader.conf 5 :
 101 .Bd -literal -offset indent
 102 dev.mpr.X.disable_msi=1
 103 .Ed
 104 .Pp
 105 To disable MSI-X interrupts for all
 106 .Nm
 107 driver instances, set this tunable value in
 108 .Xr loader.conf 5 :
 109 .Bd -literal -offset indent
 110 hw.mpr.disable_msix=1
 111 .Ed
 112 .Pp
 113 To disable MSI-X interrupts for a specific
 114 .Nm
 115 driver instance, set this tunable value in
 116 .Xr loader.conf 5 :
 117 .Bd -literal -offset indent
 118 dev.mpr.X.disable_msix=1
 119 .Ed
 120 .Pp
 121 To set the maximum number of DMA chains allocated for all adapters, set
 122 this tunable in
 123 .Xr loader.conf 5 :
 124 .Bd -literal -offset indent
 125 hw.mpr.max_chains=NNNN
 126 .Ed
 127 .Pp
 128 To set the maximum number of DMA chains allocated for a specific adapter,
 129 set this tunable in
 130 .Xr loader.conf 5 :
 131 .Bd -literal -offset indent
 132 dev.mpr.X.max_chains=NNNN
 133 .Ed
 134 .Pp
 135 The default max_chains value is 2048.
 136 .Pp
 137 The current number of free chain frames is stored in the
 138 dev.mpr.X.chain_free
 139 .Xr sysctl 8
 140 variable.
 141 .Pp
 142 The lowest number of free chain frames seen since boot is stored in the
 143 dev.mpr.X.chain_free_lowwater
 144 .Xr sysctl 8
 145 variable.
 146 .Pp
 147 The number of times that chain frame allocations have failed since boot is
 148 stored in the
 149 dev.mpr.X.chain_alloc_fail
 150 .Xr sysctl 8
 151 variable.
 152 This can be used to determine whether the max_chains tunable should be
 153 increased to help performance.
 154 .Pp
 155 The current number of active I/O commands is shown in the
 156 dev.mpr.X.io_cmds_active
 157 .Xr sysctl 8
 158 variable.
 159 .Pp
 160 The highest number of active I/O commands seen since boot is stored in the
 161 dev.mpr.X.io_cmds_highwater
 162 .Xr sysctl 8
 163 variable.
 164 .Pp
 165 Devices can be excluded from
 166 .Nm
 167 control for all adapters by setting this tunable in
 168 .Xr loader.conf 5 :
 169 .Bd -literal -offset indent
 170 hw.mpr.exclude_ids=Y
 171 .Ed
 172 .Pp
 173 Y represents the target ID of the device.
 174 If more than one device is to be excluded, target IDs are separated by commas.
 175 .Pp
 176 Devices can be excluded from
 177 .Nm
 178 control for a specific adapter by setting this tunable in
 179 .Xr loader.conf 5 :
 180 .Bd -literal -offset indent
 181 dev.mpr.X.exclude_ids=Y
 182 .Ed
 183 .Pp
 184 Y represents the target ID of the device.
 185 If more than one device is to be excluded, target IDs are separated by commas.
 186 .Pp
 187 The adapter can issue the
 188 .Sy StartStopUnit
 189 SCSI command to SATA direct-access devices during shutdown.
 190 This allows the device to quiesce powering down.
 191 To control this feature for all adapters, set the
 192 .Bd -literal -offset indent
 193 hw.mpr.enable_ssu
 194 .Ed
 195 .Pp
 196 tunable in
 197 .Xr loader.conf 5
 198 to one of these values:
 199 .Bl -tag -width 6n -offset indent
 200 .It 0
 201 Do not send SSU to either HDDs or SSDs.
 202 .It 1
 203 Send SSU to SSDs, but not to HDDs.
 204 This is the default value.
 205 .It 2
 206 Send SSU to HDDs, but not to SSDs.
 207 .It 3
 208 Send SSU to both HDDs and SSDs.
 209 .El
 210 .Pp
 211 To control the feature for a specific adapter, set this tunable value in
 212 .Xr loader.conf 5 :
 213 .Bd -literal -offset indent
 214 dev.mpr.X.enable_ssu
 215 .Ed
 216 .Pp
 217 The same set of values are valid when setting this tunable for all adapters.
 218 .Pp
 219 SATA disks that take several seconds to spin up and fail the SATA Identify
 220 command might not be discovered by the driver.
 221 This problem can sometimes be overcome by increasing the value of the spinup
 222 wait time in
 223 .Xr loader.conf 5 :
 224 with the
 225 .Bd -literal -offset indent
 226 hw.mpr.spinup_wait_time=NNNN
 227 .Ed
 228 .Pp
 229 tunable.
 230 NNNN represents the number of seconds to wait for SATA devices to spin up when
 231 the device fails the initial SATA Identify command.
 232 .Pp
 233 Spinup wait times can be set for specific adapters in
 234 .Xr loader.conf 5 :
 235 with the
 236 .Bd -literal -offset indent
 237 dev.mpr.X.spinup_wait_time=NNNN
 238 .Ed
 239 .Pp
 240 tunable.
 241 NNNN is the number of seconds to wait for SATA devices to spin up when they fail
 242 the initial SATA Identify command.
 243 .Sh DEBUGGING
 244 To enable debugging prints from the
 245 .Nm
 246 driver, set the
 247 .Bd -literal -offset indent
 248 hw.mpr.X.debug_level
 249 .Ed
 250 .Pp
 251 tunable, either in
 252 .Xr loader.conf 5
 253 or by using
 254 .Xr sysctl 8 .
 255 These bits have the described effects:
 256 .Bd -literal -offset indent
 257 0x0001 Enable informational prints (set by default).
 258 0x0002 Enable prints for driver faults (set by default).
 259 0x0004 Enable prints for controller events.
 260 0x0008 Enable prints for controller logging.
 261 0x0010 Enable prints for tracing recovery operations.
 262 0x0020 Enable prints for parameter errors and programming bugs.
 263 0x0040 Enable prints for system initialization operations.
 264 0x0080 Enable prints for more detailed information.
 265 0x0100 Enable prints for user-generated commands (IOCTL).
 266 0x0200 Enable prints for device mapping.
 267 0x0400 Enable prints for tracing through driver functions.
 268 .Ed
 269 .Sh SEE ALSO
 270 .Xr cam 4 ,
 271 .Xr cd 4 ,
 272 .Xr ch 4 ,
 273 .Xr da 4 ,
 274 .Xr mps 4 ,
 275 .Xr mpt 4 ,
 276 .Xr pci 4 ,
 277 .Xr sa 4 ,
 278 .Xr scsi 4 ,
 279 .Xr targ 4 ,
 280 .Xr loader.conf 5 ,
 281 .Xr sysctl 8
 282 .Sh HISTORY
 283 The
 284 .Nm
 285 driver first appeared in FreeBSD 9.3.
 286 .Sh AUTHORS
 287 The
 288 .Nm
 289 driver was originally written by
 290 .An -nosplit
 291 .An Scott Long Aq Mt scottl@FreeBSD.org .
 292 It has been improved and tested by LSI Corporation,
 293 Avago Technologies (formally LSI), and Broadcom Ltd. (formally Avago).
 294 .Pp
 295 This man page was written by
 296 .An Ken Merry Aq Mt ken@FreeBSD.org
 297 with additional input from
 298 .An Stephen McConnell Aq Mt slm@FreeBSD.org .