libATA Developer’s Guide

Author:Jeff Garzik

Introduction

libATA is a library used inside the Linux kernel to support ATA hostcontrollers and devices. libATA provides an ATA driver API, classtransports for ATA and ATAPI devices, and SCSI<->ATA translation for ATAdevices according to the T10 SAT specification.

This Guide documents the libATA driver API, library functions, libraryinternals, and a couple sample ATA low-level drivers.

libata Driver API

structata_port_operationsis defined for every low-level libatahardware driver, and it controls how the low-level driver interfaceswith 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 mannersimilar to PCI IDE hardware may utilize several generic helpers,defining at a bare minimum the bus I/O addresses of the ATA shadowregister blocks.

structata_port_operations

Disable ATA port

void (*port_disable) (struct ata_port *);

Called fromata_bus_probe() error path, as well as when unregisteringfrom the SCSI module (rmmod, hot unplug). This function should dowhatever needs to be done to take the port out of use. In most cases,ata_port_disable() can be used as this hook.

Called fromata_bus_probe() on a failed probe. Called fromata_scsi_release().

Post-IDENTIFY device configuration

void (*dev_config) (struct ata_port *, struct ata_device *);

Called after IDENTIFY [PACKET] DEVICE is issued to each device found.Typically used to apply device-specific fixups prior to issue of SETFEATURES - XFER MODE, and prior to operation.

This entry may be specified as NULL in ata_port_operations.

Set PIO/DMA mode

void (*set_piomode) (struct ata_port *, struct ata_device *);void (*set_dmamode) (struct ata_port *, struct ata_device *);void (*post_set_mode) (struct ata_port *);unsigned int (*mode_filter) (struct ata_port *, struct ata_device *, unsigned int);

Hooks called prior to the issue of SET FEATURES - XFER MODE command. Theoptional->mode_filter() hook is called when libata has built a mask ofthe possible modes. This is passed to the->mode_filter() functionwhich should return a mask of valid modes after filtering thoseunsuitable due to hardware limits. It is not valid to use this interfaceto add modes.

dev->pio_mode anddev->dma_mode are guaranteed to be valid when->set_piomode() and when->set_dmamode() is called. The timings forany other drive sharing the cable will also be valid at this point. Thatis the library records the decisions for the modes of each drive on achannel before it attempts to set any of them.

->post_set_mode() is called unconditionally, after the SET FEATURES -XFER MODE command completes successfully.

->set_piomode() is always called (if present), but->set_dma_mode()is only called if DMA is possible.

Taskfile read/write

void (*sff_tf_load) (struct ata_port *ap, struct ata_taskfile *tf);void (*sff_tf_read) (struct ata_port *ap, struct ata_taskfile *tf);

->tf_load() is called to load the given taskfile into hardwareregisters / DMA buffers.->tf_read() is called to read the hardwareregisters / DMA buffers, to obtain the current set of taskfile registervalues. Most drivers for taskfile-based hardware (PIO or MMIO) useata_sff_tf_load() andata_sff_tf_read() for these hooks.

PIO data read/write

void (*sff_data_xfer) (struct ata_device *, unsigned char *, unsigned int, int);

All bmdma-style drivers must implement this hook. This is the low-leveloperation that actually copies the data bytes during a PIO datatransfer. Typically the driver will choose one ofata_sff_data_xfer(), orata_sff_data_xfer32().

ATA command execute

void (*sff_exec_command)(struct ata_port *ap, struct ata_taskfile *tf);

causes an ATA command, previously loaded with->tf_load(), to beinitiated in hardware. Most drivers for taskfile-based hardware useata_sff_exec_command() for this hook.

Per-cmd ATAPI DMA capabilities filter

int (*check_atapi_dma) (struct ata_queued_cmd *qc);

Allow low-level driver to filter ATA PACKET commands, returning a statusindicating whether or not it is OK to use DMA for the supplied PACKETcommand.

This hook may be specified as NULL, in which case libata will assumethat atapi dma can be supported.

Read specific ATA shadow registers

u8   (*sff_check_status)(struct ata_port *ap);u8   (*sff_check_altstatus)(struct ata_port *ap);

Reads the Status/AltStatus ATA shadow register from hardware. On somehardware, reading the Status register has the side effect of clearingthe interrupt condition. Most drivers for taskfile-based hardware useata_sff_check_status() for this hook.

Write specific ATA shadow register

void (*sff_set_devctl)(struct ata_port *ap, u8 ctl);

Write the device control ATA shadow register to the hardware. Mostdrivers don’t need to define this.

Select ATA device on bus

void (*sff_dev_select)(struct ata_port *ap, unsigned int device);

Issues the low-level hardware command(s) that causes one of N hardwaredevices to be considered ‘selected’ (active and available for use) onthe ATA bus. This generally has no meaning on FIS-based devices.

Most drivers for taskfile-based hardware useata_sff_dev_select() forthis hook.

Private tuning method

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

By default libata performs drive and controller tuning in accordancewith the ATA timing rules and also applies blacklists and cable limits.Some controllers need special handling and have custom tuning rules,typically raid controllers that use ATA commands but do not actually dodrive timing.

Warning

This hook should not be used to replace the standard controllertuning logic when a controller has quirks. Replacing the defaulttuning logic in that case would bypass handling for drive and bridgequirks that may be important to data reliability. If a controllerneeds to filter the mode selection it should use the mode_filterhook instead.

Control PCI IDE BMDMA engine

void (*bmdma_setup) (struct ata_queued_cmd *qc);void (*bmdma_start) (struct ata_queued_cmd *qc);void (*bmdma_stop) (struct ata_port *ap);u8   (*bmdma_status) (struct ata_port *ap);

When setting up an IDE BMDMA transaction, these hooks arm(->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop) thehardware’s DMA engine.->bmdma_status is used to read the standard PCIIDE DMA Status register.

These hooks are typically either no-ops, or simply not implemented, inFIS-based drivers.

Most legacy IDE drivers useata_bmdma_setup() for thebmdma_setup() hook.ata_bmdma_setup() will write the pointerto the PRD table to the IDE PRD Table Address register, enable DMA in the DMACommand register, and callexec_command() to begin the transfer.

Most legacy IDE drivers useata_bmdma_start() for thebmdma_start() hook.ata_bmdma_start() will write theATA_DMA_START flag to the DMA Command register.

Many legacy IDE drivers useata_bmdma_stop() for thebmdma_stop() hook.ata_bmdma_stop() clears the ATA_DMA_STARTflag in the DMA command register.

Many legacy IDE drivers useata_bmdma_status() as thebmdma_status() hook.

High-level taskfile hooks

enum ata_completion_errors (*qc_prep) (struct ata_queued_cmd *qc);int (*qc_issue) (struct ata_queued_cmd *qc);

Higher-level hooks, these two hooks can potentially supersede several ofthe above taskfile/DMA engine hooks.->qc_prep is called after thebuffers have been DMA-mapped, and is typically used to populate thehardware’s DMA scatter-gather table. Some drivers use the standardata_bmdma_qc_prep() andata_bmdma_dumb_qc_prep() helperfunctions, but more advanced drivers roll their own.

->qc_issue is used to make a command active, once the hardware and S/Gtables have been prepared. IDE BMDMA drivers use the helper functionata_sff_qc_issue() for taskfile protocol-based dispatch. Moreadvanced drivers implement their own->qc_issue.

ata_sff_qc_issue() calls->sff_tf_load(),->bmdma_setup(), and->bmdma_start() as necessary to initiate a transfer.

Exception and probe handling (EH)

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 othercondition disrupts normal operation of the port. A frozen port is notallowed to perform any operation until the port is thawed, which usuallyfollows a successful reset.

The optional->freeze() callback can be used for freezing the porthardware-wise (e.g. mask interrupt and stop DMA engine). If a portcannot be frozen hardware-wise, the interrupt handler must ack and clearinterrupts 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. Unmaskinterrupts, start DMA engine, etc.

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

->error_handler() is a driver’s hook into probe, hotplug, and recoveryand other exceptional conditions. The primary responsibility of animplementation is to callata_do_eh() orata_bmdma_drive_eh()with a set of EH hooks as arguments:

‘prereset’ hook (may be NULL) is called during an EH reset, before anyother actions are taken.

‘postreset’ hook (may be NULL) is called after the EH reset isperformed. Based on existing conditions, severity of the problem, andhardware capabilities,

Either ‘softreset’ (may be NULL) or ‘hardreset’ (may be NULL) will becalled to perform the low-level EH reset.

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

Perform any hardware-specific actions necessary to finish processingafter executing a probe-time or EH-time command viaata_exec_internal().

Hardware interrupt handling

irqreturn_t (*irq_handler)(int, void *, struct pt_regs *);void (*irq_clear) (struct ata_port *);

->irq_handler is the interrupt handling routine registered with thesystem, by libata.->irq_clear is called during probe just before theinterrupt handler is registered, to be sure hardware is quiet.

The second argument, dev_instance, should be cast to a pointer tostructata_host_set.

Most legacy IDE drivers useata_sff_interrupt() for the irq_handlerhook, which scans all ports in the host_set, determines which queuedcommand was active (if any), and calls ata_sff_host_intr(ap,qc).

Most legacy IDE drivers useata_sff_irq_clear() for theirq_clear() hook, which simply clears the interrupt and error flagsin the DMA status register.

SATA phy read/write

int (*scr_read) (struct ata_port *ap, unsigned int sc_reg,         u32 *val);int (*scr_write) (struct ata_port *ap, unsigned int sc_reg,                   u32 val);

Read and write standard SATA phy registers. Currently only used if->phy_reset hook called thesata_phy_reset() helper function.sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE.

Init and shutdown

int (*port_start) (struct ata_port *ap);void (*port_stop) (struct ata_port *ap);void (*host_stop) (struct ata_host_set *host_set);

->port_start() is called just after the data structures for each portare initialized. Typically this is used to alloc per-port DMA buffers /tables / rings, enable DMA engines, and similar tasks. Some drivers alsouse this entry point as a chance to allocate driver-private memory forap->private_data.

Many drivers useata_port_start() as this hook or call it from theirownport_start() hooks.ata_port_start() allocates space fora legacy IDE PRD table and returns.

->port_stop() is called after->host_stop(). Its sole function is torelease DMA/memory resources, now that they are no longer actively beingused. Many drivers also free driver-private data from port at this time.

->host_stop() is called after all->port_stop() calls have completed.The hook must finalize hardware shutdown, release DMA and otherresources, etc. This hook may be specified as NULL, in which case it isnot called.

Error handling

This chapter describes how errors are handled under libata. Readers areadvised to read SCSI EH (Documentation/scsi/scsi_eh.rst) and ATAexceptions doc first.

Origins of commands

In libata, a command is represented withstructata_queued_cmd or qc.qc’s are preallocated during port initialization and repetitively usedfor command executions. Currently only one qc is allocated per port butyet-to-be-merged NCQ branch allocates one for each tag and maps each qcto NCQ tag 1-to-1.

libata commands can originate from two sources - libata itself and SCSImidlayer. libata internal commands are used for initialization and errorhandling. All normal blk requests and commands for SCSI emulation arepassed as SCSI commands through queuecommand callback of SCSI hosttemplate.

How commands are issued

Internal commands

First, qc is allocated and initialized usingata_qc_new_init().Althoughata_qc_new_init() doesn’t implement any wait or retrymechanism when qc is not available, internal commands are currentlyissued only during initialization and error recovery, so no othercommand is active and allocation is guaranteed to succeed.

Once allocated qc’s taskfile is initialized for the command to beexecuted. qc currently has two mechanisms to notify completion. Oneis viaqc->complete_fn() callback and the other is completionqc->waiting.qc->complete_fn() callback is the asynchronous pathused by normal SCSI translated commands andqc->waiting is thesynchronous (issuer sleeps in process context) path used by internalcommands.

Once initialization is complete, host_set lock is acquired and theqc is issued.

SCSI commands

All libata drivers useata_scsi_queuecmd() ashostt->queuecommand callback. scmds can either be simulated ortranslated. No qc is involved in processing a simulated scmd. Theresult is computed right away and the scmd is completed.

For a translated scmd,ata_qc_new_init() is invoked to allocate aqc and the scmd is translated into the qc. SCSI midlayer’scompletion notification function pointer is stored intoqc->scsidone.

qc->complete_fn() callback is used for completion notification. ATAcommands useata_scsi_qc_complete() while ATAPI commands useatapi_qc_complete(). Both functions end up callingqc->scsidoneto notify upper layer when the qc is finished. After translation iscompleted, the qc is issued withata_qc_issue().

Note that SCSI midlayer invokes hostt->queuecommand while holdinghost_set lock, so all above occur while holding host_set lock.

How commands are processed

Depending on which protocol and which controller are used, commands areprocessed differently. For the purpose of discussion, a controller whichuses taskfile interface and all standard callbacks is assumed.

Currently 6 ATA command protocols are used. They can be sorted into thefollowing four categories according to how they are processed.

ATA NO DATA or DMA
ATA_PROT_NODATA and ATA_PROT_DMA fall into this category. Thesetypes of commands don’t require any software intervention onceissued. Device will raise interrupt on completion.
ATA PIO
ATA_PROT_PIO is in this category. libata currently implements PIOwith polling. ATA_NIEN bit is set to turn off interrupt andpio_task on ata_wq performs polling and IO.
ATAPI NODATA or DMA
ATA_PROT_ATAPI_NODATA and ATA_PROT_ATAPI_DMA are in thiscategory. packet_task is used to poll BSY bit after issuing PACKETcommand. Once BSY is turned off by the device, packet_tasktransfers CDB and hands off processing to interrupt handler.
ATAPI PIO
ATA_PROT_ATAPI is in this category. ATA_NIEN bit is set and, asin ATAPI NODATA or DMA, packet_task submits cdb. However, aftersubmitting cdb, further processing (data transfer) is handed off topio_task.

How commands are completed

Once issued, all qc’s are either completed withata_qc_complete() ortime out. For commands which are handled by interrupts,ata_host_intr() invokesata_qc_complete(), and, for PIO tasks,pio_task invokesata_qc_complete(). In error cases, packet_task mayalso complete commands.

