code:
========================
libATA Developer's Guide
========================

:Author: Jeff Garzik

Introduction
============

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

This Guide documents the libATA driver API, library functions, library
internals, 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 libata
hardware driver, and it controls how the low-level driver interfaces
with the ATA and SCSI layers.

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

:c:type:`struct ata_port_operations <ata_port_operations>`
----------------------------------------------------------

Disable ATA port
~~~~~~~~~~~~~~~~

::

    void (*port_disable) (struct ata_port *);

Called from :c:func:`ata_bus_probe` error path, as well as when unregistering
from the SCSI module (rmmod, hot unplug). This function should do
whatever needs to be done to take the port out of use. In most cases,
:c:func:`ata_port_disable` can be used as this hook.

Called from :c:func:`ata_bus_probe` on a failed probe. Called from
:c:func:`ata_scsi_release`.

Post-IDENTIFY device configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

::

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

Called after IDENTIFY [PACKET] DEVICE is issued to each device found.
Typically used to apply device-specific fixups prior to issue of SET
FEATURES - 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. The
optional ``->mode_filter()`` hook is called when libata has built a mask of
the possible modes. This is passed to the ``->mode_filter()`` function
which should return a mask of valid modes after filtering those
unsuitable due to hardware limits. It is not valid to use this interface
to 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 for
any other drive sharing the cable will also be valid at this point. That
is the library records the decisions for the modes of each drive on a
channel 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 hardware
registers / DMA buffers. ``->tf_read()`` is called to read the hardware
registers / DMA buffers, to obtain the current set of taskfile register
values. 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-level
operation that actually copies the data bytes during a PIO data
transfer. 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 be
initiated 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 status
indicating whether or not it is OK to use DMA for the supplied PACKET
command.

This hook may be specified as NULL, in which case libata will assume
that 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 some
hardware, reading the Status register has the side effect of clearing
the 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. Most
drivers 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 hardware
devices to be considered 'selected' (active and available for use) on
the ATA bus. This generally has no meaning on FIS-based devices.

Most drivers for taskfile-based hardware use :c:func:`ata_sff_dev_select` for
this hook.

Private tuning method
~~~~~~~~~~~~~~~~~~~~~

::

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

By default libata performs drive and controller tuning in accordance
with 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 do
drive 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``) the
hardware's DMA engine. ``->bmdma_status`` is used to read the standard PCI
IDE DMA Status register.

These hooks are typically either no-ops, or simply not implemented, in
FIS-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 pointer
to the PRD table to the IDE PRD Table Address register, enable DMA in the DMA
Command 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 the
ATA_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_START
flag 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 of
the above taskfile/DMA engine hooks. ``->qc_prep`` is called after the
buffers have been DMA-mapped, and is typically used to populate the
hardware's DMA scatter-gather table. Some drivers use the standard
:c:func:`ata_bmdma_qc_prep` and :c:func:`ata_bmdma_dumb_qc_prep` helper
functions, but more advanced drivers roll their own.

``->qc_issue`` is used to make a command active, once the hardware and S/G
tables have been prepared. IDE BMDMA drivers use the helper function
:c:func:`ata_sff_qc_issue` for taskfile protocol-based dispatch. More
advanced 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 (*eng_timeout) (struct ata_port *ap);
    void (*phy_reset) (struct ata_port *ap);

Deprecated. Use ``->error_handler()`` instead.

::

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

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

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

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

::

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

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

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

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

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

::

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

Perform any hardware-specific actions necessary to finish processing
after executing a probe-time or EH-time command via
: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 the
system, by libata. ``->irq_clear`` is called during probe just before the
interrupt 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_handler
hook, which scans all ports in the host_set, determines which queued
command 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 flags
in the DMA status register.

SATA phy read/write
~~~~~~~~~~~~~~~~~~~

::

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

Read and write standard SATA phy registers. Currently only used if
``->phy_reset`` hook called the :c:func:`sata_phy_reset` helper function.
sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE.

Init and shutdown
~~~~~~~~~~~~~~~~~

::

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

``->port_start()`` is called just after the data structures for each port
are initialized. Typically this is used to alloc per-port DMA buffers /
tables / rings, enable DMA engines, and similar tasks. Some drivers also
use 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 their
own :c:func:`port_start` hooks. :c:func:`ata_port_start` allocates space for
a legacy IDE PRD table and returns.

``->port_stop()`` is called after ``->host_stop()``. Its sole function is to
release DMA/memory resources, now that they are no longer actively being
used. 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 other
resources, etc. This hook may be specified as NULL, in which case it is
not called.

Error handling
==============

This chapter describes how errors are handled under libata. Readers are
advised to read SCSI EH (Documentation/scsi/scsi_eh.rst) and ATA
exceptions 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 used
for command executions. Currently only one qc is allocated per port but
yet-to-be-merged NCQ branch allocates one for each tag and maps each qc
to NCQ tag 1-to-1.

libata commands can originate from two sources - libata itself and SCSI
midlayer. libata internal commands are used for initialization and error
handling. All normal blk requests and commands for SCSI emulation are
passed as SCSI commands through queuecommand callback of SCSI host
template.

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 are
processed differently. For the purpose of discussion, a controller which
uses taskfile interface and all standard callbacks is assumed.

Currently 6 ATA command protocols are used. They can be sorted into the
following 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` or
time 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 may
also 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 exception
is 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 same
code path is taken and very little error handling takes place. A qc is
completed with success status if it succeeded, with failed status
otherwise.

However, failed ATAPI commands require more handling as REQUEST SENSE is
needed to acquire sense data. If an ATAPI command fails,
:c:func:`ata_qc_complete` is invoked with error status, which in turn invokes
:c:func:`atapi_qc_complete` via ``qc->complete_fn()`` callback.

This makes :c:func:`atapi_qc_complete` set ``scmd->result`` to
SAM_STAT_CHECK_CONDITION, complete the scmd and return 1. As the
sense data is empty but ``scmd->result`` is CHECK CONDITION, SCSI midlayer
will invoke EH for the scmd, and returning 1 makes :c:func:`ata_qc_complete`
to return without deallocating the qc. This leads us to
:c:func:`ata_scsi_error` with partially completed qc.

:c:func:`ata_scsi_error`
------------------------

:c:func:`ata_scsi_error` is the current ``transportt->eh_strategy_handler()``
for libata. As discussed above, this will be entered in two cases -
timeout and ATAPI error completion. This function calls low level libata
driver's :c:func:`eng_timeout` callback, the standard callback for which is
:c:func:`ata_eng_timeout`. It checks if a qc is active and calls
:c:func:`ata_qc_timeout` on the qc if so. Actual error handling occurs in
:c:func:`ata_qc_timeout`.

If EH is invoked for timeout, :c:func:`ata_qc_timeout` stops BMDMA and
completes the qc. Note that as we're currently in EH, we cannot call
scsi_done. As described in SCSI EH doc, a recovered scmd should be
either retried with :c:func:`scsi_queue_insert` or finished with
:c:func:`scsi_finish_command`. Here, we override ``qc->scsidone`` with
:c:func:`scsi_finish_command` and calls :c:func:`ata_qc_complete`.

If EH is invoked due to a failed ATAPI qc, the qc here is completed but
not deallocated. The purpose of this half-completion is to use the qc as
place 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
:c:func:`__ata_qc_complete` explicitly. Then, internal qc for REQUEST SENSE
is issued. Once sense data is acquired, scmd is finished by directly
invoking :c:func:`scsi_finish_command` on the scmd. Note that as we already
have completed and deallocated the qc which was associated with the
scmd, we don't need to/cannot call :c:func:`ata_qc_complete` again.

Problems with the current EH
----------------------------

-  Error representation is too crude. Currently any and all error
   conditions are represented with ATA STATUS and ERROR registers.
   Errors which aren't ATA device errors are treated as ATA device
   errors by setting ATA_ERR bit. Better error descriptor which can
   properly represent ATA and other errors/exceptions is needed.

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

-  EH handling via :c:func:`ata_scsi_error` is not properly protected from
   usual command processing. On EH entrance, the device is not in
   quiescent 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 mismatch
   errors and other errors quite often require reset to return to known
   state. Also, advanced error handling is necessary to support features
   like NCQ and hotplug.

-  ATA errors are directly handled in the interrupt handler and PIO
   errors in pio_task. This is problematic for advanced error handling
   for the following reasons.

   First, advanced error handling often requires context and internal qc
   execution.

   Second, even a simple failure (say, CRC error) needs information
   gathering 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 drivers
   difficult. Low level drivers override libata callbacks. If EH is
   scattered over several places, each affected callbacks should perform
   its part of error handling. This can be error prone and painful.

libata Library
==============

.. kernel-doc:: drivers/ata/libata-core.c
   :export:

libata Core Internals
=====================

.. kernel-doc:: drivers/ata/libata-core.c
   :internal:

.. kernel-doc:: drivers/ata/libata-eh.c

libata SCSI translation/emulation
=================================

.. kernel-doc:: drivers/ata/libata-scsi.c
   :export:

.. kernel-doc:: drivers/ata/libata-scsi.c
   :internal:

ATA errors and exceptions
=========================

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

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

The term 'exception' is either used to describe exceptional conditions
which are not errors (say, power or hotplug events), or to describe both
errors and non-error exceptional conditions. Where explicit distinction
between error and exception is necessary, the term 'non-error exception'
is used.

Exception categories
--------------------

Exceptions are described primarily with respect to legacy taskfile + bus
master IDE interface. If a controller provides other better mechanism
for error reporting, mapping those into categories described below
shouldn't be difficult.

In the following sections, two recovery actions - reset and
reconfiguring transport - are mentioned. These are described further in
`EH recovery actions <#exrec>`__.

