[PATCH] drm/sched: Document purpose of drm_sched_{start,stop}

[Alex Deucher]

On Tue, Oct 29, 2024 at 9:39 AM Philipp Stanner <pstanner at redhat.com> wrote:
>
> drm_sched_start()'s and drm_sched_stop()'s names suggest that those
> functions might be intended for actively starting and stopping the
> scheduler on initialization and teardown.
>
> They are, however, only used on timeout handling (reset recovery). The
> docstrings should reflect that to prevent confusion.
>
> Document those functions' purpose.
>
> Signed-off-by: Philipp Stanner <pstanner at redhat.com>

Reviewed-by: Alex Deucher <alexander.deucher at amd.com>

> ---
>  drivers/gpu/drm/scheduler/sched_main.c | 8 +++++++-
>  1 file changed, 7 insertions(+), 1 deletion(-)
>
> diff --git a/drivers/gpu/drm/scheduler/sched_main.c b/drivers/gpu/drm/scheduler/sched_main.c
> index eaef20f41786..59fd49fc790e 100644
> --- a/drivers/gpu/drm/scheduler/sched_main.c
> +++ b/drivers/gpu/drm/scheduler/sched_main.c
> @@ -601,6 +601,9 @@ static void drm_sched_job_timedout(struct work_struct *work)
>   * callers responsibility to release it manually if it's not part of the
>   * pending list any more.
>   *
> + * This function is typically used for reset recovery (see the docu of
> + * drm_sched_backend_ops.timedout_job() for details). Do not call it for
> + * scheduler teardown, i.e., before calling drm_sched_fini().
>   */
>  void drm_sched_stop(struct drm_gpu_scheduler *sched, struct drm_sched_job *bad)
>  {
> @@ -673,7 +676,6 @@ void drm_sched_stop(struct drm_gpu_scheduler *sched, struct drm_sched_job *bad)
>          */
>         cancel_delayed_work(&sched->work_tdr);
>  }
> -
>  EXPORT_SYMBOL(drm_sched_stop);
>
>  /**
> @@ -681,6 +683,10 @@ EXPORT_SYMBOL(drm_sched_stop);
>   *
>   * @sched: scheduler instance
>   *
> + * This function is typically used for reset recovery (see the docu of
> + * drm_sched_backend_ops.timedout_job() for details). Do not call it for
> + * scheduler startup. The scheduler itself is fully operational after
> + * drm_sched_init() succeeded.
>   */
>  void drm_sched_start(struct drm_gpu_scheduler *sched)
>  {
> --
> 2.47.0
>