ata_qc_complete() does the following.

  1. DMA memory is unmapped.
  2. ATA_QCFLAG_ACTIVE is cleared from qc->flags.
  3. qc->complete_fn() callback is invoked. If the return value of thecallback is not zero. Completion is short circuited andata_qc_complete() returns.
  4. __ata_qc_complete() is called, which does
    1. qc->flags is cleared to zero.
    2. ap->active_tag andqc->tag are poisoned.
    3. qc->waiting is cleared & completed (in that order).
    4. qc is deallocated by clearing appropriate bit inap->qactive.

So, it basically notifies upper layer and deallocates qc. One exceptionis short-circuit path in #3 which is used byatapi_qc_complete().

For all non-ATAPI commands, whether it fails or not, almost the samecode path is taken and very little error handling takes place. A qc iscompleted with success status if it succeeded, with failed statusotherwise.

However, failed ATAPI commands require more handling as REQUEST SENSE isneeded to acquire sense data. If an ATAPI command fails,ata_qc_complete() is invoked with error status, which in turn invokesatapi_qc_complete() viaqc->complete_fn() callback.

This makesatapi_qc_complete() setscmd->result toSAM_STAT_CHECK_CONDITION, complete the scmd and return 1. As thesense data is empty butscmd->result is CHECK CONDITION, SCSI midlayerwill invoke EH for the scmd, and returning 1 makesata_qc_complete()to return without deallocating the qc. This leads us toata_scsi_error() with partially completed qc.

ata_scsi_error()

ata_scsi_error() is the currenttransportt->eh_strategy_handler()for libata. As discussed above, this will be entered in two cases -timeout and ATAPI error completion. This function calls low level libatadriver’seng_timeout() callback, the standard callback for which isata_eng_timeout(). It checks if a qc is active and callsata_qc_timeout() on the qc if so. Actual error handling occurs inata_qc_timeout().

If EH is invoked for timeout,ata_qc_timeout() stops BMDMA andcompletes the qc. Note that as we’re currently in EH, we cannot callscsi_done. As described in SCSI EH doc, a recovered scmd should beeither retried withscsi_queue_insert() or finished withscsi_finish_command(). Here, we overrideqc->scsidone withscsi_finish_command() and callsata_qc_complete().

If EH is invoked due to a failed ATAPI qc, the qc here is completed butnot deallocated. The purpose of this half-completion is to use the qc asplace holder to make EH code reach this place. This is a bit hackish,but it works.

Once control reaches here, the qc is deallocated by invoking__ata_qc_complete() explicitly. Then, internal qc for REQUEST SENSEis issued. Once sense data is acquired, scmd is finished by directlyinvokingscsi_finish_command() on the scmd. Note that as we alreadyhave completed and deallocated the qc which was associated with thescmd, we don’t need to/cannot callata_qc_complete() again.

Problems with the current EH

  • Error representation is too crude. Currently any and all errorconditions are represented with ATA STATUS and ERROR registers.Errors which aren’t ATA device errors are treated as ATA deviceerrors by setting ATA_ERR bit. Better error descriptor which canproperly represent ATA and other errors/exceptions is needed.

  • When handling timeouts, no action is taken to make device forgetabout the timed out command and ready for new commands.

  • EH handling viaata_scsi_error() is not properly protected fromusual command processing. On EH entrance, the device is not inquiescent state. Timed out commands may succeed or fail any time.pio_task and atapi_task may still be running.

  • Too weak error recovery. Devices / controllers causing HSM mismatcherrors and other errors quite often require reset to return to knownstate. Also, advanced error handling is necessary to support featureslike NCQ and hotplug.

  • ATA errors are directly handled in the interrupt handler and PIOerrors in pio_task. This is problematic for advanced error handlingfor the following reasons.

    First, advanced error handling often requires context and internal qcexecution.

    Second, even a simple failure (say, CRC error) needs informationgathering and could trigger complex error handling (say, resetting &reconfiguring). Having multiple code paths to gather information,enter EH and trigger actions makes life painful.

    Third, scattered EH code makes implementing low level driversdifficult. Low level drivers override libata callbacks. If EH isscattered over several places, each affected callbacks should performits part of error handling. This can be error prone and painful.

libata Library

struct ata_link *ata_link_next(struct ata_link * link, struct ata_port * ap, enum ata_link_iter_mode mode)

link iteration helper

Parameters

structata_link*link
the previous link, NULL to start
structata_port*ap
ATA port containing links to iterate
enumata_link_iter_modemode

iteration mode, one of ATA_LITER_*

LOCKING:Host lock or EH context.

Return

Pointer to the next link.
struct ata_device *ata_dev_next(struct ata_device * dev, struct ata_link * link, enum ata_dev_iter_mode mode)

device iteration helper

Parameters

structata_device*dev
the previous device, NULL to start
structata_link*link
ATA link containing devices to iterate
enumata_dev_iter_modemode

iteration mode, one of ATA_DITER_*

LOCKING:Host lock or EH context.

Return

Pointer to the next device.
intatapi_cmd_type(u8 opcode)

Determine ATAPI command type from SCSI opcode

Parameters

u8opcode

SCSI opcode

Determine ATAPI command type fromopcode.

LOCKING:None.

Return

ATAPI_{READ|WRITE|READ_CD|PASS_THRU|MISC}
unsigned longata_pack_xfermask(unsigned long pio_mask, unsigned long mwdma_mask, unsigned long udma_mask)

Pack pio, mwdma and udma masks into xfer_mask

Parameters

unsignedlongpio_mask
pio_mask
unsignedlongmwdma_mask
mwdma_mask
unsignedlongudma_mask

udma_mask

Packpio_mask,mwdma_mask andudma_mask into a singleunsigned int xfer_mask.

LOCKING:None.

Return

Packed xfer_mask.
u8ata_xfer_mask2mode(unsigned long xfer_mask)

Find matching XFER_* for the given xfer_mask

Parameters

unsignedlongxfer_mask

xfer_mask of interest

Return matching XFER_* value forxfer_mask. Only the highestbit ofxfer_mask is considered.

LOCKING:None.

Return

Matching XFER_* value, 0xff if no match found.
unsigned longata_xfer_mode2mask(u8 xfer_mode)

Find matching xfer_mask for XFER_*

Parameters

u8xfer_mode

XFER_* of interest

Return matching xfer_mask forxfer_mode.

LOCKING:None.

Return

Matching xfer_mask, 0 if no match found.
intata_xfer_mode2shift(unsigned long xfer_mode)

Find matching xfer_shift for XFER_*

Parameters

unsignedlongxfer_mode

XFER_* of interest

Return matching xfer_shift forxfer_mode.

LOCKING:None.

Return

Matching xfer_shift, -1 if no match found.
const char *ata_mode_string(unsigned long xfer_mask)

convert xfer_mask to string

Parameters

unsignedlongxfer_mask

mask of bits supported; only highest bit counts.

Determine string which represents the highest speed(highest bit inmodemask).

LOCKING:None.

Return

Constant C string representing highest speed listed inmode_mask, or the constant C string “<n/a>”.
unsigned intata_dev_classify(const struct ata_taskfile * tf)

determine device type based on ATA-spec signature

Parameters

conststructata_taskfile*tf

ATA taskfile register set for device to be identified

Determine from taskfile register contents whether a device isATA or ATAPI, as per “Signature and persistence” sectionof ATA/PI spec (volume 1, sect 5.14).

LOCKING:None.

Return

Device type,ATA_DEV_ATA,ATA_DEV_ATAPI,ATA_DEV_PMP,ATA_DEV_ZAC, orATA_DEV_UNKNOWN the event of failure.
voidata_id_string(const u16 * id, unsigned char * s, unsigned int ofs, unsigned int len)

Convert IDENTIFY DEVICE page into string

Parameters

constu16*id
IDENTIFY DEVICE results we will examine
unsignedchar*s
string into which data is output
unsignedintofs
offset into identify device page
unsignedintlen

length of string to return. must be an even number.

The strings in the IDENTIFY DEVICE page are broken up into16-bit chunks. Run through the string, and output each8-bit chunk linearly, regardless of platform.

LOCKING:caller.

voidata_id_c_string(const u16 * id, unsigned char * s, unsigned int ofs, unsigned int len)

Convert IDENTIFY DEVICE page into C string

Parameters

constu16*id
IDENTIFY DEVICE results we will examine
unsignedchar*s
string into which data is output
unsignedintofs
offset into identify device page
unsignedintlen

length of string to return. must be an odd number.

This function is identical to ata_id_string except that ittrims trailing spaces and terminates the resulting string withnull.len must be actual maximum length (even number) + 1.

LOCKING:caller.

unsigned longata_id_xfermask(const u16 * id)

Compute xfermask from the given IDENTIFY data

Parameters

constu16*id

IDENTIFY data to compute xfer mask from

Compute the xfermask for this device. This is not as trivialas it seems if we must consider early devices correctly.

FIXME: pre IDE drive timing (do we care ?).

LOCKING:None.

Return

Computed xfermask
unsigned intata_pio_need_iordy(const struct ata_device * adev)

check if iordy needed

Parameters

conststructata_device*adev

ATA device

Check if the current speed of the device requires IORDY. Usedby various controllers for chip configuration.

unsigned intata_do_dev_read_id(struct ata_device * dev, struct ata_taskfile * tf, u16 * id)

default ID read method

Parameters

structata_device*dev
device
structata_taskfile*tf
proposed taskfile
u16*id

data buffer

Issue the identify taskfile and hand back the buffer containingidentify data. For some RAID controllers and for pre ATA devicesthis function is wrapped or replaced by the driver

intata_cable_40wire(struct ata_port * ap)

return 40 wire cable type

Parameters

structata_port*ap

port

Helper method for drivers which want to hardwire 40 wire cabledetection.

intata_cable_80wire(struct ata_port * ap)

return 80 wire cable type

Parameters

structata_port*ap

port

Helper method for drivers which want to hardwire 80 wire cabledetection.

intata_cable_unknown(struct ata_port * ap)

return unknown PATA cable.

Parameters

structata_port*ap

port

Helper method for drivers which have no PATA cable detection.

intata_cable_ignore(struct ata_port * ap)

return ignored PATA cable.

Parameters

structata_port*ap

port

Helper method for drivers which don’t use cable type to limittransfer mode.

intata_cable_sata(struct ata_port * ap)

return SATA cable type

Parameters

structata_port*ap

port

Helper method for drivers which have SATA cables

struct ata_device *ata_dev_pair(struct ata_device * adev)

return other device on cable

Parameters

structata_device*adev

device

Obtain the other device on the same cable, or if none ispresent NULL is returned

intata_do_set_mode(struct ata_link * link, struct ata_device ** r_failed_dev)

Program timings and issue SET FEATURES - XFER

Parameters

structata_link*link
link on which timings will be programmed
structata_device**r_failed_dev

out parameter for failed device

Standard implementation of the function used to tune and setATA device disk transfer mode (PIO3, UDMA6, etc.). Ifata_dev_set_mode() fails, pointer to the failing device isreturned inr_failed_dev.

LOCKING:PCI/etc. bus probe sem.

Return

0 on success, negative errno otherwise
intata_wait_after_reset(struct ata_link * link, unsigned long deadline, int (*check_ready)(struct ata_link *link))

wait for link to become ready after reset

Parameters

structata_link*link
link to be waited on
unsignedlongdeadline
deadline jiffies for the operation
int(*)(structata_link*link)check_ready

callback to check link readiness

Wait forlink to become ready after reset.

LOCKING:EH context.

Return

0 iflink is ready beforedeadline; otherwise, -errno.
intata_std_prereset(struct ata_link * link, unsigned long deadline)

prepare for reset

Parameters

structata_link*link
ATA link to be reset
unsignedlongdeadline

deadline jiffies for the operation

link is about to be reset. Initialize it. Failure fromprereset makes libata abort whole reset sequence and give upthat port, so prereset should be best-effort. It does itsbest to prepare for reset sequence but if things go wrong, itshould just whine, not fail.

LOCKING:Kernel thread context (may sleep)

Return

0 on success, -errno otherwise.
intsata_std_hardreset(struct ata_link * link, unsigned int * class, unsigned long deadline)

COMRESET w/o waiting or classification

Parameters

structata_link*link
link to reset
unsignedint*class
resulting class of attached device
unsignedlongdeadline

deadline jiffies for the operation

Standard SATA COMRESET w/o waiting or classification.

LOCKING:Kernel thread context (may sleep)

Return

0 if link offline, -EAGAIN if link online, -errno on errors.
voidata_std_postreset(struct ata_link * link, unsigned int * classes)

standard postreset callback

Parameters

structata_link*link
the target ata_link
unsignedint*classes

classes of attached devices

This function is invoked after a successful reset. Note thatthe device might have been reset more than once usingdifferent reset methods before postreset is invoked.

LOCKING:Kernel thread context (may sleep)

unsigned intata_dev_set_feature(struct ata_device * dev, u8 enable, u8 feature)

Issue SET FEATURES - SATA FEATURES

Parameters

structata_device*dev
Device to which command will be sent
u8enable
Whether to enable or disable the feature
u8feature

The sector count represents the feature to set

Issue SET FEATURES - SATA FEATURES command to devicedevon portap with sector count

LOCKING:PCI/etc. bus probe sem.

Return

0 on success, AC_ERR_* mask otherwise.
intata_std_qc_defer(struct ata_queued_cmd * qc)

Check whether a qc needs to be deferred

Parameters

structata_queued_cmd*qc

ATA command in question

Non-NCQ commands cannot run with any other command, NCQ ornot. As upper layer only knows the queue depth, we areresponsible for maintaining exclusion. This function checkswhether a new commandqc can be issued.

LOCKING:spin_lock_irqsave(host lock)

Return

ATA_DEFER_* if deferring is needed, 0 otherwise.
voidata_qc_complete(struct ata_queued_cmd * qc)

Complete an active ATA command

Parameters

structata_queued_cmd*qc

Command to complete

Indicate to the mid and upper layers that an ATA command hascompleted, with either an ok or not-ok status.

Refrain from calling this function multiple times whensuccessfully completing multiple NCQ commands.ata_qc_complete_multiple() should be used instead, which willproperly update IRQ expect state.

LOCKING:spin_lock_irqsave(host lock)

u64ata_qc_get_active(struct ata_port * ap)

get bitmask of active qcs

Parameters

structata_port*ap

port in question

LOCKING:spin_lock_irqsave(host lock)

Return

Bitmask of active qcs
boolata_link_online(struct ata_link * link)

test whether the given link is online

Parameters

structata_link*link

ATA link to test

Test whetherlink is online. This is identical toata_phys_link_online() when there’s no slave link. Whenthere’s a slave link, this function should only be called onthe master link and will return true if any of M/S links isonline.