HSM violation
~~~~~~~~~~~~~

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

-  ATA_STATUS doesn't contain !BSY && DRDY && !DRQ while trying to
   issue a command.

-  !BSY && !DRQ during PIO data transfer.

-  DRQ on command completion.

-  !BSY && ERR after CDB transfer starts but before the last byte of CDB
   is transferred. ATA/ATAPI standard states that "The device shall not
   terminate the PACKET command with an error before the last byte of
   the command packet has been written" in the error outputs description
   of PACKET command and the state diagram doesn't include such
   transitions.

In these cases, HSM is violated and not much information regarding the
error can be acquired from STATUS or ERROR register. IOW, this error can
be 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 as
transmission 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 indicating
device problems. For this type of errors, STATUS and ERROR register
values are valid and describe error condition. Note that some of ATA bus
errors are detected by ATA/ATAPI devices and reported using the same
mechanism as device errors. Those cases are described later in this
section.

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

For ATAPI commands,

-  !BSY && ERR && ABRT right after issuing PACKET indicates that PACKET
   command is not supported and falls in this category.

-  !BSY && ERR(==CHK) && !ABRT after the last byte of CDB is transferred
   indicates 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 this
   category.

Of errors detected as above, the following are not ATA/ATAPI device
errors but ATA bus errors and should be handled according to
`ATA bus error <#excatATAbusErr>`__.

CRC error during data transfer
    This is indicated by ICRC bit in the ERROR register and means that
    corruption occurred during data transfer. Up to ATA/ATAPI-7, the
    standard specifies that this bit is only applicable to UDMA
    transfers but ATA/ATAPI-8 draft revision 1f says that the bit may be
    applicable 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 on
    ICRC errors and on cases where a device is not able to complete a
    command. Combined with the fact that MWDMA and PIO transfer errors
    aren't allowed to use ICRC bit up to ATA/ATAPI-7, it seems to imply
    that ABRT bit alone could indicate transfer errors.

    However, ATA/ATAPI-8 draft revision 1f removes the part that ICRC
    errors can turn on ABRT. So, this is kind of gray area. Some
    heuristics 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 devices
    reports UNC error only after certain number of retries cannot
    recover the data, so there's nothing much else to do other than
    notifying upper layer.

    READ and WRITE commands report CHS or LBA of the first failed sector
    but ATA/ATAPI standard specifies that the amount of transferred data
    on error completion is indeterminate, so we cannot assume that
    sectors preceding the failed sector have been transferred and thus
    cannot 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 upper
    layer.

Other errors
    This can be invalid command or parameter indicated by ABRT ERROR bit
    or some other error condition. Note that ABRT bit can indicate a lot
    of things including ICRC and Address errors. Heuristics needed.

Depending on commands, not all STATUS/ERROR bits are applicable. These
non-applicable bits are marked with "na" in the output descriptions but
up 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 this
        standard and should not be checked by the host or device. N/A
        fields should be cleared to zero.

So, it seems reasonable to assume that "na" bits are cleared to zero by
devices 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 a
PACKET command. For this kind of errors, sense data should be acquired
to gather information regarding the errors. REQUEST SENSE packet command
should be used to acquire sense data.

Once sense data is acquired, this type of errors can be handled
similarly to other SCSI errors. Note that sense data may indicate ATA
bus error (e.g. Sense Key 04h HARDWARE ERROR && ASC/ASCQ 47h/00h SCSI
PARITY ERROR). In such cases, the error should be considered as an ATA
bus error and handled according to `ATA bus error <#excatATAbusErr>`__.

ATA device error (NCQ)
~~~~~~~~~~~~~~~~~~~~~~

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

READ LOG EXT Log Page 10h reports which tag has failed and taskfile
register values describing the error. With this information the failed
command can be handled as a normal ATA command error as in
`ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) <#excatDevErr>`__
and all other in-flight commands must be retried. Note that this retry
should not be counted - it's likely that commands retried this way would
have completed normally if it were not for the failed command.

Note that ATA bus errors can be reported as ATA device NCQ errors. This
should be handled as described in `ATA bus error <#excatATAbusErr>`__.

If READ LOG EXT Log Page 10h fails or reports NQ, we're thoroughly
screwed. This condition should be treated according to
`HSM violation <#excatHSMviolation>`__.

ATA bus error
~~~~~~~~~~~~~

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

-  ICRC or ABRT error as described in
   `ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION) <#excatDevErr>`__.

-  Controller-specific error completion with error information
   indicating transmission error.

-  On some controllers, command timeout. In this case, there may be a
   mechanism 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 of
symptoms 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 to
transmission error or not; therefore, it's necessary to employ some kind
of heuristic when dealing with errors and timeouts. For example,
encountering repetitive ABRT errors for known supported command is
likely 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 may
alleviate the problem. See `Reconfigure transport <#exrecReconf>`__ for
more information.

PCI bus error
~~~~~~~~~~~~~

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

Late completion
~~~~~~~~~~~~~~~

This occurs when timeout occurs and the timeout handler finds out that
the timed out command has completed successfully or with error. This is
usually 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 the
host and device are in unknown state. When this occurs, HSM could be in
any valid or invalid state. To bring the device to known state and make
it forget about the timed out command, resetting is necessary. The timed
out command may be retried.

Timeouts can also be caused by transmission errors. Refer to
`ATA bus error <#excatATAbusErr>`__ 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 error
handler. Different controllers may have different requirements.

For SATA, it's strongly recommended to clear at least SError register
during 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 condition
to improve EH robustness. Whether to reset both or either one of HBA and
device depends on situation but the following scheme is recommended.

-  When it's known that HBA is in ready state but ATA/ATAPI device is in
   unknown state, reset only device.

-  If HBA is in unknown state, reset both HBA and device.

HBA resetting is implementation specific. For a controller complying to
taskfile/BMDMA PCI IDE, stopping active DMA transaction may be
sufficient iff BMDMA state is the only HBA context. But even mostly
taskfile/BMDMA PCI IDE complying controllers may have implementation
specific requirements and mechanism to reset themselves. This must be
addressed by specific drivers.

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

PATA hardware reset
    This is hardware initiated device reset signalled with asserted PATA
    RESET- signal. There is no standard way to initiate hardware reset
    from software although some hardware provides registers that allow
    driver 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 require
    controller-specific support as the second Register FIS to clear SRST
    should 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 implies
    some level of resetting, possibly similar level with software reset.
    Host-side EDD protocol can be handled with normal command processing
    and most SATA controllers should be able to handle EDD's just like
    other commands. As in software reset, EDD affects both devices on a
    PATA bus.

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

ATAPI DEVICE RESET command
    This is very similar to software reset except that reset can be
    restricted to the selected device without affecting the other device
    sharing 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 done
    with the standard SCR Control register. As such, it's usually easier
    to implement than software reset.

