[PATCH 1/2] drm/xe: Improve devcoredump documentation

[Raag Jadav]

On Thu, Oct 31, 2024 at 11:29:15AM -0700, Lucas De Marchi wrote:

...

> - * Snapshot at hang:
> - * The 'data' file is printed with a drm_printer pointer at devcoredump read
> - * time. For this reason, we need to take snapshots from when the hang has
> - * happened, and not only when the user is reading the file. Otherwise the
> - * information is outdated since the resets might have happened in between.
> + * The following characteristics are observed by xe when creating a device
> + * coredump:
>   *
> - * 'First' failure snapshot:
> - * In general, the first hang is the most critical one since the following hangs
> - * can be a consequence of the initial hang. For this reason we only take the
> - * snapshot of the 'first' failure and ignore subsequent calls of this function,
> - * at least while the coredump device is alive. Dev_coredump has a delayed work
> - * queue that will eventually delete the device and free all the dump
> - * information.
> + * **Snapshot at hang**:
> + *   The 'data' file contains a snapshot of the HW state at the time the hang
> + *   happened. Due to the driver recovering from resets/crashes, it may not
> + *   correspond to the state of when the file is read by userspace.

Does that mean the devcoredump will be present even after a successful recovery?
Perhaps moving the 'release' part to above paragraph will add required context.

> + * **First failure only**:
> + *   In general, the first hang is the most critical one since the following
> + *   hangs can be a consequence of the initial hang. For this reason a snapshot
> + *   is taken only for the first failure. Until the devcoredump is released by
> + *   userspace or kernel, all subsequent hangs do not override the snapshot nor
> + *   create new ones. Devcoredump has a delayed work queue that will eventually
> + *   delete the file node and free all the dump information.

Raag