LOCKING:None.

Return

True if the port online status is available and online.
boolata_link_offline(struct ata_link * link)

test whether the given link is offline

Parameters

structata_link*link

ATA link to test

Test whetherlink is offline. This is identical toata_phys_link_offline() when there’s no slave link. Whenthere’s a slave link, this function should only be called onthe master link and will return true if both M/S links areoffline.

LOCKING:None.

Return

True if the port offline status is available and offline.
intata_host_suspend(struct ata_host * host, pm_message_t mesg)

suspend host

Parameters

structata_host*host
host to suspend
pm_message_tmesg

PM message

Suspendhost. Actual operation is performed by port suspend.

voidata_host_resume(struct ata_host * host)

resume host

Parameters

structata_host*host

host to resume

Resumehost. Actual operation is performed by port resume.

struct ata_host *ata_host_alloc(structdevice * dev, int max_ports)

allocate and init basic ATA host resources

Parameters

structdevice*dev
generic device this host is associated with
intmax_ports

maximum number of ATA ports associated with this host

Allocate and initialize basic ATA host resources. LLD callsthis function to allocate a host, initializes it fully andattaches it usingata_host_register().

max_ports ports are allocated and host->n_ports isinitialized tomax_ports. The caller is allowed to decreasehost->n_ports before callingata_host_register(). The unusedports will be automatically freed on registration.

Return

Allocate ATA host on success, NULL on failure.

LOCKING:Inherited from calling layer (may sleep).

struct ata_host *ata_host_alloc_pinfo(structdevice * dev, const struct ata_port_info *const * ppi, int n_ports)

alloc host and init with port_info array

Parameters

structdevice*dev
generic device this host is associated with
conststructata_port_info*const*ppi
array of ATA port_info to initialize host with
intn_ports

number of ATA ports attached to this host

Allocate ATA host and initialize with info fromppi. If NULLterminated,ppi may contain fewer entries thann_ports. Thelast entry will be used for the remaining ports.

Return

Allocate ATA host on success, NULL on failure.

LOCKING:Inherited from calling layer (may sleep).

intata_host_start(struct ata_host * host)

start and freeze ports of an ATA host

Parameters

structata_host*host

ATA host to start ports for

Start and then freeze ports ofhost. Started status isrecorded in host->flags, so this function can be calledmultiple times. Ports are guaranteed to get started onlyonce. If host->ops isn’t initialized yet, its set to thefirst non-dummy port ops.

LOCKING:Inherited from calling layer (may sleep).

Return

0 if all ports are started successfully, -errno otherwise.
voidata_host_init(struct ata_host * host, structdevice * dev, struct ata_port_operations * ops)

Initialize a host struct for sas (ipr, libsas)

Parameters

structata_host*host
host to initialize
structdevice*dev
device host is attached to
structata_port_operations*ops
port_ops
intata_host_register(struct ata_host * host, struct scsi_host_template * sht)

register initialized ATA host

Parameters

structata_host*host
ATA host to register
structscsi_host_template*sht

template for SCSI host

Register initialized ATA host.host is allocated usingata_host_alloc() and fully initialized by LLD. This functionstarts ports, registershost with ATA and SCSI layers andprobe registered devices.

LOCKING:Inherited from calling layer (may sleep).

Return

0 on success, -errno otherwise.
intata_host_activate(struct ata_host * host, int irq, irq_handler_t irq_handler, unsigned long irq_flags, struct scsi_host_template * sht)

start host, request IRQ and register it

Parameters

structata_host*host
target ATA host
intirq
IRQ to request
irq_handler_tirq_handler
irq_handler used when requesting IRQ
unsignedlongirq_flags
irq_flags used when requesting IRQ
structscsi_host_template*sht

scsi_host_template to use when registering the host

After allocating an ATA host and initializing it, most libataLLDs perform three steps to activate the host - start host,request IRQ and register it. This helper takes necessaryarguments and performs the three steps in one go.

An invalid IRQ skips the IRQ registration and expects the host tohave set polling mode on the port. In this case,irq_handlershould be NULL.

LOCKING:Inherited from calling layer (may sleep).

Return

0 on success, -errno otherwise.
voidata_host_detach(struct ata_host * host)

Detach all ports of an ATA host

Parameters

structata_host*host

Host to detach

Detach all ports ofhost.

LOCKING:Kernel thread context (may sleep).

voidata_pci_remove_one(struct pci_dev * pdev)

PCI layer callback for device removal

Parameters

structpci_dev*pdev

PCI device that was removed

PCI layer indicates to libata via this hook that hot-unplug ormodule unload event has occurred. Detach all ports. Resourcerelease is handled via devres.

LOCKING:Inherited from PCI layer (may sleep).

intata_platform_remove_one(struct platform_device * pdev)

Platform layer callback for device removal

Parameters

structplatform_device*pdev

Platform device that was removed

Platform layer indicates to libata via this hook that hot-unplug ormodule unload event has occurred. Detach all ports. Resourcerelease is handled via devres.

LOCKING:Inherited from platform layer (may sleep).

voidata_msleep(struct ata_port * ap, unsigned int msecs)

ATA EH owner aware msleep

Parameters

structata_port*ap
ATA port to attribute the sleep to
unsignedintmsecs

duration to sleep in milliseconds

Sleepsmsecs. If the current task is owner ofap’s EH, theownership is released before going to sleep and reacquiredafter the sleep is complete. IOW, other ports sharing theap->host will be allowed to own the EH while this task issleeping.

LOCKING:Might sleep.

u32ata_wait_register(struct ata_port * ap, void __iomem * reg, u32 mask, u32 val, unsigned long interval, unsigned long timeout)

wait until register value changes

Parameters

structata_port*ap
ATA port to wait register for, can be NULL
void__iomem*reg
IO-mapped register
u32mask
Mask to apply to read register value
u32val
Wait condition
unsignedlonginterval
polling interval in milliseconds
unsignedlongtimeout

timeout in milliseconds

Waiting for some bits of register to change is a commonoperation for ATA controllers. This function reads 32bit LEIO-mapped registerreg and tests for the following condition.

(*reg & mask) != val

If the condition is met, it returns; otherwise, the process isrepeated afterinterval_msec until timeout.

LOCKING:Kernel thread context (may sleep)

Return

The final register value.

libata Core Internals

struct ata_link *ata_dev_phys_link(struct ata_device * dev)

find physical link for a device

Parameters

structata_device*dev

ATA device to look up physical link for

Look up physical link whichdev is attached to. Note thatthis is different fromdev->link only whendev is on slavelink. For all other cases, it’s the same asdev->link.

LOCKING:Don’t care.

Return

Pointer to the found physical link.
voidata_force_cbl(struct ata_port * ap)

force cable type according to libata.force

Parameters

structata_port*ap

ATA port of interest

Force cable type according to libata.force and whine about it.The last entry which has matching port number is used, so itcan be specified as part of device force parameters. Forexample, both “a:40c,1.00:udma4” and “1.00:40c,udma4” have thesame effect.

LOCKING:EH context.

voidata_force_link_limits(struct ata_link * link)

force link limits according to libata.force

Parameters

structata_link*link

ATA link of interest

Force link flags and SATA spd limit according to libata.forceand whine about it. When only the port part is specified(e.g. 1:), the limit applies to all links connected to boththe host link and all fan-out ports connected via PMP. If thedevice part is specified as 0 (e.g. 1.00:), it specifies thefirst fan-out link not the host link. Device number 15 alwayspoints to the host link whether PMP is attached or not. If thecontroller has slave link, device number 16 points to it.

LOCKING:EH context.

voidata_force_xfermask(struct ata_device * dev)

force xfermask according to libata.force

Parameters

structata_device*dev

ATA device of interest

Force xfer_mask according to libata.force and whine about it.For consistency with link selection, device number 15 selectsthe first device connected to the host link.

LOCKING:EH context.

voidata_force_horkage(struct ata_device * dev)

force horkage according to libata.force

Parameters

structata_device*dev

ATA device of interest

Force horkage according to libata.force and whine about it.For consistency with link selection, device number 15 selectsthe first device connected to the host link.

LOCKING:EH context.

intata_rwcmd_protocol(struct ata_taskfile * tf, struct ata_device * dev)

set taskfile r/w commands and protocol

Parameters

structata_taskfile*tf
command to examine and configure
structata_device*dev

device tf belongs to

Examine the device configuration and tf->flags to calculatethe proper read/write commands and protocol to use.

LOCKING:caller.

u64ata_tf_read_block(const struct ata_taskfile * tf, struct ata_device * dev)

Read block address from ATA taskfile

Parameters

conststructata_taskfile*tf
ATA taskfile of interest
structata_device*dev

ATA devicetf belongs to

LOCKING:None.

Read block address fromtf. This function can handle allthree address formats - LBA, LBA48 and CHS. tf->protocol andflags select the address format to use.

Return

Block address read fromtf.
intata_build_rw_tf(struct ata_taskfile * tf, struct ata_device * dev, u64 block, u32 n_block, unsigned int tf_flags, unsigned int tag, int class)

Build ATA taskfile for given read/write request

Parameters

structata_taskfile*tf
Target ATA taskfile
structata_device*dev
ATA devicetf belongs to
u64block
Block address
u32n_block
Number of blocks
unsignedinttf_flags
RW/FUA etc…
unsignedinttag
tag
intclass

IO priority class

LOCKING:None.

Build ATA taskfiletf for read/write request described byblock,n_block,tf_flags andtag ondev.

Return

0 on success, -ERANGE if the request is too large fordev,-EINVAL if the request is invalid.
voidata_unpack_xfermask(unsigned long xfer_mask, unsigned long * pio_mask, unsigned long * mwdma_mask, unsigned long * udma_mask)

Unpack xfer_mask into pio, mwdma and udma masks

Parameters

unsignedlongxfer_mask
xfer_mask to unpack
unsignedlong*pio_mask
resulting pio_mask
unsignedlong*mwdma_mask
resulting mwdma_mask
unsignedlong*udma_mask

resulting udma_mask

Unpackxfer_mask intopio_mask,mwdma_mask andudma_mask.Any NULL destination masks will be ignored.

intata_read_native_max_address(struct ata_device * dev, u64 * max_sectors)

Read native max address

Parameters

structata_device*dev
target device
u64*max_sectors

out parameter for the result native max address

Perform an LBA48 or LBA28 native size query upon the device inquestion.

Return

0 on success, -EACCES if command is aborted by the drive.-EIO on other errors.
intata_set_max_sectors(struct ata_device * dev, u64 new_sectors)

Set max sectors

Parameters

structata_device*dev
target device
u64new_sectors

new max sectors value to set for the device

Set max sectors ofdev tonew_sectors.

Return

0 on success, -EACCES if command is aborted or denied (due toprevious non-volatile SET_MAX) by the drive. -EIO on othererrors.
intata_hpa_resize(struct ata_device * dev)

Resize a device with an HPA set

Parameters

structata_device*dev

Device to resize

Read the size of an LBA28 or LBA48 disk with HPA features and resizeit if required to the full size of the media. The caller must checkthe drive has the HPA feature set enabled.

Return

0 on success, -errno on failure.
voidata_dump_id(const u16 * id)

IDENTIFY DEVICE info debugging output

Parameters

constu16*id

IDENTIFY DEVICE page to dump

Dump selected 16-bit words from the given IDENTIFY DEVICEpage.

LOCKING:caller.

unsignedata_exec_internal_sg(struct ata_device * dev, struct ata_taskfile * tf, const u8 * cdb, int dma_dir, struct scatterlist * sgl, unsigned int n_elem, unsigned long timeout)

execute libata internal command

Parameters

structata_device*dev
Device to which the command is sent
structata_taskfile*tf
Taskfile registers for the command and the result
constu8*cdb
CDB for packet command
intdma_dir
Data transfer direction of the command
structscatterlist*sgl
sg list for the data buffer of the command
unsignedintn_elem
Number of sg entries
unsignedlongtimeout

Timeout in msecs (0 for default)

Executes libata internal command with timeout.tf containscommand on entry and result on return. Timeout and errorconditions are reported via return value. No recovery actionis taken after a command times out. It’s caller’s duty toclean up after timeout.

LOCKING:None. Should be called with kernel context, might sleep.

Return

Zero on success, AC_ERR_* mask on failure
unsignedata_exec_internal(struct ata_device * dev, struct ata_taskfile * tf, const u8 * cdb, int dma_dir, void * buf, unsigned int buflen, unsigned long timeout)

execute libata internal command

Parameters

structata_device*dev
Device to which the command is sent
structata_taskfile*tf
Taskfile registers for the command and the result
constu8*cdb
CDB for packet command
intdma_dir
Data transfer direction of the command
void*buf
Data buffer of the command
unsignedintbuflen
Length of data buffer
unsignedlongtimeout

Timeout in msecs (0 for default)

Wrapper aroundata_exec_internal_sg() which takes simplebuffer instead of sg list.

LOCKING:None. Should be called with kernel context, might sleep.

Return

Zero on success, AC_ERR_* mask on failure
u32ata_pio_mask_no_iordy(const struct ata_device * adev)

Return the non IORDY mask

Parameters

conststructata_device*adev

ATA device

Compute the highest mode possible if we are not using iordy. Return-1 if no iordy mode is available.

intata_dev_read_id(struct ata_device * dev, unsigned int * p_class, unsigned int flags, u16 * id)

Read ID data from the specified device

Parameters

structata_device*dev
target device
unsignedint*p_class
pointer to class of the target device (may be changed)
unsignedintflags
ATA_READID_* flags
u16*id

buffer to read IDENTIFY data into

Read ID data from the specified device. ATA_CMD_ID_ATA isperformed on ATA devices and ATA_CMD_ID_ATAPI on ATAPIdevices. This function also issues ATA_CMD_INIT_DEV_PARAMSfor pre-ATA4 drives.

FIXME: ATA_CMD_ID_ATA is optional for early drives and rightnow we abort if we hit that case.

LOCKING:Kernel thread context (may sleep)

Return

0 on success, -errno otherwise.
unsigned intata_read_log_page(struct ata_device * dev, u8 log, u8 page, void * buf, unsigned int sectors)

read a specific log page

Parameters

structata_device*dev
target device
u8log
log to read
u8page
page to read
void*buf
buffer to store read page
unsignedintsectors

number of sectors to read

Read log page using READ_LOG_EXT command.

LOCKING:Kernel thread context (may sleep).

