FEX-Emu/linux
1
0
Fork 0
mirror of https://github.com/FEX-Emu/linux.git synced 2024-12-13 20:33:15 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

[PATCH] libata: add ATA exceptions chapter to doc

Browse Source 
Hello, Jeff.

This patch adds ATA errors & exceptions chapter to
Documentation/DocBook/libata.tmpl.  As suggested, the chapter is
placed before low level driver specific chapters.  Contents are
unchanged from the last posting.

Signed-off-by: Tejun Heo <htejun@gmail.com>
Signed-off-by: Jeff Garzik <jgarzik@pobox.com>
This commit is contained in:
Tejun Heo 2005-10-02 11:54:29 +09:00 committed by Jeff Garzik
parent 31961943e3
commit fe998aa7e2
1 changed files with 716 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

716
Documentation/DocBook/libata.tmpl
View File

@ -787,6 +787,722 @@ and other resources, etc.
!Idrivers/scsi/libata-scsi.c
</chapter>
<chapter id="ataExceptions">
<title>ATA errors &amp; exceptions</title>
<para>
This chapter tries to identify what error/exception conditions exist
for ATA/ATAPI devices and describe how they should be handled in
implementation-neutral way.
</para>
<para>
The term 'error' is used to describe conditions where either an
explicit error condition is reported from device or a command has
timed out.
</para>
<para>
The term 'exception' is either used to describe exceptional
conditions which are not errors (say, power or hotplug events), or
to describe both errors and non-error exceptional conditions. Where
explicit distinction between error and exception is necessary, the
term 'non-error exception' is used.
</para>
<sect1 id="excat">
<title>Exception categories</title>
<para>
Exceptions are described primarily with respect to legacy
taskfile + bus master IDE interface. If a controller provides
other better mechanism for error reporting, mapping those into
categories described below shouldn't be difficult.
</para>
<para>
In the following sections, two recovery actions - reset and
reconfiguring transport - are mentioned. These are described
further in <xref linkend="exrec"/>.
</para>
<sect2 id="excatHSMviolation">
<title>HSM violation</title>
<para>
This error is indicated when STATUS value doesn't match HSM
requirement during issuing or excution any ATA/ATAPI command.
</para>
<itemizedlist>
<title>Examples</title>
<listitem>
<para>
ATA_STATUS doesn't contain !BSY &amp;&amp; DRDY &amp;&amp; !DRQ while trying
to issue a command.
</para>
</listitem>
<listitem>
<para>
!BSY &amp;&amp; !DRQ during PIO data transfer.
</para>
</listitem>
<listitem>
<para>
DRQ on command completion.
</para>
</listitem>
<listitem>
<para>
!BSY &amp;&amp; ERR after CDB tranfer starts but before the
last byte of CDB is transferred. ATA/ATAPI standard states
that &quot;The device shall not terminate the PACKET command
with an error before the last byte of the command packet has
been written&quot; in the error outputs description of PACKET
command and the state diagram doesn't include such
transitions.
</para>
</listitem>
</itemizedlist>
<para>
In these cases, HSM is violated and not much information
regarding the error can be acquired from STATUS or ERROR
register. IOW, this error can be anything - driver bug,
faulty device, controller and/or cable.
</para>
<para>
As HSM is violated, reset is necessary to restore known state.
Reconfiguring transport for lower speed might be helpful too
as transmission errors sometimes cause this kind of errors.
</para>
</sect2>
<sect2 id="excatDevErr">
<title>ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION)</title>
<para>
These are errors detected and reported by ATA/ATAPI devices
indicating device problems. For this type of errors, STATUS
and ERROR register values are valid and describe error
condition. Note that some of ATA bus errors are detected by
ATA/ATAPI devices and reported using the same mechanism as
device errors. Those cases are described later in this
section.
</para>
<para>
For ATA commands, this type of errors are indicated by !BSY
&amp;&amp; ERR during command execution and on completion.
</para>
<para>For ATAPI commands,</para>
<itemizedlist>
<listitem>
<para>
!BSY &amp;&amp; ERR &amp;&amp; ABRT right after issuing PACKET
indicates that PACKET command is not supported and falls in
this category.
</para>
</listitem>
<listitem>
<para>
!BSY &amp;&amp; ERR(==CHK) &amp;&amp; !ABRT after the last
byte of CDB is transferred indicates CHECK CONDITION and
doesn't fall in this category.
</para>
</listitem>
<listitem>
<para>
!BSY &amp;&amp; ERR(==CHK) &amp;&amp; ABRT after the last byte
of CDB is transferred *probably* indicates CHECK CONDITION and
doesn't fall in this category.
</para>
</listitem>
</itemizedlist>
<para>
Of errors detected as above, the followings are not ATA/ATAPI
device errors but ATA bus errors and should be handled
according to <xref linkend="excatATAbusErr"/>.
</para>
<variablelist>
<varlistentry>
<term>CRC error during data transfer</term>
<listitem>
<para>
This is indicated by ICRC bit in the ERROR register and
means that corruption occurred during data transfer. Upto
ATA/ATAPI-7, the standard specifies that this bit is only
applicable to UDMA transfers but ATA/ATAPI-8 draft revision
1f says that the bit may be applicable to multiword DMA and
PIO.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ABRT error during data transfer or on completion</term>
<listitem>
<para>
Upto ATA/ATAPI-7, the standard specifies that ABRT could be
set on ICRC errors and on cases where a device is not able
to complete a command. Combined with the fact that MWDMA
and PIO transfer errors aren't allowed to use ICRC bit upto
ATA/ATAPI-7, it seems to imply that ABRT bit alone could
indicate tranfer errors.
</para>
<para>
However, ATA/ATAPI-8 draft revision 1f removes the part
that ICRC errors can turn on ABRT. So, this is kind of
gray area. Some heuristics are needed here.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
ATA/ATAPI device errors can be further categorized as follows.
</para>
<variablelist>
<varlistentry>
<term>Media errors</term>
<listitem>
<para>
This is indicated by UNC bit in the ERROR register. ATA
devices reports UNC error only after certain number of
retries cannot recover the data, so there's nothing much
else to do other than notifying upper layer.
</para>
<para>
READ and WRITE commands report CHS or LBA of the first
failed sector but ATA/ATAPI standard specifies that the
amount of transferred data on error completion is
indeterminate, so we cannot assume that sectors preceding
the failed sector have been transferred and thus cannot
complete those sectors successfully as SCSI does.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Media changed / media change requested error</term>
<listitem>
<para>
&lt;&lt;TODO: fill here&gt;&gt;
</para>
</listitem>
</varlistentry>
<varlistentry><term>Address error</term>
<listitem>
<para>
This is indicated by IDNF bit in the ERROR register.
Report to upper layer.
</para>
</listitem>
</varlistentry>
<varlistentry><term>Other errors</term>
<listitem>
<para>
This can be invalid command or parameter indicated by ABRT
ERROR bit or some other error condition. Note that ABRT
bit can indicate a lot of things including ICRC and Address
errors. Heuristics needed.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
Depending on commands, not all STATUS/ERROR bits are
applicable. These non-applicable bits are marked with
&quot;na&quot; in the output descriptions but upto ATA/ATAPI-7
no definition of &quot;na&quot; can be found. However,
ATA/ATAPI-8 draft revision 1f describes &quot;N/A&quot; as
follows.
</para>
<blockquote>
<variablelist>
<varlistentry><term>3.2.3.3a N/A</term>
<listitem>
<para>
A keyword the indicates a field has no defined value in
this standard and should not be checked by the host or
device. N/A fields should be cleared to zero.
</para>
</listitem>
</varlistentry>
</variablelist>
</blockquote>
<para>
So, it seems reasonable to assume that &quot;na&quot; bits are
cleared to zero by devices and thus need no explicit masking.
</para>
</sect2>
<sect2 id="excatATAPIcc">
<title>ATAPI device CHECK CONDITION</title>
<para>
ATAPI device CHECK CONDITION error is indicated by set CHK bit
(ERR bit) in the STATUS register after the last byte of CDB is
transferred for a PACKET command. For this kind of errors,
sense data should be acquired to gather information regarding
the errors. REQUEST SENSE packet command should be used to
acquire sense data.
</para>
<para>
Once sense data is acquired, this type of errors can be
handled similary to other SCSI errors. Note that sense data
may indicate ATA bus error (e.g. Sense Key 04h HARDWARE ERROR
&amp;&amp; ASC/ASCQ 47h/00h SCSI PARITY ERROR). In such
cases, the error should be considered as an ATA bus error and
handled according to <xref linkend="excatATAbusErr"/>.
</para>
</sect2>
<sect2 id="excatNCQerr">
<title>ATA device error (NCQ)</title>
<para>
NCQ command error is indicated by cleared BSY and set ERR bit
during NCQ command phase (one or more NCQ commands
outstanding). Although STATUS and ERROR registers will
contain valid values describing the error, READ LOG EXT is
required to clear the error condition, determine which command
has failed and acquire more information.
</para>
<para>
READ LOG EXT Log Page 10h reports which tag has failed and
taskfile register values describing the error. With this
information the failed command can be handled as a normal ATA
command error as in <xref linkend="excatDevErr"/> and all
other in-flight commands must be retried. Note that this
retry should not be counted - it's likely that commands
retried this way would have completed normally if it were not
for the failed command.
</para>
<para>
Note that ATA bus errors can be reported as ATA device NCQ
errors. This should be handled as described in <xref
linkend="excatATAbusErr"/>.
</para>
<para>
If READ LOG EXT Log Page 10h fails or reports NQ, we're
thoroughly screwed. This condition should be treated
according to <xref linkend="excatHSMviolation"/>.
</para>
</sect2>
<sect2 id="excatATAbusErr">
<title>ATA bus error</title>
<para>
ATA bus error means that data corruption occurred during
transmission over ATA bus (SATA or PATA). This type of errors
can be indicated by
</para>
<itemizedlist>
<listitem>
<para>
ICRC or ABRT error as described in <xref linkend="excatDevErr"/>.
</para>
</listitem>
<listitem>
<para>
Controller-specific error completion with error information
indicating transmission error.
</para>
</listitem>
<listitem>
<para>
On some controllers, command timeout. In this case, there may
be a mechanism to determine that the timeout is due to
transmission error.
</para>
</listitem>
<listitem>
<para>
Unknown/random errors, timeouts and all sorts of weirdities.
</para>
</listitem>
</itemizedlist>
<para>
As described above, transmission errors can cause wide variety
of symptoms ranging from device ICRC error to random device
lockup, and, for many cases, there is no way to tell if an
error condition is due to transmission error or not;
therefore, it's necessary to employ some kind of heuristic
when dealing with errors and timeouts. For example,
encountering repetitive ABRT errors for known supported
command is likely to indicate ATA bus error.
</para>
<para>
Once it's determined that ATA bus errors have possibly
occurred, lowering ATA bus transmission speed is one of
actions which may alleviate the problem. See <xref
linkend="exrecReconf"/> for more information.
</para>
</sect2>
<sect2 id="excatPCIbusErr">
<title>PCI bus error</title>
<para>
Data corruption or other failures during transmission over PCI
(or other system bus). For standard BMDMA, this is indicated
by Error bit in the BMDMA Status register. This type of
errors must be logged as it indicates something is very wrong
with the system. Resetting host controller is recommended.
</para>
</sect2>
<sect2 id="excatLateCompletion">
<title>Late completion</title>
<para>
This occurs when timeout occurs and the timeout handler finds
out that the timed out command has completed successfully or
with error. This is usually caused by lost interrupts. This
type of errors must be logged. Resetting host controller is
recommended.
</para>
</sect2>
<sect2 id="excatUnknown">
<title>Unknown error (timeout)</title>
<para>
This is when timeout occurs and the command is still
processing or the host and device are in unknown state. When
this occurs, HSM could be in any valid or invalid state. To
bring the device to known state and make it forget about the
timed out command, resetting is necessary. The timed out
command may be retried.
</para>
<para>
Timeouts can also be caused by transmission errors. Refer to
<xref linkend="excatATAbusErr"/> for more details.
</para>
</sect2>
<sect2 id="excatHoplugPM">
<title>Hotplug and power management exceptions</title>
<para>
&lt;&lt;TODO: fill here&gt;&gt;
</para>
</sect2>
</sect1>
<sect1 id="exrec">
<title>EH recovery actions</title>
<para>
This section discusses several important recovery actions.
</para>
<sect2 id="exrecClr">
<title>Clearing error condition</title>
<para>
Many controllers require its error registers to be cleared by
error handler. Different controllers may have different
requirements.
</para>
<para>
For SATA, it's strongly recommended to clear at least SError
register during error handling.
</para>
</sect2>
<sect2 id="exrecRst">
<title>Reset</title>
<para>
During EH, resetting is necessary in the following cases.
</para>
<itemizedlist>
<listitem>
<para>
HSM is in unknown or invalid state
</para>
</listitem>
<listitem>
<para>
HBA is in unknown or invalid state
</para>
</listitem>
<listitem>
<para>
EH needs to make HBA/device forget about in-flight commands
</para>
</listitem>
<listitem>
<para>
HBA/device behaves weirdly
</para>
</listitem>
</itemizedlist>
<para>
Resetting during EH might be a good idea regardless of error
condition to improve EH robustness. Whether to reset both or
either one of HBA and device depends on situation but the
following scheme is recommended.
</para>
<itemizedlist>
<listitem>
<para>
When it's known that HBA is in ready state but ATA/ATAPI
device in in unknown state, reset only device.
</para>
</listitem>
<listitem>
<para>
If HBA is in unknown state, reset both HBA and device.
</para>
</listitem>
</itemizedlist>
<para>
HBA resetting is implementation specific. For a controller
complying to taskfile/BMDMA PCI IDE, stopping active DMA
transaction may be sufficient iff BMDMA state is the only HBA
context. But even mostly taskfile/BMDMA PCI IDE complying
controllers may have implementation specific requirements and
mechanism to reset themselves. This must be addressed by
specific drivers.
</para>
<para>
OTOH, ATA/ATAPI standard describes in detail ways to reset
ATA/ATAPI devices.
</para>
<variablelist>
<varlistentry><term>PATA hardware reset</term>
<listitem>
<para>
This is hardware initiated device reset signalled with
asserted PATA RESET- signal. There is no standard way to
initiate hardware reset from software although some
hardware provides registers that allow driver to directly
tweak the RESET- signal.
</para>
</listitem>
</varlistentry>
<varlistentry><term>Software reset</term>
<listitem>
<para>
This is achieved by turning CONTROL SRST bit on for at
least 5us. Both PATA and SATA support it but, in case of
SATA, this may require controller-specific support as the
second Register FIS to clear SRST should be transmitted
while BSY bit is still set. Note that on PATA, this resets
both master and slave devices on a channel.
</para>
</listitem>
</varlistentry>
<varlistentry><term>EXECUTE DEVICE DIAGNOSTIC command</term>
<listitem>
<para>
Although ATA/ATAPI standard doesn't describe exactly, EDD
implies some level of resetting, possibly similar level
with software reset. Host-side EDD protocol can be handled
with normal command processing and most SATA controllers
should be able to handle EDD's just like other commands.
As in software reset, EDD affects both devices on a PATA
bus.
</para>
<para>
Although EDD does reset devices, this doesn't suit error
handling as EDD cannot be issued while BSY is set and it's
unclear how it will act when device is in unknown/weird
state.
</para>
</listitem>
</varlistentry>
<varlistentry><term>ATAPI DEVICE RESET command</term>
<listitem>
<para>
This is very similar to software reset except that reset
can be restricted to the selected device without affecting
the other device sharing the cable.
</para>
</listitem>
</varlistentry>
<varlistentry><term>SATA phy reset</term>
<listitem>
<para>
This is the preferred way of resetting a SATA device. In
effect, it's identical to PATA hardware reset. Note that
this can be done with the standard SCR Control register.
As such, it's usually easier to implement than software
reset.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
One more thing to consider when resetting devices is that
resetting clears certain configuration parameters and they
need to be set to their previous or newly adjusted values
after reset.
</para>
<para>
Parameters affected are.
</para>
<itemizedlist>
<listitem>
<para>
CHS set up with INITIALIZE DEVICE PARAMETERS (seldomly used)
</para>
</listitem>
<listitem>
<para>
Parameters set with SET FEATURES including transfer mode setting
</para>
</listitem>
<listitem>
<para>
Block count set with SET MULTIPLE MODE
</para>
</listitem>
<listitem>
<para>
Other parameters (SET MAX, MEDIA LOCK...)
</para>
</listitem>
</itemizedlist>
<para>
ATA/ATAPI standard specifies that some parameters must be
maintained across hardware or software reset, but doesn't
strictly specify all of them. Always reconfiguring needed
parameters after reset is required for robustness. Note that
this also applies when resuming from deep sleep (power-off).
</para>
<para>
Also, ATA/ATAPI standard requires that IDENTIFY DEVICE /
IDENTIFY PACKET DEVICE is issued after any configuration
parameter is updated or a hardware reset and the result used
for further operation. OS driver is required to implement
revalidation mechanism to support this.
</para>
</sect2>
<sect2 id="exrecReconf">
<title>Reconfigure transport</title>
<para>
For both PATA and SATA, a lot of corners are cut for cheap
connectors, cables or controllers and it's quite common to see
high transmission error rate. This can be mitigated by
lowering transmission speed.
</para>
<para>
The following is a possible scheme Jeff Garzik suggested.
</para>
<blockquote>
<para>
If more than $N (3?) transmission errors happen in 15 minutes,
</para>
<itemizedlist>
<listitem>
<para>
if SATA, decrease SATA PHY speed. if speed cannot be decreased,
</para>
</listitem>
<listitem>
<para>
decrease UDMA xfer speed. if at UDMA0, switch to PIO4,
</para>
</listitem>
<listitem>
<para>
decrease PIO xfer speed. if at PIO3, complain, but continue
</para>
</listitem>
</itemizedlist>
</blockquote>
</sect2>
</sect1>
</chapter>
<chapter id="PiixInt">
<title>ata_piix Internals</title>
!Idrivers/scsi/ata_piix.c