share/man/man4/twe.4

   1 .\"
   2 .\" Copyright (c) 2000 Michael Smith
   3 .\" Copyright (c) 2000 BSDi
   4 .\" All rights reserved.
   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. The name of the author may not be used to endorse or promote products
  12 .\"    derived from this software without specific prior written permission
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  15 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  16 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  17 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  18 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  19 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  20 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  21 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  22 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  23 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: src/share/man/man4/twe.4,v 1.18 2012/11/17 01:50:48 svnexp Exp $
  26 .\"
  27 .Dd December 10, 2014
  28 .Dt TWE 4
  29 .Os
  30 .Sh NAME
  31 .Nm twe
  32 .Nd 3ware 5000/6000/7000/8000 series PATA/SATA RAID adapter driver
  33 .Sh SYNOPSIS
  34 To compile this driver into the kernel,
  35 place the following lines in your
  36 kernel configuration file:
  37 .Bd -ragged -offset indent
  38 .Cd "device pci"
  39 .Cd "device twe"
  40 .Ed
  41 .Pp
  42 Alternatively, to load the driver as a
  43 module at boot time, place the following line in
  44 .Xr loader.conf 5 :
  45 .Bd -literal -offset indent
  46 twe_load="YES"
  47 .Ed
  48 .Sh DESCRIPTION
  49 The
  50 .Nm
  51 driver provides support for AMCC's 3ware 5000/6000/7000/8000 series
  52 PATA/SATA RAID adapters.
  53 These adapters were formerly known as
  54 .Dq 3ware Escalade .
  55 .Pp
  56 These devices support 2, 4, 8, or 12 ATA disk drives
  57 and provide RAID0 (striping) and RAID1 (mirroring) functionality.
  58 .Sh FILES
  59 .Bl -tag -width ".Pa /dev/twedX" -compact
  60 .It Pa /dev/twedX
  61 .Nm
  62 device nodes
  63 .El
  64 .Sh HARDWARE
  65 The
  66 .Nm
  67 driver supports the following PATA/SATA RAID
  68 controllers:
  69 .Pp
  70 .Bl -bullet -compact
  71 .It
  72 AMCC's 3ware 5000 series
  73 .It
  74 AMCC's 3ware 6000 series
  75 .It
  76 AMCC's 3ware 7000-2
  77 .It
  78 AMCC's 3ware 7006-2
  79 .It
  80 AMCC's 3ware 7500-4LP
  81 .It
  82 AMCC's 3ware 7500-8
  83 .It
  84 AMCC's 3ware 7500-12
  85 .It
  86 AMCC's 3ware 7506-4LP
  87 .It
  88 AMCC's 3ware 7506-8
  89 .It
  90 AMCC's 3ware 7506-12
  91 .It
  92 AMCC's 3ware 8006-2LP
  93 .It
  94 AMCC's 3ware 8500-4LP
  95 .It
  96 AMCC's 3ware 8500-8
  97 .It
  98 AMCC's 3ware 8500-12
  99 .It
 100 AMCC's 3ware 8506-4LP
 101 .It
 102 AMCC's 3ware 8506-8
 103 .It
 104 AMCC's 3ware 8506-8MI
 105 .It
 106 AMCC's 3ware 8506-12
 107 .It
 108 AMCC's 3ware 8506-12MI
 109 .El
 110 .Sh DIAGNOSTICS
 111 .Ss Controller initialisation phase
 112 .Bl -diag
 113 .It twe%d: microcontroller not ready
 114 .Pp
 115 The controller's onboard CPU is not reporting that it is ready;
 116 this may be due to either a board or system failure.
 117 Initialisation has failed.
 118 .It twe%d: no attention interrupt
 119 .It twe%d: can't drain AEN queue
 120 .It twe%d: reset not reported
 121 .It twe%d: controller errors detected
 122 .It twe%d: can't drain response queue
 123 .It twe%d: reset %d failed, trying again
 124 .Pp
 125 The controller is not responding correctly to
 126 the driver's attempts to reset and initialise it.
 127 This process is retried several times.
 128 .It twe%d: can't initialise controller, giving up
 129 .Pp
 130 Several attempts to reset and initialise the controller have failed;
 131 initialisation has failed
 132 and the driver will not attach to this controller.
 133 .El
 134 .Ss Driver initialisation/shutdown phase
 135 .Bl -diag
 136 .It twe%d: register window not available
 137 .It twe%d: can't allocate register window
 138 .It twe%d: can't allocate parent DMA tag
 139 .It twe%d: can't allocate interrupt
 140 .It twe%d: can't set up interrupt
 141 .It twe%d: can't establish configuration hook
 142 .Pp
 143 A resource allocation error occurred while initialising the driver;
 144 initialisation has failed
 145 and the driver will not attach to this controller.
 146 .It twe%d: can't detect attached units
 147 .Pp
 148 Fetching the list of attached units failed; initialisation has failed.
 149 .It twe%d: error fetching capacity for unit %d
 150 .It twe%d: error fetching state for unit %d
 151 .It twe%d: error fetching descriptor size for unit %d
 152 .It twe%d: error fetching descriptor for unit %d
 153 .It twe%d: device_add_child failed
 154 .It twe%d: bus_generic_attach returned %d
 155 .Pp
 156 Creation of the disk devices failed, either due to communication
 157 problems with the adapter or due to resource shortage;
 158 attachment of one or more units may have been aborted.
 159 .El
 160 .Ss Operational phase
 161 .Bl -diag
 162 .It twe%d: command completed - %s
 163 .El
 164 .Pp
 165 A command was reported completed with a warning by the controller.
 166 The warning may be one of:
 167 .Bl -diag
 168 .It redundant/inconsequential request ignored
 169 .It failed to write zeroes to LBA 0
 170 .It failed to profile TwinStor zones
 171 .El
 172 .Bl -diag
 173 .It twe%d: command failed - %s
 174 .El
 175 .Pp
 176 A command was reported as failed by the controller.
 177 The failure message may be one of:
 178 .Bl -diag
 179 .It aborted due to system command or reconfiguration
 180 .It aborted
 181 .It access error
 182 .It access violation
 183 .It device failure
 184 .It controller error
 185 .It timed out
 186 .It invalid unit number
 187 .It unit not available
 188 .It undefined opcode
 189 .It request incompatible with unit
 190 .It invalid request
 191 .It firmware error, reset requested
 192 .Pp
 193 The command will be returned to the operating system after a
 194 fatal error.
 195 .El
 196 .Bl -diag
 197 .It twe%d: command failed submission - controller wedged
 198 .Pp
 199 A command could not be delivered to the controller because
 200 the controller is unresponsive.
 201 .It twe%d: AEN: <%s>
 202 .El
 203 .Pp
 204 The controller has reported a change in status using an AEN
 205 (Asynchronous Event Notification).
 206 The following AENs may be reported:
 207 .Bl -diag
 208 .It queue empty
 209 .It soft reset
 210 .It degraded mirror
 211 .It controller error
 212 .It rebuild fail
 213 .It rebuild done
 214 .It incomplete unit
 215 .It initialisation done
 216 .It unclean shutdown detected
 217 .It drive timeout
 218 .It drive error
 219 .It rebuild started
 220 .It aen queue full
 221 .Pp
 222 AENs are also queued internally for use by management tools.
 223 .El
 224 .Bl -diag
 225 .It twe%d: error polling for signalled AENs
 226 .Pp
 227 The controller has reported
 228 that one or more status messages are ready for the driver,
 229 but attempting to fetch one of these has returned an error.
 230 .It twe%d: AEN queue overflow, lost AEN <%s>
 231 .Pp
 232 A status message was retrieved from the controller,
 233 but there is no more room to queue it in the driver.
 234 The message is lost (but will be printed to the console).
 235 .It twe%d: missing expected status bits %s
 236 .It twe%d: unexpected status bits %s
 237 .Pp
 238 A check of the controller's status bits
 239 indicates an unexpected condition.
 240 .It twe%d: host interrupt
 241 .Pp
 242 The controller has signalled a host interrupt.
 243 This serves an unknown purpose and is ignored.
 244 .It twe%d: command interrupt
 245 .Pp
 246 The controller has signalled a command interrupt.
 247 This is not used, and will be disabled.
 248 .It twe%d: controller reset in progress...
 249 .Pp
 250 The controller is being reset by the driver.
 251 Typically this is done when the driver has determined that the
 252 controller is in an unrecoverable state.
 253 .It twe%d: can't reset controller, giving up
 254 .Pp
 255 The driver has given up on resetting the controller.
 256 No further I/O will be handled.
 257 .It controller reset done, %d commands restarted
 258 .Pp
 259 The controller was successfully reset,
 260 and outstanding commands were restarted.
 261 .El
 262 .Sh SEE ALSO
 263 .Xr twa 4 ,
 264 .Xr tws 4
 265 .Sh AUTHORS
 266 .An -nosplit
 267 The
 268 .Nm
 269 driver and manual page were written by
 270 .An Michael Smith Aq Mt msmith@FreeBSD.org .
 271 .Pp
 272 Extensive work done on the driver by
 273 .An Vinod Kashyap Aq Mt vkashyap@FreeBSD.org
 274 and
 275 .An Paul Saab Aq Mt ps@FreeBSD.org .
 276 .Sh BUGS
 277 The controller cannot handle I/O transfers
 278 that are not aligned to a 512-byte boundary.
 279 In order to support raw device access from user-space,
 280 the driver will perform alignment fixup on non-aligned data.
 281 This process is inefficient,
 282 and thus in order to obtain best performance
 283 user-space applications accessing the device
 284 should do so with aligned buffers.