Return

0 on success, AC_ERR_* mask otherwise.
intata_dev_configure(struct ata_device * dev)

Configure the specified ATA/ATAPI device

Parameters

structata_device*dev

Target device to configure

Configuredev according todev->id. Generic and low-leveldriver specific fixups are also applied.

LOCKING:Kernel thread context (may sleep)

Return

0 on success, -errno otherwise
intata_bus_probe(struct ata_port * ap)

Reset and probe ATA bus

Parameters

structata_port*ap

Bus to probe

Master ATA bus probing function. Initiates a hardware-dependentbus reset, then attempts to identify any devices found onthe bus.

LOCKING:PCI/etc. bus probe sem.

Return

Zero on success, negative errno otherwise.
voidsata_print_link_status(struct ata_link * link)

Print SATA link status

Parameters

structata_link*link

SATA link to printk link status about

This function prints link speed and status of a SATA link.

LOCKING:None.

intsata_down_spd_limit(struct ata_link * link, u32 spd_limit)

adjust SATA spd limit downward

Parameters

structata_link*link
Link to adjust SATA spd limit for
u32spd_limit

Additional limit

Adjust SATA spd limit oflink downward. Note that thisfunction only adjusts the limit. The change must be appliedusing sata_set_spd().

Ifspd_limit is non-zero, the speed is limited to equal to orlower thanspd_limit if such speed is supported. Ifspd_limit is slower than any supported speed, only the lowestsupported speed is allowed.

LOCKING:Inherited from caller.

Return

0 on success, negative errno on failure
u8ata_timing_cycle2mode(unsigned int xfer_shift, int cycle)

find xfer mode for the specified cycle duration

Parameters

unsignedintxfer_shift
ATA_SHIFT_* value for transfer type to examine.
intcycle

cycle duration in ns

Return matching xfer mode forcycle. The returned mode is ofthe transfer type specified byxfer_shift. Ifcycle is tooslow forxfer_shift, 0xff is returned. Ifcycle is fasterthan the fastest known mode, the fasted mode is returned.

LOCKING:None.

Return

Matching xfer_mode, 0xff if no match found.
intata_down_xfermask_limit(struct ata_device * dev, unsigned int sel)

adjust dev xfer masks downward

Parameters

structata_device*dev
Device to adjust xfer masks
unsignedintsel

ATA_DNXFER_* selector

Adjust xfer masks ofdev downward. Note that this functiondoes not apply the change. Invokingata_set_mode() afterwardswill apply the limit.

LOCKING:Inherited from caller.

Return

0 on success, negative errno on failure
intata_wait_ready(struct ata_link * link, unsigned long deadline, int (*check_ready)(struct ata_link *link))

wait for link to become ready

Parameters

structata_link*link
link to be waited on
unsignedlongdeadline
deadline jiffies for the operation
int(*)(structata_link*link)check_ready

callback to check link readiness

Wait forlink to become ready.check_ready should returnpositive number iflink is ready, 0 if it isn’t, -ENODEV iflink doesn’t seem to be occupied, other errno for other errorconditions.

Transient -ENODEV conditions are allowed forATA_TMOUT_FF_WAIT.

LOCKING:EH context.

Return

0 iflink is ready beforedeadline; otherwise, -errno.
intata_dev_same_device(struct ata_device * dev, unsigned int new_class, const u16 * new_id)

Determine whether new ID matches configured device

Parameters

structata_device*dev
device to compare against
unsignedintnew_class
class of the new device
constu16*new_id

IDENTIFY page of the new device

Comparenew_class andnew_id againstdev and determinewhetherdev is the device indicated bynew_class andnew_id.

LOCKING:None.

Return

1 ifdev matchesnew_class andnew_id, 0 otherwise.
intata_dev_reread_id(struct ata_device * dev, unsigned int readid_flags)

Re-read IDENTIFY data

Parameters

structata_device*dev
target ATA device
unsignedintreadid_flags

read ID flags

Re-read IDENTIFY page and make suredev is still attached tothe port.

LOCKING:Kernel thread context (may sleep)

Return

0 on success, negative errno otherwise
intata_dev_revalidate(struct ata_device * dev, unsigned int new_class, unsigned int readid_flags)

Revalidate ATA device

Parameters

structata_device*dev
device to revalidate
unsignedintnew_class
new class code
unsignedintreadid_flags

read ID flags

Re-read IDENTIFY page, make suredev is still attached to theport and reconfigure it according to the new IDENTIFY page.

LOCKING:Kernel thread context (may sleep)

Return

0 on success, negative errno otherwise
intata_is_40wire(struct ata_device * dev)

check drive side detection

Parameters

structata_device*dev

device

Perform drive side detection decoding, allowing for device vendorswho can’t follow the documentation.

intcable_is_40wire(struct ata_port * ap)

40/80/SATA decider

Parameters

structata_port*ap

port to consider

This function encapsulates the policy for speed managementin one place. At the moment we don’t cache the result butthere is a good case for setting ap->cbl to the result whenwe are called with unknown cables (and figuring out if itimpacts hotplug at all).

Return 1 if the cable appears to be 40 wire.

voidata_dev_xfermask(struct ata_device * dev)

Compute supported xfermask of the given device

Parameters

structata_device*dev

Device to compute xfermask for

Compute supported xfermask ofdev and store it indev->*_mask. This function is responsible for applying allknown limits including host controller limits, deviceblacklist, etc…

LOCKING:None.

unsigned intata_dev_set_xfermode(struct ata_device * dev)

Issue SET FEATURES - XFER MODE command

Parameters

structata_device*dev

Device to which command will be sent

Issue SET FEATURES - XFER MODE command to devicedevon portap.

LOCKING:PCI/etc. bus probe sem.

Return

0 on success, AC_ERR_* mask otherwise.
unsigned intata_dev_init_params(struct ata_device * dev, u16 heads, u16 sectors)

Issue INIT DEV PARAMS command

Parameters

structata_device*dev
Device to which command will be sent
u16heads
Number of heads (taskfile parameter)
u16sectors

Number of sectors (taskfile parameter)

LOCKING:Kernel thread context (may sleep)

Return

0 on success, AC_ERR_* mask otherwise.
intatapi_check_dma(struct ata_queued_cmd * qc)

Check whether ATAPI DMA can be supported

Parameters

structata_queued_cmd*qc

Metadata associated with taskfile to check

Allow low-level driver to filter ATA PACKET commands, returninga status indicating whether or not it is OK to use DMA for thesupplied PACKET command.

LOCKING:spin_lock_irqsave(host lock)

Return

0 when ATAPI DMA can be used
nonzero otherwise
voidata_sg_init(struct ata_queued_cmd * qc, struct scatterlist * sg, unsigned int n_elem)

Associate command with scatter-gather table.

Parameters

structata_queued_cmd*qc
Command to be associated
structscatterlist*sg
Scatter-gather table.
unsignedintn_elem

Number of elements in s/g table.

Initialize the data-related elements of queued_cmdqcto point to a scatter-gather tablesg, containingn_elemelements.

LOCKING:spin_lock_irqsave(host lock)

voidata_sg_clean(struct ata_queued_cmd * qc)

Unmap DMA memory associated with command

Parameters

structata_queued_cmd*qc

Command containing DMA memory to be released

Unmap all mapped DMA memory associated with this command.

LOCKING:spin_lock_irqsave(host lock)

intata_sg_setup(struct ata_queued_cmd * qc)

DMA-map the scatter-gather table associated with a command.

Parameters

structata_queued_cmd*qc

Command with scatter-gather table to be mapped.

DMA-map the scatter-gather table associated with queued_cmdqc.

LOCKING:spin_lock_irqsave(host lock)

Return

Zero on success, negative on error.
voidswap_buf_le16(u16 * buf, unsigned int buf_words)

swap halves of 16-bit words in place

Parameters

u16*buf
Buffer to swap
unsignedintbuf_words

Number of 16-bit words in buffer.

Swap halves of 16-bit words if needed to convert fromlittle-endian byte order to native cpu byte order, orvice-versa.

LOCKING:Inherited from caller.

struct ata_queued_cmd *ata_qc_new_init(struct ata_device * dev, int tag)

Request an available ATA command, and initialize it

Parameters

structata_device*dev
Device from whom we request an available command structure
inttag

tag

LOCKING:None.

voidata_qc_free(struct ata_queued_cmd * qc)

free unused ata_queued_cmd

Parameters

structata_queued_cmd*qc

Command to complete

Designed to free unused ata_queued_cmd objectin case something prevents using it.

LOCKING:spin_lock_irqsave(host lock)

voidata_qc_issue(struct ata_queued_cmd * qc)

issue taskfile to device

Parameters

structata_queued_cmd*qc

command to issue to device

Prepare an ATA command to submission to device.This includes mapping the data into a DMA-ablearea, filling in the S/G table, and finallywriting the taskfile to hardware, starting the command.

LOCKING:spin_lock_irqsave(host lock)

boolata_phys_link_online(struct ata_link * link)

test whether the given link is online

Parameters

structata_link*link

ATA link to test

Test whetherlink is online. Note that this function returns0 if online status oflink cannot be obtained, soata_link_online(link) != !ata_link_offline(link).

LOCKING:None.

Return

True if the port online status is available and online.
boolata_phys_link_offline(struct ata_link * link)

test whether the given link is offline

Parameters

structata_link*link

ATA link to test

Test whetherlink is offline. Note that this functionreturns 0 if offline status oflink cannot be obtained, soata_link_online(link) != !ata_link_offline(link).

LOCKING:None.

Return

True if the port offline status is available and offline.
voidata_dev_init(struct ata_device * dev)

Initialize an ata_device structure

Parameters

structata_device*dev

Device structure to initialize

Initializedev in preparation for probing.

LOCKING:Inherited from caller.

voidata_link_init(struct ata_port * ap, struct ata_link * link, int pmp)

Initialize an ata_link structure

Parameters

structata_port*ap
ATA port link is attached to
structata_link*link
Link structure to initialize
intpmp

Port multiplier port number

Initializelink.

LOCKING:Kernel thread context (may sleep)

intsata_link_init_spd(struct ata_link * link)

Initialize link->sata_spd_limit

Parameters

structata_link*link

Link to configure sata_spd_limit for

Initializelink->[hw_]sata_spd_limit to the currentlyconfigured value.

LOCKING:Kernel thread context (may sleep).

Return

0 on success, -errno on failure.
struct ata_port *ata_port_alloc(struct ata_host * host)

allocate and initialize basic ATA port resources

Parameters

structata_host*host

ATA host this allocated port belongs to

Allocate and initialize basic ATA port resources.

Return

Allocate ATA port on success, NULL on failure.

LOCKING:Inherited from calling layer (may sleep).

voidata_finalize_port_ops(struct ata_port_operations * ops)

finalize ata_port_operations

Parameters

structata_port_operations*ops

ata_port_operations to finalize

An ata_port_operations can inherit from another ops and thatops can again inherit from another. This can go on as manytimes as necessary as long as there is no loop in theinheritance chain.

Ops tables are finalized when the host is started. NULL orunspecified entries are inherited from the closet ancestorwhich has the method and the entry is populated with it.After finalization, the ops table directly points to all themethods and ->inherits is no longer necessary and cleared.

Using ATA_OP_NULL, inheriting ops can force a method to NULL.

LOCKING:None.

voidata_port_detach(struct ata_port * ap)

Detach ATA port in preparation of device removal

Parameters

structata_port*ap

ATA port to be detached

Detach all ATA devices and the associated SCSI devices ofap;then, remove the associated SCSI host.ap is guaranteed tobe quiescent on return from this function.

LOCKING:Kernel thread context (may sleep).

void__ata_ehi_push_desc(struct ata_eh_info * ehi, const char * fmt, ...)

push error description without adding separator

Parameters

structata_eh_info*ehi
target EHI
constchar*fmt

printf format string

Format string according tofmt and append it toehi->desc.

LOCKING:spin_lock_irqsave(host lock)

...
variable arguments
voidata_ehi_push_desc(struct ata_eh_info * ehi, const char * fmt, ...)

push error description with separator

Parameters

structata_eh_info*ehi
target EHI
constchar*fmt

printf format string

Format string according tofmt and append it toehi->desc.Ifehi->desc is not empty, “, ” is added in-between.

LOCKING:spin_lock_irqsave(host lock)

...
variable arguments
voidata_ehi_clear_desc(struct ata_eh_info * ehi)

clean error description

Parameters

structata_eh_info*ehi

target EHI

Clearehi->desc.

LOCKING:spin_lock_irqsave(host lock)

voidata_port_desc(struct ata_port * ap, const char * fmt, ...)

append port description

Parameters

structata_port*ap
target ATA port
constchar*fmt

printf format string

Format string according tofmt and append it to portdescription. If port description is not empty, ” ” is addedin-between. This function is to be used while initializingata_host. The description is printed on host registration.

LOCKING:None.

...
variable arguments
voidata_port_pbar_desc(struct ata_port * ap, int bar, ssize_t offset, const char * name)

append PCI BAR description

Parameters

structata_port*ap
target ATA port
intbar
target PCI BAR
ssize_toffset
offset into PCI BAR
constchar*name

name of the area

Ifoffset is negative, this function formats a string whichcontains the name, address, size and type of the BAR andappends it to the port description. Ifoffset is zero orpositive, only name and offsetted address is appended.

LOCKING:None.

unsigned longata_internal_cmd_timeout(struct ata_device * dev, u8 cmd)

determine timeout for an internal command

Parameters

structata_device*dev
target device
u8cmd

internal command to be issued

Determine timeout for internal commandcmd fordev.

LOCKING:EH context.

Return

Determined timeout.
voidata_internal_cmd_timed_out(struct ata_device * dev, u8 cmd)

notification for internal command timeout

Parameters

structata_device*dev
target device
u8cmd

internal command which timed out

Notify EH that internal commandcmd fordev timed out. Thisfunction should be called only for commands whose timeouts aredetermined usingata_internal_cmd_timeout().

LOCKING:EH context.

voidata_eh_acquire(struct ata_port * ap)

acquire EH ownership

Parameters

structata_port*ap

ATA port to acquire EH ownership for

Acquire EH ownership forap. This is the basic exclusionmechanism for ports sharing a host. Only one port hanging offthe same host can claim the ownership of EH.

LOCKING:EH context.

voidata_eh_release(struct ata_port * ap)

release EH ownership

Parameters

structata_port*ap