One more thing to consider when resetting devices is that resetting
clears certain configuration parameters and they need to be set to their
previous 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 maintained
across hardware or software reset, but doesn't strictly specify all of
them. Always reconfiguring needed parameters after reset is required for
robustness. Note that this also applies when resuming from deep sleep
(power-off).

Also, ATA/ATAPI standard requires that IDENTIFY DEVICE / IDENTIFY PACKET
DEVICE is issued after any configuration parameter is updated or a
hardware reset and the result used for further operation. OS driver is
required 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 transmission
error 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
===================

.. kernel-doc:: drivers/ata/ata_piix.c
   :internal:

sata_sil Internals
===================

.. kernel-doc:: drivers/ata/sata_sil.c
   :internal:

Thanks
======

The bulk of the ATA knowledge comes thanks to long conversations with
Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA and
SCSI 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 all
the early probing was based on extensive study of Hale Landis's
probe/reset code in his ATADRVR driver (www.ata-atapi.com).


code:
============================
The Common Mailbox Framework
============================

:Author: Jassi Brar <jaswinder.singh@linaro.org>

This document aims to help developers write client and controller
drivers for the API. But before we start, let us note that the
client (especially) and controller drivers are likely going to be
very platform specific because the remote firmware is likely to be
proprietary and implement non-standard protocol. So even if two
platforms employ, say, PL320 controller, the client drivers can't
be shared across them. Even the PL320 driver might need to accommodate
some platform specific quirks. So the API is meant mainly to avoid
similar copies of code written for each platform. Having said that,
nothing prevents the remote f/w to also be Linux based and use the
same api there. However none of that helps us locally because we only
ever deal at client's protocol level.

Some of the choices made during implementation are the result of this
peculiarity of this "common" framework.

Controller Driver (See include/linux/mailbox_controller.h)
==========================================================

Allocate mbox_controller and the array of mbox_chan.
Populate mbox_chan_ops, except peek_data() all are mandatory.
The controller driver might know a message has been consumed
by the remote by getting an IRQ or polling some hardware flag
or it can never know (the client knows by way of the protocol).
The method in order of preference is IRQ -> Poll -> None, which
the controller driver should set via 'txdone_irq' or 'txdone_poll'
or neither.

Client Driver (See include/linux/mailbox_client.h)
==================================================

The client might want to operate in blocking mode (synchronously
send a message through before returning) or non-blocking/async mode (submit
a message and a callback function to the API and return immediately).

::

	struct demo_client {
		struct mbox_client cl;
		struct mbox_chan *mbox;
		struct completion c;
		bool async;
		/* ... */
	};

	/*
	* This is the handler for data received from remote. The behaviour is purely
	* dependent upon the protocol. This is just an example.
	*/
	static void message_from_remote(struct mbox_client *cl, void *mssg)
	{
		struct demo_client *dc = container_of(cl, struct demo_client, cl);
		if (dc->async) {
			if (is_an_ack(mssg)) {
				/* An ACK to our last sample sent */
				return; /* Or do something else here */
			} else { /* A new message from remote */
				queue_req(mssg);
			}
		} else {
			/* Remote f/w sends only ACK packets on this channel */
			return;
		}
	}

	static void sample_sent(struct mbox_client *cl, void *mssg, int r)
	{
		struct demo_client *dc = container_of(cl, struct demo_client, cl);
		complete(&dc->c);
	}

	static void client_demo(struct platform_device *pdev)
	{
		struct demo_client *dc_sync, *dc_async;
		/* The controller already knows async_pkt and sync_pkt */
		struct async_pkt ap;
		struct sync_pkt sp;

		dc_sync = kzalloc(sizeof(*dc_sync), GFP_KERNEL);
		dc_async = kzalloc(sizeof(*dc_async), GFP_KERNEL);

		/* Populate non-blocking mode client */
		dc_async->cl.dev = &pdev->dev;
		dc_async->cl.rx_callback = message_from_remote;
		dc_async->cl.tx_done = sample_sent;
		dc_async->cl.tx_block = false;
		dc_async->cl.tx_tout = 0; /* doesn't matter here */
		dc_async->cl.knows_txdone = false; /* depending upon protocol */
		dc_async->async = true;
		init_completion(&dc_async->c);

		/* Populate blocking mode client */
		dc_sync->cl.dev = &pdev->dev;
		dc_sync->cl.rx_callback = message_from_remote;
		dc_sync->cl.tx_done = NULL; /* operate in blocking mode */
		dc_sync->cl.tx_block = true;
		dc_sync->cl.tx_tout = 500; /* by half a second */
		dc_sync->cl.knows_txdone = false; /* depending upon protocol */
		dc_sync->async = false;

		/* ASync mailbox is listed second in 'mboxes' property */
		dc_async->mbox = mbox_request_channel(&dc_async->cl, 1);
		/* Populate data packet */
		/* ap.xxx = 123; etc */
		/* Send async message to remote */
		mbox_send_message(dc_async->mbox, &ap);

		/* Sync mailbox is listed first in 'mboxes' property */
		dc_sync->mbox = mbox_request_channel(&dc_sync->cl, 0);
		/* Populate data packet */
		/* sp.abc = 123; etc */
		/* Send message to remote in blocking mode */
		mbox_send_message(dc_sync->mbox, &sp);
		/* At this point 'sp' has been sent */

		/* Now wait for async chan to be done */
		wait_for_completion(&dc_async->c);
	}

repo_name: angery/linux


code:
.. SPDX-License-Identifier: GPL-2.0

====
RAID
====

.. toctree::
   :maxdepth: 1

   md-cluster
   raid5-cache
   raid5-ppl


code:
==========
MD Cluster
==========

The cluster MD is a shared-device RAID for a cluster, it supports
two levels: raid1 and raid10 (limited support).

1. On-disk format
=================

Separate write-intent-bitmaps are used for each cluster node.
The bitmaps record all writes that may have been started on that node,
and may not yet have finished. The on-disk layout is::

  0                    4k                     8k                    12k
  -------------------------------------------------------------------
  | idle                | md super            | bm super [0] + bits |
  | bm bits[0, contd]   | bm super[1] + bits  | bm bits[1, contd]   |
  | bm super[2] + bits  | bm bits [2, contd]  | bm super[3] + bits  |
  | bm bits [3, contd]  |                     |                     |

During "normal" functioning we assume the filesystem ensures that only
one node writes to any given block at a time, so a write request will

 - set the appropriate bit (if not already set)
 - commit the write to all mirrors
 - schedule the bit to be cleared after a timeout.

Reads are just handled normally. It is up to the filesystem to ensure
one node doesn't read from a location where another node (or the same
node) is writing.

2. DLM Locks for management
===========================

There are three groups of locks for managing the device:

2.1 Bitmap lock resource (bm_lockres)
-------------------------------------

 The bm_lockres protects individual node bitmaps. They are named in
 the form bitmap000 for node 1, bitmap001 for node 2 and so on. When a
 node joins the cluster, it acquires the lock in PW mode and it stays
 so during the lifetime the node is part of the cluster. The lock
 resource number is based on the slot number returned by the DLM
 subsystem. Since DLM starts node count from one and bitmap slots
 start from zero, one is subtracted from the DLM slot number to arrive
 at the bitmap slot number.

 The LVB of the bitmap lock for a particular node records the range
 of sectors that are being re-synced by that node.  No other
 node may write to those sectors.  This is used when a new nodes
 joins the cluster.

2.2 Message passing locks
-------------------------

 Each node has to communicate with other nodes when starting or ending
 resync, and for metadata superblock updates.  This communication is
 managed through three locks: "token", "message", and "ack", together
 with the Lock Value Block (LVB) of one of the "message" lock.

2.3 new-device management
-------------------------

 A single lock: "no-new-dev" is used to co-ordinate the addition of
 new devices - this must be synchronized across the array.
 Normally all nodes hold a concurrent-read lock on this device.

3. Communication
================

 Messages can be broadcast to all nodes, and the sender waits for all
 other nodes to acknowledge the message before proceeding.  Only one
 message can be processed at a time.

3.1 Message Types
-----------------

 There are six types of messages which are passed:

3.1.1 METADATA_UPDATED
^^^^^^^^^^^^^^^^^^^^^^

   informs other nodes that the metadata has
   been updated, and the node must re-read the md superblock. This is
   performed synchronously. It is primarily used to signal device
   failure.

