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

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

[Philipp Stanner]

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@redhat.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

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

[Alex Deucher]

On Tue, Oct 29, 2024 at 9:39 AM Philipp Stanner <pstanner@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@redhat.com>

Reviewed-by: Alex Deucher <alexander.deucher@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
>

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

[Philipp Stanner]

On Tue, 2024-10-29 at 09:47 -0400, Alex Deucher wrote:
> On Tue, Oct 29, 2024 at 9:39 AM Philipp Stanner <pstanner@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@redhat.com>
> 
> Reviewed-by: Alex Deucher <alexander.deucher@amd.com>

Thanks.

Applied to drm-misc-next.

P.

> 
> > ---
> >  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
> > 
>