ATA port to release EH ownership for

Release EH ownership forap if the caller. The caller musthave acquired EH ownership usingata_eh_acquire() previously.

LOCKING:EH context.

voidata_scsi_error(struct Scsi_Host * host)

SCSI layer error handler callback

Parameters

structScsi_Host*host

SCSI host on which error occurred

Handles SCSI-layer-thrown error events.

LOCKING:Inherited from SCSI layer (none, can sleep)

Return

Zero.
voidata_scsi_cmd_error_handler(struct Scsi_Host * host, struct ata_port * ap, struct list_head * eh_work_q)

error callback for a list of commands

Parameters

structScsi_Host*host
scsi host containing the port
structata_port*ap
ATA port within the host
structlist_head*eh_work_q
list of commands to process

Description

process the given list of commands and return those finished to theap->eh_done_q. This function is the first part of the libata errorhandler which processes a given list of failed commands.

voidata_scsi_port_error_handler(struct Scsi_Host * host, struct ata_port * ap)

recover the port after the commands

Parameters

structScsi_Host*host
SCSI host containing the port
structata_port*ap
the ATA port

Description

Handle the recovery of the portap after all the commandshave been recovered.

voidata_port_wait_eh(struct ata_port * ap)

Wait for the currently pending EH to complete

Parameters

structata_port*ap

Port to wait EH for

Wait until the currently pending EH is complete.

LOCKING:Kernel thread context (may sleep).

voidata_eh_set_pending(struct ata_port * ap, int fastdrain)

set ATA_PFLAG_EH_PENDING and activate fast drain

Parameters

structata_port*ap
target ATA port
intfastdrain

activate fast drain

Set ATA_PFLAG_EH_PENDING and activate fast drain iffastdrainis non-zero and EH wasn’t pending before. Fast drain ensuresthat EH kicks in in timely manner.

LOCKING:spin_lock_irqsave(host lock)

voidata_qc_schedule_eh(struct ata_queued_cmd * qc)

schedule qc for error handling

Parameters

structata_queued_cmd*qc

command to schedule error handling for

Schedule error handling forqc. EH will kick in as soon asother commands are drained.

LOCKING:spin_lock_irqsave(host lock)

voidata_std_sched_eh(struct ata_port * ap)

non-libsas ata_ports issue eh with this common routine

Parameters

structata_port*ap

ATA port to schedule EH for

LOCKING: inherited from ata_port_schedule_ehspin_lock_irqsave(host lock)

voidata_std_end_eh(struct ata_port * ap)

non-libsas ata_ports complete eh with this common routine

Parameters

structata_port*ap
ATA port to end EH for

Description

In the libata object model there is a 1:1 mapping of ata_port toshost, so host fields can be directly manipulated under ap->lock, inthe libsas case we need to hold a lock at the ha->level to coordinatethese events.

LOCKING:spin_lock_irqsave(host lock)
voidata_port_schedule_eh(struct ata_port * ap)

schedule error handling without a qc

Parameters

structata_port*ap

ATA port to schedule EH for

Schedule error handling forap. EH will kick in as soon asall commands are drained.

LOCKING:spin_lock_irqsave(host lock)

intata_link_abort(struct ata_link * link)

abort all qc’s on the link

Parameters

structata_link*link

ATA link to abort qc’s for

Abort all active qc’s active onlink and schedule EH.

LOCKING:spin_lock_irqsave(host lock)

Return

Number of aborted qc’s.
intata_port_abort(struct ata_port * ap)

abort all qc’s on the port

Parameters

structata_port*ap

ATA port to abort qc’s for

Abort all active qc’s ofap and schedule EH.

LOCKING:spin_lock_irqsave(host_set lock)

Return

Number of aborted qc’s.
void__ata_port_freeze(struct ata_port * ap)

freeze port

Parameters

structata_port*ap

ATA port to freeze

This function is called when HSM violation or some othercondition disrupts normal operation of the port. Frozen portis not allowed to perform any operation until the port isthawed, which usually follows a successful reset.

ap->ops->freeze() callback can be used for freezing the porthardware-wise (e.g. mask interrupt and stop DMA engine). If aport cannot be frozen hardware-wise, the interrupt handlermust ack and clear interrupts unconditionally while the portis frozen.

LOCKING:spin_lock_irqsave(host lock)

intata_port_freeze(struct ata_port * ap)

abort & freeze port

Parameters

structata_port*ap

ATA port to freeze

Abort and freezeap. The freeze operation must be calledfirst, because some hardware requires special operationsbefore the taskfile registers are accessible.

LOCKING:spin_lock_irqsave(host lock)

Return

Number of aborted commands.
voidata_eh_freeze_port(struct ata_port * ap)

EH helper to freeze port

Parameters

structata_port*ap

ATA port to freeze

Freezeap.

LOCKING:None.

voidata_eh_thaw_port(struct ata_port * ap)

EH helper to thaw port

Parameters

structata_port*ap

ATA port to thaw

Thaw frozen portap.

LOCKING:None.

voidata_eh_qc_complete(struct ata_queued_cmd * qc)

Complete an active ATA command from EH

Parameters

structata_queued_cmd*qc

Command to complete

Indicate to the mid and upper layers that an ATA command hascompleted. To be used from EH.

voidata_eh_qc_retry(struct ata_queued_cmd * qc)

Tell midlayer to retry an ATA command after EH

Parameters

structata_queued_cmd*qc

Command to retry

Indicate to the mid and upper layers that an ATA commandshould be retried. To be used from EH.

SCSI midlayer limits the number of retries to scmd->allowed.scmd->allowed is incremented for commands which get retrieddue to unrelated failures (qc->err_mask is zero).

voidata_dev_disable(struct ata_device * dev)

disable ATA device

Parameters

structata_device*dev

ATA device to disable

Disabledev.

Locking:EH context.

voidata_eh_detach_dev(struct ata_device * dev)

detach ATA device

Parameters

structata_device*dev

ATA device to detach

Detachdev.

LOCKING:None.

voidata_eh_about_to_do(struct ata_link * link, struct ata_device * dev, unsigned int action)

about to perform eh_action

Parameters

structata_link*link
target ATA link
structata_device*dev
target ATA dev for per-dev action (can be NULL)
unsignedintaction

action about to be performed

Called just before performing EH actions to clear related bitsinlink->eh_info such that eh actions are not unnecessarilyrepeated.

LOCKING:None.

voidata_eh_done(struct ata_link * link, struct ata_device * dev, unsigned int action)

EH action complete

Parameters

structata_link*link
ATA link for which EH actions are complete
structata_device*dev
target ATA dev for per-dev action (can be NULL)
unsignedintaction

action just completed

Called right after performing EH actions to clear related bitsinlink->eh_context.

LOCKING:None.

const char *ata_err_string(unsigned int err_mask)

convert err_mask to descriptive string

Parameters

unsignedinterr_mask

error mask to convert to string

Converterr_mask to descriptive string. Errors areprioritized according to severity and only the most severeerror is reported.

LOCKING:None.

Return

Descriptive string forerr_mask
unsigned intatapi_eh_tur(struct ata_device * dev, u8 * r_sense_key)

perform ATAPI TEST_UNIT_READY

Parameters

structata_device*dev
target ATAPI device
u8*r_sense_key

out parameter for sense_key

Perform ATAPI TEST_UNIT_READY.

LOCKING:EH context (may sleep).

Return

0 on success, AC_ERR_* mask on failure.
voidata_eh_request_sense(struct ata_queued_cmd * qc, struct scsi_cmnd * cmd)

perform REQUEST_SENSE_DATA_EXT

Parameters

structata_queued_cmd*qc
qc to perform REQUEST_SENSE_SENSE_DATA_EXT to
structscsi_cmnd*cmd

scsi command for which the sense code should be set

Perform REQUEST_SENSE_DATA_EXT after the device reported CHECKSENSE. This function is an EH helper.

LOCKING:Kernel thread context (may sleep).

unsigned intatapi_eh_request_sense(struct ata_device * dev, u8 * sense_buf, u8 dfl_sense_key)

perform ATAPI REQUEST_SENSE

Parameters

structata_device*dev
device to perform REQUEST_SENSE to
u8*sense_buf
result sense data buffer (SCSI_SENSE_BUFFERSIZE bytes long)
u8dfl_sense_key

default sense key to use

Perform ATAPI REQUEST_SENSE after the device reported CHECKSENSE. This function is EH helper.

LOCKING:Kernel thread context (may sleep).

Return

0 on success, AC_ERR_* mask on failure
voidata_eh_analyze_serror(struct ata_link * link)

analyze SError for a failed port

Parameters

structata_link*link

ATA link to analyze SError for

Analyze SError if available and further determine cause offailure.

LOCKING:None.

unsigned intata_eh_analyze_tf(struct ata_queued_cmd * qc, const struct ata_taskfile * tf)

analyze taskfile of a failed qc

Parameters

structata_queued_cmd*qc
qc to analyze
conststructata_taskfile*tf

Taskfile registers to analyze

Analyze taskfile ofqc and further determine cause offailure. This function also requests ATAPI sense data ifavailable.

LOCKING:Kernel thread context (may sleep).

Return

Determined recovery action
unsigned intata_eh_speed_down_verdict(struct ata_device * dev)

Determine speed down verdict

Parameters

structata_device*dev

Device of interest

This function examines error ring ofdev and determineswhether NCQ needs to be turned off, transfer speed should bestepped down, or falling back to PIO is necessary.

ECAT_ATA_BUS : ATA_BUS error for any command

ECAT_TOUT_HSM:TIMEOUT for any command or HSM violation for
IO commands

ECAT_UNK_DEV : Unknown DEV error for IO commands

ECAT_DUBIOUS_*:Identical to above three but occurred while
data transfer hasn’t been verified.

Verdicts are

NCQ_OFF : Turn off NCQ.

SPEED_DOWN:Speed down transfer speed but don’t fall back
to PIO.

FALLBACK_TO_PIO : Fall back to PIO.

Even if multiple verdicts are returned, only one action istaken per error. An action triggered by non-DUBIOUS errorsclears ering, while one triggered by DUBIOUS_* errors doesn’t.This is to expedite speed down decisions right after device isinitially configured.

The following are speed down rules. #1 and #2 deal withDUBIOUS errors.

  1. If more than one DUBIOUS_ATA_BUS or DUBIOUS_TOUT_HSM errorsoccurred during last 5 mins, SPEED_DOWN and FALLBACK_TO_PIO.
  2. If more than one DUBIOUS_TOUT_HSM or DUBIOUS_UNK_DEV errorsoccurred during last 5 mins, NCQ_OFF.
  3. If more than 8 ATA_BUS, TOUT_HSM or UNK_DEV errorsoccurred during last 5 mins, FALLBACK_TO_PIO
  4. If more than 3 TOUT_HSM or UNK_DEV errors occurredduring last 10 mins, NCQ_OFF.
  5. If more than 3 ATA_BUS or TOUT_HSM errors, or more than 6UNK_DEV errors occurred during last 10 mins, SPEED_DOWN.

LOCKING:Inherited from caller.

Return

OR of ATA_EH_SPDN_* flags.
unsigned intata_eh_speed_down(struct ata_device * dev, unsigned int eflags, unsigned int err_mask)

record error and speed down if necessary

Parameters

structata_device*dev
Failed device
unsignedinteflags
mask of ATA_EFLAG_* flags
unsignedinterr_mask

err_mask of the error

Record error and examine error history to determine whetheradjusting transmission speed is necessary. It also setstransmission limits appropriately if such adjustment isnecessary.

LOCKING:Kernel thread context (may sleep).

Return

Determined recovery action.
intata_eh_worth_retry(struct ata_queued_cmd * qc)

analyze error and decide whether to retry

Parameters

structata_queued_cmd*qc

qc to possibly retry

Look at the cause of the error and decide if a retrymight be useful or not. We don’t want to retry media errorsbecause the drive itself has probably already taken 10-30 secondsdoing its own internal retries before reporting the failure.

boolata_eh_quiet(struct ata_queued_cmd * qc)

check if we need to be quiet about a command error

Parameters

structata_queued_cmd*qc

qc to check

Look at the qc flags anbd its scsi command request flags to determineif we need to be quiet about the command failure.

voidata_eh_link_autopsy(struct ata_link * link)

analyze error and determine recovery action

Parameters

structata_link*link

host link to perform autopsy on

Analyze whylink failed and determine which recovery actionsare needed. This function also sets more detailed AC_ERR_*values and fills sense data for ATAPI CHECK SENSE.

LOCKING:Kernel thread context (may sleep).

voidata_eh_autopsy(struct ata_port * ap)

analyze error and determine recovery action

Parameters

structata_port*ap

host port to perform autopsy on

Analyze all links ofap and determine why they failed andwhich recovery actions are needed.

LOCKING:Kernel thread context (may sleep).

const char *ata_get_cmd_descript(u8 command)

get description for ATA command

Parameters

u8command

ATA command code to get description for

Return a textual description of the given command, or NULL if thecommand is not known.

LOCKING:None

voidata_eh_link_report(struct ata_link * link)

report error handling to user

Parameters

structata_link*link

ATA link EH is going on

Report EH to user.

LOCKING:None.

voidata_eh_report(struct ata_port * ap)

report error handling to user

Parameters

structata_port*ap

ATA port to report EH about

Report EH to user.

LOCKING:None.

intata_set_mode(struct ata_link * link, struct ata_device ** r_failed_dev)

Program timings and issue SET FEATURES - XFER

Parameters

structata_link*link
link on which timings will be programmed
structata_device**r_failed_dev

out parameter for failed device

Set ATA device disk transfer mode (PIO3, UDMA6, etc.). Ifata_set_mode() fails, pointer to the failing device isreturned inr_failed_dev.

LOCKING:PCI/etc. bus probe sem.

Return

0 on success, negative errno otherwise
intatapi_eh_clear_ua(struct ata_device * dev)

Clear ATAPI UNIT ATTENTION after reset

Parameters

structata_device*dev

ATAPI device to clear UA for

Resets and other operations can make an ATAPI device raiseUNIT ATTENTION which causes the next operation to fail. Thisfunction clears UA.

LOCKING:EH context (may sleep).

Return

0 on success, -errno on failure.
intata_eh_maybe_retry_flush(struct ata_device * dev)

Retry FLUSH if necessary

Parameters

structata_device*dev

ATA device which may need FLUSH retry

