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

[Riana Tauro]

On 7/23/2025 7:04 PM, Raag Jadav wrote:
> 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?

The document title is Xe Device Wedging.
This is just the tag
> 
>> + * 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?

Okay will fix this.
vsec is initialized for any telemetry collection
> 
>> + * 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
> 

Sure will fix this

Thanks,
Riana

> ... and so on.
> 
> Raag