share/man/man4/mrsas.4

   1 .\" Copyright (c) 2014 LSI Corp
   2 .\" All rights reserved.
   3 .\" Author: Kashyap Desai
   4 .\" Support: freebsdraid@lsi.com
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the <ORGANIZATION> nor the names of its
  15 .\"    contributors may be used to endorse or promote products derived
  16 .\"    from this software without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  21 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  22 .\" COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  23 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  24 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  25 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  26 .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
  28 .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  29 .\" POSSIBILITY OF SUCH DAMAGE.
  30 .\"
  31 .\" The views and conclusions contained in the software and documentation
  32 .\" are those of the authors and should not be interpreted as representing
  33 .\" official policies, either expressed or implied, of the FreeBSD Project.
  34 .\"
  35 .\" $FreeBSD$
  36 .\"
  37 .Dd March 13, 2019
  38 .Dt MRSAS 4
  39 .Os
  40 .Sh NAME
  41 .Nm mrsas
  42 .Nd "LSI MegaRAID 6Gb/s and 12Gb/s SAS+SATA RAID controller driver"
  43 .Sh SYNOPSIS
  44 To compile this driver into the kernel,
  45 place the following lines in your
  46 kernel configuration file:
  47 .Bd -ragged -offset indent
  48 .Cd "device pci"
  49 .Cd "device mrsas"
  50 .Ed
  51 .Pp
  52 Alternatively, to load the driver as a
  53 module at boot time, place the following line in
  54 .Xr loader.conf 5 :
  55 .Bd -literal -offset indent
  56 mrsas_load="YES"
  57 .Ed
  58 .Sh DESCRIPTION
  59 The
  60 .Nm
  61 driver will detect LSI's next generation (6Gb/s and 12Gb/s) PCI Express
  62 SAS/SATA RAID controllers.
  63 See the
  64 .Nm HARDWARE
  65 section for the supported devices list.
  66 A disk (virtual disk/physical disk) attached to the
  67 .Nm
  68 driver will be visible to the user through
  69 .Xr camcontrol 8
  70 as
  71 .Pa /dev/da?
  72 device nodes.
  73 A simple management interface is also provided on a per-controller basis via the
  74 .Pa /dev/mrsas?
  75 device node.
  76 .Pp
  77 The
  78 .Nm
  79 name is derived from the phrase "MegaRAID SAS HBA", which is
  80 substantially different than the old "MegaRAID" Driver
  81 .Xr mfi 4
  82 which does not connect targets
  83 to the
  84 .Xr cam 4
  85 layer and thus requires a new driver which attaches targets to the
  86 .Xr cam 4
  87 layer.
  88 Older MegaRAID controllers are supported by
  89 .Xr mfi 4
  90 and will not work with
  91 .Nm ,
  92 but both the
  93 .Xr mfi 4
  94 and
  95 .Nm
  96 drivers can detect and manage the LSI MegaRAID SAS 2208/2308/3008/3108 series of
  97 controllers.
  98 .Pp
  99 The
 100 .Xr device.hints 5
 101 option is provided to tune the
 102 .Nm
 103 driver's behavior for LSI MegaRAID SAS 2208/2308/3008/3108 controllers.
 104 By default, the
 105 .Xr mfi 4
 106 driver will detect these controllers.
 107 See the
 108 .Nm PRIORITY
 109 section to know more about driver priority for MR-Fusion devices.
 110 .Pp
 111 .Nm
 112 will provide a priority of (-30) (between
 113 .Dv BUS_PROBE_DEFAULT
 114 and
 115 .Dv BUS_PROBE_LOW_PRIORITY )
 116 at probe call for device id's 0x005B, 0x005D, and
 117 0x005F so that
 118 .Nm
 119 does not take control of these devices without user intervention.
 120 .Pp
 121 Solid-state drives (SSD) get ATA TRIM support with
 122 .Nm
 123 if underlying adapter allows it.
 124 This may require configuring SSD as Non-RAID drive
 125 rather then JBOD virtual mode.
 126 .Sh HARDWARE
 127 The
 128 .Nm
 129 driver supports the following hardware:
 130 .Pp
 131 [ Thunderbolt 6Gb/s MR controller ]
 132 .Bl -bullet -compact
 133 .It
 134 LSI MegaRAID SAS 9265
 135 .It
 136 LSI MegaRAID SAS 9266
 137 .It
 138 LSI MegaRAID SAS 9267
 139 .It
 140 LSI MegaRAID SAS 9270
 141 .It
 142 LSI MegaRAID SAS 9271
 143 .It
 144 LSI MegaRAID SAS 9272
 145 .It
 146 LSI MegaRAID SAS 9285
 147 .It
 148 LSI MegaRAID SAS 9286
 149 .It
 150 DELL PERC H810
 151 .It
 152 DELL PERC H710/P
 153 .El
 154 .Pp
 155 [ Invader/Fury 12Gb/s MR controller ]
 156 .Bl -bullet -compact
 157 .It
 158 LSI MegaRAID SAS 9380
 159 .It
 160 LSI MegaRAID SAS 9361
 161 .It
 162 LSI MegaRAID SAS 9341
 163 .It
 164 DELL PERC H830
 165 .It
 166 DELL PERC H730/P
 167 .It
 168 DELL PERC H330
 169 .El
 170 .Sh CONFIGURATION
 171 To disable Online Controller Reset(OCR) for a specific
 172 .Nm
 173 driver instance, set the
 174 following tunable value in
 175 .Xr loader.conf 5 :
 176 .Bd -literal -offset indent
 177 dev.mrsas.X.disable_ocr=1
 178 .Ed
 179 .Pp
 180 where X is the adapter number.
 181 .Pp
 182 To change the I/O timeout value for a specific
 183 .Nm
 184 driver instance, set the following tunable value in
 185 .Xr loader.conf 5 :
 186 .Bd -literal -offset indent
 187 dev.mrsas.X.mrsas_io_timeout=NNNNNN
 188 .Ed
 189 .Pp
 190 where NNNNNN is the timeout value in milli-seconds.
 191 .Pp
 192 To change the firmware fault check timer value for a specific
 193 .Nm
 194 driver instance, set the following tunable value in
 195 .Xr loader.conf 5 :
 196 .Bd -literal -offset indent
 197 dev.mrsas.X.mrsas_fw_fault_check_delay=NN
 198 .Ed
 199 .Pp
 200 where NN is the fault check delay value in seconds.
 201 .Pp
 202 The current number of active I/O commands is shown in the
 203 .Va dev.mrsas.X.fw_outstanding
 204 .Xr sysctl 8
 205 variable.
 206 .Sh DEBUGGING
 207 To enable debugging prints from the
 208 .Nm
 209 driver, set the
 210 .Va hw.mrsas.X.debug_level
 211 variable, where X is the adapter number, either in
 212 .Xr loader.conf 5
 213 or via
 214 .Xr sysctl 8 .
 215 The following bits have the described effects:
 216 .Bl -tag -width indent -offset indent
 217 .It 0x01
 218 Enable informational prints.
 219 .It 0x02
 220 Enable tracing prints.
 221 .It 0x04
 222 Enable prints for driver faults.
 223 .It 0x08
 224 Enable prints for OCR and I/O timeout.
 225 .It 0x10
 226 Enable prints for AEN events.
 227 .El
 228 .Sh PRIORITY
 229 The
 230 .Nm
 231 driver will always set a default (-30) priority in the PCI subsystem for
 232 selection of MR-Fusion cards.
 233 (It is between
 234 .Dv BUS_PROBE_DEFAULT
 235 and
 236 .Dv BUS_PROBE_LOW_PRIORITY ) .
 237 MR-Fusion Controllers include all cards with the
 238 Device IDs -
 239 0x005B,
 240 0x005D,
 241 0x005F.
 242 .Pp
 243 The
 244 .Xr mfi 4
 245 driver will set a priority of either
 246 .Dv BUS_PROBE_DEFAULT
 247 or
 248 .Dv BUS_PROBE_LOW_PRIORITY
 249 (depending on the device.hints setting) in the PCI
 250 subsystem for selection of MR-Fusion cards.
 251 With the above design in place, the
 252 .Xr mfi 4
 253 driver will attach to a MR-Fusion card given that it has a higher priority than
 254 .Nm .
 255 .Pp
 256 Using
 257 .Pa /boot/device.hints
 258 (as mentioned below), the user can provide a preference
 259 for the
 260 .Nm
 261 driver to detect a MR-Fusion card instead of the
 262 .Xr mfi 4
 263 driver.
 264 .Bd -ragged -offset indent
 265 .Cd hw.mfi.mrsas_enable="1"
 266 .Ed
 267 .Pp
 268 At boot time, the
 269 .Xr mfi 4
 270 driver will get priority to detect MR-Fusion controllers by default.
 271 Before
 272 changing this default driver selection policy, LSI advises users to understand
 273 how the driver selection policy works.
 274 LSI's policy is to provide priority to
 275 the
 276 .Xr mfi 4
 277 driver to detect MR-Fusion cards, but allow for the ability to choose the
 278 .Nm
 279 driver to detect MR-Fusion cards.
 280 .Pp
 281 LSI recommends setting hw.mfi.mrsas_enable="0" for customers who are using the
 282 older
 283 .Xr mfi 4
 284 driver and do not want to switch to
 285 .Nm .
 286 For those customers who are using a MR-Fusion controller for the first time, LSI
 287 recommends using the
 288 .Nm
 289 driver and setting hw.mfi.mrsas_enable="1".
 290 .Pp
 291 Changing the default behavior is well tested under most conditions, but
 292 unexpected behavior may pop up if more complex and unrealistic operations are
 293 executed by switching between the
 294 .Xr mfi 4
 295 and
 296 .Nm
 297 drivers for MR-Fusion.
 298 Switching drivers is designed to happen only one time.
 299 Although multiple
 300 switching is possible, it is not recommended.
 301 The user should decide from
 302 .Nm Start of Day
 303 which driver they want to use for the MR-Fusion card.
 304 .Pp
 305 The user may see different device names when switching from
 306 .Xr mfi 4
 307 to
 308 .Nm .
 309 This behavior is
 310 .Nm Functions As Designed
 311 and the user needs to change the
 312 .Xr fstab 5
 313 entry manually if they are doing any experiments with
 314 .Xr mfi 4
 315 and
 316 .Nm
 317 interoperability.
 318 .Sh FILES
 319 .Bl -tag -width ".Pa /dev/mrsas?" -compact
 320 .It Pa /dev/da?
 321 array/logical disk interface
 322 .It Pa /dev/mrsas?
 323 management interface
 324 .El
 325 .Sh SEE ALSO
 326 .Xr cam 4 ,
 327 .Xr mfi 4 ,
 328 .Xr pci 4 ,
 329 .Xr device.hints 5 ,
 330 .Xr camcontrol 8
 331 .Sh HISTORY
 332 The
 333 .Nm
 334 driver first appeared in
 335 .Fx 10.1 .
 336 .Bd -ragged
 337 .Cd "mfi Driver:"
 338 .Xr mfi 4
 339 is the old
 340 .Fx
 341 driver which started with support for Gen-1 Controllers and
 342 was extended to support up to MR-Fusion (Device ID = 0x005B, 0x005D, 0x005F).
 343 .Ed
 344 .Bd -ragged
 345 .Cd "mrsas Driver:"
 346 .Nm
 347 is the new driver reworked by LSI which supports Thunderbolt and onward
 348 products.
 349 The SAS+SATA RAID controller with device id 0x005b is referred to as
 350 the Thunderbolt controller throughout this man page.
 351 .Ed
 352 .Bd -ragged
 353 .Nm cam aware HBA drivers:
 354 .Fx
 355 has a
 356 .Xr cam 4
 357 layer which attaches storage devices and provides a common access mechanism to
 358 storage controllers and attached devices.
 359 The
 360 .Nm
 361 driver is
 362 .Xr cam 4
 363 aware and devices associated with
 364 .Nm
 365 can be seen using
 366 .Xr camcontrol 8 .
 367 The
 368 .Xr mfi 4
 369 driver does not understand the
 370 .Xr cam 4
 371 layer and it directly associates storage disks to the block layer.
 372 .Pp
 373 .Nm Thunderbolt Controller:
 374 This is the 6Gb/s MegaRAID HBA card which has device id 0x005B.
 375 .Pp
 376 .Nm Invader Controller:
 377 This is 12Gb/s MegaRAID HBA card which has device id 0x005D.
 378 .Pp
 379 .Nm Fury Controller:
 380 This is the 12Gb/s MegaRAID HBA card which has device id 0x005F.
 381 .Ed
 382 .Sh AUTHORS
 383 The
 384 .Nm
 385 driver and this manual page were written by
 386 .An Kashyap Desai Aq Mt Kashyap.Desai@lsi.com .
 387 .Sh TODO
 388 The driver does not support big-endian architectures at this time.
 389 .Pp
 390 The driver does not support alias for device name (it is required when the user
 391 switches between two drivers and does not want to edit
 392 .Pa /etc/fstab
 393 manually).
 394 .Pp
 395 The
 396 .Nm
 397 driver exposes devices as
 398 .Pa /dev/da? ,
 399 whereas
 400 .Xr mfi 4
 401 exposes devices as
 402 .Pa /dev/mfid? .
 403 .Pp
 404 .Nm
 405 does not support the Linux Emulator interface.
 406 .Pp
 407 .Nm
 408 will not work with
 409 .Xr mfiutil 8 .