Ifdev failed FLUSH, it needs to be reported upper layerimmediately as it means thatdev failed to remap and alreadylost at least a sector and further FLUSH retrials won’t makeany difference to the lost sector. However, if FLUSH failedfor other reasons, for example transmission error, FLUSH needsto be retried.

This function determines whether FLUSH failure retry isnecessary and performs it if so.

Return

0 if EH can continue, -errno if EH needs to be repeated.
intata_eh_set_lpm(struct ata_link * link, enum ata_lpm_policy policy, struct ata_device ** r_failed_dev)

configure SATA interface power management

Parameters

structata_link*link
link to configure power management
enumata_lpm_policypolicy
the link power management policy
structata_device**r_failed_dev

out parameter for failed device

Enable SATA Interface power management. This will enableDevice Interface Power Management (DIPM) for min_power andmedium_power_with_dipm policies, and then call driver specificcallbacks for enabling Host Initiated Power management.

LOCKING:EH context.

Return

0 on success, -errno on failure.
intata_eh_recover(struct ata_port * ap, ata_prereset_fn_t prereset, ata_reset_fn_t softreset, ata_reset_fn_t hardreset, ata_postreset_fn_t postreset, struct ata_link ** r_failed_link)

recover host port after error

Parameters

structata_port*ap
host port to recover
ata_prereset_fn_tprereset
prereset method (can be NULL)
ata_reset_fn_tsoftreset
softreset method (can be NULL)
ata_reset_fn_thardreset
hardreset method (can be NULL)
ata_postreset_fn_tpostreset
postreset method (can be NULL)
structata_link**r_failed_link

out parameter for failed link

This is the alpha and omega, eum and yang, heart and soul oflibata exception handling. On entry, actions required torecover each link and hotplug requests are recorded in thelink’s eh_context. This function executes all the operationswith appropriate retrials and fallbacks to resurrect faileddevices, detach goners and greet newcomers.

LOCKING:Kernel thread context (may sleep).

Return

0 on success, -errno on failure.
voidata_eh_finish(struct ata_port * ap)

finish up EH

Parameters

structata_port*ap

host port to finish EH for

Recovery is complete. Clean up EH states and retry or finishfailed qcs.

LOCKING:None.

voidata_do_eh(struct ata_port * ap, ata_prereset_fn_t prereset, ata_reset_fn_t softreset, ata_reset_fn_t hardreset, ata_postreset_fn_t postreset)

do standard error handling

Parameters

structata_port*ap
host port to handle error for
ata_prereset_fn_tprereset
prereset method (can be NULL)
ata_reset_fn_tsoftreset
softreset method (can be NULL)
ata_reset_fn_thardreset
hardreset method (can be NULL)
ata_postreset_fn_tpostreset

postreset method (can be NULL)

Perform standard error handling sequence.

LOCKING:Kernel thread context (may sleep).

voidata_std_error_handler(struct ata_port * ap)

standard error handler

Parameters

structata_port*ap

host port to handle error for

Standard error handler

LOCKING:Kernel thread context (may sleep).

voidata_eh_handle_port_suspend(struct ata_port * ap)

perform port suspend operation

Parameters

structata_port*ap

port to suspend

Suspendap.

LOCKING:Kernel thread context (may sleep).

voidata_eh_handle_port_resume(struct ata_port * ap)

perform port resume operation

Parameters

structata_port*ap

port to resume

Resumeap.

LOCKING:Kernel thread context (may sleep).

libata SCSI translation/emulation

intata_std_bios_param(struct scsi_device * sdev, struct block_device * bdev, sector_t capacity, int geom)

generic bios head/sector/cylinder calculator used by sd.

Parameters

structscsi_device*sdev
SCSI device for which BIOS geometry is to be determined
structblock_device*bdev
block device associated withsdev
sector_tcapacity
capacity of SCSI device
intgeom

location to which geometry will be output

Generic bios head/sector/cylinder calculatorused by sd. Most BIOSes nowadays expect a XXX/255/16 (CHS)mapping. Some situations may arise where the disk is notbootable if this is not used.

LOCKING:Defined by the SCSI layer. We don’t really care.

Return

Zero.
voidata_scsi_unlock_native_capacity(struct scsi_device * sdev)

unlock native capacity

Parameters

structscsi_device*sdev

SCSI device to adjust device capacity for

This function is called if a partition onsdev extends beyondthe end of the device. It requests EH to unlock HPA.

LOCKING:Defined by the SCSI layer. Might sleep.

boolata_scsi_dma_need_drain(struct request * rq)

Check whether data transfer may overflow

Parameters

structrequest*rq

request to be checked

ATAPI commands which transfer variable length data to hostmight overflow due to application error or hardware bug. Thisfunction checks whether overflow should be drained and ignoredforrequest.

LOCKING:None.

Return

1 if ; otherwise, 0.
intata_scsi_slave_config(struct scsi_device * sdev)

Set SCSI device attributes

Parameters

structscsi_device*sdev

SCSI device to examine

This is called before we actually start readingand writing to the device, to configure certainSCSI mid-layer behaviors.

LOCKING:Defined by SCSI layer. We don’t really care.

voidata_scsi_slave_destroy(struct scsi_device * sdev)

SCSI device is about to be destroyed

Parameters

structscsi_device*sdev

SCSI device to be destroyed

sdev is about to be destroyed for hot/warm unplugging. Ifthis unplugging was initiated by libata as indicated by NULLdev->sdev, this function doesn’t have to do anything.Otherwise, SCSI layer initiated warm-unplug is in progress.Clear dev->sdev, schedule the device for ATA detach and invokeEH.

LOCKING:Defined by SCSI layer. We don’t really care.

intata_scsi_queuecmd(struct Scsi_Host * shost, struct scsi_cmnd * cmd)

Issue SCSI cdb to libata-managed device

Parameters

structScsi_Host*shost
SCSI host of command to be sent
structscsi_cmnd*cmd

SCSI command to be sent

In some cases, this function translates SCSI commands intoATA taskfiles, and queues the taskfiles to be sent tohardware. In other cases, this function simulates aSCSI device by evaluating and responding to certainSCSI commands. This creates the overall effect ofATA and ATAPI devices appearing as SCSI devices.

LOCKING:ATA host lock

Return

Return value from __ata_scsi_queuecmd() ifcmd can be queued,0 otherwise.
intata_get_identity(struct ata_port * ap, struct scsi_device * sdev, void __user * arg)

Handler for HDIO_GET_IDENTITY ioctl

Parameters

structata_port*ap
target port
structscsi_device*sdev
SCSI device to get identify data for
void__user*arg

User buffer area for identify data

LOCKING:Defined by the SCSI layer. We don’t really care.

Return

Zero on success, negative errno on error.
intata_cmd_ioctl(struct scsi_device * scsidev, void __user * arg)

Handler for HDIO_DRIVE_CMD ioctl

Parameters

structscsi_device*scsidev
Device to which we are issuing command
void__user*arg

User provided data for issuing command

LOCKING:Defined by the SCSI layer. We don’t really care.

Return

Zero on success, negative errno on error.
intata_task_ioctl(struct scsi_device * scsidev, void __user * arg)

Handler for HDIO_DRIVE_TASK ioctl

Parameters

structscsi_device*scsidev
Device to which we are issuing command
void__user*arg

User provided data for issuing command

LOCKING:Defined by the SCSI layer. We don’t really care.

Return

Zero on success, negative errno on error.
struct ata_queued_cmd *ata_scsi_qc_new(struct ata_device * dev, struct scsi_cmnd * cmd)

acquire new ata_queued_cmd reference

Parameters

structata_device*dev
ATA device to which the new command is attached
structscsi_cmnd*cmd

SCSI command that originated this ATA command

Obtain a reference to an unused ata_queued_cmd structure,which is the basic libata structure representing a singleATA command sent to the hardware.

If a command was available, fill in the SCSI-specificportions of the structure with information on thecurrent command.

LOCKING:spin_lock_irqsave(host lock)

Return

Command allocated, orNULL if none available.
voidata_dump_status(unsigned id, struct ata_taskfile * tf)

user friendly display of error info

Parameters

unsignedid
id of the port in question
structata_taskfile*tf

ptr to filled out taskfile

Decode and dump the ATA error/status registers for the user sothat they have some idea what really happened at the nonmake-believe layer.

LOCKING:inherited from caller

voidata_to_sense_error(unsigned id, u8 drv_stat, u8 drv_err, u8 * sk, u8 * asc, u8 * ascq, int verbose)

convert ATA error to SCSI error

Parameters

unsignedid
ATA device number
u8drv_stat
value contained in ATA status register
u8drv_err
value contained in ATA error register
u8*sk
the sense key we’ll fill out
u8*asc
the additional sense code we’ll fill out
u8*ascq
the additional sense code qualifier we’ll fill out
intverbose

be verbose

Converts an ATA error into a SCSI error. Fill out pointers toSK, ASC, and ASCQ bytes for later use in fixed or descriptorformat sense blocks.

LOCKING:spin_lock_irqsave(host lock)

voidata_gen_ata_sense(struct ata_queued_cmd * qc)

generate a SCSI fixed sense block

Parameters

structata_queued_cmd*qc

Command that we are erroring out

Generate sense block for a failed ATA commandqc. Descriptorformat is used to accommodate LBA48 block address.

LOCKING:None.

unsigned intata_scsi_start_stop_xlat(struct ata_queued_cmd * qc)

Translate SCSI START STOP UNIT command

Parameters

structata_queued_cmd*qc

Storage for translated ATA taskfile

Sets up an ATA taskfile to issue STANDBY (to stop) or READ VERIFY(to start). Perhaps these commands should be preceded byCHECK POWER MODE to see what power mode the device is already in.[See SAT revision 5 at www.t10.org]

LOCKING:spin_lock_irqsave(host lock)

Return

Zero on success, non-zero on error.
unsigned intata_scsi_flush_xlat(struct ata_queued_cmd * qc)

Translate SCSI SYNCHRONIZE CACHE command

Parameters

structata_queued_cmd*qc

Storage for translated ATA taskfile

Sets up an ATA taskfile to issue FLUSH CACHE orFLUSH CACHE EXT.

LOCKING:spin_lock_irqsave(host lock)

Return

Zero on success, non-zero on error.
voidscsi_6_lba_len(const u8 * cdb, u64 * plba, u32 * plen)

Get LBA and transfer length

Parameters

constu8*cdb

SCSI command to translate

Calculate LBA and transfer length for 6-byte commands.

u64*plba
the LBA
u32*plen
the transfer length
voidscsi_10_lba_len(const u8 * cdb, u64 * plba, u32 * plen)

Get LBA and transfer length

Parameters

constu8*cdb

SCSI command to translate

Calculate LBA and transfer length for 10-byte commands.

u64*plba
the LBA
u32*plen
the transfer length
voidscsi_16_lba_len(const u8 * cdb, u64 * plba, u32 * plen)

Get LBA and transfer length

Parameters

constu8*cdb

SCSI command to translate

Calculate LBA and transfer length for 16-byte commands.

u64*plba
the LBA
u32*plen
the transfer length
unsigned intata_scsi_verify_xlat(struct ata_queued_cmd * qc)

Translate SCSI VERIFY command into an ATA one

Parameters

structata_queued_cmd*qc

Storage for translated ATA taskfile

Converts SCSI VERIFY command to an ATA READ VERIFY command.

LOCKING:spin_lock_irqsave(host lock)

Return

Zero on success, non-zero on error.
unsigned intata_scsi_rw_xlat(struct ata_queued_cmd * qc)

Translate SCSI r/w command into an ATA one

Parameters

structata_queued_cmd*qc

Storage for translated ATA taskfile

Converts any of six SCSI read/write commands into theATA counterpart, including starting sector (LBA),sector count, and taking into account the device’s LBA48support.

CommandsREAD_6,READ_10,READ_16,WRITE_6,WRITE_10, andWRITE_16 are currently supported.

LOCKING:spin_lock_irqsave(host lock)

Return

Zero on success, non-zero on error.
intata_scsi_translate(struct ata_device * dev, struct scsi_cmnd * cmd, ata_xlat_func_t xlat_func)

Translate then issue SCSI command to ATA device

Parameters

structata_device*dev
ATA device to which the command is addressed
structscsi_cmnd*cmd
SCSI command to execute
ata_xlat_func_txlat_func

Actor which translatescmd to an ATA taskfile

Our ->queuecommand() function has decided that the SCSIcommand issued can be directly translated into an ATAcommand, rather than handled internally.

This function sets up an ata_queued_cmd structure for theSCSI command, and sends that ata_queued_cmd to the hardware.

The xlat_func argument (actor) returns 0 if ready to executeATA command, else 1 to finish translation. If 1 is returnedthen cmd->result (and possibly cmd->sense_buffer) are assumedto be set reflecting an error condition or clean (early)termination.

LOCKING:spin_lock_irqsave(host lock)

Return

0 on success, SCSI_ML_QUEUE_DEVICE_BUSY if the commandneeds to be deferred.
void *ata_scsi_rbuf_get(struct scsi_cmnd * cmd, bool copy_in, unsigned long * flags)

Map response buffer.

Parameters

structscsi_cmnd*cmd
SCSI command containing buffer to be mapped.
boolcopy_in

copy in from user buffer

Prepare buffer for simulated SCSI commands.

LOCKING:spin_lock_irqsave(ata_scsi_rbuf_lock) on success

unsignedlong*flags
unsigned long variable to store irq enable status

Return

Pointer to response buffer.
voidata_scsi_rbuf_put(struct scsi_cmnd * cmd, bool copy_out, unsigned long * flags)

Unmap response buffer.

Parameters

structscsi_cmnd*cmd
SCSI command containing buffer to be unmapped.
boolcopy_out
copy out result
unsignedlong*flags

flags passed toata_scsi_rbuf_get()

Returns rbuf buffer. The result is copied tocmd’s buffer ifcopy_back is true.

LOCKING:Unlocks ata_scsi_rbuf_lock.

voidata_scsi_rbuf_fill(struct ata_scsi_args * args, unsigned int (*actor)(struct ata_scsi_args *args, u8 *rbuf))

wrapper for SCSI command simulators

Parameters

structata_scsi_args*args
device IDENTIFY data / SCSI command of interest.
unsignedint(*)(structata_scsi_args*args,u8*rbuf)actor

Callback hook for desired SCSI command simulator

Takes care of the hard work of simulating a SCSI command…Mapping the response buffer, calling the command’s handler,and handling the handler’s return value. This return valueindicates whether the handler wishes the SCSI command to becompleted successfully (0), or not (in which case cmd->resultand sense buffer are assumed to be set).

