share/man/man4/mpr.4

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