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