LOCKING:spin_lock_irqsave(host lock)

unsigned intata_scsiop_inq_std(struct ata_scsi_args * args, u8 * rbuf)

Simulate INQUIRY command

Parameters

structata_scsi_args*args
device IDENTIFY data / SCSI command of interest.
u8*rbuf

Response buffer, to which simulated SCSI cmd output is sent.

Returns standard device identification data associatedwith non-VPD INQUIRY command output.

LOCKING:spin_lock_irqsave(host lock)

unsigned intata_scsiop_inq_00(struct ata_scsi_args * args, u8 * rbuf)

Simulate INQUIRY VPD page 0, list of pages

Parameters

structata_scsi_args*args
device IDENTIFY data / SCSI command of interest.
u8*rbuf

Response buffer, to which simulated SCSI cmd output is sent.

Returns list of inquiry VPD pages available.

LOCKING:spin_lock_irqsave(host lock)

unsigned intata_scsiop_inq_80(struct ata_scsi_args * args, u8 * rbuf)

Simulate INQUIRY VPD page 80, device serial number

Parameters

structata_scsi_args*args
device IDENTIFY data / SCSI command of interest.
u8*rbuf

Response buffer, to which simulated SCSI cmd output is sent.

Returns ATA device serial number.

LOCKING:spin_lock_irqsave(host lock)

unsigned intata_scsiop_inq_83(struct ata_scsi_args * args, u8 * rbuf)

Simulate INQUIRY VPD page 83, device identity

Parameters

structata_scsi_args*args
device IDENTIFY data / SCSI command of interest.
u8*rbuf

Response buffer, to which simulated SCSI cmd output is sent.

Yields two logical unit device identification designators:
  • vendor specific ASCII containing the ATA serial number
  • SAT defined “t10 vendor id based” containing ASCII vendorname (“ATA “), model and serial numbers.

LOCKING:spin_lock_irqsave(host lock)

unsigned intata_scsiop_inq_89(struct ata_scsi_args * args, u8 * rbuf)

Simulate INQUIRY VPD page 89, ATA info

Parameters

structata_scsi_args*args
device IDENTIFY data / SCSI command of interest.
u8*rbuf

Response buffer, to which simulated SCSI cmd output is sent.

Yields SAT-specified ATA VPD page.

LOCKING:spin_lock_irqsave(host lock)

voidmodecpy(u8 * dest, const u8 * src, int n, bool changeable)

Prepare response for MODE SENSE

Parameters

u8*dest
output buffer
constu8*src
data being copied
intn
length of mode page
boolchangeable

whether changeable parameters are requested

Generate a generic MODE SENSE page for either current or changeableparameters.

LOCKING:None.

unsigned intata_msense_caching(u16 * id, u8 * buf, bool changeable)

Simulate MODE SENSE caching info page

Parameters

u16*id
device IDENTIFY data
u8*buf
output buffer
boolchangeable

whether changeable parameters are requested

Generate a caching info page, which conditionally indicateswrite caching to the SCSI layer, depending on devicecapabilities.

LOCKING:None.

unsigned intata_msense_control(struct ata_device * dev, u8 * buf, bool changeable)

Simulate MODE SENSE control mode page

Parameters

structata_device*dev
ATA device of interest
u8*buf
output buffer
boolchangeable

whether changeable parameters are requested

Generate a generic MODE SENSE control mode page.

LOCKING:None.

unsigned intata_msense_rw_recovery(u8 * buf, bool changeable)

Simulate MODE SENSE r/w error recovery page

Parameters

u8*buf
output buffer
boolchangeable

whether changeable parameters are requested

Generate a generic MODE SENSE r/w error recovery page.

LOCKING:None.

unsigned intata_scsiop_mode_sense(struct ata_scsi_args * args, u8 * rbuf)

Simulate MODE SENSE 6, 10 commands

Parameters

structata_scsi_args*args
device IDENTIFY data / SCSI command of interest.
u8*rbuf

Response buffer, to which simulated SCSI cmd output is sent.

Simulate MODE SENSE commands. Assume this is invoked for directaccess devices (e.g. disks) only. There should be no blockdescriptor for other device types.

LOCKING:spin_lock_irqsave(host lock)

unsigned intata_scsiop_read_cap(struct ata_scsi_args * args, u8 * rbuf)

Simulate READ CAPACITY[ 16] commands

Parameters

structata_scsi_args*args
device IDENTIFY data / SCSI command of interest.
u8*rbuf

Response buffer, to which simulated SCSI cmd output is sent.

Simulate READ CAPACITY commands.

LOCKING:None.

unsigned intata_scsiop_report_luns(struct ata_scsi_args * args, u8 * rbuf)

Simulate REPORT LUNS command

Parameters

structata_scsi_args*args
device IDENTIFY data / SCSI command of interest.
u8*rbuf

Response buffer, to which simulated SCSI cmd output is sent.

Simulate REPORT LUNS command.

LOCKING:spin_lock_irqsave(host lock)

unsigned intatapi_xlat(struct ata_queued_cmd * qc)

Initialize PACKET taskfile

Parameters

structata_queued_cmd*qc

command structure to be initialized

LOCKING:spin_lock_irqsave(host lock)

Return

Zero on success, non-zero on failure.
struct ata_device *ata_scsi_find_dev(struct ata_port * ap, const struct scsi_device * scsidev)

lookup ata_device from scsi_cmnd

Parameters

structata_port*ap
ATA port to which the device is attached
conststructscsi_device*scsidev

SCSI device from which we derive the ATA device

Given various information provided in struct scsi_cmnd,map that onto an ATA bus, and using that mappingdetermine which ata_device is associated with theSCSI command to be sent.

LOCKING:spin_lock_irqsave(host lock)

Return

Associated ATA device, orNULL if not found.
unsigned intata_scsi_pass_thru(struct ata_queued_cmd * qc)

convert ATA pass-thru CDB to taskfile

Parameters

structata_queued_cmd*qc

command structure to be initialized

Handles either 12, 16, or 32-byte versions of the CDB.

Return

Zero on success, non-zero on failure.
size_tata_format_dsm_trim_descr(struct scsi_cmnd * cmd, u32 trmax, u64 sector, u32 count)

SATL Write Same to DSM Trim

Parameters

structscsi_cmnd*cmd
SCSI command being translated
u32trmax
Maximum number of entries that will fit in sector_size bytes.
u64sector
Starting sector
u32count
Total Range of request in logical sectors

Description

Rewrite the WRITE SAME descriptor to be a DSM TRIM little-endian formatteddescriptor.

Upto 64 entries of the format:
63:48 Range Length47:0 LBA

Range Length of 0 is ignored.LBA’s should be sorted order and not overlap.

NOTE

this is the same format as ADD LBA(S) TO NV CACHE PINNED SET

Return

Number of bytes copied into sglist.

unsigned intata_scsi_write_same_xlat(struct ata_queued_cmd * qc)

SATL Write Same to ATA SCT Write Same

Parameters

structata_queued_cmd*qc
Command to be translated

Description

Translate a SCSI WRITE SAME command to be either a DSM TRIM command oran SCT Write Same command.Based on WRITE SAME has the UNMAP flag:

  • When set translate to DSM TRIM
  • When clear translate to SCT Write Same
unsigned intata_scsiop_maint_in(struct ata_scsi_args * args, u8 * rbuf)

Simulate a subset of MAINTENANCE_IN

Parameters

structata_scsi_args*args
device MAINTENANCE_IN data / SCSI command of interest.
u8*rbuf

Response buffer, to which simulated SCSI cmd output is sent.

Yields a subset to satisfyscsi_report_opcode()

LOCKING:spin_lock_irqsave(host lock)

voidata_scsi_report_zones_complete(struct ata_queued_cmd * qc)

convert ATA output

Parameters

structata_queued_cmd*qc

command structure returning the data

Convert T-13 little-endian field representation intoT-10 big-endian field representation.What a mess.

intata_mselect_caching(struct ata_queued_cmd * qc, const u8 * buf, int len, u16 * fp)

Simulate MODE SELECT for caching info page

Parameters

structata_queued_cmd*qc
Storage for translated ATA taskfile
constu8*buf
input buffer
intlen
number of valid bytes in the input buffer
u16*fp

out parameter for the failed field on error

Prepare a taskfile to modify caching information for the device.

LOCKING:None.

intata_mselect_control(struct ata_queued_cmd * qc, const u8 * buf, int len, u16 * fp)

Simulate MODE SELECT for control page

Parameters

structata_queued_cmd*qc
Storage for translated ATA taskfile
constu8*buf
input buffer
intlen
number of valid bytes in the input buffer
u16*fp

out parameter for the failed field on error

Prepare a taskfile to modify caching information for the device.

LOCKING:None.

unsigned intata_scsi_mode_select_xlat(struct ata_queued_cmd * qc)

Simulate MODE SELECT 6, 10 commands

Parameters

structata_queued_cmd*qc

Storage for translated ATA taskfile

Converts a MODE SELECT command to an ATA SET FEATURES taskfile.Assume this is invoked for direct access devices (e.g. disks) only.There should be no block descriptor for other device types.

LOCKING:spin_lock_irqsave(host lock)

unsigned intata_scsi_var_len_cdb_xlat(struct ata_queued_cmd * qc)

SATL variable length CDB to Handler

Parameters

structata_queued_cmd*qc

Command to be translated

Translate a SCSI variable length CDB to specified commands.It checks a service action value in CDB to call corresponding handler.

Return

Zero on success, non-zero on failure
ata_xlat_func_tata_get_xlat_func(struct ata_device * dev, u8 cmd)

check if SCSI to ATA translation is possible

Parameters

structata_device*dev
ATA device
u8cmd

SCSI command opcode to consider

Look up the SCSI command given, and determine whether theSCSI command is to be translated or simulated.

Return

Pointer to translation function if possible,NULL if not.
voidata_scsi_dump_cdb(struct ata_port * ap, struct scsi_cmnd * cmd)

dump SCSI command contents to dmesg

Parameters

structata_port*ap
ATA port to which the command was being sent
structscsi_cmnd*cmd

SCSI command to dump

Prints the contents of a SCSI command viaprintk().

voidata_scsi_simulate(struct ata_device * dev, struct scsi_cmnd * cmd)

simulate SCSI command on ATA device

Parameters

structata_device*dev
the target device
structscsi_cmnd*cmd

SCSI command being sent to device.

Interprets and directly executes a select list of SCSI commandsthat can be handled internally.

LOCKING:spin_lock_irqsave(host lock)

intata_scsi_offline_dev(struct ata_device * dev)

offline attached SCSI device

Parameters

structata_device*dev

ATA device to offline attached SCSI device for

This function is called from ata_eh_hotplug() and responsiblefor taking the SCSI device attached todev offline. Thisfunction is called with host lock which protects dev->sdevagainst clearing.

LOCKING:spin_lock_irqsave(host lock)

Return

1 if attached SCSI device exists, 0 otherwise.
voidata_scsi_remove_dev(struct ata_device * dev)

remove attached SCSI device

Parameters

structata_device*dev

ATA device to remove attached SCSI device for

This function is called from ata_eh_scsi_hotplug() andresponsible for removing the SCSI device attached todev.

LOCKING:Kernel thread context (may sleep).

voidata_scsi_media_change_notify(struct ata_device * dev)

send media change event

Parameters

structata_device*dev

Pointer to the disk device with media change event

Tell the block layer to send a media change notificationevent.

LOCKING:spin_lock_irqsave(host lock)

voidata_scsi_hotplug(struct work_struct * work)

SCSI part of hotplug

Parameters

structwork_struct*work

Pointer to ATA port to perform SCSI hotplug on

Perform SCSI part of hotplug. It’s executed from a separateworkqueue after EH completes. This is necessary because SCSIhot plugging requires working EH and hot unplugging issynchronized with hot plugging with a mutex.

LOCKING:Kernel thread context (may sleep).

intata_scsi_user_scan(struct Scsi_Host * shost, unsigned int channel, unsigned int id, u64 lun)

indication for user-initiated bus scan

Parameters

structScsi_Host*shost
SCSI host to scan
unsignedintchannel
Channel to scan
unsignedintid
ID to scan
u64lun

LUN to scan

This function is called when user explicitly requests busscan. Set probe pending flag and invoke EH.

LOCKING:SCSI layer (we don’t care)

Return

Zero.
voidata_scsi_dev_rescan(struct work_struct * work)

initiate scsi_rescan_device()

Parameters

structwork_struct*work

Pointer to ATA port to perform scsi_rescan_device()

After ATA pass thru (SAT) commands are executed successfully,libata need to propagate the changes to SCSI layer.

LOCKING:Kernel thread context (may sleep).

ATA errors and exceptions

This chapter tries to identify what error/exception conditions exist forATA/ATAPI devices and describe how they should be handled inimplementation-neutral way.

The term ‘error’ is used to describe conditions where either an expliciterror condition is reported from device or a command has timed out.

The term ‘exception’ is either used to describe exceptional conditionswhich are not errors (say, power or hotplug events), or to describe botherrors and non-error exceptional conditions. Where explicit distinctionbetween error and exception is necessary, the term ‘non-error exception’is used.

Exception categories

Exceptions are described primarily with respect to legacy taskfile + busmaster IDE interface. If a controller provides other better mechanismfor error reporting, mapping those into categories described belowshouldn’t be difficult.

In the following sections, two recovery actions - reset andreconfiguring transport - are mentioned. These are described further inEH recovery actions.

HSM violation

This error is indicated when STATUS value doesn’t match HSM requirementduring issuing or execution any ATA/ATAPI command.

  • ATA_STATUS doesn’t contain !BSY && DRDY && !DRQ while trying toissue a command.
  • !BSY && !DRQ during PIO data transfer.
  • DRQ on command completion.
  • !BSY && ERR after CDB transfer starts but before the last byte of CDBis transferred. ATA/ATAPI standard states that “The device shall notterminate the PACKET command with an error before the last byte ofthe command packet has been written” in the error outputs descriptionof PACKET command and the state diagram doesn’t include suchtransitions.

In these cases, HSM is violated and not much information regarding theerror can be acquired from STATUS or ERROR register. IOW, this error canbe anything - driver bug, faulty device, controller and/or cable.

As HSM is violated, reset is necessary to restore known state.Reconfiguring transport for lower speed might be helpful too astransmission errors sometimes cause this kind of errors.

ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION)

