[PATCH 0/3] htmldocs fixes for next-20230203

[PATCH 0/3] htmldocs fixes for next-20230203

[Bagas Sanjaya]

Here are small htmldocs fixes for htmldocs warnings that are recently
reported for next-20230203. Each patch can be applied separately by
respective maintainers.

Bagas Sanjaya (3):
  drm/i915/doc: Escape wildcard in method names
  drm/scheduler: Fix elapsed_ns kernel-doc error
  media: v4l2-core: Describe privacy_led field of v4l2_subdev

 drivers/gpu/drm/i915/gt/intel_workarounds.c | 6 +++---
 include/drm/gpu_scheduler.h                 | 2 +-
 include/media/v4l2-subdev.h                 | 1 +
 3 files changed, 5 insertions(+), 4 deletions(-)


base-commit: 4fafd96910add124586b549ad005dcd179de8a18
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 1/3] drm/i915/doc: Escape wildcard in method names

[Bagas Sanjaya]

Stephen Rothwell reported htmldocs warnings:

Documentation/gpu/i915:64: drivers/gpu/drm/i915/gt/intel_workarounds.c:32: WARNING: Inline emphasis start-string without end-string.
Documentation/gpu/i915:64: drivers/gpu/drm/i915/gt/intel_workarounds.c:57: WARNING: Inline emphasis start-string without end-string.
Documentation/gpu/i915:64: drivers/gpu/drm/i915/gt/intel_workarounds.c:66: WARNING: Inline emphasis start-string without end-string.

Escape wildcards in *_ctx_workarounds_init(), *_gt_workarounds_init(), and
*_whitelist_build() to fix above warnings.

Link: https://lore.kernel.org/linux-next/20230203134622.0b6315b9@canb.auug.org.au/
Fixes: 0c3064cf33fbfa ("drm/i915/doc: Document where to implement register workarounds")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 drivers/gpu/drm/i915/gt/intel_workarounds.c | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/drivers/gpu/drm/i915/gt/intel_workarounds.c b/drivers/gpu/drm/i915/gt/intel_workarounds.c
index 3111df350f5722..a00ec692d980c0 100644
--- a/drivers/gpu/drm/i915/gt/intel_workarounds.c
+++ b/drivers/gpu/drm/i915/gt/intel_workarounds.c
@@ -30,7 +30,7 @@
  *   creation to have a "primed golden context", i.e. a context image that
  *   already contains the changes needed to all the registers.
  *
- *   Context workarounds should be implemented in the *_ctx_workarounds_init()
+ *   Context workarounds should be implemented in the \*_ctx_workarounds_init()
  *   variants respective to the targeted platforms.
  *
  * - Engine workarounds: the list of these WAs is applied whenever the specific
@@ -55,7 +55,7 @@
  * - GT workarounds: the list of these WAs is applied whenever these registers
  *   revert to their default values: on GPU reset, suspend/resume [1]_, etc.
  *
- *   GT workarounds should be implemented in the *_gt_workarounds_init()
+ *   GT workarounds should be implemented in the \*_gt_workarounds_init()
  *   variants respective to the targeted platforms.
  *
  * - Register whitelist: some workarounds need to be implemented in userspace,
@@ -64,7 +64,7 @@
  *   this is just a special case of a MMIO workaround (as we write the list of
  *   these to/be-whitelisted registers to some special HW registers).
  *
- *   Register whitelisting should be done in the *_whitelist_build() variants
+ *   Register whitelisting should be done in the \*_whitelist_build() variants
  *   respective to the targeted platforms.
  *
  * - Workaround batchbuffers: buffers that get executed automatically by the
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 1/3] drm/i915/doc: Escape wildcard in method names

[Rodrigo Vivi]

On Fri, Feb 03, 2023 at 05:02:13PM +0700, Bagas Sanjaya wrote:
> Stephen Rothwell reported htmldocs warnings:
> 
> Documentation/gpu/i915:64: drivers/gpu/drm/i915/gt/intel_workarounds.c:32: WARNING: Inline emphasis start-string without end-string.
> Documentation/gpu/i915:64: drivers/gpu/drm/i915/gt/intel_workarounds.c:57: WARNING: Inline emphasis start-string without end-string.
> Documentation/gpu/i915:64: drivers/gpu/drm/i915/gt/intel_workarounds.c:66: WARNING: Inline emphasis start-string without end-string.
> 
> Escape wildcards in *_ctx_workarounds_init(), *_gt_workarounds_init(), and
> *_whitelist_build() to fix above warnings.
> 
> Link: https://lore.kernel.org/linux-next/20230203134622.0b6315b9@canb.auug.org.au/
> Fixes: 0c3064cf33fbfa ("drm/i915/doc: Document where to implement register workarounds")
> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>

