share/man/man4/mpr.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 .\" mpr driver man page.
  34 .\"
  35 .\" Author: Ken Merry <ken@FreeBSD.org>
  36 .\" Author: Stephen McConnell <slm@FreeBSD.org>
  37 .\"
  38 .\" $Id$
  39 .\" $FreeBSD: head/share/man/man4/mpr.4 324806 2017-10-20 15:29:28Z asomers $
  40 .\"
  41 .Dd April 24, 2018
  42 .Dt MPR 4
  43 .Os
  44 .Sh NAME
  45 .Nm mpr
  46 .Nd "LSI Fusion-MPT 3/3.5 IT/IR 12Gb/s Serial Attached SCSI/SATA/PCIe 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/3.5 IT/IR
  66 .Tn SAS/PCIe
  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 .It
  85 Broadcom Ltd./Avago Tech (LSI) SAS 3316 (16 Port SAS)
  86 .It
  87 Broadcom Ltd./Avago Tech (LSI) SAS 3324 (24 Port SAS)
  88 .It
  89 Broadcom Ltd./Avago Tech (LSI) SAS 3408 (8 Port SAS/PCIe)
  90 .It
  91 Broadcom Ltd./Avago Tech (LSI) SAS 3416 (16 Port SAS/PCIe)
  92 .It
  93 Broadcom Ltd./Avago Tech (LSI) SAS 3508 (8 Port SAS/PCIe)
  94 .It
  95 Broadcom Ltd./Avago Tech (LSI) SAS 3516 (16 Port SAS/PCIe)
  96 .It
  97 Broadcom Ltd./Avago Tech (LSI) SAS 3616 (16 Port SAS/PCIe)
  98 .It
  99 Broadcom Ltd./Avago Tech (LSI) SAS 3708 (8 Port SAS/PCIe)
 100 .It
 101 Broadcom Ltd./Avago Tech (LSI) SAS 3716 (16 Port SAS/PCIe)
 102 .El
 103 .Sh CONFIGURATION
 104 In all tunable descriptions below, X represents the adapter number.
 105 .Pp
 106 To disable MSI interrupts for all
 107 .Nm
 108 driver instances, set this tunable value in
 109 .Xr loader.conf 5 :
 110 .Bd -literal -offset indent
 111 hw.mpr.msi_enable=0
 112 .Ed
 113 .Pp
 114 To disable MSI interrupts for a specific
 115 .Nm
 116 driver instance, set this tunable value in
 117 .Xr loader.conf 5 :
 118 .Bd -literal -offset indent
 119 dev.mpr.X.msi_enable=0
 120 .Ed
 121 .Pp
 122 .\"To disable MSI-X interrupts for all
 123 .\".Nm
 124 .\"driver instances, set this tunable value in
 125 .\".Xr loader.conf 5 :
 126 .\".Bd -literal -offset indent
 127 .\"hw.mpr.disable_msix=1
 128 .\".Ed
 129 .\".Pp
 130 .\"To disable MSI-X interrupts for a specific
 131 .\".Nm
 132 .\"driver instance, set this tunable value in
 133 .\".Xr loader.conf 5 :
 134 .\".Bd -literal -offset indent
 135 .\"dev.mpr.X.disable_msix=1
 136 .\".Ed
 137 .\".Pp
 138 To set the maximum number of DMA chains allocated for all adapters, set
 139 this tunable in
 140 .Xr loader.conf 5 :
 141 .Bd -literal -offset indent
 142 hw.mpr.max_chains=NNNN
 143 .Ed
 144 .Pp
 145 To set the maximum number of DMA chains allocated for a specific adapter,
 146 set this tunable in
 147 .Xr loader.conf 5 :
 148 .Bd -literal -offset indent
 149 dev.mpr.X.max_chains=NNNN
 150 .Ed
 151 .Pp
 152 The default max_chains value is 2048.
 153 .Pp
 154 The current number of free chain frames is stored in the
 155 dev.mpr.X.chain_free
 156 .Xr sysctl 8
 157 variable.
 158 .Pp
 159 The lowest number of free chain frames seen since boot is stored in the
 160 dev.mpr.X.chain_free_lowwater
 161 .Xr sysctl 8
 162 variable.
 163 .Pp
 164 The number of times that chain frame allocations have failed since boot is
 165 stored in the
 166 dev.mpr.X.chain_alloc_fail
 167 .Xr sysctl 8
 168 variable.
 169 This can be used to determine whether the max_chains tunable should be
 170 increased to help performance.
 171 .Pp
 172 The current number of active I/O commands is shown in the
 173 dev.mpr.X.io_cmds_active
 174 .Xr sysctl 8
 175 variable.
 176 .Pp
 177 The current number of free PRP pages is stored in the
 178 dev.mpr.X.prp_pages_free
 179 .Xr sysctl 8
 180 variable.
 181 PRP pages are used by NVMe devices for I/O transfers, much like Scatter/Gather
 182 lists.
 183 .Pp
 184 The lowest number of free PRP pages seen since boot is stored in the
 185 dev.mpr.X.prp_pages_free_lowwater
 186 .Xr sysctl 8
 187 variable.
 188 .Pp
 189 The number of times that PRP page allocations have failed since boot is
 190 stored in the
 191 dev.mpr.X.prp_page_alloc_fail
 192 .Xr sysctl 8
 193 variable.
 194 .Pp
 195 To set the maximum number of pages that will be used per I/O for all adapters,
 196 set this tunable in
 197 .Xr loader.conf 5 :
 198 .Bd -literal -offset indent
 199 hw.mpr.max_io_pages=NNNN
 200 .Ed
 201 .Pp
 202 To set the maximum number of pages that will be used per I/O for a specific
 203 adapter, set this tunable in
 204 .Xr loader.conf 5 :
 205 .Bd -literal -offset indent
 206 dev.mpr.X.max_io_pages=NNNN
 207 .Ed
 208 .Pp
 209 The default max_io_pages value is -1, meaning that the maximum I/O size that
 210 will be used per I/O will be calculated using the IOCFacts values stored in
 211 the controller.
 212 The lowest value that the driver will use for max_io_pages is 1, otherwise
 213 IOCFacts will be used to calculate the maximum I/O size.
 214 The smaller I/O size calculated from either max_io_pages or IOCFacts will be the
 215 maximum I/O size used by the driver.
 216 .Pp
 217 The highest number of active I/O commands seen since boot is stored in the
 218 dev.mpr.X.io_cmds_highwater
 219 .Xr sysctl 8
 220 variable.
 221 .Pp
 222 Devices can be excluded from
 223 .Nm
 224 control for all adapters by setting this tunable in
 225 .Xr loader.conf 5 :
 226 .Bd -literal -offset indent
 227 hw.mpr.exclude_ids=Y
 228 .Ed
 229 .Pp
 230 Y represents the target ID of the device.
 231 If more than one device is to be excluded, target IDs are separated by commas.
 232 .Pp
 233 Devices can be excluded from
 234 .Nm
 235 control for a specific adapter by setting this tunable in
 236 .Xr loader.conf 5 :
 237 .Bd -literal -offset indent
 238 dev.mpr.X.exclude_ids=Y
 239 .Ed
 240 .Pp
 241 Y represents the target ID of the device.
 242 If more than one device is to be excluded, target IDs are separated by commas.
 243 .Pp
 244 The adapter can issue the
 245 .Sy StartStopUnit
 246 SCSI command to SATA direct-access devices during shutdown.
 247 This allows the device to quiesce powering down.
 248 To control this feature for all adapters, set the
 249 .Bd -literal -offset indent
 250 hw.mpr.enable_ssu
 251 .Ed
 252 .Pp
 253 tunable in
 254 .Xr loader.conf 5
 255 to one of these values:
 256 .Bl -tag -width 6n -offset indent
 257 .It 0
 258 Do not send SSU to either HDDs or SSDs.
 259 .It 1
 260 Send SSU to SSDs, but not to HDDs.
 261 This is the default value.
 262 .It 2
 263 Send SSU to HDDs, but not to SSDs.
 264 .It 3
 265 Send SSU to both HDDs and SSDs.
 266 .El
 267 .Pp
 268 To control this feature for a specific adapter, set this tunable value in
 269 .Xr loader.conf 5 :
 270 .Bd -literal -offset indent
 271 dev.mpr.X.enable_ssu
 272 .Ed
 273 .Pp
 274 The same set of values are valid as when setting this tunable for all adapters.
 275 .Pp
 276 SATA disks that take several seconds to spin up and fail the SATA Identify
 277 command might not be discovered by the driver.
 278 This problem can sometimes be overcome by increasing the value of the spinup
 279 wait time in
 280 .Xr loader.conf 5
 281 with the
 282 .Bd -literal -offset indent
 283 hw.mpr.spinup_wait_time=NNNN
 284 .Ed
 285 .Pp
 286 tunable.
 287 NNNN represents the number of seconds to wait for SATA devices to spin up when
 288 the device fails the initial SATA Identify command.
 289 .Pp
 290 Spinup wait times can be set for specific adapters in
 291 .Xr loader.conf 5 :
 292 with the
 293 .Bd -literal -offset indent
 294 dev.mpr.X.spinup_wait_time=NNNN
 295 .Ed
 296 .Pp
 297 tunable.
 298 NNNN is the number of seconds to wait for SATA devices to spin up when they fail
 299 the initial SATA Identify command.
 300 .Pp
 301 The driver can map devices discovered by the adapter so that target IDs
 302 corresponding to a specific device persist across resets and reboots.
 303 In some cases it is possible for devices to lose their mapped IDs due to
 304 unexpected behavior from certain hardware, such as some types of enclosures.
 305 To overcome this problem, a tunable is provided that will force the driver to
 306 map devices using the Phy number associated with the device.
 307 This feature is not recommended if the topology includes multiple
 308 enclosures/expanders.
 309 If multiple enclosures/expanders are present in the topology, Phy numbers are
 310 repeated, causing all devices at these Phy numbers except the first device to
 311 fail enumeration.
 312 To control this feature for all adapters, set the
 313 .Bd -literal -offset indent
 314 hw.mpr.use_phy_num
 315 .Ed
 316 .Pp
 317 tunable in
 318 .Xr loader.conf 5
 319 to one of these values:
 320 .Bl -tag -width 6n -offset indent
 321 .It -1
 322 Only use Phy numbers to map devices and bypass the driver's mapping logic.
 323 .It 0
 324 Never use Phy numbers to map devices.
 325 .It 1
 326 Use Phy numbers to map devices, but only if the driver's mapping logic fails
 327 to map the device that is being enumerated.
 328 This is the default value.
 329 .El
 330 .Pp
 331 To control this feature for a specific adapter, set this tunable value in
 332 .Xr loader.conf 5 :
 333 .Bd -literal -offset indent
 334 dev.mpr.X.use_phy_num
 335 .Ed
 336 .Pp
 337 The same set of values are valid as when setting this tunable for all adapters.
 338 .Sh DEBUGGING
 339 To enable debugging prints from the
 340 .Nm
 341 driver, set the
 342 .Bd -literal -offset indent
 343 hw.mpr.X.debug_level
 344 .Ed
 345 .Pp
 346 tunable, either in
 347 .Xr loader.conf 5
 348 or by using
 349 .Xr sysctl 8 .
 350 These bits have the described effects:
 351 .Bd -literal -offset indent
 352 0x0001 Enable informational prints (set by default).
 353 0x0002 Enable prints for driver faults (set by default).
 354 0x0004 Enable prints for controller events.
 355 0x0008 Enable prints for controller logging.
 356 0x0010 Enable prints for tracing recovery operations.
 357 0x0020 Enable prints for parameter errors and programming bugs.
 358 0x0040 Enable prints for system initialization operations.
 359 0x0080 Enable prints for more detailed information.
 360 0x0100 Enable prints for user-generated commands (IOCTL).
 361 0x0200 Enable prints for device mapping.
 362 0x0400 Enable prints for tracing through driver functions.
 363 .Ed
 364 .Sh SEE ALSO
 365 .Xr cam 4 ,
 366 .Xr cd 4 ,
 367 .Xr ch 4 ,
 368 .Xr da 4 ,
 369 .Xr mps 4 ,
 370 .Xr mpt 4 ,
 371 .Xr pci 4 ,
 372 .Xr sa 4 ,
 373 .Xr scsi 4 ,
 374 .Xr targ 4 ,
 375 .Xr loader.conf 5 ,
 376 .Xr sysctl 8
 377 .Sh HISTORY
 378 The
 379 .Nm
 380 driver first appeared in
 381 .Fx 9.3 .
 382 .Sh AUTHORS
 383 The
 384 .Nm
 385 driver was originally written by
 386 .An -nosplit
 387 .An Scott Long Aq Mt scottl@FreeBSD.org .
 388 It has been improved and tested by LSI Corporation,
 389 Avago Technologies (formally LSI), and Broadcom Ltd. (formally Avago).
 390 .Pp
 391 This man page was written by
 392 .An Ken Merry Aq Mt ken@FreeBSD.org
 393 with additional input from
 394 .An Stephen McConnell Aq Mt slm@FreeBSD.org .