share/man/man4/mps.4

   1 .\"
   2 .\" Copyright (c) 2010 Spectra Logic Corporation
   3 .\" Copyright (c) 2014 LSI Corp
   4 .\" Copyright (c) 2015-2017 Avago Technologies
   5 .\" Copyright (c) 2015-2017 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 .\" mps driver man page.
  34 .\"
  35 .\" Author: Ken Merry <ken@FreeBSD.org>
  36 .\" Author: Stephen McConnell <slm@FreeBSD.org>
  37 .\"
  38 .\" $Id: //depot/SpectraBSD/head/share/man/man4/mps.4#6 $
  39 .\" $FreeBSD$
  40 .\"
  41 .Dd June 1, 2019
  42 .Dt MPS 4
  43 .Os
  44 .Sh NAME
  45 .Nm mps
  46 .Nd "LSI Fusion-MPT 2 IT/IR 6Gb/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 mps"
  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 mps_load="YES"
  60 .Ed
  61 .Sh DESCRIPTION
  62 The
  63 .Nm
  64 driver provides support for Broadcom Ltd./Avago Tech (LSI)
  65 Fusion-MPT 2 IT/IR
  66 .Tn SAS
  67 controllers and WarpDrive solid state storage cards.
  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 2004 (4 Port SAS)
  76 .It
  77 Broadcom Ltd./Avago Tech (LSI) SAS 2008 (8 Port SAS)
  78 .It
  79 Broadcom Ltd./Avago Tech (LSI) SAS 2108 (8 Port SAS)
  80 .It
  81 Broadcom Ltd./Avago Tech (LSI) SAS 2116 (16 Port SAS)
  82 .It
  83 Broadcom Ltd./Avago Tech (LSI) SAS 2208 (8 Port SAS)
  84 .It
  85 Broadcom Ltd./Avago Tech (LSI) SAS 2308 (8 Port SAS)
  86 .It
  87 Broadcom Ltd./Avago Tech (LSI) SSS6200 Solid State Storage
  88 .It
  89 Intel Integrated RAID Module RMS25JB040
  90 .It
  91 Intel Integrated RAID Module RMS25JB080
  92 .It
  93 Intel Integrated RAID Module RMS25KB040
  94 .It
  95 Intel Integrated RAID Module RMS25KB080
  96 .El
  97 .Sh CONFIGURATION
  98 In all tunable descriptions below, X represents the adapter number.
  99 .Pp
 100 To disable MSI interrupts for all
 101 .Nm
 102 driver instances, set this tunable value in
 103 .Xr loader.conf 5 :
 104 .Bd -literal -offset indent
 105 hw.mps.disable_msi=1
 106 .Ed
 107 .Pp
 108 To disable MSI interrupts for a specific
 109 .Nm
 110 driver instance, set this tunable value in
 111 .Xr loader.conf 5 :
 112 .Bd -literal -offset indent
 113 dev.mps.X.disable_msi=1
 114 .Ed
 115 .Pp
 116 To disable MSI-X interrupts for all
 117 .Nm
 118 driver instances, set this tunable value in
 119 .Xr loader.conf 5 :
 120 .Bd -literal -offset indent
 121 hw.mps.disable_msix=1
 122 .Ed
 123 .Pp
 124 To disable MSI-X interrupts for a specific
 125 .Nm
 126 driver instance, set this tunable value in
 127 .Xr loader.conf 5 :
 128 .Bd -literal -offset indent
 129 dev.mps.X.disable_msix=1
 130 .Ed
 131 .Pp
 132 To set the maximum number of DMA chains allocated for all adapters, set this
 133 tunable in
 134 .Xr loader.conf 5 :
 135 .Bd -literal -offset indent
 136 hw.mps.max_chains=NNNN
 137 .Ed
 138 .Pp
 139 To set the maximum number of DMA chains allocated for a specific adapter,
 140 set this tunable in
 141 .Xr loader.conf 5 :
 142 .Bd -literal -offset indent
 143 dev.mps.X.max_chains=NNNN
 144 .Ed
 145 .Pp
 146 The default max_chains value is 16384.
 147 .Pp
 148 The current number of free chain frames is stored in the
 149 dev.mps.X.chain_free
 150 .Xr sysctl 8
 151 variable.
 152 .Pp
 153 The lowest number of free chain frames seen since boot is stored in the
 154 dev.mps.X.chain_free_lowwater
 155 .Xr sysctl 8
 156 variable.
 157 .Pp
 158 The number of times that chain frame allocations have failed since boot is
 159 stored in the
 160 dev.mps.X.chain_alloc_fail
 161 .Xr sysctl 8
 162 variable.
 163 This can be used to determine whether the max_chains tunable should be
 164 increased to help performance.
 165 .Pp
 166 The current number of active I/O commands is shown in the
 167 dev.mps.X.io_cmds_active
 168 .Xr sysctl 8
 169 variable.
 170 .Pp
 171 To set the maximum number of pages that will be used per I/O for all adapters,
 172 set this tunable in
 173 .Xr loader.conf 5 :
 174 .Bd -literal -offset indent
 175 hw.mps.max_io_pages=NNNN
 176 .Ed
 177 .Pp
 178 To set the maximum number of pages that will be used per I/O for a specific
 179 adapter, set this tunable in
 180 .Xr loader.conf 5 :
 181 .Bd -literal -offset indent
 182 dev.mps.X.max_io_pages=NNNN
 183 .Ed
 184 .Pp
 185 The default max_io_pages value is -1, meaning that the maximum I/O size that
 186 will be used per I/O will be calculated using the IOCFacts values stored in
 187 the controller.
 188 The lowest value that the driver will use for max_io_pages is 1, otherwise
 189 IOCFacts will be used to calculate the maximum I/O size.
 190 The smaller I/O size calculated from either max_io_pages or IOCFacts will be the
 191 maximum I/O size used by the driver.
 192 .Pp
 193 The highest number of active I/O commands seen since boot is stored in the
 194 dev.mps.X.io_cmds_highwater
 195 .Xr sysctl 8
 196 variable.
 197 .Pp
 198 Devices can be excluded from
 199 .Nm
 200 control for all adapters by setting this tunable in
 201 .Xr loader.conf 5 :
 202 .Bd -literal -offset indent
 203 hw.mps.exclude_ids=Y
 204 .Ed
 205 .Pp
 206 Y represents the target ID of the device.
 207 If more than one device is to be excluded, target IDs are separated by commas.
 208 .Pp
 209 Devices can be excluded from
 210 .Nm
 211 control for a specific adapter by setting this tunable in
 212 .Xr loader.conf 5 :
 213 .Bd -literal -offset indent
 214 dev.mps.X.exclude_ids=Y
 215 .Ed
 216 .Pp
 217 Y represents the target ID of the device.
 218 If more than one device is to be excluded, target IDs are separated by commas.
 219 .Pp
 220 The adapter can issue the
 221 .Sy StartStopUnit
 222 SCSI command to SATA direct-access devices during shutdown.
 223 This allows the device to quiesce powering down.
 224 To control this feature for all adapters, set the
 225 .Bd -literal -offset indent
 226 hw.mps.enable_ssu
 227 .Ed
 228 .Pp
 229 tunable in
 230 .Xr loader.conf 5
 231 to one of these values:
 232 .Bl -tag -width 6n -offset indent
 233 .It 0
 234 Do not send SSU to either HDDs or SSDs.
 235 .It 1
 236 Send SSU to SSDs, but not to HDDs.
 237 This is the default value.
 238 .It 2
 239 Send SSU to HDDs, but not to SSDs.
 240 .It 3
 241 Send SSU to both HDDs and SSDs.
 242 .El
 243 .Pp
 244 To control this feature for a specific adapter, set this tunable value in
 245 .Xr loader.conf 5 :
 246 .Bd -literal -offset indent
 247 dev.mps.X.enable_ssu
 248 .Ed
 249 .Pp
 250 The same set of values are valid as when setting this tunable for all adapters.
 251 .Pp
 252 SATA disks that take several seconds to spin up and fail the SATA Identify
 253 command might not be discovered by the driver.
 254 This problem can sometimes be overcome by increasing the value of the spinup
 255 wait time in
 256 .Xr loader.conf 5
 257 with the
 258 .Bd -literal -offset indent
 259 hw.mps.spinup_wait_time=NNNN
 260 .Ed
 261 .Pp
 262 tunable.
 263 NNNN represents the number of seconds to wait for SATA devices to spin up when
 264 the device fails the initial SATA Identify command.
 265 .Pp
 266 Spinup wait times can be set for specific adapters in
 267 .Xr loader.conf 5 :
 268 with the
 269 .Bd -literal -offset indent
 270 dev.mps.X.spinup_wait_time=NNNN
 271 .Ed
 272 .Pp
 273 tunable.
 274 NNNN is the number of seconds to wait for SATA devices to spin up when they fail
 275 the initial SATA Identify command.
 276 .Pp
 277 The driver can map devices discovered by the adapter so that target IDs
 278 corresponding to a specific device persist across resets and reboots.
 279 In some cases it is possible for devices to lose their mapped IDs due to
 280 unexpected behavior from certain hardware, such as some types of enclosures.
 281 To overcome this problem, a tunable is provided that will force the driver to
 282 map devices using the Phy number associated with the device.
 283 This feature is not recommended if the topology includes multiple
 284 enclosures/expanders.
 285 If multiple enclosures/expanders are present in the topology, Phy numbers are
 286 repeated, causing all devices at these Phy numbers except the first device to
 287 fail enumeration.
 288 To control this feature for all adapters, set the
 289 .Bd -literal -offset indent
 290 hw.mps.use_phy_num
 291 .Ed
 292 .Pp
 293 tunable in
 294 .Xr loader.conf 5
 295 to one of these values:
 296 .Bl -tag -width 6n -offset indent
 297 .It -1
 298 Only use Phy numbers to map devices and bypass the driver's mapping logic.
 299 .It 0
 300 Never use Phy numbers to map devices.
 301 .It 1
 302 Use Phy numbers to map devices, but only if the driver's mapping logic fails
 303 to map the device that is being enumerated.
 304 This is the default value.
 305 .El
 306 .Pp
 307 To control this feature for a specific adapter, set this tunable value in
 308 .Xr loader.conf 5 :
 309 .Bd -literal -offset indent
 310 dev.mps.X.use_phy_num
 311 .Ed
 312 .Pp
 313 The same set of values are valid as when setting this tunable for all adapters.
 314 .Pp
 315 .Sh DEBUGGING
 316 Driver diagnostic printing is controlled in
 317 .Xr loader.conf 5
 318 by using the global
 319 .Va hw.mps.debug_level
 320 and per-device
 321 .Va dev.mps.X.debug_level
 322 tunables.
 323 One can alter the debug level for any adapter at run-time using the
 324 .Xr sysctl 8
 325 variable
 326 .Va dev.mps.X.debug_level .
 327 .Pp
 328 All
 329 .Va debug_level
 330 variables can be named by either an integer value or a text string.
 331 Multiple values can be specified together by either ORing the
 332 integer values or by providing a comma-separated list of names.
 333 A text string prefixed by
 334 .Qq +
 335 adds the specified debug levels to the existing set, while the prefix
 336 .Qq -
 337 removes them from the existing set.
 338 The current
 339 .Va debug_level
 340 status is reported in both formats for convenience.
 341 The following levels are available:
 342 .Bl -column "FlagXX" "NameXXXX" "Description" -offset indent
 343 .It Em Flag Ta Em Name Ta Em Description
 344 .It 0x0001 Ta info Ta Basic information (enabled by default)
 345 .It 0x0002 Ta fault Ta Driver faults (enabled by default)
 346 .It 0x0004 Ta event Ta Controller events
 347 .It 0x0008 Ta log Ta Logging data from controller
 348 .It 0x0010 Ta recovery Ta Tracing of recovery operations
 349 .It 0x0020 Ta error Ta Parameter errors and programming bugs
 350 .It 0x0040 Ta init Ta System initialization operations
 351 .It 0x0080 Ta xinfo Ta More detailed information
 352 .It 0x0100 Ta user Ta Tracing of user-generated commands (IOCTL)
 353 .It 0x0200 Ta mapping Ta Tracing of device mapping
 354 .It 0x0400 Ta trace Ta Tracing through driver functions
 355 .El
 356 .Sh SEE ALSO
 357 .Xr cam 4 ,
 358 .Xr cd 4 ,
 359 .Xr ch 4 ,
 360 .Xr da 4 ,
 361 .Xr mpr 4 ,
 362 .Xr mpt 4 ,
 363 .Xr pci 4 ,
 364 .Xr sa 4 ,
 365 .Xr scsi 4 ,
 366 .Xr targ 4 ,
 367 .Xr loader.conf 5 ,
 368 .Xr sysctl 8
 369 .Sh HISTORY
 370 The
 371 .Nm
 372 driver first appeared in
 373 .Fx 9.0 .
 374 .Sh AUTHORS
 375 The
 376 .Nm
 377 driver was originally written by
 378 .An -nosplit
 379 .An Scott Long Aq Mt scottl@FreeBSD.org .
 380 It has been improved and tested by LSI Corporation,
 381 Avago Technologies (formally LSI), and Broadcom Ltd. (formally Avago).
 382 .Pp
 383 This man page was written by
 384 .An Ken Merry Aq Mt ken@FreeBSD.org
 385 with additional input from
 386 .An Stephen McConnell Aq Mt slm@FreeBSD.org .