3.1.2 RESYNCING
^^^^^^^^^^^^^^^
   informs other nodes that a resync is initiated or
   ended so that each node may suspend or resume the region.  Each
   RESYNCING message identifies a range of the devices that the
   sending node is about to resync. This overrides any previous
   notification from that node: only one ranged can be resynced at a
   time per-node.

3.1.3 NEWDISK
^^^^^^^^^^^^^

   informs other nodes that a device is being added to
   the array. Message contains an identifier for that device.  See
   below for further details.

3.1.4 REMOVE
^^^^^^^^^^^^

   A failed or spare device is being removed from the
   array. The slot-number of the device is included in the message.

 3.1.5 RE_ADD:

   A failed device is being re-activated - the assumption
   is that it has been determined to be working again.

 3.1.6 BITMAP_NEEDS_SYNC:

   If a node is stopped locally but the bitmap
   isn't clean, then another node is informed to take the ownership of
   resync.

3.2 Communication mechanism
---------------------------

 The DLM LVB is used to communicate within nodes of the cluster. There
 are three resources used for the purpose:

3.2.1 token
^^^^^^^^^^^
   The resource which protects the entire communication
   system. The node having the token resource is allowed to
   communicate.

3.2.2 message
^^^^^^^^^^^^^
   The lock resource which carries the data to communicate.

3.2.3 ack
^^^^^^^^^

   The resource, acquiring which means the message has been
   acknowledged by all nodes in the cluster. The BAST of the resource
   is used to inform the receiving node that a node wants to
   communicate.

The algorithm is:

 1. receive status - all nodes have concurrent-reader lock on "ack"::

	sender                         receiver                 receiver
	"ack":CR                       "ack":CR                 "ack":CR

 2. sender get EX on "token",
    sender get EX on "message"::

	sender                        receiver                 receiver
	"token":EX                    "ack":CR                 "ack":CR
	"message":EX
	"ack":CR

    Sender checks that it still needs to send a message. Messages
    received or other events that happened while waiting for the
    "token" may have made this message inappropriate or redundant.

 3. sender writes LVB

    sender down-convert "message" from EX to CW

    sender try to get EX of "ack"

    ::

      [ wait until all receivers have *processed* the "message" ]

                                       [ triggered by bast of "ack" ]
                                       receiver get CR on "message"
                                       receiver read LVB
                                       receiver processes the message
                                       [ wait finish ]
                                       receiver releases "ack"
                                       receiver tries to get PR on "message"

     sender                         receiver                  receiver
     "token":EX                     "message":CR              "message":CR
     "message":CW
     "ack":EX

 4. triggered by grant of EX on "ack" (indicating all receivers
    have processed message)

    sender down-converts "ack" from EX to CR

    sender releases "message"

    sender releases "token"

    ::

                                 receiver upconvert to PR on "message"
                                 receiver get CR of "ack"
                                 receiver release "message"

     sender                      receiver                   receiver
     "ack":CR                    "ack":CR                   "ack":CR

4. Handling Failures
====================

4.1 Node Failure
----------------

 When a node fails, the DLM informs the cluster with the slot
 number. The node starts a cluster recovery thread. The cluster
 recovery thread:

	- acquires the bitmap<number> lock of the failed node
	- opens the bitmap
	- reads the bitmap of the failed node
	- copies the set bitmap to local node
	- cleans the bitmap of the failed node
	- releases bitmap<number> lock of the failed node
	- initiates resync of the bitmap on the current node
	  md_check_recovery is invoked within recover_bitmaps,
	  then md_check_recovery -> metadata_update_start/finish,
	  it will lock the communication by lock_comm.
	  Which means when one node is resyncing it blocks all
	  other nodes from writing anywhere on the array.

 The resync process is the regular md resync. However, in a clustered
 environment when a resync is performed, it needs to tell other nodes
 of the areas which are suspended. Before a resync starts, the node
 send out RESYNCING with the (lo,hi) range of the area which needs to
 be suspended. Each node maintains a suspend_list, which contains the
 list of ranges which are currently suspended. On receiving RESYNCING,
 the node adds the range to the suspend_list. Similarly, when the node
 performing resync finishes, it sends RESYNCING with an empty range to
 other nodes and other nodes remove the corresponding entry from the
 suspend_list.

 A helper function, ->area_resyncing() can be used to check if a
 particular I/O range should be suspended or not.

4.2 Device Failure
==================

 Device failures are handled and communicated with the metadata update
 routine.  When a node detects a device failure it does not allow
 any further writes to that device until the failure has been
 acknowledged by all other nodes.

5. Adding a new Device
----------------------

 For adding a new device, it is necessary that all nodes "see" the new
 device to be added. For this, the following algorithm is used:

   1.  Node 1 issues mdadm --manage /dev/mdX --add /dev/sdYY which issues
       ioctl(ADD_NEW_DISK with disc.state set to MD_DISK_CLUSTER_ADD)
   2.  Node 1 sends a NEWDISK message with uuid and slot number
   3.  Other nodes issue kobject_uevent_env with uuid and slot number
       (Steps 4,5 could be a udev rule)
   4.  In userspace, the node searches for the disk, perhaps
       using blkid -t SUB_UUID=""
   5.  Other nodes issue either of the following depending on whether
       the disk was found:
       ioctl(ADD_NEW_DISK with disc.state set to MD_DISK_CANDIDATE and
       disc.number set to slot number)
       ioctl(CLUSTERED_DISK_NACK)
   6.  Other nodes drop lock on "no-new-devs" (CR) if device is found
   7.  Node 1 attempts EX lock on "no-new-dev"
   8.  If node 1 gets the lock, it sends METADATA_UPDATED after
       unmarking the disk as SpareLocal
   9.  If not (get "no-new-dev" lock), it fails the operation and sends
       METADATA_UPDATED.
   10. Other nodes get the information whether a disk is added or not
       by the following METADATA_UPDATED.

6. Module interface
===================

 There are 17 call-backs which the md core can make to the cluster
 module.  Understanding these can give a good overview of the whole
 process.

6.1 join(nodes) and leave()
---------------------------

 These are called when an array is started with a clustered bitmap,
 and when the array is stopped.  join() ensures the cluster is
 available and initializes the various resources.
 Only the first 'nodes' nodes in the cluster can use the array.

6.2 slot_number()
-----------------

 Reports the slot number advised by the cluster infrastructure.
 Range is from 0 to nodes-1.

6.3 resync_info_update()
------------------------

 This updates the resync range that is stored in the bitmap lock.
 The starting point is updated as the resync progresses.  The
 end point is always the end of the array.
 It does *not* send a RESYNCING message.

6.4 resync_start(), resync_finish()
-----------------------------------

 These are called when resync/recovery/reshape starts or stops.
 They update the resyncing range in the bitmap lock and also
 send a RESYNCING message.  resync_start reports the whole
 array as resyncing, resync_finish reports none of it.

 resync_finish() also sends a BITMAP_NEEDS_SYNC message which
 allows some other node to take over.

6.5 metadata_update_start(), metadata_update_finish(), metadata_update_cancel()
-------------------------------------------------------------------------------

 metadata_update_start is used to get exclusive access to
 the metadata.  If a change is still needed once that access is
 gained, metadata_update_finish() will send a METADATA_UPDATE
 message to all other nodes, otherwise metadata_update_cancel()
 can be used to release the lock.

6.6 area_resyncing()
--------------------

 This combines two elements of functionality.

 Firstly, it will check if any node is currently resyncing
 anything in a given range of sectors.  If any resync is found,
 then the caller will avoid writing or read-balancing in that
 range.

 Secondly, while node recovery is happening it reports that
 all areas are resyncing for READ requests.  This avoids races
 between the cluster-filesystem and the cluster-RAID handling
 a node failure.

6.7 add_new_disk_start(), add_new_disk_finish(), new_disk_ack()
---------------------------------------------------------------

 These are used to manage the new-disk protocol described above.
 When a new device is added, add_new_disk_start() is called before
 it is bound to the array and, if that succeeds, add_new_disk_finish()
 is called the device is fully added.

 When a device is added in acknowledgement to a previous
 request, or when the device is declared "unavailable",
 new_disk_ack() is called.

6.8 remove_disk()
-----------------

 This is called when a spare or failed device is removed from
 the array.  It causes a REMOVE message to be send to other nodes.

