========================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================= :c:type:`struct ata_port_operations <ata_port_operations>`is 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. :c:type:`struct ata_port_operations <ata_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`` and ``dev->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) use:c:func:`ata_sff_tf_load` and :c:func:`ata_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 of:c:func:`ata_sff_data_xfer`, or :c:func:`ata_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 use:c:func:`ata_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 use:c:func:`ata_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 use :c:func:`ata_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 controller    tuning logic when a controller has quirks. Replacing the default    tuning logic in that case would bypass handling for drive and bridge    quirks that may be important to data reliability. If a controller    needs to filter the mode selection it should use the mode_filter    hook 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 use :c:func:`ata_bmdma_setup` for the:c:func:`bmdma_setup` hook. :c:func:`ata_bmdma_setup` will write the pointerto the PRD table to the IDE PRD Table Address register, enable DMA in the DMACommand register, and call :c:func:`exec_command` to begin the transfer. Most legacy IDE drivers use :c:func:`ata_bmdma_start` for the:c:func:`bmdma_start` hook. :c:func:`ata_bmdma_start` will write theATA_DMA_START flag to the DMA Command register. Many legacy IDE drivers use :c:func:`ata_bmdma_stop` for the:c:func:`bmdma_stop` hook. :c:func:`ata_bmdma_stop` clears the ATA_DMA_STARTflag in the DMA command register. Many legacy IDE drivers use :c:func:`ata_bmdma_status` as the:c:func:`bmdma_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 standard:c:func:`ata_bmdma_qc_prep` and :c:func:`ata_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 function:c:func:`ata_sff_qc_issue` for taskfile protocol-based dispatch. Moreadvanced drivers implement their own ``->qc_issue``. :c:func:`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);  :c:func:`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 call :c:func:`ata_std_error_handler`. :c:func:`ata_std_error_handler` will perform a standard error handling sequenceto resurrect 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 is  performed. Based on existing conditions, severity of the problem, and hardware  capabilities, * Either the 'softreset' operation or the 'hardreset' operation will be called  to perform the low-level EH reset. If both operations are defined,  'hardreset' is preferred and used. If both are not defined, no low-level reset  is performed and EH assumes that an ATA class device is connected through the  link. ::     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 via:c:func:`ata_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 to:c:type:`struct ata_host_set <ata_host_set>`. Most legacy IDE drivers use :c:func:`ata_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 use :c:func:`ata_sff_irq_clear` for the:c:func:`irq_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 for``ap->private_data``. Many drivers use :c:func:`ata_port_start` as this hook or call it from theirown :c:func:`port_start` hooks. :c:func:`ata_port_start` allocates space fora legacy IDE PRD table and returns. ``->port_stop()`` is called after ``->host_stop()``. Its sole function is torelease DMA/memory resources, now that they are no longer actively beingused. Many drivers also free driver-private data from port at this time. ``->host_stop()`` is called after all ``->port_stop()`` calls have completed.The hook must finalize hardware shutdown, release DMA and otherresources, etc. This hook may be specified as NULL, in which case it isnot called. Error handling============== This chapter describes how errors are handled under libata. Readers areadvised to read SCSI EH (Documentation/scsi/scsi_eh.rst) and ATAexceptions doc first. Origins of commands------------------- In libata, a command is represented with:c:type:`struct ata_queued_cmd <ata_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 be    executed. qc currently has two mechanisms to notify completion. One    is via ``qc->complete_fn()`` callback and the other is completion    ``qc->waiting``. ``qc->complete_fn()`` callback is the asynchronous path    used by normal SCSI translated commands and ``qc->waiting`` is the    synchronous (issuer sleeps in process context) path used by internal    commands.     Once initialization is complete, host_set lock is acquired and the    qc is issued. SCSI commands    All libata drivers use :c:func:`ata_scsi_queuecmd` as    ``hostt->queuecommand`` callback. scmds can either be simulated or    translated. No qc is involved in processing a simulated scmd. The    result is computed right away and the scmd is completed.     ``qc->complete_fn()`` callback is used for completion notification. ATA    commands use :c:func:`ata_scsi_qc_complete` while ATAPI commands use    :c:func:`atapi_qc_complete`. Both functions end up calling ``qc->scsidone``    to notify upper layer when the qc is finished. After translation is    completed, the qc is issued with :c:func:`ata_qc_issue`.     Note that SCSI midlayer invokes hostt->queuecommand while holding    host_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. These    types of commands don't require any software intervention once    issued. Device will raise interrupt on completion. ATA PIO    ATA_PROT_PIO is in this category. libata currently implements PIO    with polling. ATA_NIEN bit is set to turn off interrupt and    pio_task on ata_wq performs polling and IO. ATAPI NODATA or DMA    ATA_PROT_ATAPI_NODATA and ATA_PROT_ATAPI_DMA are in this    category. packet_task is used to poll BSY bit after issuing PACKET    command. Once BSY is turned off by the device, packet_task    transfers CDB and hands off processing to interrupt handler. ATAPI PIO    ATA_PROT_ATAPI is in this category. ATA_NIEN bit is set and, as    in ATAPI NODATA or DMA, packet_task submits cdb. However, after    submitting cdb, further processing (data transfer) is handed off to    pio_task. How commands are completed-------------------------- Once issued, all qc's are either completed with :c:func:`ata_qc_complete` ortime out. For commands which are handled by interrupts,:c:func:`ata_host_intr` invokes :c:func:`ata_qc_complete`, and, for PIO tasks,pio_task invokes :c:func:`ata_qc_complete`. In error cases, packet_task mayalso complete commands. :c:func:`ata_qc_complete` does the following. 1. DMA memory is unmapped. 2. ATA_QCFLAG_ACTIVE is cleared from qc->flags. 3. :c:expr:`qc->complete_fn` callback is invoked. If the return value of the   callback is not zero. Completion is short circuited and   :c:func:`ata_qc_complete` returns. 4. :c:func:`__ata_qc_complete` is called, which does    1. ``qc->flags`` is cleared to zero.    2. ``ap->active_tag`` and ``qc->tag`` are poisoned.    3. ``qc->waiting`` is cleared & completed (in that order).    4. qc is deallocated by clearing appropriate bit in ``ap->qactive``. So, it basically notifies upper layer and deallocates qc. One exceptionis short-circuit path in #3 which is used by :c:func:`atapi_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 is

Lines 1–500 of 1000. Load more