pushing this now.
thank you.

> ---
>  drivers/gpu/drm/i915/gt/intel_workarounds.c | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/drivers/gpu/drm/i915/gt/intel_workarounds.c b/drivers/gpu/drm/i915/gt/intel_workarounds.c
> index 3111df350f5722..a00ec692d980c0 100644
> --- a/drivers/gpu/drm/i915/gt/intel_workarounds.c
> +++ b/drivers/gpu/drm/i915/gt/intel_workarounds.c
> @@ -30,7 +30,7 @@
>   *   creation to have a "primed golden context", i.e. a context image that
>   *   already contains the changes needed to all the registers.
>   *
> - *   Context workarounds should be implemented in the *_ctx_workarounds_init()
> + *   Context workarounds should be implemented in the \*_ctx_workarounds_init()
>   *   variants respective to the targeted platforms.
>   *
>   * - Engine workarounds: the list of these WAs is applied whenever the specific
> @@ -55,7 +55,7 @@
>   * - GT workarounds: the list of these WAs is applied whenever these registers
>   *   revert to their default values: on GPU reset, suspend/resume [1]_, etc.
>   *
> - *   GT workarounds should be implemented in the *_gt_workarounds_init()
> + *   GT workarounds should be implemented in the \*_gt_workarounds_init()
>   *   variants respective to the targeted platforms.
>   *
>   * - Register whitelist: some workarounds need to be implemented in userspace,
> @@ -64,7 +64,7 @@
>   *   this is just a special case of a MMIO workaround (as we write the list of
>   *   these to/be-whitelisted registers to some special HW registers).
>   *
> - *   Register whitelisting should be done in the *_whitelist_build() variants
> + *   Register whitelisting should be done in the \*_whitelist_build() variants
>   *   respective to the targeted platforms.
>   *
>   * - Workaround batchbuffers: buffers that get executed automatically by the
> -- 
> An old man doll... just what I always wanted! - Clara
> 

[PATCH 2/3] drm/scheduler: Fix elapsed_ns kernel-doc error

[Bagas Sanjaya]

Stephen Rothwell reported htmldocs warnings:

include/drm/gpu_scheduler.h:232: warning: Incorrect use of kernel-doc format:          * @elapsed_ns
include/drm/gpu_scheduler.h:238: warning: Function parameter or member 'elapsed_ns' not described in 'drm_sched_entity'

Fix the error by appending missing colon to @elapsed_ns name in its
kernel-doc comment.