6.9 gather_bitmaps()
--------------------

 This sends a RE_ADD message to all other nodes and then
 gathers bitmap information from all bitmaps.  This combined
 bitmap is then used to recovery the re-added device.

6.10 lock_all_bitmaps() and unlock_all_bitmaps()
------------------------------------------------

 These are called when change bitmap to none. If a node plans
 to clear the cluster raid's bitmap, it need to make sure no other
 nodes are using the raid which is achieved by lock all bitmap
 locks within the cluster, and also those locks are unlocked
 accordingly.

7. Unsupported features
=======================

There are somethings which are not supported by cluster MD yet.

- change array_sectors.


code:
================
RAID 4/5/6 cache
================

Raid 4/5/6 could include an extra disk for data cache besides normal RAID
disks. The role of RAID disks isn't changed with the cache disk. The cache disk
caches data to the RAID disks. The cache can be in write-through (supported
since 4.4) or write-back mode (supported since 4.10). mdadm (supported since
3.4) has a new option '--write-journal' to create array with cache. Please
refer to mdadm manual for details. By default (RAID array starts), the cache is
in write-through mode. A user can switch it to write-back mode by::

	echo "write-back" > /sys/block/md0/md/journal_mode

And switch it back to write-through mode by::

	echo "write-through" > /sys/block/md0/md/journal_mode

In both modes, all writes to the array will hit cache disk first. This means
the cache disk must be fast and sustainable.

write-through mode
==================

This mode mainly fixes the 'write hole' issue. For RAID 4/5/6 array, an unclean
shutdown can cause data in some stripes to not be in consistent state, eg, data
and parity don't match. The reason is that a stripe write involves several RAID
disks and it's possible the writes don't hit all RAID disks yet before the
unclean shutdown. We call an array degraded if it has inconsistent data. MD
tries to resync the array to bring it back to normal state. But before the
resync completes, any system crash will expose the chance of real data
corruption in the RAID array. This problem is called 'write hole'.

The write-through cache will cache all data on cache disk first. After the data
is safe on the cache disk, the data will be flushed onto RAID disks. The
two-step write will guarantee MD can recover correct data after unclean
shutdown even the array is degraded. Thus the cache can close the 'write hole'.

In write-through mode, MD reports IO completion to upper layer (usually
filesystems) after the data is safe on RAID disks, so cache disk failure
doesn't cause data loss. Of course cache disk failure means the array is
exposed to 'write hole' again.

In write-through mode, the cache disk isn't required to be big. Several
hundreds megabytes are enough.

write-back mode
===============

write-back mode fixes the 'write hole' issue too, since all write data is
cached on cache disk. But the main goal of 'write-back' cache is to speed up
write. If a write crosses all RAID disks of a stripe, we call it full-stripe
write. For non-full-stripe writes, MD must read old data before the new parity
can be calculated. These synchronous reads hurt write throughput. Some writes
which are sequential but not dispatched in the same time will suffer from this
overhead too. Write-back cache will aggregate the data and flush the data to
RAID disks only after the data becomes a full stripe write. This will
completely avoid the overhead, so it's very helpful for some workloads. A
typical workload which does sequential write followed by fsync is an example.

In write-back mode, MD reports IO completion to upper layer (usually
filesystems) right after the data hits cache disk. The data is flushed to raid
disks later after specific conditions met. So cache disk failure will cause
data loss.

In write-back mode, MD also caches data in memory. The memory cache includes
the same data stored on cache disk, so a power loss doesn't cause data loss.
The memory cache size has performance impact for the array. It's recommended
the size is big. A user can configure the size by::

	echo "2048" > /sys/block/md0/md/stripe_cache_size

Too small cache disk will make the write aggregation less efficient in this
mode depending on the workloads. It's recommended to use a cache disk with at
least several gigabytes size in write-back mode.

The implementation
==================

The write-through and write-back cache use the same disk format. The cache disk
is organized as a simple write log. The log consists of 'meta data' and 'data'
pairs. The meta data describes the data. It also includes checksum and sequence
ID for recovery identification. Data can be IO data and parity data. Data is
checksumed too. The checksum is stored in the meta data ahead of the data. The
checksum is an optimization because MD can write meta and data freely without
worry about the order. MD superblock has a field pointed to the valid meta data
of log head.

The log implementation is pretty straightforward. The difficult part is the
order in which MD writes data to cache disk and RAID disks. Specifically, in
write-through mode, MD calculates parity for IO data, writes both IO data and
parity to the log, writes the data and parity to RAID disks after the data and
parity is settled down in log and finally the IO is finished. Read just reads
from raid disks as usual.

In write-back mode, MD writes IO data to the log and reports IO completion. The
data is also fully cached in memory at that time, which means read must query
memory cache. If some conditions are met, MD will flush the data to RAID disks.
MD will calculate parity for the data and write parity into the log. After this
is finished, MD will write both data and parity into RAID disks, then MD can
release the memory cache. The flush conditions could be stripe becomes a full
stripe write, free cache disk space is low or free in-kernel memory cache space
is low.

After an unclean shutdown, MD does recovery. MD reads all meta data and data
from the log. The sequence ID and checksum will help us detect corrupted meta
data and data. If MD finds a stripe with data and valid parities (1 parity for
raid4/5 and 2 for raid6), MD will write the data and parities to RAID disks. If
parities are incompleted, they are discarded. If part of data is corrupted,
they are discarded too. MD then loads valid data and writes them to RAID disks
in normal way.


code:
==================
Partial Parity Log
==================

Partial Parity Log (PPL) is a feature available for RAID5 arrays. The issue
addressed by PPL is that after a dirty shutdown, parity of a particular stripe
may become inconsistent with data on other member disks. If the array is also
in degraded state, there is no way to recalculate parity, because one of the
disks is missing. This can lead to silent data corruption when rebuilding the
array or using it is as degraded - data calculated from parity for array blocks
that have not been touched by a write request during the unclean shutdown can
be incorrect. Such condition is known as the RAID5 Write Hole. Because of
this, md by default does not allow starting a dirty degraded array.

Partial parity for a write operation is the XOR of stripe data chunks not
modified by this write. It is just enough data needed for recovering from the
write hole. XORing partial parity with the modified chunks produces parity for
the stripe, consistent with its state before the write operation, regardless of
which chunk writes have completed. If one of the not modified data disks of
this stripe is missing, this updated parity can be used to recover its
contents. PPL recovery is also performed when starting an array after an
unclean shutdown and all disks are available, eliminating the need to resync
the array. Because of this, using write-intent bitmap and PPL together is not
supported.

When handling a write request PPL writes partial parity before new data and
parity are dispatched to disks. PPL is a distributed log - it is stored on
array member drives in the metadata area, on the parity drive of a particular
stripe.  It does not require a dedicated journaling drive. Write performance is
reduced by up to 30%-40% but it scales with the number of drives in the array
and the journaling drive does not become a bottleneck or a single point of
failure.

Unlike raid5-cache, the other solution in md for closing the write hole, PPL is
not a true journal. It does not protect from losing in-flight data, only from
silent data corruption. If a dirty disk of a stripe is lost, no PPL recovery is
performed for this stripe (parity is not updated). So it is possible to have
arbitrary data in the written part of a stripe if that disk is lost. In such
case the behavior is the same as in plain raid5.

PPL is available for md version-1 metadata and external (specifically IMSM)
metadata arrays. It can be enabled using mdadm option --consistency-policy=ppl.

There is a limitation of maximum 64 disks in the array for PPL. It allows to
keep data structures and implementation simple. RAID5 arrays with so many disks
are not likely due to high risk of multiple disks failure. Such restriction
should not be a real life limitation.


code:
.. SPDX-License-Identifier: GPL-2.0

Writing camera sensor drivers
=============================

CSI-2 and parallel (BT.601 and BT.656) busses
---------------------------------------------

Please see :ref:`transmitter-receiver`.

Handling clocks
---------------

Camera sensors have an internal clock tree including a PLL and a number of
divisors. The clock tree is generally configured by the driver based on a few
input parameters that are specific to the hardware:: the external clock frequency
and the link frequency. The two parameters generally are obtained from system
firmware. **No other frequencies should be used in any circumstances.**

The reason why the clock frequencies are so important is that the clock signals
come out of the SoC, and in many cases a specific frequency is designed to be
used in the system. Using another frequency may cause harmful effects
elsewhere. Therefore only the pre-determined frequencies are configurable by the
user.

