[PATCH] drm/amd/display: fix kernel-doc warnings for cgs register typedefs

[PATCH] drm/amd/display: fix kernel-doc warnings for cgs register typedefs

[Omokefe Emmanuel Onanaroghene]

kernel-doc reports prototype mismatches for the cgs register accessor
typedefs, whose comments do not use the documented typedef format, e.g.:

  drivers/gpu/drm/amd/include/cgs_common.h:89 ... expecting prototype
  for cgs_read_register(). Prototype was for uint32_t() instead

Use the typedef comment format for all four accessors (also restoring
the dropped _t suffix) and replace the wrong @offset with the real
@space/@index params in the two indirect-register comments.

Signed-off-by: Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com>
---
 drivers/gpu/drm/amd/include/cgs_common.h | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/drivers/gpu/drm/amd/include/cgs_common.h b/drivers/gpu/drm/amd/include/cgs_common.h
index f40b6a03fe63..3a25c3c75a3a 100644
--- a/drivers/gpu/drm/amd/include/cgs_common.h
+++ b/drivers/gpu/drm/amd/include/cgs_common.h
@@ -81,7 +81,7 @@ struct cgs_firmware_info {
 typedef unsigned long cgs_handle_t;
 
 /**
- * cgs_read_register() - Read an MMIO register
+ * typedef cgs_read_register_t - Read an MMIO register
  * @cgs_device:	opaque device handle
  * @offset:	register offset
  *
@@ -90,7 +90,7 @@ typedef unsigned long cgs_handle_t;
 typedef uint32_t (*cgs_read_register_t)(struct cgs_device *cgs_device, unsigned offset);
 
 /**
- * cgs_write_register() - Write an MMIO register
+ * typedef cgs_write_register_t - Write an MMIO register
  * @cgs_device:	opaque device handle
  * @offset:	register offset
  * @value:	register value
@@ -99,9 +99,10 @@ typedef void (*cgs_write_register_t)(struct cgs_device *cgs_device, unsigned off
 				     uint32_t value);
 
 /**
- * cgs_read_ind_register() - Read an indirect register
+ * typedef cgs_read_ind_register_t - Read an indirect register
  * @cgs_device:	opaque device handle
- * @offset:	register offset
+ * @space:	indirect register space
+ * @index:	register index
  *
  * Return:  register value
  */
@@ -109,9 +110,10 @@ typedef uint32_t (*cgs_read_ind_register_t)(struct cgs_device *cgs_device, enum
 					    unsigned index);
 
 /**
- * cgs_write_ind_register() - Write an indirect register
+ * typedef cgs_write_ind_register_t - Write an indirect register
  * @cgs_device:	opaque device handle
- * @offset:	register offset
+ * @space:	indirect register space
+ * @index:	register index
  * @value:	register value
  */
 typedef void (*cgs_write_ind_register_t)(struct cgs_device *cgs_device, enum cgs_ind_reg space,
-- 
2.43.0

Re: [PATCH] drm/amd/display: fix kernel-doc warnings for cgs register typedefs

[Christian König]

On 10/2/26 04:17, Omokefe Emmanuel Onanaroghene wrote:
> kernel-doc reports prototype mismatches for the cgs register accessor
> typedefs, whose comments do not use the documented typedef format, e.g.:
> 
>   drivers/gpu/drm/amd/include/cgs_common.h:89 ... expecting prototype
>   for cgs_read_register(). Prototype was for uint32_t() instead
> 
> Use the typedef comment format for all four accessors (also restoring
> the dropped _t suffix) and replace the wrong @offset with the real
> @space/@index params in the two indirect-register comments.
> 
> Signed-off-by: Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com>

We should potentially just completely nuke those typedefs since they are actually an unnecessarily layer of indirection.

Regards,
Christian.

> ---
>  drivers/gpu/drm/amd/include/cgs_common.h | 14 ++++++++------
>  1 file changed, 8 insertions(+), 6 deletions(-)
> 
> diff --git a/drivers/gpu/drm/amd/include/cgs_common.h b/drivers/gpu/drm/amd/include/cgs_common.h
> index f40b6a03fe63..3a25c3c75a3a 100644
> --- a/drivers/gpu/drm/amd/include/cgs_common.h
> +++ b/drivers/gpu/drm/amd/include/cgs_common.h
> @@ -81,7 +81,7 @@ struct cgs_firmware_info {
>  typedef unsigned long cgs_handle_t;
> 
>  /**
> - * cgs_read_register() - Read an MMIO register
> + * typedef cgs_read_register_t - Read an MMIO register
>   * @cgs_device:        opaque device handle
>   * @offset:    register offset
>   *
> @@ -90,7 +90,7 @@ typedef unsigned long cgs_handle_t;
>  typedef uint32_t (*cgs_read_register_t)(struct cgs_device *cgs_device, unsigned offset);
> 
>  /**
> - * cgs_write_register() - Write an MMIO register
> + * typedef cgs_write_register_t - Write an MMIO register
>   * @cgs_device:        opaque device handle
>   * @offset:    register offset
>   * @value:     register value
> @@ -99,9 +99,10 @@ typedef void (*cgs_write_register_t)(struct cgs_device *cgs_device, unsigned off
>                                      uint32_t value);
> 
>  /**
> - * cgs_read_ind_register() - Read an indirect register
> + * typedef cgs_read_ind_register_t - Read an indirect register
>   * @cgs_device:        opaque device handle
> - * @offset:    register offset
> + * @space:     indirect register space
> + * @index:     register index
>   *
>   * Return:  register value
>   */
> @@ -109,9 +110,10 @@ typedef uint32_t (*cgs_read_ind_register_t)(struct cgs_device *cgs_device, enum
>                                             unsigned index);
> 
>  /**
> - * cgs_write_ind_register() - Write an indirect register
> + * typedef cgs_write_ind_register_t - Write an indirect register
>   * @cgs_device:        opaque device handle
> - * @offset:    register offset
> + * @space:     indirect register space
> + * @index:     register index
>   * @value:     register value
>   */
>  typedef void (*cgs_write_ind_register_t)(struct cgs_device *cgs_device, enum cgs_ind_reg space,
> --
> 2.43.0
>