Re: [PATCH v3 3/3] Documentation: driver-api: Update libata error handler information

[Niklas Cassel <cassel@kernel.org>]

On Fri, Jul 11, 2025 at 05:35:44PM +0900, Damien Le Moal wrote:
> Update ``->error_handler()`` section of the libata documentation file
> Documentation/driver-api/libata.rst to remove the reference to the
> function ata_do_eh() as that function was removed. The reference to the
> function ata_bmdma_drive_eh() is also removed as that function does not
> exist at all. And while at it, cleanup the description of the various
> reset operations using a bullet list.
> 
> Signed-off-by: Damien Le Moal <dlemoal@kernel.org>
> ---
>  Documentation/driver-api/libata.rst | 25 ++++++++++++++++---------
>  1 file changed, 16 insertions(+), 9 deletions(-)
> 
> diff --git a/Documentation/driver-api/libata.rst b/Documentation/driver-api/libata.rst
> index 5da27a749246..93d97fe78e3f 100644
> --- a/Documentation/driver-api/libata.rst
> +++ b/Documentation/driver-api/libata.rst
> @@ -283,18 +283,25 @@ interrupts, start DMA engine, etc.
>  
>  ``->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:
> +implementation is to call :c:func:`ata_std_error_handler`.
>  
> -'prereset' hook (may be NULL) is called during an EH reset, before any
> -other actions are taken.
> +:c:func:`ata_std_error_handler` will perform a standard error handling sequence
> +to resurect failed devices, detach lost devices and add new devices (if any).
> +This function will call the various reset operations for a port, as needed.
> +These operations are as follows.
>  
> -'postreset' hook (may be NULL) is called after the EH reset is
> -performed. Based on existing conditions, severity of the problem, and
> -hardware capabilities,
> +* The 'prereset' operation (which may be NULL) is called during an EH reset,
> +  before any other action is taken.
>  
> -Either 'softreset' (may be NULL) or 'hardreset' (may be NULL) will be
> -called to perform the low-level EH reset.
> +* The 'postreset' hook (which may be NULL) is called after the EH reset is
> +  performed. Based on existing conditions, severity of the problem, and hardware
> +  capabilities,
> +
> +* Either the 'softreset' operation or the 'hardreset' operation will be called
> +  to perform the low-level EH reset. If both operations are defined,
> +  'hardreset' is preferred and used. If both are not defined, no low-level reset
> +  is performed and EH assumes that an ATA class device is connected through the
> +  link.
>  
>  ::
>  
> -- 
> 2.50.1
> 

Reviewed-by: Niklas Cassel <cassel@kernel.org>