Link: https://lore.kernel.org/linux-next/20230203135027.1a4679d3@canb.auug.org.au/
Fixes: 248cd9b265fca6 ("drm/scheduler: track GPU active time per entity")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 include/drm/gpu_scheduler.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/drm/gpu_scheduler.h b/include/drm/gpu_scheduler.h
index 9a50365621ed8d..9db9e5e504eeb3 100644
--- a/include/drm/gpu_scheduler.h
+++ b/include/drm/gpu_scheduler.h
@@ -229,7 +229,7 @@ struct drm_sched_entity {
 	struct rb_node			rb_tree_node;
 
 	/**
-	 * @elapsed_ns
+	 * @elapsed_ns:
 	 *
 	 * Records the amount of time where jobs from this entity were active
 	 * on the GPU.
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 2/3] drm/scheduler: Fix elapsed_ns kernel-doc error

[Lucas Stach]

Am Freitag, dem 03.02.2023 um 17:02 +0700 schrieb Bagas Sanjaya:
> Stephen Rothwell reported htmldocs warnings:
> 
> include/drm/gpu_scheduler.h:232: warning: Incorrect use of kernel-doc format:          * @elapsed_ns
> include/drm/gpu_scheduler.h:238: warning: Function parameter or member 'elapsed_ns' not described in 'drm_sched_entity'
> 
> Fix the error by appending missing colon to @elapsed_ns name in its
> kernel-doc comment.
> 

Thanks, I've added this to the etnaviv tree.

Since the commit is only in -next and not a non-rebase tree yet, I
might be tempted to squash the fix into the offending commit. What
would be the right way to credit you for the fix in that case?

Regards,
Lucas

> Link: https://lore.kernel.org/linux-next/20230203135027.1a4679d3@canb.auug.org.au/
> Fixes: 248cd9b265fca6 ("drm/scheduler: track GPU active time per entity")
> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  include/drm/gpu_scheduler.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/include/drm/gpu_scheduler.h b/include/drm/gpu_scheduler.h
> index 9a50365621ed8d..9db9e5e504eeb3 100644
> --- a/include/drm/gpu_scheduler.h
> +++ b/include/drm/gpu_scheduler.h
> @@ -229,7 +229,7 @@ struct drm_sched_entity {
>  	struct rb_node			rb_tree_node;
>  
>  	/**
> -	 * @elapsed_ns
> +	 * @elapsed_ns:
>  	 *
>  	 * Records the amount of time where jobs from this entity were active
>  	 * on the GPU.

Re: [PATCH 2/3] drm/scheduler: Fix elapsed_ns kernel-doc error

[Bagas Sanjaya]

On 2/3/23 18:27, Lucas Stach wrote:
> Thanks, I've added this to the etnaviv tree.
> 
> Since the commit is only in -next and not a non-rebase tree yet, I
> might be tempted to squash the fix into the offending commit. What
> would be the right way to credit you for the fix in that case?
> 

On SoB area, you can add:

[Bagas: Append missing colon to @elapsed_ns]
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[PATCH 3/3] media: v4l2-core: Describe privacy_led field of v4l2_subdev

[Bagas Sanjaya]

Stephen Rothwell reported htmldocs warning:

include/media/v4l2-subdev.h:1088: warning: Function parameter or member 'privacy_led' not described in 'v4l2_subdev'

Describe privacy_led field to fix the warning.

Link: https://lore.kernel.org/linux-next/20230203135303.32da1fc6@canb.auug.org.au/
Fixes: 10d96e289fbd77 ("media: v4l2-core: Make the v4l2-core code enable/disable the privacy LED if present")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 include/media/v4l2-subdev.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
index 1ef5bbbf9d38c8..3e7a97c0657e1c 100644
--- a/include/media/v4l2-subdev.h
+++ b/include/media/v4l2-subdev.h
@@ -1033,6 +1033,7 @@ struct v4l2_subdev_platform_data {
  * @active_state: Active state for the subdev (NULL for subdevs tracking the
  *		  state internally). Initialized by calling
  *		  v4l2_subdev_init_finalize().
+ * @privacy_led: Privacy LED associated with the sub-device.
  * @enabled_streams: Bitmask of enabled streams used by
  *		     v4l2_subdev_enable_streams() and
  *		     v4l2_subdev_disable_streams() helper functions for fallback
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 3/3] media: v4l2-core: Describe privacy_led field of v4l2_subdev

[Sakari Ailus]

Hi Bagas,

On Fri, Feb 03, 2023 at 05:02:15PM +0700, Bagas Sanjaya wrote:
> Stephen Rothwell reported htmldocs warning:
> 
> include/media/v4l2-subdev.h:1088: warning: Function parameter or member 'privacy_led' not described in 'v4l2_subdev'
> 
> Describe privacy_led field to fix the warning.
> 
> Link: https://lore.kernel.org/linux-next/20230203135303.32da1fc6@canb.auug.org.au/
> Fixes: 10d96e289fbd77 ("media: v4l2-core: Make the v4l2-core code enable/disable the privacy LED if present")
> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  include/media/v4l2-subdev.h | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
> index 1ef5bbbf9d38c8..3e7a97c0657e1c 100644
> --- a/include/media/v4l2-subdev.h
> +++ b/include/media/v4l2-subdev.h
> @@ -1033,6 +1033,7 @@ struct v4l2_subdev_platform_data {
>   * @active_state: Active state for the subdev (NULL for subdevs tracking the
>   *		  state internally). Initialized by calling
>   *		  v4l2_subdev_init_finalize().
> + * @privacy_led: Privacy LED associated with the sub-device.
>   * @enabled_streams: Bitmask of enabled streams used by
>   *		     v4l2_subdev_enable_streams() and
>   *		     v4l2_subdev_disable_streams() helper functions for fallback

I'm not sure how this ever was an issue --- privacy_led field was
documented in the same patch that added it.

-- 
Kind regards,

Sakari Ailus