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