Documentation/networking/devlink/devlink-health.rst

Source file repositories/reference/linux-study-clean/Documentation/networking/devlink/devlink-health.rst

File Facts

System
Linux kernel
Corpus path
Documentation/networking/devlink/devlink-health.rst
Extension
.rst
Size
6333 bytes
Lines
143
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

==============
Devlink Health
==============

Background
==========

The ``devlink`` health mechanism is targeted for Real Time Alerting, in
order to know when something bad happened to a PCI device.

  * Provide alert debug information.
  * Self healing.
  * If problem needs vendor support, provide a way to gather all needed
    debugging information.

Overview
========

The main idea is to unify and centralize driver health reports in the
generic ``devlink`` instance and allow the user to set different
attributes of the health reporting and recovery procedures.

The ``devlink`` health reporter:
Device driver creates a "health reporter" per each error/health type.
Error/Health type can be a known/generic (e.g. PCI error, fw error, rx/tx error)
or unknown (driver specific).
For each registered health reporter a driver can issue error/health reports
asynchronously. All health reports handling is done by ``devlink``.
Device driver can provide specific callbacks for each "health reporter", e.g.:

  * Recovery procedures
  * Diagnostics procedures
  * Object dump procedures

Drivers also provide default values for generic reporter parameters when
creating a health reporter.

Different parts of the driver can register different types of health reporters
with different handlers.

Actions
=======

Once an error is reported, devlink health will perform the following actions:

  * A log is being send to the kernel trace events buffer
  * Health status and statistics are being updated for the reporter instance
  * Object dump is being taken and saved at the reporter instance. This is
    best effort and skipped when recovery is aborted, auto-dump is disabled,
    no dump callback is registered, or a dump is already stored.
  * Auto recovery attempt is being done. Depends on:

    - Auto-recovery configuration
    - Grace period (and burst period)  vs. time passed since last recover

Devlink formatted message
=========================

To handle devlink health diagnose and health dump requests, devlink creates a
formatted message structure ``devlink_fmsg`` and send it to the driver's callback
to fill the data in using the devlink fmsg API.

Devlink fmsg is a mechanism to pass descriptors between drivers and devlink, in
json-like format. The API allows the driver to add nested attributes such as
object, object pair and value array, in addition to attributes such as name and
value.

Driver should use this API to fill the fmsg context in a format which will be

Annotation

Implementation Notes