These are errors detected and reported by ATA/ATAPI devices indicatingdevice problems. For this type of errors, STATUS and ERROR registervalues are valid and describe error condition. Note that some of ATA buserrors are detected by ATA/ATAPI devices and reported using the samemechanism as device errors. Those cases are described later in thissection.

For ATA commands, this type of errors are indicated by !BSY && ERRduring command execution and on completion.

For ATAPI commands,

  • !BSY && ERR && ABRT right after issuing PACKET indicates that PACKETcommand is not supported and falls in this category.
  • !BSY && ERR(==CHK) && !ABRT after the last byte of CDB is transferredindicates CHECK CONDITION and doesn’t fall in this category.
  • !BSY && ERR(==CHK) && ABRT after the last byte of CDB is transferred*probably* indicates CHECK CONDITION and doesn’t fall in thiscategory.

Of errors detected as above, the following are not ATA/ATAPI deviceerrors but ATA bus errors and should be handled according toATA bus error.

CRC error during data transfer
This is indicated by ICRC bit in the ERROR register and means thatcorruption occurred during data transfer. Up to ATA/ATAPI-7, thestandard specifies that this bit is only applicable to UDMAtransfers but ATA/ATAPI-8 draft revision 1f says that the bit may beapplicable to multiword DMA and PIO.
ABRT error during data transfer or on completion

Up to ATA/ATAPI-7, the standard specifies that ABRT could be set onICRC errors and on cases where a device is not able to complete acommand. Combined with the fact that MWDMA and PIO transfer errorsaren’t allowed to use ICRC bit up to ATA/ATAPI-7, it seems to implythat ABRT bit alone could indicate transfer errors.

However, ATA/ATAPI-8 draft revision 1f removes the part that ICRCerrors can turn on ABRT. So, this is kind of gray area. Someheuristics are needed here.

ATA/ATAPI device errors can be further categorized as follows.

Media errors

This is indicated by UNC bit in the ERROR register. ATA devicesreports UNC error only after certain number of retries cannotrecover the data, so there’s nothing much else to do other thannotifying upper layer.

READ and WRITE commands report CHS or LBA of the first failed sectorbut ATA/ATAPI standard specifies that the amount of transferred dataon error completion is indeterminate, so we cannot assume thatsectors preceding the failed sector have been transferred and thuscannot complete those sectors successfully as SCSI does.

Media changed / media change requested error
<<TODO: fill here>>
Address error
This is indicated by IDNF bit in the ERROR register. Report to upperlayer.
Other errors
This can be invalid command or parameter indicated by ABRT ERROR bitor some other error condition. Note that ABRT bit can indicate a lotof things including ICRC and Address errors. Heuristics needed.

Depending on commands, not all STATUS/ERROR bits are applicable. Thesenon-applicable bits are marked with “na” in the output descriptions butup to ATA/ATAPI-7 no definition of “na” can be found. However,ATA/ATAPI-8 draft revision 1f describes “N/A” as follows.

3.2.3.3a N/A
A keyword the indicates a field has no defined value in thisstandard and should not be checked by the host or device. N/Afields should be cleared to zero.

So, it seems reasonable to assume that “na” bits are cleared to zero bydevices and thus need no explicit masking.

ATAPI device CHECK CONDITION

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 aPACKET command. For this kind of errors, sense data should be acquiredto gather information regarding the errors. REQUEST SENSE packet commandshould be used to acquire sense data.

Once sense data is acquired, this type of errors can be handledsimilarly to other SCSI errors. Note that sense data may indicate ATAbus error (e.g. Sense Key 04h HARDWARE ERROR && ASC/ASCQ 47h/00h SCSIPARITY ERROR). In such cases, the error should be considered as an ATAbus error and handled according toATA bus error.

ATA device error (NCQ)

NCQ command error is indicated by cleared BSY and set ERR bit during NCQcommand phase (one or more NCQ commands outstanding). Although STATUSand ERROR registers will contain valid values describing the error, READLOG EXT is required to clear the error condition, determine whichcommand has failed and acquire more information.

READ LOG EXT Log Page 10h reports which tag has failed and taskfileregister values describing the error. With this information the failedcommand can be handled as a normal ATA command error as inATA/ATAPI device error (non-NCQ / non-CHECK CONDITION)and all other in-flight commands must be retried. Note that this retryshould not be counted - it’s likely that commands retried this way wouldhave completed normally if it were not for the failed command.

Note that ATA bus errors can be reported as ATA device NCQ errors. Thisshould be handled as described inATA bus error.

If READ LOG EXT Log Page 10h fails or reports NQ, we’re thoroughlyscrewed. This condition should be treated according toHSM violation.

ATA bus error

ATA bus error means that data corruption occurred during transmissionover ATA bus (SATA or PATA). This type of errors can be indicated by

  • ICRC or ABRT error as described inATA/ATAPI device error (non-NCQ / non-CHECK CONDITION).
  • Controller-specific error completion with error informationindicating transmission error.
  • On some controllers, command timeout. In this case, there may be amechanism to determine that the timeout is due to transmission error.
  • Unknown/random errors, timeouts and all sorts of weirdities.

As described above, transmission errors can cause wide variety ofsymptoms 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 totransmission error or not; therefore, it’s necessary to employ some kindof heuristic when dealing with errors and timeouts. For example,encountering repetitive ABRT errors for known supported command islikely to indicate ATA bus error.

Once it’s determined that ATA bus errors have possibly occurred,lowering ATA bus transmission speed is one of actions which mayalleviate the problem. SeeReconfigure transport formore information.

PCI bus error

Data corruption or other failures during transmission over PCI (or othersystem bus). For standard BMDMA, this is indicated by Error bit in theBMDMA Status register. This type of errors must be logged as itindicates something is very wrong with the system. Resetting hostcontroller is recommended.

Late completion

This occurs when timeout occurs and the timeout handler finds out thatthe timed out command has completed successfully or with error. This isusually caused by lost interrupts. This type of errors must be logged.Resetting host controller is recommended.

Unknown error (timeout)

This is when timeout occurs and the command is still processing or thehost and device are in unknown state. When this occurs, HSM could be inany valid or invalid state. To bring the device to known state and makeit forget about the timed out command, resetting is necessary. The timedout command may be retried.

Timeouts can also be caused by transmission errors. Refer toATA bus error for more details.

Hotplug and power management exceptions

<<TODO: fill here>>

EH recovery actions

This section discusses several important recovery actions.

Clearing error condition

Many controllers require its error registers to be cleared by errorhandler. Different controllers may have different requirements.

For SATA, it’s strongly recommended to clear at least SError registerduring error handling.

Reset

During EH, resetting is necessary in the following cases.

  • HSM is in unknown or invalid state
  • HBA is in unknown or invalid state
  • EH needs to make HBA/device forget about in-flight commands
  • HBA/device behaves weirdly

Resetting during EH might be a good idea regardless of error conditionto improve EH robustness. Whether to reset both or either one of HBA anddevice depends on situation but the following scheme is recommended.

  • When it’s known that HBA is in ready state but ATA/ATAPI device is inunknown state, reset only device.
  • If HBA is in unknown state, reset both HBA and device.

HBA resetting is implementation specific. For a controller complying totaskfile/BMDMA PCI IDE, stopping active DMA transaction may besufficient iff BMDMA state is the only HBA context. But even mostlytaskfile/BMDMA PCI IDE complying controllers may have implementationspecific requirements and mechanism to reset themselves. This must beaddressed by specific drivers.

OTOH, ATA/ATAPI standard describes in detail ways to reset ATA/ATAPIdevices.

PATA hardware reset
This is hardware initiated device reset signalled with asserted PATARESET- signal. There is no standard way to initiate hardware resetfrom software although some hardware provides registers that allowdriver to directly tweak the RESET- signal.
Software reset
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 requirecontroller-specific support as the second Register FIS to clear SRSTshould be transmitted while BSY bit is still set. Note that on PATA,this resets both master and slave devices on a channel.
EXECUTE DEVICE DIAGNOSTIC command

Although ATA/ATAPI standard doesn’t describe exactly, EDD impliessome level of resetting, possibly similar level with software reset.Host-side EDD protocol can be handled with normal command processingand most SATA controllers should be able to handle EDD’s just likeother commands. As in software reset, EDD affects both devices on aPATA bus.

Although EDD does reset devices, this doesn’t suit error handling asEDD cannot be issued while BSY is set and it’s unclear how it willact when device is in unknown/weird state.

ATAPI DEVICE RESET command
This is very similar to software reset except that reset can berestricted to the selected device without affecting the other devicesharing the cable.
SATA phy reset
This is the preferred way of resetting a SATA device. In effect,it’s identical to PATA hardware reset. Note that this can be donewith the standard SCR Control register. As such, it’s usually easierto implement than software reset.

One more thing to consider when resetting devices is that resettingclears certain configuration parameters and they need to be set to theirprevious or newly adjusted values after reset.

Parameters affected are.

  • CHS set up with INITIALIZE DEVICE PARAMETERS (seldom used)
  • Parameters set with SET FEATURES including transfer mode setting
  • Block count set with SET MULTIPLE MODE
  • Other parameters (SET MAX, MEDIA LOCK…)

ATA/ATAPI standard specifies that some parameters must be maintainedacross hardware or software reset, but doesn’t strictly specify all ofthem. Always reconfiguring needed parameters after reset is required forrobustness. Note that this also applies when resuming from deep sleep(power-off).

Also, ATA/ATAPI standard requires that IDENTIFY DEVICE / IDENTIFY PACKETDEVICE is issued after any configuration parameter is updated or ahardware reset and the result used for further operation. OS driver isrequired to implement revalidation mechanism to support this.

Reconfigure transport

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 transmissionerror rate. This can be mitigated by lowering transmission speed.

The following is a possible scheme Jeff Garzik suggested.

If more than $N (3?) transmission errors happen in 15 minutes,

  • if SATA, decrease SATA PHY speed. if speed cannot be decreased,
  • decrease UDMA xfer speed. if at UDMA0, switch to PIO4,
  • decrease PIO xfer speed. if at PIO3, complain, but continue

ata_piix Internals

intich_pata_cable_detect(struct ata_port * ap)

Probe host controller cable detect info

Parameters

structata_port*ap

Port for which cable detect info is desired

Read 80c cable indicator from ATA PCI device’s PCI configregister. This register is normally set by firmware (BIOS).

LOCKING:None (inherited from caller).

intpiix_pata_prereset(struct ata_link * link, unsigned long deadline)

prereset for PATA host controller

Parameters

structata_link*link
Target link
unsignedlongdeadline

deadline jiffies for the operation

LOCKING:None (inherited from caller).

voidpiix_set_piomode(struct ata_port * ap, struct ata_device * adev)

Initialize host controller PATA PIO timings

Parameters

structata_port*ap
Port whose timings we are configuring
structata_device*adev

Drive in question

Set PIO mode for device, in host controller PCI config space.

LOCKING:None (inherited from caller).

voiddo_pata_set_dmamode(struct ata_port * ap, struct ata_device * adev, int isich)

Initialize host controller PATA PIO timings

Parameters

structata_port*ap
Port whose timings we are configuring
structata_device*adev
Drive in question
intisich

set if the chip is an ICH device

Set UDMA mode for device, in host controller PCI config space.

LOCKING:None (inherited from caller).

voidpiix_set_dmamode(struct ata_port * ap, struct ata_device * adev)

Initialize host controller PATA DMA timings

Parameters

structata_port*ap
Port whose timings we are configuring
structata_device*adev

um

Set MW/UDMA mode for device, in host controller PCI config space.

LOCKING:None (inherited from caller).

voidich_set_dmamode(struct ata_port * ap, struct ata_device * adev)

Initialize host controller PATA DMA timings

Parameters

structata_port*ap
Port whose timings we are configuring
structata_device*adev

um

Set MW/UDMA mode for device, in host controller PCI config space.

LOCKING:None (inherited from caller).

intpiix_check_450nx_errata(struct pci_dev * ata_dev)

Check for problem 450NX setup

Parameters

structpci_dev*ata_dev

the PCI device to check

Check for the present of 450NX errata #19 and errata #25. Ifthey are found return an error code so we can turn off DMA

intpiix_init_one(struct pci_dev * pdev, const structpci_device_id * ent)

Register PIIX ATA PCI device with kernel services

Parameters

structpci_dev*pdev
PCI device to register
conststructpci_device_id*ent

Entry in piix_pci_tbl matching withpdev

Called from kernel PCI layer. We probe for combined mode (sigh),and then hand over control to libata, for it to do the rest.

LOCKING:Inherited from PCI layer (may sleep).

Return

Zero on success, or -ERRNO value.

sata_sil Internals

intsil_set_mode(struct ata_link * link, struct ata_device ** r_failed)

wrap set_mode functions

Parameters

structata_link*link
link to set up
structata_device**r_failed

returned device when we fail

Wrap the libata method for device setup as after the setup we needto inspect the results and do some configuration work

voidsil_dev_config(struct ata_device * dev)

Apply device/host-specific errata fixups

Parameters

structata_device*dev

Device to be examined

After the IDENTIFY [PACKET] DEVICE step is complete, and adevice is known to be present, this function is called.We apply two errata fixups which are specific to Silicon Image,a Seagate and a Maxtor fixup.

For certain Seagate devices, we must limit the maximum sectorsto under 8K.

For certain Maxtor devices, we must not program the drivebeyond udma5.

Both fixups are unfairly pessimistic. As soon as I get moreinformation on these errata, I will create a more exhaustivelist, and apply the fixups to only the specificdevices/hosts/firmwares that need it.

20040111 - Seagate drives affected by the Mod15Write bug are blacklistedThe Maxtor quirk is in the blacklist, but I’m keeping the originalpessimistic fix for the following reasons…- There seems to be less info on it, only one device gleaned off theWindows driver, maybe only one is affected. More info would be greatlyappreciated.- But then again UDMA5 is hardly anything to complain about

Thanks

The bulk of the ATA knowledge comes thanks to long conversations withAndre Hedrick (www.linux-ide.org), and long hours pondering the ATA andSCSI specifications.

Thanks to Alan Cox for pointing out similarities between SATA and SCSI,and in general for motivation to hack on libata.

libata’s device detection method, ata_pio_devchk, and in general allthe early probing was based on extensive study of Hale Landis’sprobe/reset code in his ATADRVR driver (www.ata-atapi.com).