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$
  26 .\"
  27 .Dd August 15, 2004
  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 .Cd device pci
  35 .Cd device twe
  36 .Sh DESCRIPTION
  37 The
  38 .Nm
  39 driver provides support for AMCC's 3ware 5000/6000/7000/8000 series
  40 PATA/SATA RAID adapters.
  41 These adapters were formerly known as
  42 .Dq 3ware Escalade .
  43 .Pp
  44 These devices support 2, 4, 8, or 12 ATA disk drives
  45 and provide RAID0 (striping) and RAID1 (mirroring) functionality.
  46 .Sh HARDWARE
  47 The
  48 .Nm
  49 driver supports the following PATA/SATA RAID
  50 controllers:
  51 .Pp
  52 .Bl -bullet -compact
  53 .It
  54 AMCC's 3ware 5000 series
  55 .It
  56 AMCC's 3ware 6000 series
  57 .It
  58 AMCC's 3ware 7000-2
  59 .It
  60 AMCC's 3ware 7006-2
  61 .It
  62 AMCC's 3ware 7500-4LP
  63 .It
  64 AMCC's 3ware 7500-8
  65 .It
  66 AMCC's 3ware 7500-12
  67 .It
  68 AMCC's 3ware 7506-4LP
  69 .It
  70 AMCC's 3ware 7506-8
  71 .It
  72 AMCC's 3ware 7506-12
  73 .It
  74 AMCC's 3ware 8006-2LP
  75 .It
  76 AMCC's 3ware 8500-4LP
  77 .It
  78 AMCC's 3ware 8500-8
  79 .It
  80 AMCC's 3ware 8500-12
  81 .It
  82 AMCC's 3ware 8506-4LP
  83 .It
  84 AMCC's 3ware 8506-8
  85 .It
  86 AMCC's 3ware 8506-8MI
  87 .It
  88 AMCC's 3ware 8506-12
  89 .It
  90 AMCC's 3ware 8506-12MI
  91 .El
  92 .Sh DIAGNOSTICS
  93 .Ss Controller initialisation phase
  94 .Bl -diag
  95 .It twe%d: microcontroller not ready
  96 .Pp
  97 The controller's onboard CPU is not reporting that it is ready;
  98 this may be due to either a board or system failure.
  99 Initialisation has failed.
 100 .It twe%d: no attention interrupt
 101 .It twe%d: can't drain AEN queue
 102 .It twe%d: reset not reported
 103 .It twe%d: controller errors detected
 104 .It twe%d: can't drain response queue
 105 .It twe%d: reset %d failed, trying again
 106 .Pp
 107 The controller is not responding correctly to
 108 the driver's attempts to reset and initialise it.
 109 This process is retried several times.
 110 .It twe%d: can't initialise controller, giving up
 111 .Pp
 112 Several attempts to reset and initialise the controller have failed;
 113 initialisation has failed
 114 and the driver will not attach to this controller.
 115 .El
 116 .Ss Driver initialisation/shutdown phase
 117 .Bl -diag
 118 .It twe%d: register window not available
 119 .It twe%d: can't allocate register window
 120 .It twe%d: can't allocate parent DMA tag
 121 .It twe%d: can't allocate interrupt
 122 .It twe%d: can't set up interrupt
 123 .It twe%d: can't establish configuration hook
 124 .Pp
 125 A resource allocation error occurred while initialising the driver;
 126 initialisation has failed
 127 and the driver will not attach to this controller.
 128 .It twe%d: can't detect attached units
 129 .Pp
 130 Fetching the list of attached units failed; initialisation has failed.
 131 .It twe%d: error fetching capacity for unit %d
 132 .It twe%d: error fetching state for unit %d
 133 .It twe%d: error fetching descriptor size for unit %d
 134 .It twe%d: error fetching descriptor for unit %d
 135 .It twe%d: device_add_child failed
 136 .It twe%d: bus_generic_attach returned %d
 137 .Pp
 138 Creation of the disk devices failed, either due to communication
 139 problems with the adapter or due to resource shortage;
 140 attachment of one or more units may have been aborted.
 141 .El
 142 .Ss Operational phase
 143 .Bl -diag
 144 .It twe%d: command completed - %s
 145 .El
 146 .Pp
 147 A command was reported completed with a warning by the controller.
 148 The warning may be one of:
 149 .Bl -diag
 150 .It redundant/inconsequential request ignored
 151 .It failed to write zeroes to LBA 0
 152 .It failed to profile TwinStor zones
 153 .El
 154 .Bl -diag
 155 .It twe%d: command failed - %s
 156 .El
 157 .Pp
 158 A command was reported as failed by the controller.
 159 The failure message may be one of:
 160 .Bl -diag
 161 .It aborted due to system command or reconfiguration
 162 .It aborted
 163 .It access error
 164 .It access violation
 165 .It device failure
 166 .It controller error
 167 .It timed out
 168 .It invalid unit number
 169 .It unit not available
 170 .It undefined opcode
 171 .It request incompatible with unit
 172 .It invalid request
 173 .It firmware error, reset requested
 174 .Pp
 175 The command will be returned to the operating system after a
 176 fatal error.
 177 .El
 178 .Bl -diag
 179 .It twe%d: command failed submission - controller wedged
 180 .Pp
 181 A command could not be delivered to the controller because
 182 the controller is unresponsive.
 183 .It twe%d: AEN: <%s>
 184 .El
 185 .Pp
 186 The controller has reported a change in status using an AEN
 187 (Asynchronous Event Notification).
 188 The following AENs may be reported:
 189 .Bl -diag
 190 .It queue empty
 191 .It soft reset
 192 .It degraded mirror
 193 .It controller error
 194 .It rebuild fail
 195 .It rebuild done
 196 .It incomplete unit
 197 .It initialisation done
 198 .It unclean shutdown detected
 199 .It drive timeout
 200 .It drive error
 201 .It rebuild started
 202 .It aen queue full
 203 .Pp
 204 AENs are also queued internally for use by management tools.
 205 .El
 206 .Bl -diag
 207 .It twe%d: error polling for signalled AENs
 208 .Pp
 209 The controller has reported
 210 that one or more status messages are ready for the driver,
 211 but attempting to fetch one of these has returned an error.
 212 .It twe%d: AEN queue overflow, lost AEN <%s>
 213 .Pp
 214 A status message was retrieved from the controller,
 215 but there is no more room to queue it in the driver.
 216 The message is lost (but will be printed to the console).
 217 .It twe%d: missing expected status bits %s
 218 .It twe%d: unexpected status bits %s
 219 .Pp
 220 A check of the controller's status bits
 221 indicates an unexpected condition.
 222 .It twe%d: host interrupt
 223 .Pp
 224 The controller has signalled a host interrupt.
 225 This serves an unknown purpose and is ignored.
 226 .It twe%d: command interrupt
 227 .Pp
 228 The controller has signalled a command interrupt.
 229 This is not used, and will be disabled.
 230 .It twe%d: controller reset in progress...
 231 .Pp
 232 The controller is being reset by the driver.
 233 Typically this is done when the driver has determined that the
 234 controller is in an unrecoverable state.
 235 .It twe%d: can't reset controller, giving up
 236 .Pp
 237 The driver has given up on resetting the controller.
 238 No further I/O will be handled.
 239 .It controller reset done, %d commands restarted
 240 .Pp
 241 The controller was successfully reset,
 242 and outstanding commands were restarted.
 243 .El
 244 .Sh AUTHORS
 245 .An -nosplit
 246 The
 247 .Nm
 248 driver and manual page were written by
 249 .An Michael Smith
 250 .Aq msmith@FreeBSD.org .
 251 .Pp
 252 Extensive work done on the driver by
 253 .An Vinod Kashyap
 254 .Aq vkashyap@FreeBSD.org
 255 and
 256 .An Paul Saab
 257 .Aq ps@FreeBSD.org .
 258 .Sh BUGS
 259 The controller cannot handle I/O transfers
 260 that are not aligned to a 512-byte boundary.
 261 In order to support raw device access from user-space,
 262 the driver will perform alignment fixup on non-aligned data.
 263 This process is inefficient,
 264 and thus in order to obtain best performance
 265 user-space applications accessing the device
 266 should do so with aligned buffers.