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
  38
  39 .Dd Apr 12, 2013
  40 .Dt MRSAS 4
  41 .Os
  42 .Sh NAME
  43 .Nm mrsas
  44 .Nd "LSI MegaRAID 6Gb/s and 12Gb/s SAS+SATA Raid controller driver"
  45 .Sh SYNOPSIS
  46 To compile this driver into the kernel,
  47 place the following lines in your
  48 kernel configuration file:
  49 .Bd -ragged -offset indent
  50 .Cd "device pci"
  51 .Cd "device mrsas"
  52 .Ed
  53 .Pp
  54 Alternatively, to load the driver as a
  55 module at boot time, place the following line in
  56 .Xr loader.conf 5 :
  57 .Bd -literal -offset indent
  58 mrsas_load="YES"
  59 .Ed
  60 .Sh DESCRIPTION
  61 The
  62 .Nm
  63 driver will detect LSI's next generation (6Gb/s and 12Gb/s) PCI Express
  64 SAS/SATA RAID controllers.
  65 See the
  66 .Nm HARDWARE
  67 section for the supported devices list.
  68 A disk (virtual disk/physical disk) attached to the
  69 .Nm
  70 driver will be visible to the user through
  71 .Xr camcontrol 8 as
  72 .Pa /dev/da?
  73 device nodes.
  74 A simple management interface is also provided on a per-controller basis via the
  75 .Pa /dev/mrsas?
  76 device node.
  77 .Pp
  78 The
  79 .Nm
  80 name is derived from the phrase "MegaRAID SAS HBA", which is
  81 substantially different than the old "MegaRAID" Driver
  82 .Xr mfi 4
  83 which does not connect targets
  84 to the
  85 .Xr cam 4
  86 layer and thus requires a new driver which attaches targets to the
  87 .Xr cam 4
  88 layer. 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 .Nm device.hints
 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. See the
 107 .Nm PRIORITY
 108 section to know more about driver priority for MR-Fusion devices.
 109 .Pp
 110 .Nm
 111 will provide a priority of (-30) (between BUS_PROBE_DEFAULT and
 112 BUS_PROBE_LOW_PRIORITY) at probe call for device id's 0x005B, 0x005D, and
 113 0x005F so that
 114 .Nm
 115 does not take control of these devices without user intervention.
 116 .Sh HARDWARE
 117 The
 118 .Nm
 119 driver supports the following hardware:
 120 .Pp
 121 .Bl -bullet -compact
 122 [ Thunderbolt 6Gbp/s MR controller ]
 123 .It
 124 LSI MegaRAID SAS 9265
 125 .It
 126 LSI MegaRAID SAS 9266
 127 .It
 128 LSI MegaRAID SAS 9267
 129 .It
 130 LSI MegaRAID SAS 9270
 131 .It
 132 LSI MegaRAID SAS 9271
 133 .It
 134 LSI MegaRAID SAS 9272
 135 .It
 136 LSI MegaRAID SAS 9285
 137 .It
 138 LSI MegaRAID SAS 9286
 139 .It
 140 DELL PERC H810
 141 .It
 142 DELL PERC H710/P
 143 .El
 144 .Pp
 145 .Bl -bullet -compact
 146 [ Invader/Fury 12Gpb/s MR controller ]
 147 .It
 148 LSI MegaRAID SAS 9380
 149 .It
 150 LSI MegaRAID SAS 9361
 151 .It
 152 LSI MegaRAID SAS 9341
 153 .It
 154 DELL PERC H830
 155 .It
 156 DELL PERC H730/P
 157 .It
 158 DELL PERC H330
 159 .El
 160 .Sh CONFIGURATION
 161 To disable Online Controller Reset(OCR) for a specific
 162 .Nm
 163 driver instance, set the
 164 following tunable value in
 165 .Xr loader.conf 5 :
 166 .Bd -literal -offset indent
 167 dev.mrsas.X.disable_ocr=1
 168 .Ed
 169 .Pp
 170 where X is the adapter number.
 171 .Pp
 172 To change the IO timeout value for a specific
 173 .Nm
 174 driver instance, set the following tunable value in
 175 .Xr loader.conf 5 :
 176 .Bd -literal -offset indent
 177 dev.mrsas.X.mrsas_io_timeout=NNNNNN
 178 .Ed
 179 .Pp
 180 where NNNNNN is the timeout value in milli-seconds.
 181 .Pp
 182 To change the firmware fault check timer 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_fw_fault_check_delay=NN
 188 .Ed
 189 .Pp
 190 where NN is the fault check delay value in seconds.
 191 .Pp
 192 The current number of active I/O commands is shown in the
 193 dev.mrsas.X.fw_outstanding
 194 .Xr sysctl 8
 195 variable.
 196 .Sh DEBUGGING
 197 To enable debugging prints from the
 198 .Nm
 199 driver, set the
 200 .Bd -literal -offset indent
 201 hw.mrsas.X.debug_level
 202 .Ed
 203 .Pp
 204 variable, where X is the adapter number, either in
 205 .Xr loader.conf 5
 206 or via
 207 .Xr sysctl 8 .
 208 The following bits have the described effects:
 209 .Bl -tag -offset indent
 210 .It 0x01
 211 Enable informational prints.
 212 .It 0x02
 213 Enable tracing prints.
 214 .It 0x04
 215 Enable prints for driver faults.
 216 .It 0x08
 217 Enable prints for OCR and IO timeout.
 218 .It 0x10
 219 Enable prints for AEN events.
 220 .El
 221 .Sh PRIORITY
 222 The
 223 .Nm
 224 driver will always set a default (-30) priority in the pci subsystem for
 225 selection of MR-Fusion cards.  (It is between BUS_PROBE_DEFAULT and
 226 BUS_PROBE_LOW_PRIORITY). MR-Fusion Controllers include all cards with the
 227 Device IDs -
 228 0x005B,
 229 0x005D,
 230 0x005F.
 231 .Pp
 232 The
 233 .Xr mfi 4
 234 driver will set a priority of either BUS_PROBE_DEFAULT or
 235 BUS_PROBE_LOW_PRIORITY (depending on the device.hint setting) in the pci
 236 subsystem for selection of MR-Fusion cards.  With the above design in place, the
 237 .Xr mfi 4
 238 driver will attach to a MR-Fusion card given that it has a higher priority than
 239 .Nm .
 240 .Pp
 241 Using /boot/device.hints (as mentioned below), the user can provide a preference
 242 for the
 243 .Nm
 244 driver to detect a MR-Fusion card instead of the
 245 .Xr mfi 4
 246 driver.
 247 .Bd -ragged -offset indent
 248 .Cd hw.mfi.mrsas_enable="1"
 249 .Ed
 250 .Pp
 251 At boot time, the
 252 .Xr mfi 4
 253 driver will get priority to detect MR-Fusion controllers by default.  Before
 254 changing this default driver selection policy, LSI advises users to understand
 255 how the driver selection policy works.  LSI's policy is to provide priority to
 256 the
 257 .Xr mfi 4
 258 driver to detect MR-Fusion cards, but allow for the ability to choose the
 259 .Nm
 260 driver to detect MR-Fusion cards.
 261 .Pp
 262 LSI recommends setting hw.mfi.mrsas_enable="0" for customers who are using the
 263 older
 264 .Xr mfi 4
 265 driver and do not want to switch to
 266 .Nm .
 267 For those customers who are using a MR-Fusion controller for the first time, LSI
 268 recommends using the
 269 .Nm
 270 driver and setting hw.mfi.mrsas_enable="1".
 271 .Pp
 272 Changing the default behavior is well tested under most conditions, but
 273 unexpected behavior may pop up if more complex and unrealistic operations are
 274 executed by switching between the
 275 .Xr mfi 4 and
 276 .Nm
 277 drivers for MR-Fusion.
 278 Switching drivers is designed to happen only one time.  Although multiple
 279 switching is possible, it is not recommended.  The user should decide from
 280 .Nm Start of Day
 281 which driver they want to use for the MR-Fusion card.
 282 .Pp
 283 The user may see different device names when switching from
 284 .Xr mfi 4
 285 to
 286 .Nm .
 287 This behavior is
 288 .Nm Functions As Designed
 289 and the user needs to change the fstab
 290 entry manually if they are doing any experiments with
 291 .Xr mfi 4
 292 and
 293 .Nm
 294 interoperability.
 295 .Sh FILES
 296 .Bl -tag -width ".Pa /dev/mrsas?" -compact
 297 .It /dev/da?
 298 array/logical disk interface
 299 .It /dev/mrsas?
 300 management interface
 301 .El
 302 .Sh SEE ALSO
 303 .Xr pci 4 ,
 304 .Xr mfi 4 ,
 305 .Xr cam 4 ,
 306 .Xr device.hints 5 ,
 307 .Sh HISTORY
 308 The
 309 .Nm
 310 driver first appeared in
 311 .Fx 10.0 .
 312 .Bd -ragged
 313 .Cd "mfi Driver:"
 314 .Xr mfi 4
 315 is the old FreeBSD driver which started with support for Gen-1 Controllers and
 316 was extended to support up to MR-Fusion (Device ID = 0x005B, 0x005D, 0x005F).
 317 .Ed
 318 .Bd -ragged
 319 .Cd "mrsas Driver:"
 320 .Nm
 321 is the new driver reworked by LSI which supports Thunderbolt and onward
 322 products. The SAS+SATA RAID controller with device id 0x005b is referred to as
 323 the Thunderbolt controller throughout in this man page.
 324 .Ed
 325 .Bd -ragged
 326 .Nm cam aware HBA drivers:
 327 FreeBSD has a
 328 .Xr cam 4
 329 layer which attaches storage devices and provides a common access mechanism to
 330 storage controllers and attached devices.  The
 331 .Nm
 332 driver is
 333 .Xr cam 4 aware and devices associated with
 334 .Nm
 335 can be seen using
 336 .Xr camcontrol 8 .
 337 The
 338 .Xr mfi 4
 339 driver does not understand the
 340 .Xr cam 4
 341 layer and it directly associates storage disks to the block layer.
 342 .Pp
 343 .Nm Thunderbolt Controller:
 344 This is the 6Gb/s MegaRAID HBA card which has device id 0x005B.
 345 .Pp
 346 .Nm Invader Controller:
 347 This is 12Gb/s MegaRAID HBA card which has device id 0x005D.
 348 .Pp
 349 .Nm Fury Controller:
 350 This is the 12Gb/s MegaRAID HBA card which has device id 0x005F.
 351 .Ed
 352 .Sh AUTHORS
 353 The
 354 .Nm
 355 driver and this manual page were written by
 356 .An Kashyap Desai Aq Kashyap.Desai@lsi.com .
 357 .Sh TODO
 358 The driver does not support big-endian architectures at this time.
 359 .Pp
 360 The driver does not support alias for device name (it is required when the user
 361 switches between two drivers and does not want to edit /etc/fstab manually).
 362 .Pp
 363 The
 364 .Nm
 365 driver exposes devices as /dev/da?, whereas
 366 .Xr mfi 4
 367 exposes deivces as /dev/mfid?
 368 .Pp
 369 .Nm
 370 does not support the Linux Emulator interface.
 371 .Pp
 372 .Nm
 373 will not work with
 374 .Xr mfiutil 8