ACPI
~~~~

Read the ``clock-frequency`` _DSD property to denote the frequency. The driver
can rely on this frequency being used.

Devicetree
~~~~~~~~~~

The currently preferred way to achieve this is using ``assigned-clocks``,
``assigned-clock-parents`` and ``assigned-clock-rates`` properties. See
``Documentation/devicetree/bindings/clock/clock-bindings.txt`` for more
information. The driver then gets the frequency using ``clk_get_rate()``.

This approach has the drawback that there's no guarantee that the frequency
hasn't been modified directly or indirectly by another driver, or supported by
the board's clock tree to begin with. Changes to the Common Clock Framework API
are required to ensure reliability.

Frame size
----------

There are two distinct ways to configure the frame size produced by camera
sensors.

Freely configurable camera sensor drivers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Freely configurable camera sensor drivers expose the device's internal
processing pipeline as one or more sub-devices with different cropping and
scaling configurations. The output size of the device is the result of a series
of cropping and scaling operations from the device's pixel array's size.

An example of such a driver is the CCS driver (see ``drivers/media/i2c/ccs``).

Register list based drivers
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Register list based drivers generally, instead of able to configure the device
they control based on user requests, are limited to a number of preset
configurations that combine a number of different parameters that on hardware
level are independent. How a driver picks such configuration is based on the
format set on a source pad at the end of the device's internal pipeline.

Most sensor drivers are implemented this way, see e.g.
``drivers/media/i2c/imx319.c`` for an example.

Frame interval configuration
----------------------------

There are two different methods for obtaining possibilities for different frame
intervals as well as configuring the frame interval. Which one to implement
depends on the type of the device.

Raw camera sensors
~~~~~~~~~~~~~~~~~~

Instead of a high level parameter such as frame interval, the frame interval is
a result of the configuration of a number of camera sensor implementation
specific parameters. Luckily, these parameters tend to be the same for more or
less all modern raw camera sensors.

The frame interval is calculated using the following equation::

	frame interval = (analogue crop width + horizontal blanking) *
			 (analogue crop height + vertical blanking) / pixel rate

The formula is bus independent and is applicable for raw timing parameters on
large variety of devices beyond camera sensors. Devices that have no analogue
crop, use the full source image size, i.e. pixel array size.

Horizontal and vertical blanking are specified by ``V4L2_CID_HBLANK`` and
``V4L2_CID_VBLANK``, respectively. The unit of the ``V4L2_CID_HBLANK`` control
is pixels and the unit of the ``V4L2_CID_VBLANK`` is lines. The pixel rate in
the sensor's **pixel array** is specified by ``V4L2_CID_PIXEL_RATE`` in the same
sub-device. The unit of that control is pixels per second.

Register list based drivers need to implement read-only sub-device nodes for the
purpose. Devices that are not register list based need these to configure the
device's internal processing pipeline.

The first entity in the linear pipeline is the pixel array. The pixel array may
be followed by other entities that are there to allow configuring binning,
skipping, scaling or digital crop :ref:`v4l2-subdev-selections`.

USB cameras etc. devices
~~~~~~~~~~~~~~~~~~~~~~~~

USB video class hardware, as well as many cameras offering a similar higher
level interface natively, generally use the concept of frame interval (or frame
rate) on device level in firmware or hardware. This means lower level controls
implemented by raw cameras may not be used on uAPI (or even kAPI) to control the
frame interval on these devices.

Power management
----------------

Always use runtime PM to manage the power states of your device. Camera sensor
drivers are in no way special in this respect: they are responsible for
controlling the power state of the device they otherwise control as well. In
general, the device must be powered on at least when its registers are being
accessed and when it is streaming.

Existing camera sensor drivers may rely on the old
struct v4l2_subdev_core_ops->s_power() callback for bridge or ISP drivers to
manage their power state. This is however **deprecated**. If you feel you need
to begin calling an s_power from an ISP or a bridge driver, instead please add
runtime PM support to the sensor driver you are using. Likewise, new drivers
should not use s_power.

Please see examples in e.g. ``drivers/media/i2c/ov8856.c`` and
``drivers/media/i2c/ccs/ccs-core.c``. The two drivers work in both ACPI
and DT based systems.

Control framework
~~~~~~~~~~~~~~~~~

``v4l2_ctrl_handler_setup()`` function may not be used in the device's runtime
PM ``runtime_resume`` callback, as it has no way to figure out the power state
of the device. This is because the power state of the device is only changed
after the power state transition has taken place. The ``s_ctrl`` callback can be
used to obtain device's power state after the power state transition:

.. c:function:: int pm_runtime_get_if_in_use(struct device *dev);

The function returns a non-zero value if it succeeded getting the power count or
runtime PM was disabled, in either of which cases the driver may proceed to
access the device.


code:
.. SPDX-License-Identifier: GPL-2.0

CEC Kernel Support
==================

The CEC framework provides a unified kernel interface for use with HDMI CEC
hardware. It is designed to handle a multiple types of hardware (receivers,
transmitters, USB dongles). The framework also gives the option to decide
what to do in the kernel driver and what should be handled by userspace
applications. In addition it integrates the remote control passthrough
feature into the kernel's remote control framework.

The CEC Protocol
----------------

The CEC protocol enables consumer electronic devices to communicate with each
other through the HDMI connection. The protocol uses logical addresses in the
communication. The logical address is strictly connected with the functionality
provided by the device. The TV acting as the communication hub is always
assigned address 0. The physical address is determined by the physical
connection between devices.

The CEC framework described here is up to date with the CEC 2.0 specification.
It is documented in the HDMI 1.4 specification with the new 2.0 bits documented
in the HDMI 2.0 specification. But for most of the features the freely available
HDMI 1.3a specification is sufficient:

https://www.hdmi.org/spec/index

CEC Adapter Interface
---------------------

The struct cec_adapter represents the CEC adapter hardware. It is created by
calling cec_allocate_adapter() and deleted by calling cec_delete_adapter():

.. c:function::
   struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops, \
					    void *priv, const char *name, \
					    u32 caps, u8 available_las);

.. c:function::
   void cec_delete_adapter(struct cec_adapter *adap);

To create an adapter you need to pass the following information:

ops:
	adapter operations which are called by the CEC framework and that you
	have to implement.

priv:
	will be stored in adap->priv and can be used by the adapter ops.
	Use cec_get_drvdata(adap) to get the priv pointer.

name:
	the name of the CEC adapter. Note: this name will be copied.

caps:
	capabilities of the CEC adapter. These capabilities determine the
	capabilities of the hardware and which parts are to be handled
	by userspace and which parts are handled by kernelspace. The
	capabilities are returned by CEC_ADAP_G_CAPS.

available_las:
	the number of simultaneous logical addresses that this
	adapter can handle. Must be 1 <= available_las <= CEC_MAX_LOG_ADDRS.

To obtain the priv pointer use this helper function:

.. c:function::
	void *cec_get_drvdata(const struct cec_adapter *adap);

To register the /dev/cecX device node and the remote control device (if
CEC_CAP_RC is set) you call:

.. c:function::
	int cec_register_adapter(struct cec_adapter *adap, \
				 struct device *parent);

where parent is the parent device.

To unregister the devices call:

.. c:function::
	void cec_unregister_adapter(struct cec_adapter *adap);

Note: if cec_register_adapter() fails, then call cec_delete_adapter() to
clean up. But if cec_register_adapter() succeeded, then only call
cec_unregister_adapter() to clean up, never cec_delete_adapter(). The
unregister function will delete the adapter automatically once the last user
of that /dev/cecX device has closed its file handle.

Implementing the Low-Level CEC Adapter
--------------------------------------

The following low-level adapter operations have to be implemented in
your driver:

.. c:struct:: cec_adap_ops

.. code-block:: none

	struct cec_adap_ops
	{
		/* Low-level callbacks */
		int (*adap_enable)(struct cec_adapter *adap, bool enable);
		int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable);
		int (*adap_monitor_pin_enable)(struct cec_adapter *adap, bool enable);
		int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr);
		void (*adap_configured)(struct cec_adapter *adap, bool configured);
		int (*adap_transmit)(struct cec_adapter *adap, u8 attempts,
				      u32 signal_free_time, struct cec_msg *msg);
		void (*adap_status)(struct cec_adapter *adap, struct seq_file *file);
		void (*adap_free)(struct cec_adapter *adap);

		/* Error injection callbacks */
		...

		/* High-level callback */
		...
	};

