libATA Developer's Guide

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

ata_scsi_error()

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)

ATAPI device 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

Reset

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