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

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

[Omokefe Emmanuel Onanaroghene]

Hi Christian,

On 10/2/26 13:38, Christian König wrote:
> We should potentially just completely nuke those typedefs since they
> are actually an unnecessarily layer of indirection.

Yes, the cleanup is necessary, but the four comments don't just name the typedefs, they're the only prose describing the operations (MMIO vs indirect access, offset/space/index semantics, return values). Should i relocated onto the struct cgs_ops members or the cgs_read_register macros?

Thanks,
Omokefe