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: head/share/man/man4/twe.4 148788 2005-08-06 13:05:45Z hmp $
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
37The
38.Nm
39driver provides support for AMCC's 3ware 5000/6000/7000/8000 series
40PATA/SATA RAID adapters.
41These adapters were formerly known as
42.Dq 3ware Escalade .
43.Pp
44These devices support 2, 4, 8, or 12 ATA disk drives
45and provide RAID0 (striping) and RAID1 (mirroring) functionality.
46.Sh HARDWARE
47The
48.Nm
49driver supports the following PATA/SATA RAID
50controllers:
51.Pp
52.Bl -bullet -compact
53.It
54AMCC's 3ware 5000 series
55.It
56AMCC's 3ware 6000 series
57.It
58AMCC's 3ware 7000-2
59.It
60AMCC's 3ware 7006-2
61.It
62AMCC's 3ware 7500-4LP
63.It
64AMCC's 3ware 7500-8
65.It
66AMCC's 3ware 7500-12
67.It
68AMCC's 3ware 7506-4LP
69.It
70AMCC's 3ware 7506-8
71.It
72AMCC's 3ware 7506-12
73.It
74AMCC's 3ware 8006-2LP
75.It
76AMCC's 3ware 8500-4LP
77.It
78AMCC's 3ware 8500-8
79.It
80AMCC's 3ware 8500-12
81.It
82AMCC's 3ware 8506-4LP
83.It
84AMCC's 3ware 8506-8
85.It
86AMCC's 3ware 8506-8MI
87.It
88AMCC's 3ware 8506-12
89.It
90AMCC'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
97The controller's onboard CPU is not reporting that it is ready;
98this may be due to either a board or system failure.
99Initialisation 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
107The controller is not responding correctly to
108the driver's attempts to reset and initialise it.
109This process is retried several times.
110.It twe%d: can't initialise controller, giving up
111.Pp
112Several attempts to reset and initialise the controller have failed;
113initialisation has failed
114and 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
125A resource allocation error occurred while initialising the driver;
126initialisation has failed
127and the driver will not attach to this controller.
128.It twe%d: can't detect attached units
129.Pp
130Fetching 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
138Creation of the disk devices failed, either due to communication
139problems with the adapter or due to resource shortage;
140attachment 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
147A command was reported completed with a warning by the controller.
148The 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
158A command was reported as failed by the controller.
159The 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
175The command will be returned to the operating system after a
176fatal error.
177.El
178.Bl -diag
179.It twe%d: command failed submission - controller wedged
180.Pp
181A command could not be delivered to the controller because
182the controller is unresponsive.
183.It twe%d: AEN: <%s>
184.El
185.Pp
186The controller has reported a change in status using an AEN
187(Asynchronous Event Notification).
188The 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
204AENs 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
209The controller has reported
210that one or more status messages are ready for the driver,
211but attempting to fetch one of these has returned an error.
212.It twe%d: AEN queue overflow, lost AEN <%s>
213.Pp
214A status message was retrieved from the controller,
215but there is no more room to queue it in the driver.
216The 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
220A check of the controller's status bits
221indicates an unexpected condition.
222.It twe%d: host interrupt
223.Pp
224The controller has signalled a host interrupt.
225This serves an unknown purpose and is ignored.
226.It twe%d: command interrupt
227.Pp
228The controller has signalled a command interrupt.
229This is not used, and will be disabled.
230.It twe%d: controller reset in progress...
231.Pp
232The controller is being reset by the driver.
233Typically this is done when the driver has determined that the
234controller is in an unrecoverable state.
235.It twe%d: can't reset controller, giving up
236.Pp
237The driver has given up on resetting the controller.
238No further I/O will be handled.
239.It controller reset done, %d commands restarted
240.Pp
241The controller was successfully reset,
242and outstanding commands were restarted.
243.El
244.Sh AUTHORS
245.An -nosplit
246The
247.Nm
248driver and manual page were written by
249.An Michael Smith
250.Aq msmith@FreeBSD.org .
251.Pp
252Extensive work done on the driver by
253.An Vinod Kashyap
254.Aq vkashyap@FreeBSD.org
255and
256.An Paul Saab
257.Aq ps@FreeBSD.org .
258.Sh BUGS
259The controller cannot handle I/O transfers
260that are not aligned to a 512-byte boundary.
261In order to support raw device access from user-space,
262the driver will perform alignment fixup on non-aligned data.
263This process is inefficient,
264and thus in order to obtain best performance
265user-space applications accessing the device
266should do so with aligned buffers.
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: head/share/man/man4/twe.4 148788 2005-08-06 13:05:45Z hmp $
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
37The
38.Nm
39driver provides support for AMCC's 3ware 5000/6000/7000/8000 series
40PATA/SATA RAID adapters.
41These adapters were formerly known as
42.Dq 3ware Escalade .
43.Pp
44These devices support 2, 4, 8, or 12 ATA disk drives
45and provide RAID0 (striping) and RAID1 (mirroring) functionality.
46.Sh HARDWARE
47The
48.Nm
49driver supports the following PATA/SATA RAID
50controllers:
51.Pp
52.Bl -bullet -compact
53.It
54AMCC's 3ware 5000 series
55.It
56AMCC's 3ware 6000 series
57.It
58AMCC's 3ware 7000-2
59.It
60AMCC's 3ware 7006-2
61.It
62AMCC's 3ware 7500-4LP
63.It
64AMCC's 3ware 7500-8
65.It
66AMCC's 3ware 7500-12
67.It
68AMCC's 3ware 7506-4LP
69.It
70AMCC's 3ware 7506-8
71.It
72AMCC's 3ware 7506-12
73.It
74AMCC's 3ware 8006-2LP
75.It
76AMCC's 3ware 8500-4LP
77.It
78AMCC's 3ware 8500-8
79.It
80AMCC's 3ware 8500-12
81.It
82AMCC's 3ware 8506-4LP
83.It
84AMCC's 3ware 8506-8
85.It
86AMCC's 3ware 8506-8MI
87.It
88AMCC's 3ware 8506-12
89.It
90AMCC'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
97The controller's onboard CPU is not reporting that it is ready;
98this may be due to either a board or system failure.
99Initialisation 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
107The controller is not responding correctly to
108the driver's attempts to reset and initialise it.
109This process is retried several times.
110.It twe%d: can't initialise controller, giving up
111.Pp
112Several attempts to reset and initialise the controller have failed;
113initialisation has failed
114and 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
125A resource allocation error occurred while initialising the driver;
126initialisation has failed
127and the driver will not attach to this controller.
128.It twe%d: can't detect attached units
129.Pp
130Fetching 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
138Creation of the disk devices failed, either due to communication
139problems with the adapter or due to resource shortage;
140attachment 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
147A command was reported completed with a warning by the controller.
148The 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
158A command was reported as failed by the controller.
159The 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
175The command will be returned to the operating system after a
176fatal error.
177.El
178.Bl -diag
179.It twe%d: command failed submission - controller wedged
180.Pp
181A command could not be delivered to the controller because
182the controller is unresponsive.
183.It twe%d: AEN: <%s>
184.El
185.Pp
186The controller has reported a change in status using an AEN
187(Asynchronous Event Notification).
188The 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
204AENs 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
209The controller has reported
210that one or more status messages are ready for the driver,
211but attempting to fetch one of these has returned an error.
212.It twe%d: AEN queue overflow, lost AEN <%s>
213.Pp
214A status message was retrieved from the controller,
215but there is no more room to queue it in the driver.
216The 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
220A check of the controller's status bits
221indicates an unexpected condition.
222.It twe%d: host interrupt
223.Pp
224The controller has signalled a host interrupt.
225This serves an unknown purpose and is ignored.
226.It twe%d: command interrupt
227.Pp
228The controller has signalled a command interrupt.
229This is not used, and will be disabled.
230.It twe%d: controller reset in progress...
231.Pp
232The controller is being reset by the driver.
233Typically this is done when the driver has determined that the
234controller is in an unrecoverable state.
235.It twe%d: can't reset controller, giving up
236.Pp
237The driver has given up on resetting the controller.
238No further I/O will be handled.
239.It controller reset done, %d commands restarted
240.Pp
241The controller was successfully reset,
242and outstanding commands were restarted.
243.El
244.Sh AUTHORS
245.An -nosplit
246The
247.Nm
248driver and manual page were written by
249.An Michael Smith
250.Aq msmith@FreeBSD.org .
251.Pp
252Extensive work done on the driver by
253.An Vinod Kashyap
254.Aq vkashyap@FreeBSD.org
255and
256.An Paul Saab
257.Aq ps@FreeBSD.org .
258.Sh BUGS
259The controller cannot handle I/O transfers
260that are not aligned to a 512-byte boundary.
261In order to support raw device access from user-space,
262the driver will perform alignment fixup on non-aligned data.
263This process is inefficient,
264and thus in order to obtain best performance
265user-space applications accessing the device
266should do so with aligned buffers.