[PATCH v5 6/9] drm/xe/doc: Document device wedged and runtime survivability

[Raag Jadav]

On Tue, Jul 15, 2025 at 04:17:26PM +0530, Riana Tauro wrote:
> Add documentation for vendor specific device wedged recovery method
> and runtime survivability.

...

> diff --git a/drivers/gpu/drm/xe/xe_device.c b/drivers/gpu/drm/xe/xe_device.c
> index bd81ebd370cb..d28c92f8b80c 100644
> --- a/drivers/gpu/drm/xe/xe_device.c
> +++ b/drivers/gpu/drm/xe/xe_device.c
> @@ -1133,6 +1133,28 @@ static void xe_device_wedged_fini(struct drm_device *drm, void *arg)
>  }
>  
>  /**
> + * DOC: Device Wedging

Xe Device Wedging?

> + * Xe driver uses device wedged uevent as documented in Documentation/gpu/drm-uapi.rst.
> + *
> + * When device is in wedged state, every IOCTL will be blocked and GT cannot be
> + * used. Certain critical errors like gt reset failure, firmware failures can cause
> + * the device to be wedged. The default recovery mechanism for a wedged state

method

> + * is re-probe (unbind + bind)

Let's use uapi naming for consistency.

> + * Another recovery method is ``WEDGED=vendor-specific`. Below are the usecases

If we mean method, it's just ``vendor-specific`` with correct quoting.

> + * that trigger vendor-specific drm wedged uevent and actions to be performed
> + * to recover the device.
> + *
> + * Case 1: CSC firmware errors require a firmware flash to restore normal device
> + *         operation. Since firmware flash is a vendor-specific action
> + *         `WEDGED=vendor-specific`` recovery method along with
> + *         :ref:`runtime survivability mode <xe-survivability-mode>` is used to
> + *         notify userspace. User can then initiate a firmware flash using userspace tools
> + *         like fwupd to restore device to normal situation.
> + */
> +
> +/*
>   * xe_device_set_wedged_method - Set wedged recovery method
>   * @xe: xe device instance
>   * @method: recovery method to set
> diff --git a/drivers/gpu/drm/xe/xe_survivability_mode.c b/drivers/gpu/drm/xe/xe_survivability_mode.c
> index 267d0e3fd85a..9f770db116f4 100644
> --- a/drivers/gpu/drm/xe/xe_survivability_mode.c
> +++ b/drivers/gpu/drm/xe/xe_survivability_mode.c
> @@ -22,15 +22,18 @@
>  #define MAX_SCRATCH_MMIO 8
>  
>  /**
> - * DOC: Xe Boot Survivability
> + * DOC: Survivability Mode
>   *
> - * Boot Survivability is a software based workflow for recovering a system in a failed boot state
> + * Survivability Mode is a software based workflow for recovering a system in a failed boot state
>   * Here system recoverability is concerned with recovering the firmware responsible for boot.
>   *
> - * This is implemented by loading the driver with bare minimum (no drm card) to allow the firmware
> - * to be flashed through mei and collect telemetry. The driver's probe flow is modified
> - * such that it enters survivability mode when pcode initialization is incomplete and boot status
> - * denotes a failure.
> + * Boot Survivability
> + * ===================
> + *
> + * Boot Survivability is implemented by loading the driver with bare minimum (no drm card) to allow
> + * the firmware to be flashed through mei and collect telemetry. The driver's probe flow is

'mei driver' or it gives the impression of a tool. Also, what telemetry?

> + * modified such that it enters survivability mode when pcode initialization is incomplete and boot
> + * status denotes a failure.
>   *
>   * Survivability mode can also be entered manually using the survivability mode attribute available
>   * through configfs which is beneficial in several usecases. It can be used to address scenarios
> @@ -46,7 +49,7 @@
>   * Survivability mode is indicated by the below admin-only readable sysfs which provides additional

If it's sensitive, does it make sense to also log it?

>   * debug information::
>   *
> - *	/sys/bus/pci/devices/<device>/surivability_mode
> + *	/sys/bus/pci/devices/<device>/survivability_mode
>   *
>   * Capability Information:
>   *	Provides boot status
> @@ -56,6 +59,22 @@
>   *	Provides history of previous failures
>   * Auxiliary Information
>   *	Certain failures may have information in addition to postcode information
> + *
> + * Runtime Survivability
> + * =====================
> + *
> + * Certain runtime firmware errors can cause the device to enter a wedged state
> + * (:ref:`xe-device-wedging`) requiring a firmware flash to restore normal operation.
> + * Runtime Survivability Mode indicates that a firmware flash is necessary to recover the device and
> + * is indicated by the presence of survivability mode sysfs::
> + *
> + *	/sys/bus/pci/devices/<device>/survivability_mode
> + *
> + * Survivability mode sysfs provides information about the type of survivability mode.
> + *
> + * When such errors occur, userspace is notified with the drm device wedged uevent and runtime
> + * survivability mode. User can then initiate a firmware update using userspace tools like fwupd
> + * to restore device to normal operation.
>   */

Overall looks good and gets the point across, but I think consistent
termiologies would make it more easy to follow and understand.

method/mechanism/actions
wedged uevent/drm wedged uevent/drm device wedged uevent
firmware flash/firmware update
operation/situation

... and so on.

Raag