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`¶

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 (*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_std_error_handler().

ata_std_error_handler() will perform a standard error handling sequenceto resurect failed devices, detach lost devices and add new devices (if any).This function will call the various reset operations for a port, as needed.These operations are as follows.

The ‘prereset’ operation (which may be NULL) is called during an EH reset,before any other action is taken.
The ‘postreset’ hook (which may be NULL) is called after the EH reset isperformed. Based on existing conditions, severity of the problem, and hardwarecapabilities,
Either the ‘softreset’ operation or the ‘hardreset’ operation will be calledto perform the low-level EH reset. If both operations are defined,‘hardreset’ is preferred and used. If both are not defined, no low-level resetis performed and EH assumes that an ATA class device is connected through thelink.

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.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 (SCSI EH) 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

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.

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.

DMA memory is unmapped.
ATA_QCFLAG_ACTIVE is cleared from qc->flags.
qc->complete_fn callback is invoked. If the return value of thecallback is not zero. Completion is short circuited andata_qc_complete() returns.
__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 will check if a qc is activeand has not failed yet. Such a qc will be marked with AC_ERR_TIMEOUT such thatEH will know to handle it later. Then it calls low level libata driver’serror_handler() callback.

When theerror_handler() callback is invoked it 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¶

structata_link*ata_link_next(structata_link*link,structata_port*ap,enumata_link_iter_modemode)¶: 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_*

Description

LOCKING:Host lock or EH context.

Return

Pointer to the next link.

structata_device*ata_dev_next(structata_device*dev,structata_link*link,enumata_dev_iter_modemode)¶: 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_*

Description

LOCKING:Host lock or EH context.

Return

Pointer to the next device.

intatapi_cmd_type(u8opcode)¶: Determine ATAPI command type from SCSI opcode

Parameters

u8opcode: SCSI opcode

Description

Determine ATAPI command type fromopcode.
LOCKING:None.

Return

ATAPI_{READ|WRITE|READ_CD|PASS_THRU|MISC}

unsignedintata_pack_xfermask(unsignedintpio_mask,unsignedintmwdma_mask,unsignedintudma_mask)¶: Pack pio, mwdma and udma masks into xfer_mask

Parameters

unsignedintpio_mask: pio_mask
unsignedintmwdma_mask: mwdma_mask
unsignedintudma_mask: udma_mask

Description

Packpio_mask,mwdma_mask andudma_mask into a singleunsigned int xfer_mask.
LOCKING:None.

Return

Packed xfer_mask.

u8ata_xfer_mask2mode(unsignedintxfer_mask)¶: Find matching XFER_* for the given xfer_mask

Parameters

unsignedintxfer_mask: xfer_mask of interest

Description

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

Return

Matching XFER_* value, 0xff if no match found.

unsignedintata_xfer_mode2mask(u8xfer_mode)¶: Find matching xfer_mask for XFER_*

Parameters

u8xfer_mode: XFER_* of interest

Description

Return matching xfer_mask forxfer_mode.
LOCKING:None.

Return

Matching xfer_mask, 0 if no match found.

intata_xfer_mode2shift(u8xfer_mode)¶: Find matching xfer_shift for XFER_*

Parameters

u8xfer_mode: XFER_* of interest

Description

Return matching xfer_shift forxfer_mode.
LOCKING:None.

Return

Matching xfer_shift, -1 if no match found.

constchar*ata_mode_string(unsignedintxfer_mask)¶: convert xfer_mask to string

Parameters

unsignedintxfer_mask: mask of bits supported; only highest bit counts.

Description

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>”.

unsignedintata_dev_classify(conststructata_taskfile*tf)¶: determine device type based on ATA-spec signature

Parameters

conststructata_taskfile*tf: ATA taskfile register set for device to be identified

Description

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(constu16*id,unsignedchar*s,unsignedintofs,unsignedintlen)¶: 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.

Description

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(constu16*id,unsignedchar*s,unsignedintofs,unsignedintlen)¶: 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.

Description

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.

unsignedintata_id_xfermask(constu16*id)¶: Compute xfermask from the given IDENTIFY data

Parameters

constu16*id: IDENTIFY data to compute xfer mask from

Description

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

unsignedintata_pio_need_iordy(conststructata_device*adev)¶: check if iordy needed

Parameters

conststructata_device*adev: ATA device

Description

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

unsignedintata_do_dev_read_id(structata_device*dev,structata_taskfile*tf,__le16*id)¶: default ID read method

Parameters

structata_device*dev: device
structata_taskfile*tf: proposed taskfile
__le16*id: data buffer

Description

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(structata_port*ap)¶: return 40 wire cable type

Parameters

structata_port*ap: port

Description

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

intata_cable_80wire(structata_port*ap)¶: return 80 wire cable type

Parameters

structata_port*ap: port

Description

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

intata_cable_unknown(structata_port*ap)¶: return unknown PATA cable.

Parameters

structata_port*ap: port

Description

Helper method for drivers which have no PATA cable detection.

intata_cable_ignore(structata_port*ap)¶: return ignored PATA cable.

Parameters

structata_port*ap: port

Description

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

intata_cable_sata(structata_port*ap)¶: return SATA cable type

Parameters

structata_port*ap: port

Description

Helper method for drivers which have SATA cables

structata_device*ata_dev_pair(structata_device*adev)¶: return other device on cable

Parameters

structata_device*adev: device

Description

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

intata_set_mode(structata_link*link,structata_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

Description

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(structata_link*link,unsignedlongdeadline,int(*check_ready)(structata_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(*check_ready)(structata_link*link): callback to check link readiness

Description

Wait forlink to become ready after reset.
LOCKING:EH context.

Return

0 iflink is ready beforedeadline; otherwise, -errno.

intata_std_prereset(structata_link*link,unsignedlongdeadline)¶: prepare for reset

Parameters

structata_link*link: ATA link to be reset
unsignedlongdeadline: deadline jiffies for the operation

Description

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

Always 0.

voidata_std_postreset(structata_link*link,unsignedint*classes)¶: standard postreset callback

Parameters

structata_link*link: the target ata_link
unsignedint*classes: classes of attached devices

Description

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)

unsignedintata_dev_set_feature(structata_device*dev,u8subcmd,u8action)¶: Issue SET FEATURES

Parameters

structata_device*dev: Device to which command will be sent
u8subcmd: The SET FEATURES subcommand to be sent
u8action: The sector count represents a subcommand specific action

Description

Issue SET FEATURES command to devicedev on portap with sector count
LOCKING:PCI/etc. bus probe sem.

Return

0 on success, AC_ERR_* mask otherwise.

intata_std_qc_defer(structata_queued_cmd*qc)¶: Check whether a qc needs to be deferred

Parameters

structata_queued_cmd*qc: ATA command in question

Description

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(structata_queued_cmd*qc)¶: Complete an active ATA command

Parameters

structata_queued_cmd*qc: Command to complete

Description

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(structata_port*ap)¶: get bitmask of active qcs

Parameters

structata_port*ap: port in question

Description

LOCKING:spin_lock_irqsave(host lock)

Return

Bitmask of active qcs

boolata_link_online(structata_link*link)¶: test whether the given link is online

Parameters

structata_link*link: ATA link to test

Description

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(structata_link*link)¶: test whether the given link is offline

Parameters

structata_link*link: ATA link to test

Description

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.

voidata_host_suspend(structata_host*host,pm_message_tmesg)¶: suspend host

Parameters

structata_host*host: host to suspend
pm_message_tmesg: PM message

Description

Suspendhost. Actual operation is performed by port suspend.

voidata_host_resume(structata_host*host)¶: resume host

Parameters

structata_host*host: host to resume

Description

Resumehost. Actual operation is performed by port resume.

structata_port*ata_port_alloc(structata_host*host)¶: allocate and initialize basic ATA port resources

Parameters

structata_host*host: ATA host this allocated port belongs to

Description

Allocate and initialize basic ATA port resources.
LOCKING:Inherited from calling layer (may sleep).

Return

Allocate ATA port on success, NULL on failure.

structata_host*ata_host_alloc(structdevice*dev,intn_ports)¶: allocate and init basic ATA host resources

Parameters

structdevice*dev: generic device this host is associated with
intn_ports: the number of ATA ports associated with this host

Description

Allocate and initialize basic ATA host resources. LLD callsthis function to allocate a host, initializes it fully andattaches it usingata_host_register().
LOCKING:Inherited from calling layer (may sleep).

Return

Allocate ATA host on success, NULL on failure.

structata_host*ata_host_alloc_pinfo(structdevice*dev,conststructata_port_info*const*ppi,intn_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

Description

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.
LOCKING:Inherited from calling layer (may sleep).

Return

Allocate ATA host on success, NULL on failure.

intata_host_start(structata_host*host)¶: start and freeze ports of an ATA host

Parameters

structata_host*host: ATA host to start ports for

Description

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 is not initialized yet, it is 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(structata_host*host,structdevice*dev,structata_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(structata_host*host,conststructscsi_host_template*sht)¶: register initialized ATA host

Parameters

structata_host*host: ATA host to register
conststructscsi_host_template*sht: template for SCSI host

Description

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(structata_host*host,intirq,irq_handler_tirq_handler,unsignedlongirq_flags,conststructscsi_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
conststructscsi_host_template*sht: scsi_host_template to use when registering the host

Description

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(structata_host*host)¶: Detach all ports of an ATA host

Parameters

structata_host*host: Host to detach

Description

Detach all ports ofhost.
LOCKING:Kernel thread context (may sleep).

voidata_pci_remove_one(structpci_dev*pdev)¶: PCI layer callback for device removal

Parameters

structpci_dev*pdev: PCI device that was removed

Description

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).

voidata_platform_remove_one(structplatform_device*pdev)¶: Platform layer callback for device removal

Parameters

structplatform_device*pdev: Platform device that was removed

Description

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(structata_port*ap,unsignedintmsecs)¶: ATA EH owner aware msleep

Parameters

structata_port*ap: ATA port to attribute the sleep to
unsignedintmsecs: duration to sleep in milliseconds

Description

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(structata_port*ap,void__iomem*reg,u32mask,u32val,unsignedintinterval,unsignedinttimeout)¶: 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
unsignedintinterval: polling interval in milliseconds
unsignedinttimeout: timeout in milliseconds

Description

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¶

structata_link*ata_dev_phys_link(structata_device*dev)¶: find physical link for a device

Parameters

structata_device*dev: ATA device to look up physical link for

Description

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(structata_port*ap)¶: force cable type according to libata.force

Parameters

structata_port*ap: ATA port of interest

Description

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_pflags(structata_port*ap)¶: force port flags according to libata.force

Parameters

structata_port*ap: ATA port of interest

Description

Force port flags according to libata.force and whine about it.
LOCKING:EH context.

voidata_force_link_limits(structata_link*link)¶: force link limits according to libata.force

Parameters

structata_link*link: ATA link of interest

Description

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(structata_device*dev)¶: force xfermask according to libata.force

Parameters

structata_device*dev: ATA device of interest

Description

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_quirks(structata_device*dev)¶: force quirks according to libata.force

Parameters

structata_device*dev: ATA device of interest

Description

Force quirks 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.

boolata_set_rwcmd_protocol(structata_device*dev,structata_taskfile*tf)¶: set taskfile r/w command and protocol

Parameters

structata_device*dev: target device for the taskfile
structata_taskfile*tf: taskfile to examine and configure

Description

Examine the device configuration and tf->flags to determinethe proper read/write command and protocol to use fortf.
LOCKING:caller.

u64ata_tf_read_block(conststructata_taskfile*tf,structata_device*dev)¶: Read block address from ATA taskfile

Parameters

conststructata_taskfile*tf: ATA taskfile of interest
structata_device*dev: ATA devicetf belongs to

Description

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(structata_queued_cmd*qc,u64block,u32n_block,unsignedinttf_flags,intcdl,intclass)¶: Build ATA taskfile for given read/write request

Parameters

structata_queued_cmd*qc: Metadata associated with the taskfile to build
u64block: Block address
u32n_block: Number of blocks
unsignedinttf_flags: RW/FUA etc...
intcdl: Command duration limit index
intclass: IO priority class

Description

LOCKING:None.
Build ATA taskfile for the commandqc for read/write request describedbyblock,n_block,tf_flags andclass.
0 on success, -ERANGE if the request is too large fordev,-EINVAL if the request is invalid.

voidata_unpack_xfermask(unsignedintxfer_mask,unsignedint*pio_mask,unsignedint*mwdma_mask,unsignedint*udma_mask)¶: Unpack xfer_mask into pio, mwdma and udma masks

Parameters

unsignedintxfer_mask: xfer_mask to unpack
unsignedint*pio_mask: resulting pio_mask
unsignedint*mwdma_mask: resulting mwdma_mask
unsignedint*udma_mask: resulting udma_mask

Description

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

intata_read_native_max_address(structata_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

Description

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(structata_device*dev,u64new_sectors)¶: Set max sectors

Parameters

structata_device*dev: target device
u64new_sectors: new max sectors value to set for the device

Description

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(structata_device*dev)¶: Resize a device with an HPA set

Parameters

structata_device*dev: Device to resize

Description

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(structata_device*dev,constu16*id)¶: IDENTIFY DEVICE info debugging output

Parameters

structata_device*dev: device from which the information is fetched
constu16*id: IDENTIFY DEVICE page to dump

Description

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

unsignedintata_exec_internal(structata_device*dev,structata_taskfile*tf,constu8*cdb,enumdma_data_directiondma_dir,void*buf,unsignedintbuflen,unsignedinttimeout)¶: 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
enumdma_data_directiondma_dir: Data transfer direction of the command
void*buf: Data buffer of the command
unsignedintbuflen: Length of data buffer
unsignedinttimeout: Timeout in msecs (0 for default)

Description

Executes libata internal command with timeout.tf containsthe command on entry and the result on return. Timeout and errorconditions are reported via the return value. No recovery actionis taken after a command times out. It is the 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

u32ata_pio_mask_no_iordy(conststructata_device*adev)¶: Return the non IORDY mask

Parameters

conststructata_device*adev: ATA device

Description

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

intata_dev_read_id(structata_device*dev,unsignedint*p_class,unsignedintflags,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

Description

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.

voidata_dev_power_set_standby(structata_device*dev)¶: Set a device power mode to standby

Parameters

structata_device*dev: target device

Description

Issue a STANDBY IMMEDIATE command to set a device power mode to standby.For an HDD device, this spins down the disks.
LOCKING:Kernel thread context (may sleep).

voidata_dev_power_set_active(structata_device*dev)¶: Set a device power mode to active

Parameters

structata_device*dev: target device

Description

Issue a VERIFY command to enter to ensure that the device is in theactive power mode. For a spun-down HDD (standby or idle power mode),the VERIFY command will complete after the disk spins up.
LOCKING:Kernel thread context (may sleep).

unsignedintata_read_log_page(structata_device*dev,u8log,u8page,void*buf,unsignedintsectors)¶: 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

Description

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(structata_device*dev)¶: Configure the specified ATA/ATAPI device

Parameters

structata_device*dev: Target device to configure

Description

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

voidsata_print_link_status(structata_link*link)¶: Print SATA link status

Parameters

structata_link*link: SATA link to printk link status about

Description

This function prints link speed and status of a SATA link.
LOCKING:None.

u8ata_timing_cycle2mode(unsignedintxfer_shift,intcycle)¶: find xfer mode for the specified cycle duration

Parameters

unsignedintxfer_shift: ATA_SHIFT_* value for transfer type to examine.
intcycle: cycle duration in ns

Description

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(structata_device*dev,unsignedintsel)¶: adjust dev xfer masks downward

Parameters

structata_device*dev: Device to adjust xfer masks
unsignedintsel: ATA_DNXFER_* selector

Description

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(structata_link*link,unsignedlongdeadline,int(*check_ready)(structata_link*link))¶: wait for link to become ready

Parameters

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

Description

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(structata_device*dev,unsignedintnew_class,constu16*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

Description

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(structata_device*dev,unsignedintreadid_flags)¶: Re-read IDENTIFY data

Parameters

structata_device*dev: target ATA device
unsignedintreadid_flags: read ID flags

Description

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(structata_device*dev,unsignedintnew_class,unsignedintreadid_flags)¶: Revalidate ATA device

Parameters

structata_device*dev: device to revalidate
unsignedintnew_class: new class code
unsignedintreadid_flags: read ID flags

Description

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(structata_device*dev)¶: check drive side detection

Parameters

structata_device*dev: device

Description

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

intcable_is_40wire(structata_port*ap)¶: 40/80/SATA decider

Parameters

structata_port*ap: port to consider

Description

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(structata_device*dev)¶: Compute supported xfermask of the given device

Parameters

structata_device*dev: Device to compute xfermask for

Description

Compute supported xfermask ofdev and store it indev->*_mask. This function is responsible for applying allknown limits including host controller limits, device quirks, etc...
LOCKING:None.

unsignedintata_dev_set_xfermode(structata_device*dev)¶: Issue SET FEATURES - XFER MODE command

Parameters

structata_device*dev: Device to which command will be sent

Description

Issue SET FEATURES - XFER MODE command to devicedevon portap.
LOCKING:PCI/etc. bus probe sem.

Return

0 on success, AC_ERR_* mask otherwise.

unsignedintata_dev_init_params(structata_device*dev,u16heads,u16sectors)¶: 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)

Description

LOCKING:Kernel thread context (may sleep)

Return

0 on success, AC_ERR_* mask otherwise.

intatapi_check_dma(structata_queued_cmd*qc)¶: Check whether ATAPI DMA can be supported

Parameters

structata_queued_cmd*qc: Metadata associated with taskfile to check

Description

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 usednonzero otherwise

voidata_sg_init(structata_queued_cmd*qc,structscatterlist*sg,unsignedintn_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.

Description

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(structata_queued_cmd*qc)¶: Unmap DMA memory associated with command

Parameters

structata_queued_cmd*qc: Command containing DMA memory to be released

Description

Unmap all mapped DMA memory associated with this command.
LOCKING:spin_lock_irqsave(host lock)

intata_sg_setup(structata_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.

Description

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,unsignedintbuf_words)¶: swap halves of 16-bit words in place

Parameters

u16*buf: Buffer to swap
unsignedintbuf_words: Number of 16-bit words in buffer.

Description

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.

voidata_qc_free(structata_queued_cmd*qc)¶: free unused ata_queued_cmd

Parameters

structata_queued_cmd*qc: Command to complete

Description

Designed to free unused ata_queued_cmd objectin case something prevents using it.
LOCKING:spin_lock_irqsave(host lock)

voidata_qc_issue(structata_queued_cmd*qc)¶: issue taskfile to device

Parameters

structata_queued_cmd*qc: command to issue to device

Description

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(structata_link*link)¶: test whether the given link is online

Parameters

structata_link*link: ATA link to test

Description

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(structata_link*link)¶: test whether the given link is offline

Parameters

structata_link*link: ATA link to test

Description

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(structata_device*dev)¶: Initialize an ata_device structure

Parameters

structata_device*dev: Device structure to initialize

Description

Initializedev in preparation for probing.
LOCKING:Inherited from caller.

voidata_link_init(structata_port*ap,structata_link*link,intpmp)¶: 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

Description

Initializelink.
LOCKING:Kernel thread context (may sleep)

intsata_link_init_spd(structata_link*link)¶: Initialize link->sata_spd_limit

Parameters

structata_link*link: Link to configure sata_spd_limit for

Description

Initializelink->[hw_]sata_spd_limit to the currentlyconfigured value.
LOCKING:Kernel thread context (may sleep).

Return

0 on success, -errno on failure.

voidata_finalize_port_ops(structata_port_operations*ops)¶: finalize ata_port_operations

Parameters

structata_port_operations*ops: ata_port_operations to finalize

Description

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_dev_free_resources(structata_device*dev)¶: Free a device resources

Parameters

structata_device*dev: Target ATA device

Description

Free resources allocated to support a device features.
LOCKING:Kernel thread context (may sleep).

voidata_port_detach(structata_port*ap)¶: Detach ATA port in preparation of device removal

Parameters

structata_port*ap: ATA port to be detached

Description

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(structata_eh_info*ehi,constchar*fmt,...)¶: push error description without adding separator

Parameters

structata_eh_info*ehi: target EHI
constchar*fmt: printf format string
...: variable arguments

Description

Format string according tofmt and append it toehi->desc.
LOCKING:spin_lock_irqsave(host lock)

voidata_ehi_push_desc(structata_eh_info*ehi,constchar*fmt,...)¶: push error description with separator

Parameters

structata_eh_info*ehi: target EHI
constchar*fmt: printf format string
...: variable arguments

Description

Format string according tofmt and append it toehi->desc.Ifehi->desc is not empty, “, “ is added in-between.
LOCKING:spin_lock_irqsave(host lock)

voidata_ehi_clear_desc(structata_eh_info*ehi)¶: clean error description

Parameters

structata_eh_info*ehi: target EHI

Description

Clearehi->desc.
LOCKING:spin_lock_irqsave(host lock)

voidata_port_desc(structata_port*ap,constchar*fmt,...)¶: append port description

Parameters

structata_port*ap: target ATA port
constchar*fmt: printf format string
...: variable arguments

Description

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.

voidata_port_pbar_desc(structata_port*ap,intbar,ssize_toffset,constchar*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

Description

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.

unsignedintata_internal_cmd_timeout(structata_device*dev,u8cmd)¶: determine timeout for an internal command

Parameters

structata_device*dev: target device
u8cmd: internal command to be issued

Description

Determine timeout for internal commandcmd fordev.
LOCKING:EH context.

Return

Determined timeout.

voidata_internal_cmd_timed_out(structata_device*dev,u8cmd)¶: notification for internal command timeout

Parameters

structata_device*dev: target device
u8cmd: internal command which timed out

Description

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(structata_port*ap)¶: acquire EH ownership

Parameters

structata_port*ap: ATA port to acquire EH ownership for

Description

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(structata_port*ap)¶: release EH ownership

Parameters

structata_port*ap: ATA port to release EH ownership for

Description

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

voidata_scsi_error(structScsi_Host*host)¶: SCSI layer error handler callback

Parameters

structScsi_Host*host: SCSI host on which error occurred

Description

Handles SCSI-layer-thrown error events.
LOCKING:Inherited from SCSI layer (none, can sleep)

Return

Zero.

voidata_scsi_cmd_error_handler(structScsi_Host*host,structata_port*ap,structlist_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(structScsi_Host*host,structata_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(structata_port*ap)¶: Wait for the currently pending EH to complete

Parameters

structata_port*ap: Port to wait EH for

Description

Wait until the currently pending EH is complete.
LOCKING:Kernel thread context (may sleep).

voidata_eh_set_pending(structata_port*ap,boolfastdrain)¶: set ATA_PFLAG_EH_PENDING and activate fast drain

Parameters

structata_port*ap: target ATA port
boolfastdrain: activate fast drain

Description

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(structata_queued_cmd*qc)¶: schedule qc for error handling

Parameters

structata_queued_cmd*qc: command to schedule error handling for

Description

Schedule error handling forqc. EH will kick in as soon asother commands are drained.
LOCKING:spin_lock_irqsave(host lock)

voidata_std_sched_eh(structata_port*ap)¶: non-libsas ata_ports issue eh with this common routine

Parameters

structata_port*ap: ATA port to schedule EH for

Description

LOCKING: inherited from ata_port_schedule_ehspin_lock_irqsave(host lock)

voidata_std_end_eh(structata_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(structata_port*ap)¶: schedule error handling without a qc

Parameters

structata_port*ap: ATA port to schedule EH for

Description

Schedule error handling forap. EH will kick in as soon asall commands are drained.
LOCKING:spin_lock_irqsave(host lock)

intata_link_abort(structata_link*link)¶: abort all qc’s on the link

Parameters

structata_link*link: ATA link to abort qc’s for

Description

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(structata_port*ap)¶: abort all qc’s on the port

Parameters

structata_port*ap: ATA port to abort qc’s for

Description

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(structata_port*ap)¶: freeze port

Parameters

structata_port*ap: ATA port to freeze

Description

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(structata_port*ap)¶: abort & freeze port

Parameters

structata_port*ap: ATA port to freeze

Description

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(structata_port*ap)¶: EH helper to freeze port

Parameters

structata_port*ap: ATA port to freeze

Description

Freezeap.
LOCKING:None.

voidata_eh_thaw_port(structata_port*ap)¶: EH helper to thaw port

Parameters

structata_port*ap: ATA port to thaw

Description

Thaw frozen portap.
LOCKING:None.

voidata_eh_qc_complete(structata_queued_cmd*qc)¶: Complete an active ATA command from EH

Parameters

structata_queued_cmd*qc: Command to complete

Description

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

voidata_eh_qc_retry(structata_queued_cmd*qc)¶: Tell midlayer to retry an ATA command after EH

Parameters

structata_queued_cmd*qc: Command to retry

Description

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(structata_device*dev)¶: disable ATA device

Parameters

structata_device*dev: ATA device to disable

Description

Disabledev.
Locking:EH context.

voidata_eh_detach_dev(structata_device*dev)¶: detach ATA device

Parameters

structata_device*dev: ATA device to detach

Description

Detachdev.
LOCKING:None.

voidata_eh_about_to_do(structata_link*link,structata_device*dev,unsignedintaction)¶: 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

Description

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

voidata_eh_done(structata_link*link,structata_device*dev,unsignedintaction)¶: 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

Description

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

constchar*ata_err_string(unsignedinterr_mask)¶: convert err_mask to descriptive string

Parameters

unsignedinterr_mask: error mask to convert to string

Description

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

Return

Descriptive string forerr_mask

unsignedintatapi_eh_tur(structata_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

Description

Perform ATAPI TEST_UNIT_READY.
LOCKING:EH context (may sleep).

Return

0 on success, AC_ERR_* mask on failure.

enumscsi_dispositionata_eh_decide_disposition(structata_queued_cmd*qc)¶: Disposition a qc based on sense data

Parameters

structata_queued_cmd*qc: qc to examine

Description

For a regular SCSI command, the SCSI completion callback (scsi_done())will callscsi_complete(), which will callscsi_decide_disposition(),which will callscsi_check_sense().scsi_complete() finally callsscsi_finish_command(). This is fine for SCSI, since any eventual sensedata is usually returned in the completion itself (without invoking SCSIEH). However, for a QC, we always need to fetch the sense dataexplicitly using SCSI EH.
A command that is completed via SCSI EH will instead be completed usingscsi_eh_flush_done_q(), which will callscsi_finish_command() directly(without ever callingscsi_check_sense()).
For a command that went through SCSI EH, it is the responsibility of theSCSI EH strategy handler to callscsi_decide_disposition(), see e.g. howscsi_eh_get_sense() callsscsi_decide_disposition() for SCSI LLDDs thatdo not get the sense data as part of the completion.
Thus, for QC commands that went via SCSI EH, we need to callscsi_check_sense() ourselves, similar to howscsi_eh_get_sense() callsscsi_decide_disposition(), which callsscsi_check_sense(), in order toset the correct SCSI ML byte (if any).
LOCKING:EH context.

Return

SUCCESS or FAILED or NEEDS_RETRY or ADD_TO_MLQUEUE

boolata_eh_request_sense(structata_queued_cmd*qc)¶: perform REQUEST_SENSE_DATA_EXT

Parameters

structata_queued_cmd*qc: qc to perform REQUEST_SENSE_SENSE_DATA_EXT to

Description

Perform REQUEST_SENSE_DATA_EXT after the device reported CHECKSENSE. This function is an EH helper.
LOCKING:Kernel thread context (may sleep).

Return

true if sense data could be fetched, false otherwise.

unsignedintatapi_eh_request_sense(structata_device*dev,u8*sense_buf,u8dfl_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

Description

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(structata_link*link)¶: analyze SError for a failed port

Parameters

structata_link*link: ATA link to analyze SError for

Description

Analyze SError if available and further determine cause offailure.
LOCKING:None.

unsignedintata_eh_analyze_tf(structata_queued_cmd*qc)¶: analyze taskfile of a failed qc

Parameters

structata_queued_cmd*qc: qc to analyze

Description

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

unsignedintata_eh_speed_down_verdict(structata_device*dev)¶: Determine speed down verdict

Parameters

structata_device*dev: Device of interest

Description

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_HSMTIMEOUT 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_DOWNSpeed 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.
If more than one DUBIOUS_ATA_BUS or DUBIOUS_TOUT_HSM errorsoccurred during last 5 mins, SPEED_DOWN and FALLBACK_TO_PIO.
If more than one DUBIOUS_TOUT_HSM or DUBIOUS_UNK_DEV errorsoccurred during last 5 mins, NCQ_OFF.
If more than 8 ATA_BUS, TOUT_HSM or UNK_DEV errorsoccurred during last 5 mins, FALLBACK_TO_PIO
If more than 3 TOUT_HSM or UNK_DEV errors occurredduring last 10 mins, NCQ_OFF.
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.

unsignedintata_eh_speed_down(structata_device*dev,unsignedinteflags,unsignedinterr_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

Description

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(structata_queued_cmd*qc)¶: analyze error and decide whether to retry

Parameters

structata_queued_cmd*qc: qc to possibly retry

Description

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(structata_queued_cmd*qc)¶: check if we need to be quiet about a command error

Parameters

structata_queued_cmd*qc: qc to check

Description

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

intata_eh_link_set_lpm(structata_link*link,enumata_lpm_policypolicy,structata_device**r_failed_dev)¶: configure SATA interface power management

Parameters

structata_link*link: link to configure
enumata_lpm_policypolicy: the link power management policy
structata_device**r_failed_dev: out parameter for failed device

Description

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.

voidata_eh_link_autopsy(structata_link*link)¶: analyze error and determine recovery action

Parameters

structata_link*link: host link to perform autopsy on

Description

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(structata_port*ap)¶: analyze error and determine recovery action

Parameters

structata_port*ap: host port to perform autopsy on

Description

Analyze all links ofap and determine why they failed andwhich recovery actions are needed.
LOCKING:Kernel thread context (may sleep).

constchar*ata_get_cmd_name(u8command)¶: get name for ATA command

Parameters

u8command: ATA command code to get name for

Description

Return a textual name of the given command or “unknown”
LOCKING:None

voidata_eh_link_report(structata_link*link)¶: report error handling to user

Parameters

structata_link*link: ATA link EH is going on

Description

Report EH to user.
LOCKING:None.

voidata_eh_report(structata_port*ap)¶: report error handling to user

Parameters

structata_port*ap: ATA port to report EH about

Description

Report EH to user.
LOCKING:None.

intata_eh_set_mode(structata_link*link,structata_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

Description

Set ATA device disk transfer mode (PIO3, UDMA6, etc.). Ifata_eh_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(structata_device*dev)¶: Clear ATAPI UNIT ATTENTION after reset

Parameters

structata_device*dev: ATAPI device to clear UA for

Description

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(structata_device*dev)¶: Retry FLUSH if necessary

Parameters

structata_device*dev: ATA device which may need FLUSH retry

Description

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_recover(structata_port*ap,structata_reset_operations*reset_ops,structata_link**r_failed_link)¶: recover host port after error

Parameters

structata_port*ap: host port to recover
structata_reset_operations*reset_ops: The set of reset operations to use
structata_link**r_failed_link: out parameter for failed link

Description

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(structata_port*ap)¶: finish up EH

Parameters

structata_port*ap: host port to finish EH for

Description

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

voidata_std_error_handler(structata_port*ap)¶: standard error handler

Parameters

structata_port*ap: host port to handle error for

Description

Perform standard error handling sequence.
LOCKING:Kernel thread context (may sleep).

voidata_eh_handle_port_suspend(structata_port*ap)¶: perform port suspend operation

Parameters

structata_port*ap: port to suspend

Description

Suspendap.
LOCKING:Kernel thread context (may sleep).

voidata_eh_handle_port_resume(structata_port*ap)¶: perform port resume operation

Parameters

structata_port*ap: port to resume

Description

Resumeap.
LOCKING:Kernel thread context (may sleep).

libata SCSI translation/emulation¶

intata_std_bios_param(structscsi_device*sdev,structgendisk*unused,sector_tcapacity,intgeom[])¶: generic bios head/sector/cylinder calculator used by sd.

Parameters

structscsi_device*sdev: SCSI device for which BIOS geometry is to be determined
structgendisk*unused: gendisk associated withsdev
sector_tcapacity: capacity of SCSI device
intgeom[]: location to which geometry will be output

Description

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(structscsi_device*sdev)¶: unlock native capacity

Parameters

structscsi_device*sdev: SCSI device to adjust device capacity for

Description

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(structrequest*rq)¶: Check whether data transfer may overflow

Parameters

structrequest*rq: request to be checked

Description

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_sdev_init(structscsi_device*sdev)¶: Early setup of SCSI device

Parameters

structscsi_device*sdev: SCSI device to examine

Description

This is called fromscsi_alloc_sdev() when the scsi deviceassociated with an ATA device is scanned on a port.
LOCKING:Defined by SCSI layer. We don’t really care.

intata_scsi_sdev_configure(structscsi_device*sdev,structqueue_limits*lim)¶: Set SCSI device attributes

Parameters

structscsi_device*sdev: SCSI device to examine
structqueue_limits*lim: queue limits

Description

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_sdev_destroy(structscsi_device*sdev)¶: SCSI device is about to be destroyed

Parameters

structscsi_device*sdev: SCSI device to be destroyed

Description

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(structScsi_Host*shost,structscsi_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

Description

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.

voidata_scsi_set_passthru_sense_fields(structata_queued_cmd*qc)¶: Set ATA fields in sense buffer

Parameters

structata_queued_cmd*qc: ATA PASS-THROUGH command.

Description

Populates “ATA Status Return sense data descriptor” / “Fixed formatsense data” with ATA taskfile fields.
LOCKING:None.

intata_get_identity(structata_port*ap,structscsi_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

Description

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

Return

Zero on success, negative errno on error.

intata_cmd_ioctl(structscsi_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

Description

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

Return

Zero on success, negative errno on error.

intata_task_ioctl(structscsi_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

Description

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

Return

Zero on success, negative errno on error.

structata_queued_cmd*ata_scsi_qc_new(structata_device*dev,structscsi_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

Description

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_to_sense_error(u8drv_stat,u8drv_err,u8*sk,u8*asc,u8*ascq)¶: convert ATA error to SCSI error

Parameters

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

Description

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(structata_queued_cmd*qc)¶: generate a SCSI fixed sense block

Parameters

structata_queued_cmd*qc: Command that we are erroring out

Description

Generate sense block for a failed ATA commandqc.
LOCKING:None.

unsignedintata_scsi_start_stop_xlat(structata_queued_cmd*qc)¶: Translate SCSI START STOP UNIT command

Parameters

structata_queued_cmd*qc: Storage for translated ATA taskfile

Description

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.

unsignedintata_scsi_flush_xlat(structata_queued_cmd*qc)¶: Translate SCSI SYNCHRONIZE CACHE command

Parameters

structata_queued_cmd*qc: Storage for translated ATA taskfile

Description

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(constu8*cdb,u64*plba,u32*plen)¶: Get LBA and transfer length

Parameters

constu8*cdb: SCSI command to translate
u64*plba: the LBA
u32*plen: the transfer length

Description

Calculate LBA and transfer length for 6-byte commands.

voidscsi_10_lba_len(constu8*cdb,u64*plba,u32*plen)¶: Get LBA and transfer length

Parameters

constu8*cdb: SCSI command to translate
u64*plba: the LBA
u32*plen: the transfer length

Description

Calculate LBA and transfer length for 10-byte commands.

voidscsi_16_lba_len(constu8*cdb,u64*plba,u32*plen)¶: Get LBA and transfer length

Parameters

constu8*cdb: SCSI command to translate
u64*plba: the LBA
u32*plen: the transfer length

Description

Calculate LBA and transfer length for 16-byte commands.

intscsi_dld(constu8*cdb)¶: Get duration limit descriptor index

Parameters

constu8*cdb: SCSI command to translate

Description

Returns the dld bits indicating the index of a command duration limitdescriptor.

unsignedintata_scsi_verify_xlat(structata_queued_cmd*qc)¶: Translate SCSI VERIFY command into an ATA one

Parameters

structata_queued_cmd*qc: Storage for translated ATA taskfile

Description

Converts SCSI VERIFY command to an ATA READ VERIFY command.
LOCKING:spin_lock_irqsave(host lock)

Return

Zero on success, non-zero on error.

unsignedintata_scsi_rw_xlat(structata_queued_cmd*qc)¶: Translate SCSI r/w command into an ATA one

Parameters

structata_queued_cmd*qc: Storage for translated ATA taskfile

Description

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(structata_device*dev,structscsi_cmnd*cmd,ata_xlat_func_txlat_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

Description

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.

voidata_scsi_rbuf_fill(structata_device*dev,structscsi_cmnd*cmd,unsignedint(*actor)(structata_device*dev,structscsi_cmnd*cmd,u8*rbuf))¶: wrapper for SCSI command simulators

Parameters

structata_device*dev: Target device.
structscsi_cmnd*cmd: SCSI command of interest.
unsignedint(*actor)(structata_device*dev,structscsi_cmnd*cmd,u8*rbuf): Callback hook for desired SCSI command simulator

Description

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)

unsignedintata_scsiop_inq_std(structata_device*dev,structscsi_cmnd*cmd,u8*rbuf)¶: Simulate standard INQUIRY command

Parameters

structata_device*dev: Target device.
structscsi_cmnd*cmd: SCSI command of interest.
u8*rbuf: Response buffer, to which simulated SCSI cmd output is sent.

Description

Returns standard device identification data associatedwith non-VPD INQUIRY command output.
LOCKING:spin_lock_irqsave(host lock)

unsignedintata_scsiop_inq_00(structata_device*dev,structscsi_cmnd*cmd,u8*rbuf)¶: Simulate INQUIRY VPD page 0, list of pages

Parameters

structata_device*dev: Target device.
structscsi_cmnd*cmd: SCSI command of interest.
u8*rbuf: Response buffer, to which simulated SCSI cmd output is sent.

Description

Returns list of inquiry VPD pages available.
LOCKING:spin_lock_irqsave(host lock)

unsignedintata_scsiop_inq_80(structata_device*dev,structscsi_cmnd*cmd,u8*rbuf)¶: Simulate INQUIRY VPD page 80, device serial number

Parameters

structata_device*dev: Target device.
structscsi_cmnd*cmd: SCSI command of interest.
u8*rbuf: Response buffer, to which simulated SCSI cmd output is sent.

Description

Returns ATA device serial number.
LOCKING:spin_lock_irqsave(host lock)

unsignedintata_scsiop_inq_83(structata_device*dev,structscsi_cmnd*cmd,u8*rbuf)¶: Simulate INQUIRY VPD page 83, device identity

Parameters

structata_device*dev: Target device.
structscsi_cmnd*cmd: SCSI command of interest.
u8*rbuf: Response buffer, to which simulated SCSI cmd output is sent.

Description

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)

unsignedintata_scsiop_inq_89(structata_device*dev,structscsi_cmnd*cmd,u8*rbuf)¶: Simulate INQUIRY VPD page 89, ATA info

Parameters

structata_device*dev: Target device.
structscsi_cmnd*cmd: SCSI command of interest.
u8*rbuf: Response buffer, to which simulated SCSI cmd output is sent.

Description

Yields SAT-specified ATA VPD page.
LOCKING:spin_lock_irqsave(host lock)

unsignedintata_scsiop_inq_b0(structata_device*dev,structscsi_cmnd*cmd,u8*rbuf)¶: Simulate INQUIRY VPD page B0, Block Limits

Parameters

structata_device*dev: Target device.
structscsi_cmnd*cmd: SCSI command of interest.
u8*rbuf: Response buffer, to which simulated SCSI cmd output is sent.

Description

Return data for the VPD page B0h (Block Limits).
LOCKING:spin_lock_irqsave(host lock)

unsignedintata_scsiop_inq_b1(structata_device*dev,structscsi_cmnd*cmd,u8*rbuf)¶: Simulate INQUIRY VPD page B1, Block Device Characteristics

Parameters

structata_device*dev: Target device.
structscsi_cmnd*cmd: SCSI command of interest.
u8*rbuf: Response buffer, to which simulated SCSI cmd output is sent.

Description

Return data for the VPD page B1h (Block Device Characteristics).
LOCKING:spin_lock_irqsave(host lock)

unsignedintata_scsiop_inq_b2(structata_device*dev,structscsi_cmnd*cmd,u8*rbuf)¶: Simulate INQUIRY VPD page B2, Logical Block Provisioning

Parameters

structata_device*dev: Target device.
structscsi_cmnd*cmd: SCSI command of interest.
u8*rbuf: Response buffer, to which simulated SCSI cmd output is sent.

Description

Return data for the VPD page B2h (Logical Block Provisioning).
LOCKING:spin_lock_irqsave(host lock)

unsignedintata_scsiop_inq_b6(structata_device*dev,structscsi_cmnd*cmd,u8*rbuf)¶: Simulate INQUIRY VPD page B6, Zoned Block Device Characteristics

Parameters

structata_device*dev: Target device.
structscsi_cmnd*cmd: SCSI command of interest.
u8*rbuf: Response buffer, to which simulated SCSI cmd output is sent.

Description

Return data for the VPD page B2h (Zoned Block Device Characteristics).
LOCKING:spin_lock_irqsave(host lock)

unsignedintata_scsiop_inq_b9(structata_device*dev,structscsi_cmnd*cmd,u8*rbuf)¶: Simulate INQUIRY VPD page B9, Concurrent Positioning Ranges

Parameters

structata_device*dev: Target device.
structscsi_cmnd*cmd: SCSI command of interest.
u8*rbuf: Response buffer, to which simulated SCSI cmd output is sent.

Description

Return data for the VPD page B9h (Concurrent Positioning Ranges).
LOCKING:spin_lock_irqsave(host lock)

unsignedintata_scsiop_inquiry(structata_device*dev,structscsi_cmnd*cmd,u8*rbuf)¶: Simulate INQUIRY command

Parameters

structata_device*dev: Target device.
structscsi_cmnd*cmd: SCSI command of interest.
u8*rbuf: Response buffer, to which simulated SCSI cmd output is sent.

Description

Returns data associated with an INQUIRY command output.
LOCKING:spin_lock_irqsave(host lock)

voidmodecpy(u8*dest,constu8*src,intn,boolchangeable)¶: 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

Description

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

unsignedintata_msense_caching(u16*id,u8*buf,boolchangeable)¶: Simulate MODE SENSE caching info page

Parameters

u16*id: device IDENTIFY data
u8*buf: output buffer
boolchangeable: whether changeable parameters are requested

Description

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

unsignedintata_msense_control(structata_device*dev,u8*buf,u8spg,boolchangeable)¶: Simulate MODE SENSE control mode page

Parameters

structata_device*dev: ATA device of interest
u8*buf: output buffer
u8spg: sub-page code
boolchangeable: whether changeable parameters are requested

Description

Generate a generic MODE SENSE control mode page.
LOCKING:None.

unsignedintata_msense_rw_recovery(u8*buf,boolchangeable)¶: Simulate MODE SENSE r/w error recovery page

Parameters

u8*buf: output buffer
boolchangeable: whether changeable parameters are requested

Description

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

unsignedintata_scsiop_mode_sense(structata_device*dev,structscsi_cmnd*cmd,u8*rbuf)¶: Simulate MODE SENSE 6, 10 commands

Parameters

structata_device*dev: Target device.
structscsi_cmnd*cmd: SCSI command of interest.
u8*rbuf: Response buffer, to which simulated SCSI cmd output is sent.

Description

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)

unsignedintata_scsiop_read_cap(structata_device*dev,structscsi_cmnd*cmd,u8*rbuf)¶: Simulate READ CAPACITY[ 16] commands

Parameters

structata_device*dev: Target device.
structscsi_cmnd*cmd: SCSI command of interest.
u8*rbuf: Response buffer, to which simulated SCSI cmd output is sent.

Description

Simulate READ CAPACITY commands.
LOCKING:None.

unsignedintata_scsiop_report_luns(structata_device*dev,structscsi_cmnd*cmd,u8*rbuf)¶: Simulate REPORT LUNS command

Parameters

structata_device*dev: Target device.
structscsi_cmnd*cmd: SCSI command of interest.
u8*rbuf: Response buffer, to which simulated SCSI cmd output is sent.

Description

Simulate REPORT LUNS command.
LOCKING:spin_lock_irqsave(host lock)

unsignedintatapi_xlat(structata_queued_cmd*qc)¶: Initialize PACKET taskfile

Parameters

structata_queued_cmd*qc: command structure to be initialized

Description

LOCKING:spin_lock_irqsave(host lock)

Return

Zero on success, non-zero on failure.

structata_device*ata_scsi_find_dev(structata_port*ap,conststructscsi_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

Description

Given various information provided instructscsi_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.

unsignedintata_scsi_pass_thru(structata_queued_cmd*qc)¶: convert ATA pass-thru CDB to taskfile

Parameters

structata_queued_cmd*qc: command structure to be initialized

Description

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(structscsi_cmnd*cmd,u32trmax,u64sector,u32count)¶: 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.

unsignedintata_scsi_write_same_xlat(structata_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

unsignedintata_scsiop_maint_in(structata_device*dev,structscsi_cmnd*cmd,u8*rbuf)¶: Simulate a subset of MAINTENANCE_IN

Parameters

structata_device*dev: Target device.
structscsi_cmnd*cmd: SCSI command of interest.
u8*rbuf: Response buffer, to which simulated SCSI cmd output is sent.

Description

Yields a subset to satisfyscsi_report_opcode()
LOCKING:spin_lock_irqsave(host lock)

voidata_scsi_report_zones_complete(structata_queued_cmd*qc)¶: convert ATA output

Parameters

structata_queued_cmd*qc: command structure returning the data

Description

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

intata_mselect_caching(structata_queued_cmd*qc,constu8*buf,intlen,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

Description

Prepare a taskfile to modify caching information for the device.
LOCKING:None.

intata_mselect_control(structata_queued_cmd*qc,u8spg,constu8*buf,intlen,u16*fp)¶: Simulate MODE SELECT for control page

Parameters

structata_queued_cmd*qc: Storage for translated ATA taskfile
u8spg: target sub-page of the control page
constu8*buf: input buffer
intlen: number of valid bytes in the input buffer
u16*fp: out parameter for the failed field on error

Description

Prepare a taskfile to modify caching information for the device.
LOCKING:None.

unsignedintata_scsi_mode_select_xlat(structata_queued_cmd*qc)¶: Simulate MODE SELECT 6, 10 commands

Parameters

structata_queued_cmd*qc: Storage for translated ATA taskfile

Description

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)

unsignedintata_scsi_var_len_cdb_xlat(structata_queued_cmd*qc)¶: SATL variable length CDB to Handler

Parameters

structata_queued_cmd*qc: Command to be translated

Description

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(structata_device*dev,u8cmd)¶: check if SCSI to ATA translation is possible

Parameters

structata_device*dev: ATA device
u8cmd: SCSI command opcode to consider

Description

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_simulate(structata_device*dev,structscsi_cmnd*cmd)¶: simulate SCSI command on ATA device

Parameters

structata_device*dev: the target device
structscsi_cmnd*cmd: SCSI command being sent to device.

Description

Interprets and directly executes a select list of SCSI commandsthat can be handled internally.
LOCKING:spin_lock_irqsave(host lock)

boolata_scsi_offline_dev(structata_device*dev)¶: offline attached SCSI device

Parameters

structata_device*dev: ATA device to offline attached SCSI device for

Description

This function is called fromata_eh_detach_dev() and is responsible fortaking the SCSI device attached todev offline. This function iscalled with host lock which protects dev->sdev against clearing.
LOCKING:spin_lock_irqsave(host lock)

Return

true if attached SCSI device exists, false otherwise.

voidata_scsi_remove_dev(structata_device*dev)¶: remove attached SCSI device

Parameters

structata_device*dev: ATA device to remove attached SCSI device for

Description

This function is called fromata_eh_scsi_hotplug() andresponsible for removing the SCSI device attached todev.
LOCKING:Kernel thread context (may sleep).

voidata_scsi_media_change_notify(structata_device*dev)¶: send media change event

Parameters

structata_device*dev: Pointer to the disk device with media change event

Description

Tell the block layer to send a media change notificationevent.
LOCKING:spin_lock_irqsave(host lock)

voidata_scsi_hotplug(structwork_struct*work)¶: SCSI part of hotplug

Parameters

structwork_struct*work: Pointer to ATA port to perform SCSI hotplug on

Description

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(structScsi_Host*shost,unsignedintchannel,unsignedintid,u64lun)¶: 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

Description

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(structwork_struct*work)¶: initiatescsi_rescan_device()

Parameters

structwork_struct*work: Pointer to ATA port to performscsi_rescan_device()

Description

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(structata_port*ap)¶: Probe host controller cable detect info

Parameters

structata_port*ap: Port for which cable detect info is desired

Description

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(structata_link*link,unsignedlongdeadline)¶: prereset for PATA host controller

Parameters

structata_link*link: Target link
unsignedlongdeadline: deadline jiffies for the operation

Description

LOCKING:None (inherited from caller).

voidpiix_set_piomode(structata_port*ap,structata_device*adev)¶: Initialize host controller PATA PIO timings

Parameters

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

Description

Set PIO mode for device, in host controller PCI config space.
LOCKING:None (inherited from caller).

voiddo_pata_set_dmamode(structata_port*ap,structata_device*adev,intisich)¶: 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

Description

Set UDMA mode for device, in host controller PCI config space.
LOCKING:None (inherited from caller).

voidpiix_set_dmamode(structata_port*ap,structata_device*adev)¶: Initialize host controller PATA DMA timings

Parameters

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

Description

Set MW/UDMA mode for device, in host controller PCI config space.
LOCKING:None (inherited from caller).

voidich_set_dmamode(structata_port*ap,structata_device*adev)¶: Initialize host controller PATA DMA timings

Parameters

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

Description

Set MW/UDMA mode for device, in host controller PCI config space.
LOCKING:None (inherited from caller).

intpiix_check_450nx_errata(structpci_dev*ata_dev)¶: Check for problem 450NX setup

Parameters

structpci_dev*ata_dev: the PCI device to check

Description

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(structpci_dev*pdev,conststructpci_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

Description

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(structata_link*link,structata_device**r_failed)¶: wrap set_mode functions

Parameters

structata_link*link: link to set up
structata_device**r_failed: returned device when we fail

Description

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

voidsil_dev_config(structata_device*dev)¶: Apply device/host-specific errata fixups

Parameters

structata_device*dev: Device to be examined

Description

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 quirkedThe Maxtor quirk is in sil_quirks, 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).

Movatterモバイル変換

libATA Developer’s Guide¶

Introduction¶

libata Driver API¶

structata_port_operations¶

Post-IDENTIFY device configuration¶

Set PIO/DMA mode¶

Taskfile read/write¶

PIO data read/write¶

ATA command execute¶

Per-cmd ATAPI DMA capabilities filter¶

Read specific ATA shadow registers¶

Write specific ATA shadow register¶

Select ATA device on bus¶

Private tuning method¶

Control PCI IDE BMDMA engine¶

High-level taskfile hooks¶

Exception and probe handling (EH)¶

Hardware interrupt handling¶

SATA phy read/write¶

Init and shutdown¶

Error handling¶

Origins of commands¶

How commands are issued¶

How commands are processed¶

How commands are completed¶

ata_scsi_error()¶

Problems with the current EH¶

libata Library¶

libata Core Internals¶

libata SCSI translation/emulation¶

ATA errors and exceptions¶

Exception categories¶

HSM violation¶

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

ATAPI device CHECK CONDITION¶

ATA device error (NCQ)¶

ATA bus error¶

PCI bus error¶

Late completion¶

Unknown error (timeout)¶

Hotplug and power management exceptions¶

EH recovery actions¶

Clearing error condition¶

Reset¶

Reconfigure transport¶

ata_piix Internals¶

sata_sil Internals¶

Thanks¶

`structata_port_operations`¶

`ata_scsi_error()`¶