Documentation/driver-api/libata.rst

10 libATA is a library used inside the Linux kernel to support ATA host
16 internals, and a couple sample ATA low-level drivers.
27 ``->qc_issue()`` high-level hooks. Hardware which behaves in a manner
29 defining at a bare minimum the bus I/O addresses of the ATA shadow
61 optional ``->mode_filter()`` hook is called when libata has built a mask of
63 which should return a mask of valid modes after filtering those
70 is the library records the decisions for the modes of each drive on a
103 operation that actually copies the data bytes during a PIO data
127 Allow low-level driver to filter ATA PACKET commands, returning a status
191     tuning logic when a controller has quirks. Replacing the default
193     quirks that may be important to data reliability. If a controller
248 ``->qc_issue`` is used to make a command active, once the hardware and S/G
254 ``->bmdma_start()`` as necessary to initiate a transfer.
268 follows a successful reset.
271 hardware-wise (e.g. mask interrupt and stop DMA engine). If a port
284 ``->error_handler()`` is a driver's hook into probe, hotplug, and recovery
287 with a set of EH hooks as arguments:
305 after executing a probe-time or EH-time command via
321 The second argument, dev_instance, should be cast to a pointer to
359 use this entry point as a chance to allocate driver-private memory for
364 a legacy IDE PRD table and returns.
385 In libata, a command is represented with
416     translated. No qc is involved in processing a simulated scmd. The
432 processed differently. For the purpose of discussion, a controller which
514 timeout and ATAPI error completion. This function will check if a qc is active
515 and has not failed yet. Such a qc will be marked with AC_ERR_TIMEOUT such that
521 scsi_done. As described in SCSI EH doc, a recovered scmd should be
526 If EH is invoked due to a failed ATAPI qc, the qc here is completed but
528 place holder to make EH code reach this place. This is a bit hackish,
567    Second, even a simple failure (say, CRC error) needs information
608 error condition is reported from device or a command has timed out.
620 master IDE interface. If a controller provides other better mechanism
635    issue a command.
694     ICRC errors and on cases where a device is not able to complete a
726     or some other error condition. Note that ABRT bit can indicate a lot
734     3.2.3.3a N/A
735         A keyword the indicates a field has no defined value in this
746 in the STATUS register after the last byte of CDB is transferred for a
768 command can be handled as a normal ATA command error as in
793 -  On some controllers, command timeout. In this case, there may be a
872 Resetting during EH might be a good idea regardless of error condition
881 HBA resetting is implementation specific. For a controller complying to
902     this resets both master and slave devices on a channel.
909     other commands. As in software reset, EDD affects both devices on a
922     This is the preferred way of resetting a SATA device. In effect,
948 DEVICE is issued after any configuration parameter is updated or a
955 For both PATA and SATA, a lot of corners are cut for cheap connectors,
959 The following is a possible scheme Jeff Garzik suggested.