libATA Developer's Guide

Jeff Garzik

The contents of this file are subject to the Open Software License version 1.1 that can be found at and is included herein by reference.

Alternatively, the contents of this file may be used under the terms of the GNU General Public License version 2 (the "GPL") as distributed in the kernel source COPYING file, in which case the provisions of the GPL are applicable instead of the above. If you wish to allow the use of your version of this file only under the terms of the GPL and not to allow others to use your version of this file under the OSL, indicate your decision by deleting the provisions above and replace them with the notice and other provisions required by the GPL. If you do not delete the provisions above, a recipient may use your version of this file under either the OSL or the GPL.

Table of Contents

1. Introduction
2. libata Driver API
struct ata_port_operations
Disable ATA port
Post-IDENTIFY device configuration
Set PIO/DMA mode
Taskfile read/write
ATA command execute
Per-cmd ATAPI DMA capabilities filter
Read specific ATA shadow registers
Select ATA device on bus
Reset ATA bus
Control PCI IDE BMDMA engine
High-level taskfile hooks
Timeout (error) handling
Hardware interrupt handling
SATA phy read/write
Init and shutdown
3. Error handling
Origins of commands
How commands are issued
How commands are processed
How commands are completed
Problems with the current EH
4. libata Library
ata_tf_load - send taskfile registers to host controller
ata_exec_command - issue ATA command to host controller
ata_tf_read - input device's ATA taskfile shadow registers
ata_check_status - Read device status reg & clear interrupt
ata_altstatus - Read device alternate status reg
ata_tf_to_fis - Convert ATA taskfile to SATA FIS structure
ata_tf_from_fis - Convert SATA FIS to ATA taskfile
ata_dev_classify - determine device type based on ATA-spec signature
ata_dev_id_string - Convert IDENTIFY DEVICE page into string
ata_noop_dev_select - Select device 0/1 on ATA bus
ata_std_dev_select - Select device 0/1 on ATA bus
ata_dev_config - Run device specific handlers and check for
ata_port_probe - Mark port as enabled
__sata_phy_reset - Wake/reset a low-level SATA PHY
sata_phy_reset - Reset SATA bus.
ata_port_disable - Disable port.
ata_bus_reset - reset host port and associated ATA channel
ata_qc_prep - Prepare taskfile for submission
ata_sg_init_one - Associate command with memory buffer
ata_sg_init - Associate command with scatter-gather table.
ata_eng_timeout - Handle timeout of queued command
ata_qc_complete - Complete an active ATA command
ata_qc_issue_prot - issue taskfile to device in proto-dependent manner
ata_bmdma_start - Start a PCI IDE BMDMA transaction
ata_bmdma_setup - Set up PCI IDE BMDMA transaction
ata_bmdma_irq_clear - Clear PCI IDE BMDMA interrupt.
ata_bmdma_status - Read PCI IDE BMDMA status
ata_bmdma_stop - Stop PCI IDE BMDMA transfer
ata_host_intr - Handle host interrupt for given (port, task)
ata_interrupt - Default ATA host interrupt handler
ata_device_resume - wakeup a previously suspended devices
ata_device_suspend - prepare a device for suspend
ata_port_stop - Undo ata_port_start
ata_device_add - Register hardware device with ATA and SCSI layers
ata_host_set_remove - PCI layer callback for device removal
ata_scsi_release - SCSI layer callback hook for host unload
ata_std_ports - initialize ioaddr with standard port offsets.
ata_pci_init_native_mode - Initialize native-mode driver
ata_pci_init_one - Initialize/register PCI IDE host controller
ata_pci_remove_one - PCI layer callback for device removal
5. libata Core Internals
ata_tf_load_pio - send taskfile registers to host controller
ata_tf_load_mmio - send taskfile registers to host controller
ata_exec_command_pio - issue ATA command to host controller
ata_exec_command_mmio - issue ATA command to host controller
ata_tf_to_host - issue ATA taskfile to host controller
ata_tf_read_pio - input device's ATA taskfile shadow registers
ata_tf_read_mmio - input device's ATA taskfile shadow registers
ata_check_status_pio - Read device status reg & clear interrupt
ata_check_status_mmio - Read device status reg & clear interrupt
ata_rwcmd_protocol - set taskfile r/w commands and protocol
ata_mode_string - convert UDMA bit offset to string
ata_pio_devchk - PATA device presence detection
ata_mmio_devchk - PATA device presence detection
ata_devchk - PATA device presence detection
ata_dev_try_classify - Parse returned ATA device signature
ata_dev_select - Select device 0/1 on ATA bus
ata_dump_id - IDENTIFY DEVICE info debugging output
ata_exec_internal - execute libata internal command
ata_dev_identify - obtain IDENTIFY x DEVICE page
ata_bus_probe - Reset and probe ATA bus
ata_set_mode - Program timings and issue SET FEATURES - XFER
ata_busy_sleep - sleep until BSY clears, or timeout
ata_bus_edd - Issue EXECUTE DEVICE DIAGNOSTIC command.
ata_choose_xfer_mode - attempt to find best transfer mode
ata_dev_set_xfermode - Issue SET FEATURES - XFER MODE command
ata_dev_reread_id - Reread the device identify device info
ata_dev_init_params - Issue INIT DEV PARAMS command
ata_sg_clean - Unmap DMA memory associated with command
ata_fill_sg - Fill PCI IDE PRD table
ata_check_atapi_dma - Check whether ATAPI DMA can be supported
ata_sg_setup_one - DMA-map the memory buffer associated with a command.
ata_sg_setup - DMA-map the scatter-gather table associated with a command.
ata_poll_qc_complete - turn irq back on and finish qc
ata_pio_poll -
ata_pio_complete - check if drive is busy or idle
swap_buf_le16 - swap halves of 16-words in place
ata_mmio_data_xfer - Transfer data by MMIO
ata_pio_data_xfer - Transfer data by PIO
ata_data_xfer - Transfer data from/to the data register.
ata_pio_sector - Transfer ATA_SECT_SIZE (512 bytes) of data.
ata_pio_sectors - Transfer one or many 512-byte sectors.
atapi_send_cdb - Write CDB bytes to hardware
ata_pio_first_block - Write first data block to hardware
__atapi_pio_bytes - Transfer data from/to the ATAPI device.
atapi_pio_bytes - Transfer data from/to the ATAPI device.
ata_pio_block - start PIO on a block
ata_qc_timeout - Handle timeout of queued command
ata_qc_new - Request an available ATA command, for queueing
ata_qc_new_init - Request an available ATA command, and initialize it
ata_qc_free - free unused ata_queued_cmd
ata_qc_issue - issue taskfile to device
ata_bmdma_setup_mmio - Set up PCI IDE BMDMA transaction
ata_bmdma_start_mmio - Start a PCI IDE BMDMA transaction
ata_bmdma_setup_pio - Set up PCI IDE BMDMA transaction (PIO)
ata_bmdma_start_pio - Start a PCI IDE BMDMA transaction (PIO)
ata_do_simple_cmd - Set port up for dma.
ata_host_remove - Unregister SCSI host structure with upper layers
ata_host_init - Initialize an ata_port structure
ata_host_add - Attach low-level ATA driver to system
6. libata SCSI translation/emulation
ata_std_bios_param - generic bios head/sector/cylinder calculator used by sd.
ata_scsi_slave_config - Set SCSI device attributes
ata_scsi_error - SCSI layer error handler callback
ata_scsi_queuecmd - Issue SCSI cdb to libata-managed device
ata_scsi_simulate - simulate SCSI command on ATA device
ata_cmd_ioctl - Handler for HDIO_DRIVE_CMD ioctl
ata_task_ioctl - Handler for HDIO_DRIVE_TASK ioctl
ata_scsi_qc_new - acquire new ata_queued_cmd reference
ata_dump_status - user friendly display of error info
ata_to_sense_error - convert ATA error to SCSI error
ata_gen_fixed_sense - generate a SCSI fixed sense block
ata_scsi_start_stop_xlat - Translate SCSI START STOP UNIT command
ata_scsi_flush_xlat - Translate SCSI SYNCHRONIZE CACHE command
scsi_6_lba_len - Get LBA and transfer length
scsi_10_lba_len - Get LBA and transfer length
scsi_16_lba_len - Get LBA and transfer length
ata_scsi_verify_xlat - Translate SCSI VERIFY command into an ATA one
ata_scsi_rw_xlat - Translate SCSI r/w command into an ATA one
ata_scsi_translate - Translate then issue SCSI command to ATA device
ata_scsi_rbuf_get - Map response buffer.
ata_scsi_rbuf_put - Unmap response buffer.
ata_scsi_rbuf_fill - wrapper for SCSI command simulators
ata_scsiop_inq_std - Simulate INQUIRY command
ata_scsiop_inq_00 - Simulate INQUIRY EVPD page 0, list of pages
ata_scsiop_inq_80 - Simulate INQUIRY EVPD page 80, device serial number
ata_scsiop_inq_83 - Simulate INQUIRY EVPD page 83, device identity
ata_scsiop_noop - Command handler that simply returns success.
ata_msense_push - Push data onto MODE SENSE data output buffer
ata_msense_caching - Simulate MODE SENSE caching info page
ata_msense_ctl_mode - Simulate MODE SENSE control mode page
ata_msense_rw_recovery - Simulate MODE SENSE r/w error recovery page
ata_scsiop_mode_sense - Simulate MODE SENSE 6, 10 commands
ata_scsiop_read_cap - Simulate READ CAPACITY[ 16] commands
ata_scsiop_report_luns - Simulate REPORT LUNS command
ata_scsi_set_sense - Set SCSI sense data and status
ata_scsi_badcmd - End a SCSI request with an error
atapi_xlat - Initialize PACKET taskfile
ata_scsi_find_dev - lookup ata_device from scsi_cmnd
ata_scsi_pass_thru - convert ATA pass-thru CDB to taskfile
ata_get_xlat_func - check if SCSI to ATA translation is possible
ata_scsi_dump_cdb - dump SCSI command contents to dmesg
7. ATA errors & exceptions
Exception categories
HSM violation
ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION)
ATA device error (NCQ)
ATA bus error
PCI bus error
Late completion
Unknown error (timeout)
Hotplug and power management exceptions
EH recovery actions
Clearing error condition
Reconfigure transport
8. ata_piix Internals
piix_pata_cbl_detect - Probe host controller cable detect info
piix_pata_phy_reset - Probe specified port on PATA host controller
piix_sata_probe - Probe PCI device for present SATA devices
piix_sata_phy_reset - Probe specified port on SATA host controller
piix_set_piomode - Initialize host controller PATA PIO timings
piix_set_dmamode - Initialize host controller PATA PIO timings
piix_check_450nx_errata - Check for problem 450NX setup
piix_init_one - Register PIIX ATA PCI device with kernel services
9. sata_sil Internals
sil_dev_config - Apply device/host-specific errata fixups
10. Thanks