The seven low-level ops deal with various aspects of controlling the CEC adapter
hardware:

To enable/disable the hardware::

	int (*adap_enable)(struct cec_adapter *adap, bool enable);

This callback enables or disables the CEC hardware. Enabling the CEC hardware
means powering it up in a state where no logical addresses are claimed. The
physical address will always be valid if CEC_CAP_NEEDS_HPD is set. If that
capability is not set, then the physical address can change while the CEC
hardware is enabled. CEC drivers should not set CEC_CAP_NEEDS_HPD unless
the hardware design requires that as this will make it impossible to wake
up displays that pull the HPD low when in standby mode.  The initial
state of the CEC adapter after calling cec_allocate_adapter() is disabled.

Note that adap_enable must return 0 if enable is false.

To enable/disable the 'monitor all' mode::

	int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable);

If enabled, then the adapter should be put in a mode to also monitor messages
that are not for us. Not all hardware supports this and this function is only
called if the CEC_CAP_MONITOR_ALL capability is set. This callback is optional
(some hardware may always be in 'monitor all' mode).

Note that adap_monitor_all_enable must return 0 if enable is false.

To enable/disable the 'monitor pin' mode::

	int (*adap_monitor_pin_enable)(struct cec_adapter *adap, bool enable);

If enabled, then the adapter should be put in a mode to also monitor CEC pin
changes. Not all hardware supports this and this function is only called if
the CEC_CAP_MONITOR_PIN capability is set. This callback is optional
(some hardware may always be in 'monitor pin' mode).

Note that adap_monitor_pin_enable must return 0 if enable is false.

To program a new logical address::

	int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr);

If logical_addr == CEC_LOG_ADDR_INVALID then all programmed logical addresses
are to be erased. Otherwise the given logical address should be programmed.
If the maximum number of available logical addresses is exceeded, then it
should return -ENXIO. Once a logical address is programmed the CEC hardware
can receive directed messages to that address.

Note that adap_log_addr must return 0 if logical_addr is CEC_LOG_ADDR_INVALID.

Called when the adapter is fully configured or unconfigured::

	void (*adap_configured)(struct cec_adapter *adap, bool configured);

If configured == true, then the adapter is fully configured, i.e. all logical
addresses have been successfully claimed. If configured == false, then the
adapter is unconfigured. If the driver has to take specific actions after
(un)configuration, then that can be done through this optional callback.

To transmit a new message::

	int (*adap_transmit)(struct cec_adapter *adap, u8 attempts,
			     u32 signal_free_time, struct cec_msg *msg);

This transmits a new message. The attempts argument is the suggested number of
attempts for the transmit.

The signal_free_time is the number of data bit periods that the adapter should
wait when the line is free before attempting to send a message. This value
depends on whether this transmit is a retry, a message from a new initiator or
a new message for the same initiator. Most hardware will handle this
automatically, but in some cases this information is needed.

The CEC_FREE_TIME_TO_USEC macro can be used to convert signal_free_time to
microseconds (one data bit period is 2.4 ms).

To log the current CEC hardware status::

	void (*adap_status)(struct cec_adapter *adap, struct seq_file *file);

This optional callback can be used to show the status of the CEC hardware.
The status is available through debugfs: cat /sys/kernel/debug/cec/cecX/status

To free any resources when the adapter is deleted::

	void (*adap_free)(struct cec_adapter *adap);

This optional callback can be used to free any resources that might have been
allocated by the driver. It's called from cec_delete_adapter.

Your adapter driver will also have to react to events (typically interrupt
driven) by calling into the framework in the following situations:

When a transmit finished (successfully or otherwise)::

	void cec_transmit_done(struct cec_adapter *adap, u8 status,
			       u8 arb_lost_cnt,  u8 nack_cnt, u8 low_drive_cnt,
			       u8 error_cnt);

or::

	void cec_transmit_attempt_done(struct cec_adapter *adap, u8 status);

The status can be one of:

CEC_TX_STATUS_OK:
	the transmit was successful.

CEC_TX_STATUS_ARB_LOST:
	arbitration was lost: another CEC initiator
	took control of the CEC line and you lost the arbitration.

CEC_TX_STATUS_NACK:
	the message was nacked (for a directed message) or
	acked (for a broadcast message). A retransmission is needed.

CEC_TX_STATUS_LOW_DRIVE:
	low drive was detected on the CEC bus. This indicates that
	a follower detected an error on the bus and requested a
	retransmission.

CEC_TX_STATUS_ERROR:
	some unspecified error occurred: this can be one of ARB_LOST
	or LOW_DRIVE if the hardware cannot differentiate or something
	else entirely. Some hardware only supports OK and FAIL as the
	result of a transmit, i.e. there is no way to differentiate
	between the different possible errors. In that case map FAIL
	to CEC_TX_STATUS_NACK and not to CEC_TX_STATUS_ERROR.

CEC_TX_STATUS_MAX_RETRIES:
	could not transmit the message after trying multiple times.
	Should only be set by the driver if it has hardware support for
	retrying messages. If set, then the framework assumes that it
	doesn't have to make another attempt to transmit the message
	since the hardware did that already.

The hardware must be able to differentiate between OK, NACK and 'something
else'.

The \*_cnt arguments are the number of error conditions that were seen.
This may be 0 if no information is available. Drivers that do not support
hardware retry can just set the counter corresponding to the transmit error
to 1, if the hardware does support retry then either set these counters to
0 if the hardware provides no feedback of which errors occurred and how many
times, or fill in the correct values as reported by the hardware.

Be aware that calling these functions can immediately start a new transmit
if there is one pending in the queue. So make sure that the hardware is in
a state where new transmits can be started *before* calling these functions.

The cec_transmit_attempt_done() function is a helper for cases where the
hardware never retries, so the transmit is always for just a single
attempt. It will call cec_transmit_done() in turn, filling in 1 for the
count argument corresponding to the status. Or all 0 if the status was OK.

When a CEC message was received:

.. c:function::
	void cec_received_msg(struct cec_adapter *adap, struct cec_msg *msg);

Speaks for itself.

Implementing the interrupt handler
----------------------------------

Typically the CEC hardware provides interrupts that signal when a transmit
finished and whether it was successful or not, and it provides and interrupt
when a CEC message was received.

The CEC driver should always process the transmit interrupts first before
handling the receive interrupt. The framework expects to see the cec_transmit_done
call before the cec_received_msg call, otherwise it can get confused if the
received message was in reply to the transmitted message.

Optional: Implementing Error Injection Support
----------------------------------------------

If the CEC adapter supports Error Injection functionality, then that can
be exposed through the Error Injection callbacks:

.. code-block:: none

	struct cec_adap_ops {
		/* Low-level callbacks */
		...

		/* Error injection callbacks */
		int (*error_inj_show)(struct cec_adapter *adap, struct seq_file *sf);
		bool (*error_inj_parse_line)(struct cec_adapter *adap, char *line);

		/* High-level CEC message callback */
		...
	};

If both callbacks are set, then an ``error-inj`` file will appear in debugfs.
The basic syntax is as follows:

Leading spaces/tabs are ignored. If the next character is a ``#`` or the end of the
line was reached, then the whole line is ignored. Otherwise a command is expected.

This basic parsing is done in the CEC Framework. It is up to the driver to decide
what commands to implement. The only requirement is that the command ``clear`` without
any arguments must be implemented and that it will remove all current error injection
commands.

This ensures that you can always do ``echo clear >error-inj`` to clear any error
injections without having to know the details of the driver-specific commands.

Note that the output of ``error-inj`` shall be valid as input to ``error-inj``.
So this must work:

.. code-block:: none

	$ cat error-inj >einj.txt
	$ cat einj.txt >error-inj

The first callback is called when this file is read and it should show the
current error injection state::

	int (*error_inj_show)(struct cec_adapter *adap, struct seq_file *sf);

It is recommended that it starts with a comment block with basic usage
information. It returns 0 for success and an error otherwise.

The second callback will parse commands written to the ``error-inj`` file::

	bool (*error_inj_parse_line)(struct cec_adapter *adap, char *line);

