Chapter 2. libata Driver API

Table of Contents

struct ata_port_operations
Disable ATA port
Post-IDENTIFY device configuration
Set PIO/DMA mode
Taskfile read/write
PIO data read/write
ATA command execute
Per-cmd ATAPI DMA capabilities filter
Read specific ATA shadow registers
Select ATA device on bus
Private tuning method
Control PCI IDE BMDMA engine
High-level taskfile hooks
Exception and probe handling (EH)
Hardware interrupt handling
SATA phy read/write
Init and shutdown

struct ata_port_operations is defined for every low-level libata hardware driver, and it controls how the low-level driver interfaces with the ATA and SCSI layers.

FIS-based drivers will hook into the system with ->qc_prep() and ->qc_issue() high-level hooks. Hardware which behaves in a manner similar to PCI IDE hardware may utilize several generic helpers, defining at a bare minimum the bus I/O addresses of the ATA shadow register blocks.

void (*eng_timeout) (struct ata_port *ap);
void (*phy_reset) (struct ata_port *ap);
	

Deprecated. Use ->error_handler() instead.

void (*freeze) (struct ata_port *ap);
void (*thaw) (struct ata_port *ap);
	

ata_port_freeze() is called when HSM violations or some other condition disrupts normal operation of the port. A frozen port is not allowed to perform any operation until the port is thawed, which usually follows a successful reset.

The optional ->freeze() callback can be used for freezing the port hardware-wise (e.g. mask interrupt and stop DMA engine). If a port cannot be frozen hardware-wise, the interrupt handler must ack and clear interrupts unconditionally while the port is frozen.

The optional ->thaw() callback is called to perform the opposite of ->freeze(): prepare the port for normal operation once again. Unmask interrupts, start DMA engine, etc.

void (*error_handler) (struct ata_port *ap);
	

->error_handler() is a driver's hook into probe, hotplug, and recovery and other exceptional conditions. The primary responsibility of an implementation is to call ata_do_eh() or ata_bmdma_drive_eh() with a set of EH hooks as arguments:

'prereset' hook (may be NULL) is called during an EH reset, before any other actions are taken.

'postreset' hook (may be NULL) is called after the EH reset is performed. Based on existing conditions, severity of the problem, and hardware capabilities,

Either 'softreset' (may be NULL) or 'hardreset' (may be NULL) will be called to perform the low-level EH reset.

void (*post_internal_cmd) (struct ata_queued_cmd *qc);
	

Perform any hardware-specific actions necessary to finish processing after executing a probe-time or EH-time command via ata_exec_internal().