On Mon, Jul 28, 2025 at 03:57:51PM +0530, Riana Tauro wrote: > Address the need for a recovery method (firmware flash on Firmware errors) > introduced in the later patches of Xe KMD. > Whenever XE KMD detects a firmware error, a firmware flash is required to > recover the device to normal operation. > > The initial proposal to use 'firmware-flash' as a recovery method was > not applicable to other drivers and could cause multiple recovery > methods specific to vendors to be added. > To address this a more generic 'vendor-specific' method is introduced, > guiding users to refer to vendor specific documentation and system logs > for detailed vendor specific recovery procedure. > > Add a recovery method 'WEDGED=vendor-specific' for such errors. > Vendors must provide additional recovery documentation if this method > is used. > > It is the responsibility of the consumer to refer to the correct vendor > specific documentation and usecase before attempting a recovery. > > For example: If driver is XE KMD, the consumer must refer > to the documentation of 'Device Wedging' under 'Documentation/gpu/xe/'. > > Recovery script contributed by Raag. > > v2: fix documentation (Raag) > v3: add more details to commit message (Sima, Rodrigo, Raag) > add an example script to the documentation (Raag) > v4: use consistent naming (Raag) > v5: fix commit message > > Cc: André Almeida <andrealm...@igalia.com> > Cc: Christian König <christian.koe...@amd.com> > Cc: David Airlie <airl...@gmail.com> > Cc: Simona Vetter <simona.vet...@ffwll.ch>
Cc: Maxime Ripard <mrip...@kernel.org> > Co-developed-by: Raag Jadav <raag.ja...@intel.com> > Signed-off-by: Raag Jadav <raag.ja...@intel.com> > Signed-off-by: Riana Tauro <riana.ta...@intel.com> > Reviewed-by: Rodrigo Vivi <rodrigo.v...@intel.com> > --- > Documentation/gpu/drm-uapi.rst | 42 ++++++++++++++++++++++++++++------ > drivers/gpu/drm/drm_drv.c | 2 ++ > include/drm/drm_device.h | 4 ++++ > 3 files changed, 41 insertions(+), 7 deletions(-) > > diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst > index 843facf01b2d..5691b29acde3 100644 > --- a/Documentation/gpu/drm-uapi.rst > +++ b/Documentation/gpu/drm-uapi.rst > @@ -418,13 +418,15 @@ needed. > Recovery > -------- > > -Current implementation defines three recovery methods, out of which, drivers > +Current implementation defines four recovery methods, out of which, drivers > can use any one, multiple or none. Method(s) of choice will be sent in the > uevent environment as ``WEDGED=<method1>[,..,<methodN>]`` in order of less to > -more side-effects. If driver is unsure about recovery or method is unknown > -(like soft/hard system reboot, firmware flashing, physical device replacement > -or any other procedure which can't be attempted on the fly), > ``WEDGED=unknown`` > -will be sent instead. > +more side-effects. If recovery method is specific to vendor > +``WEDGED=vendor-specific`` will be sent and userspace should refer to vendor > +specific documentation for the recovery procedure. As an example if the > driver > +is 'Xe' then the documentation for 'Device Wedging' of Xe driver needs to be > +referred for the recovery procedure. If driver is unsure about recovery or > +method is unknown, ``WEDGED=unknown`` will be sent instead. What if instead of this we do something like: --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -441,6 +441,29 @@ following expectations. unknown consumer policy =============== ======================================== +Vendor-Specific Recovery +++++++++++++++++++++++++ + +When ``WEDGED=vendor-specific`` is emitted, it indicates that the device requires a +recovery method that is *not standardized* and is specific to the hardware vendor. + +In this case, the vendor driver must provide detailed documentation describing +every single recovery possibilities and its processes. It needs to include: + +- Hints: Which of the following will be used to identify the + specific device, and guide the administrator: + + Sysfs, debugfs, tracepoints, or kernel logs (e.g., ``dmesg``) +- Explicit guidance: for any admin or userspace tools and scripts necessary + to carry out recovery. + +**Example**: + If the device uses the ``Xe`` driver, then administrators should consult the + *"Device Wedging"* section of the Xe driver's documentation to determine + the proper steps for recovery. + +Notes ++++++ + The only exception to this is ``WEDGED=none``, which signifies that the device ---------------------- Maxime, is it any better? Thanks, Rodrigo. > > Userspace consumers can parse this event and attempt recovery as per the > following expectations. > @@ -435,6 +437,7 @@ following expectations. > none optional telemetry collection > rebind unbind + bind driver > bus-reset unbind + bus reset/re-enumeration + bind > + vendor-specific vendor specific recovery method > unknown consumer policy > =============== ======================================== > > @@ -472,8 +475,12 @@ erroring out, all device memory should be unmapped and > file descriptors should > be closed to prevent leaks or undefined behaviour. The idea here is to clear > the > device of all user context beforehand and set the stage for a clean recovery. > > -Example > -------- > +For ``WEDGED=vendor-specific`` recovery method, it is the responsibility of > the > +consumer to check the driver documentation and the usecase before attempting > +a recovery. > + > +Example - rebind > +---------------- > > Udev rule:: > > @@ -491,6 +498,27 @@ Recovery script:: > echo -n $DEVICE > $DRIVER/unbind > echo -n $DEVICE > $DRIVER/bind > > +Example - vendor-specific > +------------------------- > + > +Udev rule:: > + > + SUBSYSTEM=="drm", ENV{WEDGED}=="vendor-specific", > DEVPATH=="*/drm/card[0-9]", > + RUN+="/path/to/vendor_specific_recovery.sh $env{DEVPATH}" > + > +Recovery script:: > + > + #!/bin/sh > + > + DEVPATH=$(readlink -f /sys/$1/device) > + DRIVERPATH=$(readlink -f $DEVPATH/driver) > + DRIVER=$(basename $DRIVERPATH) > + > + if [ "$DRIVER" = "xe" ]; then > + # Refer XE documentation and check usecase and recovery procedure > + fi > + > + > Customization > ------------- > > diff --git a/drivers/gpu/drm/drm_drv.c b/drivers/gpu/drm/drm_drv.c > index cdd591b11488..0ac723a46a91 100644 > --- a/drivers/gpu/drm/drm_drv.c > +++ b/drivers/gpu/drm/drm_drv.c > @@ -532,6 +532,8 @@ static const char *drm_get_wedge_recovery(unsigned int > opt) > return "rebind"; > case DRM_WEDGE_RECOVERY_BUS_RESET: > return "bus-reset"; > + case DRM_WEDGE_RECOVERY_VENDOR: > + return "vendor-specific"; > default: > return NULL; > } > diff --git a/include/drm/drm_device.h b/include/drm/drm_device.h > index a33aedd5e9ec..59fd3f4d5995 100644 > --- a/include/drm/drm_device.h > +++ b/include/drm/drm_device.h > @@ -26,10 +26,14 @@ struct pci_controller; > * Recovery methods for wedged device in order of less to more side-effects. > * To be used with drm_dev_wedged_event() as recovery @method. Callers can > * use any one, multiple (or'd) or none depending on their needs. > + * > + * Refer to "Device Wedging" chapter in Documentation/gpu/drm-uapi.rst for > more > + * details. > */ > #define DRM_WEDGE_RECOVERY_NONE BIT(0) /* optional telemetry > collection */ > #define DRM_WEDGE_RECOVERY_REBIND BIT(1) /* unbind + bind driver */ > #define DRM_WEDGE_RECOVERY_BUS_RESET BIT(2) /* unbind + reset bus device + > bind */ > +#define DRM_WEDGE_RECOVERY_VENDOR BIT(3) /* vendor specific recovery > method */ > > /** > * struct drm_wedge_task_info - information about the guilty task of a wedge > dev > -- > 2.47.1 >