The ``line`` argument points to the start of the command. Any leading
spaces or tabs have already been skipped. It is a single line only (so there
are no embedded newlines) and it is 0-terminated. The callback is free to
modify the contents of the buffer. It is only called for lines containing a
command, so this callback is never called for empty lines or comment lines.

Return true if the command was valid or false if there were syntax errors.

Implementing the High-Level CEC Adapter
---------------------------------------

The low-level operations drive the hardware, the high-level operations are
CEC protocol driven. The following high-level callbacks are available:

.. code-block:: none

	struct cec_adap_ops {
		/* Low-level callbacks */
		...

		/* Error injection callbacks */
		...

		/* High-level CEC message callback */
		int (*received)(struct cec_adapter *adap, struct cec_msg *msg);
	};

The received() callback allows the driver to optionally handle a newly
received CEC message::

	int (*received)(struct cec_adapter *adap, struct cec_msg *msg);

If the driver wants to process a CEC message, then it can implement this
callback. If it doesn't want to handle this message, then it should return
-ENOMSG, otherwise the CEC framework assumes it processed this message and
it will not do anything with it.

CEC framework functions
-----------------------

CEC Adapter drivers can call the following CEC framework functions:

.. c:function::
   int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg, \
			bool block);

Transmit a CEC message. If block is true, then wait until the message has been
transmitted, otherwise just queue it and return.

.. c:function::
   void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, bool block);

Change the physical address. This function will set adap->phys_addr and
send an event if it has changed. If cec_s_log_addrs() has been called and
the physical address has become valid, then the CEC framework will start
claiming the logical addresses. If block is true, then this function won't
return until this process has finished.

When the physical address is set to a valid value the CEC adapter will
be enabled (see the adap_enable op). When it is set to CEC_PHYS_ADDR_INVALID,
then the CEC adapter will be disabled. If you change a valid physical address
to another valid physical address, then this function will first set the
address to CEC_PHYS_ADDR_INVALID before enabling the new physical address.

.. c:function::
   void cec_s_phys_addr_from_edid(struct cec_adapter *adap, \
				  const struct edid *edid);

A helper function that extracts the physical address from the edid struct
and calls cec_s_phys_addr() with that address, or CEC_PHYS_ADDR_INVALID
if the EDID did not contain a physical address or edid was a NULL pointer.

.. c:function::
	int cec_s_log_addrs(struct cec_adapter *adap, \
			    struct cec_log_addrs *log_addrs, bool block);

Claim the CEC logical addresses. Should never be called if CEC_CAP_LOG_ADDRS
is set. If block is true, then wait until the logical addresses have been
claimed, otherwise just queue it and return. To unconfigure all logical
addresses call this function with log_addrs set to NULL or with
log_addrs->num_log_addrs set to 0. The block argument is ignored when
unconfiguring. This function will just return if the physical address is
invalid. Once the physical address becomes valid, then the framework will
attempt to claim these logical addresses.

CEC Pin framework
-----------------

Most CEC hardware operates on full CEC messages where the software provides
the message and the hardware handles the low-level CEC protocol. But some
hardware only drives the CEC pin and software has to handle the low-level
CEC protocol. The CEC pin framework was created to handle such devices.

Note that due to the close-to-realtime requirements it can never be guaranteed
to work 100%. This framework uses highres timers internally, but if a
timer goes off too late by more than 300 microseconds wrong results can
occur. In reality it appears to be fairly reliable.

One advantage of this low-level implementation is that it can be used as
a cheap CEC analyser, especially if interrupts can be used to detect
CEC pin transitions from low to high or vice versa.

.. kernel-doc:: include/media/cec-pin.h

CEC Notifier framework
----------------------

Most drm HDMI implementations have an integrated CEC implementation and no
notifier support is needed. But some have independent CEC implementations
that have their own driver. This could be an IP block for an SoC or a
completely separate chip that deals with the CEC pin. For those cases a
drm driver can install a notifier and use the notifier to inform the
CEC driver about changes in the physical address.

.. kernel-doc:: include/media/cec-notifier.h


code:
.. SPDX-License-Identifier: GPL-2.0

The bttv driver
===============

bttv and sound mini howto
-------------------------

There are a lot of different bt848/849/878/879 based boards available.
Making video work often is not a big deal, because this is handled
completely by the bt8xx chip, which is common on all boards.  But
sound is handled in slightly different ways on each board.

To handle the grabber boards correctly, there is a array tvcards[] in
bttv-cards.c, which holds the information required for each board.
Sound will work only, if the correct entry is used (for video it often
makes no difference).  The bttv driver prints a line to the kernel
log, telling which card type is used.  Like this one::

	bttv0: model: BT848(Hauppauge old) [autodetected]

You should verify this is correct.  If it isn't, you have to pass the
correct board type as insmod argument, ``insmod bttv card=2`` for
example.  The file Documentation/admin-guide/media/bttv-cardlist.rst has a list
of valid arguments for card.

If your card isn't listed there, you might check the source code for
new entries which are not listed yet.  If there isn't one for your
card, you can check if one of the existing entries does work for you
(just trial and error...).

Some boards have an extra processor for sound to do stereo decoding
and other nice features.  The msp34xx chips are used by Hauppauge for
example.  If your board has one, you might have to load a helper
module like ``msp3400`` to make sound work.  If there isn't one for the
chip used on your board:  Bad luck.  Start writing a new one.  Well,
you might want to check the video4linux mailing list archive first...

Of course you need a correctly installed soundcard unless you have the
speakers connected directly to the grabber board.  Hint: check the
mixer settings too.  ALSA for example has everything muted by default.

How sound works in detail
~~~~~~~~~~~~~~~~~~~~~~~~~

Still doesn't work?  Looks like some driver hacking is required.
Below is a do-it-yourself description for you.

The bt8xx chips have 32 general purpose pins, and registers to control
these pins.  One register is the output enable register
(``BT848_GPIO_OUT_EN``), it says which pins are actively driven by the
bt848 chip.  Another one is the data register (``BT848_GPIO_DATA``), where
you can get/set the status if these pins.  They can be used for input
and output.

Most grabber board vendors use these pins to control an external chip
which does the sound routing.  But every board is a little different.
These pins are also used by some companies to drive remote control
receiver chips.  Some boards use the i2c bus instead of the gpio pins
to connect the mux chip.

As mentioned above, there is a array which holds the required
information for each known board.  You basically have to create a new
line for your board.  The important fields are these two::

  struct tvcard
  {
	[ ... ]
	u32 gpiomask;
	u32 audiomux[6]; /* Tuner, Radio, external, internal, mute, stereo */
  };

gpiomask specifies which pins are used to control the audio mux chip.
The corresponding bits in the output enable register
(``BT848_GPIO_OUT_EN``) will be set as these pins must be driven by the
bt848 chip.

The ``audiomux[]`` array holds the data values for the different inputs
(i.e. which pins must be high/low for tuner/mute/...).  This will be
written to the data register (``BT848_GPIO_DATA``) to switch the audio
mux.

What you have to do is figure out the correct values for gpiomask and
the audiomux array.  If you have Windows and the drivers four your
card installed, you might to check out if you can read these registers
values used by the windows driver.  A tool to do this is available
from http://btwincap.sourceforge.net/download.html.

You might also dig around in the ``*.ini`` files of the Windows applications.
You can have a look at the board to see which of the gpio pins are
connected at all and then start trial-and-error ...

Starting with release 0.7.41 bttv has a number of insmod options to
make the gpio debugging easier:

	=================	==============================================
	bttv_gpio=0/1		enable/disable gpio debug messages
	gpiomask=n		set the gpiomask value
	audiomux=i,j,...	set the values of the audiomux array
	audioall=a		set the values of the audiomux array (one
				value for all array elements, useful to check
				out which effect the particular value has).
	=================	==============================================

The messages printed with ``bttv_gpio=1`` look like this::

	bttv0: gpio: en=00000027, out=00000024 in=00ffffd8 [audio: off]

	en  =	output _en_able register (BT848_GPIO_OUT_EN)
	out =	_out_put bits of the data register (BT848_GPIO_DATA),
		i.e. BT848_GPIO_DATA & BT848_GPIO_OUT_EN
	in  = 	_in_put bits of the data register,
		i.e. BT848_GPIO_DATA & ~BT848_GPIO_OUT_EN