When ``WEDGED=cold-reset`` is sent, it indicates that the device has encountered an error condition that cannot be resolved through other recovery methods such as driver rebind or bus reset, and requires a complete device power cycle to restore functionality.
Signed-off-by: Mallesh Koujalagi <[email protected]> --- v2: - Add several instead of number to avoid update. (Jani) v3: - Update document with generic scenario. (Riana) - Consistent with terminology. (Raag) - Remove already covered information. v4: - Update doc. (Raag/Riana) - Change commit message. v5: - Update commit message. (Raag) - Remove unbind. - Simplify cold-reset script. v6: - Look up the hotplug slot in DEVPATH instead of scanning every PCI slot on the system. (Raag) - Drop arbitrary sleep values from the example script. v7: - Update recovery script. (Raag) --- Documentation/gpu/drm-uapi.rst | 85 +++++++++++++++++++++++++++++++++- 1 file changed, 84 insertions(+), 1 deletion(-) diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index 93df92c4ac8c..8ab2fdd20cb5 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -424,7 +424,7 @@ needed. Recovery -------- -Current implementation defines four recovery methods, out of which, drivers +Current implementation defines several 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. See the section `Vendor Specific Recovery`_ @@ -441,6 +441,7 @@ following expectations. rebind unbind + bind driver bus-reset unbind + bus reset/re-enumeration + bind vendor-specific vendor specific recovery method + cold-reset remove device + slot power cycle + rescan unknown consumer policy =============== ======================================== @@ -453,6 +454,17 @@ debug purpose in order to root cause the hang. This is useful because the first hang is usually the most critical one which can result in consequential hangs or complete wedging. +Cold Reset Recovery +------------------- + +When ``WEDGED=cold-reset`` is sent, it indicates that the device has +encountered an error condition that cannot be resolved through other +recovery methods such as driver rebind or bus reset, and requires a complete +device power cycle to restore functionality. + +This method is used by devices that are plugged directly into the PCIe slot +which supports removing the power. + Vendor Specific Recovery ------------------------ @@ -530,6 +542,77 @@ Recovery script:: echo -n $DEVICE > $DRIVER/unbind echo -n $DEVICE > $DRIVER/bind +Example - cold-reset +-------------------- + +Udev rule:: + + SUBSYSTEM=="drm", ENV{WEDGED}=="cold-reset", DEVPATH=="*/drm/card[0-9]", + RUN+="/path/to/cold-reset.sh $env{DEVPATH}" + +Recovery script:: + + #!/bin/sh + die() { echo "ERROR: $*" >&2; exit 1; } + + [ -n "$1" ] || die "Usage: $0 <device-path>" + + PCI_DEVS=/sys/bus/pci/devices + PCI_SLOTS=/sys/bus/pci/slots + + syspath=$(readlink -f "/sys/$1/device" 2>/dev/null || readlink -f "/sys/$1" 2>/dev/null) + [ -n "$syspath" ] || die "cannot resolve sysfs path for: $1" + + dev=$(basename "$syspath") + [ -e "$PCI_DEVS/$dev" ] || die "not a PCI device: $dev" + echo "device : $dev" + + slot="" + walk=$(dirname "$(readlink -f "$PCI_DEVS/$dev")") + + while true; do + ancestor=$(basename "$walk") + case "$ancestor" in pci*) break ;; esac # reached the virtual bus root + + ancestor_nofn=${ancestor%.*} # strip function: 0000:03:01.0 -> 0000:03:01 + + for f in "$PCI_SLOTS"/*/address; do + [ -f "$f" ] || continue + addr=$(cat "$f") + case "$ancestor_nofn" in + *"$addr") slot=$(basename "$(dirname "$f")"); break ;; + esac + done + + if [ -n "$slot" ] && [ -e "$PCI_SLOTS/$slot/power" ]; then + echo "slot : $slot (port $ancestor)" + break + fi + slot="" + walk=$(dirname "$walk") + done + + [ -n "$slot" ] || die "no hotplug slot with power control found in PCIe topology" + + # Cold reset: remove the device, cut slot power, restore power, rescan. + echo "Removing $dev..." + [ -e "$PCI_DEVS/$dev" ] && echo 1 > "$PCI_DEVS/$dev/remove" + + echo "Powering off slot $slot..." + echo 0 > "$PCI_SLOTS/$slot/power" + + echo "Powering on slot $slot..." + echo 1 > "$PCI_SLOTS/$slot/power" + + echo "Rescanning PCI bus..." + echo 1 > /sys/bus/pci/rescan + + if [ -e "$PCI_DEVS/$dev" ]; then + echo "Done: $dev is back online." + else + echo "WARNING: $dev did not re-appear after reset." + fi + Customization ------------- -- 2.34.1
