Re: [PATCH v3] drm/amdgpu: amdgpu{_reset}.h: fix all kernel-doc warnings

[Christian König <christian.koenig@amd.com>]

On 4/27/26 20:38, Randy Dunlap wrote:
> Fix all kernel-doc warnings in amdgpu.h and amdgpu_reset.h:
> - Use the struct keyword for kernel-doc struct comments.
> - Use the correct enum names in enum amd_reset_method.
> 
> This eliminates these warnings:
> 
> Warning: drivers/gpu/drm/amd/amdgpu/amdgpu.h:477 cannot understand
>  function prototype: 'struct amdgpu_wb'
> Warning: drivers/gpu/drm/amd/amdgpu/amdgpu.h:576 Enum value
>  'AMD_RESET_METHOD_LEGACY' not described in enum 'amd_reset_method'
> Warning: drivers/gpu/drm/amd/amdgpu/amdgpu.h:576 Enum value
>  'AMD_RESET_METHOD_MODE0' not described in enum 'amd_reset_method'
> Warning: drivers/gpu/drm/amd/amdgpu/amdgpu.h:576 Enum value
>  'AMD_RESET_METHOD_MODE1' not described in enum 'amd_reset_method'
> Warning: drivers/gpu/drm/amd/amdgpu/amdgpu.h:576 Enum value
>  'AMD_RESET_METHOD_MODE2' not described in enum 'amd_reset_method'
> Warning: drivers/gpu/drm/amd/amdgpu/amdgpu.h:576 Enum value
>  'AMD_RESET_METHOD_LINK' not described in enum 'amd_reset_method'
> Warning: drivers/gpu/drm/amd/amdgpu/amdgpu.h:576 Enum value
>  'AMD_RESET_METHOD_BACO' not described in enum 'amd_reset_method'
> Warning: drivers/gpu/drm/amd/amdgpu/amdgpu.h:576 Enum value
>  'AMD_RESET_METHOD_PCI' not described in enum 'amd_reset_method'
> Warning: drivers/gpu/drm/amd/amdgpu/amdgpu.h:576 Enum value
>  'AMD_RESET_METHOD_ON_INIT' not described in enum 'amd_reset_method'
> Warning: drivers/gpu/drm/amd/amdgpu/amdgpu.h:576 Excess enum value
>  '@AMD_RESET_LEGACY' description in 'amd_reset_method'
> Warning: drivers/gpu/drm/amd/amdgpu/amdgpu.h:576 Excess enum value
>  '@AMD_RESET_MODE0' description in 'amd_reset_method'
> Warning: drivers/gpu/drm/amd/amdgpu/amdgpu.h:576 Excess enum value
>  '@AMD_RESET_MODE1' description in 'amd_reset_method'
> Warning: drivers/gpu/drm/amd/amdgpu/amdgpu.h:576 Excess enum value
>  '@AMD_RESET_MODE2' description in 'amd_reset_method'
> Warning: drivers/gpu/drm/amd/amdgpu/amdgpu.h:576 Excess enum value
>  '@AMD_RESET_LINK' description in 'amd_reset_method'
> Warning: drivers/gpu/drm/amd/amdgpu/amdgpu.h:576 Excess enum value
>  '@AMD_RESET_BACO' description in 'amd_reset_method'
> Warning: drivers/gpu/drm/amd/amdgpu/amdgpu.h:576 Excess enum value
>  '@AMD_RESET_PCI' description in 'amd_reset_method'
> 
> Also move the enum to amdgpu_reset.h and eventually only forward declare
> it in amdgpu.h. (Christian)
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>

Acked-by: Christian König <christian.koenig@amd.com>

> ---
> v2: I moved the enum to amdgpu_reset.h and then #included amdgpu_reset.h
>     in amdgpu.h. The simpler method causes build errors.
> v3: rebase and resend
> 
> Cc: Alex Deucher <alexander.deucher@amd.com>
> Cc: Christian König <christian.koenig@amd.com>
> Cc: amd-gfx@lists.freedesktop.org
> Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
> Cc: Maxime Ripard <mripard@kernel.org>
> Cc: Thomas Zimmermann <tzimmermann@suse.de>
> Cc: David Airlie <airlied@gmail.com>
> Cc: Simona Vetter <simona@ffwll.ch>
> 
>  drivers/gpu/drm/amd/amdgpu/amdgpu.h       |   42 ------------
>  drivers/gpu/drm/amd/amdgpu/amdgpu_reset.h |   69 +++++++++++++++-----
>  2 files changed, 58 insertions(+), 53 deletions(-)
> 
> --- linux-next-20260427.orig/drivers/gpu/drm/amd/amdgpu/amdgpu.h
> +++ linux-next-20260427/drivers/gpu/drm/amd/amdgpu/amdgpu.h
> @@ -464,7 +464,7 @@ int amdgpu_file_to_fpriv(struct file *fi
>  #define AMDGPU_MAX_WB 1024	/* Reserve at most 1024 WB slots for amdgpu-owned rings. */
>  
>  /**
> - * amdgpu_wb - This struct is used for small GPU memory allocation.
> + * struct amdgpu_wb - This struct is used for small GPU memory allocation.
>   *
>   * This struct is used to allocate a small amount of GPU memory that can be
>   * used to shadow certain states into the memory. This is especially useful for
> @@ -538,44 +538,6 @@ struct amdgpu_allowed_register_entry {
>  	bool grbm_indexed;
>  };
>  
> -/**
> - * enum amd_reset_method - Methods for resetting AMD GPU devices
> - *
> - * @AMD_RESET_METHOD_NONE: The device will not be reset.
> - * @AMD_RESET_LEGACY: Method reserved for SI, CIK and VI ASICs.
> - * @AMD_RESET_MODE0: Reset the entire ASIC. Not currently available for the
> - *                   any device.
> - * @AMD_RESET_MODE1: Resets all IP blocks on the ASIC (SDMA, GFX, VCN, etc.)
> - *                   individually. Suitable only for some discrete GPU, not
> - *                   available for all ASICs.
> - * @AMD_RESET_MODE2: Resets a lesser level of IPs compared to MODE1. Which IPs
> - *                   are reset depends on the ASIC. Notably doesn't reset IPs
> - *                   shared with the CPU on APUs or the memory controllers (so
> - *                   VRAM is not lost). Not available on all ASICs.
> - * @AMD_RESET_LINK: Triggers SW-UP link reset on other GPUs
> - * @AMD_RESET_BACO: BACO (Bus Alive, Chip Off) method powers off and on the card
> - *                  but without powering off the PCI bus. Suitable only for
> - *                  discrete GPUs.
> - * @AMD_RESET_PCI: Does a full bus reset using core Linux subsystem PCI reset
> - *                 and does a secondary bus reset or FLR, depending on what the
> - *                 underlying hardware supports.
> - *
> - * Methods available for AMD GPU driver for resetting the device. Not all
> - * methods are suitable for every device. User can override the method using
> - * module parameter `reset_method`.
> - */
> -enum amd_reset_method {
> -	AMD_RESET_METHOD_NONE = -1,
> -	AMD_RESET_METHOD_LEGACY = 0,
> -	AMD_RESET_METHOD_MODE0,
> -	AMD_RESET_METHOD_MODE1,
> -	AMD_RESET_METHOD_MODE2,
> -	AMD_RESET_METHOD_LINK,
> -	AMD_RESET_METHOD_BACO,
> -	AMD_RESET_METHOD_PCI,
> -	AMD_RESET_METHOD_ON_INIT,
> -};
> -
>  struct amdgpu_video_codec_info {
>  	u32 codec_type;
>  	u32 max_width;
> @@ -1373,6 +1335,8 @@ int emu_soc_asic_init(struct amdgpu_devi
>  #define RBIOS16(i) (RBIOS8(i) | (RBIOS8((i)+1) << 8))
>  #define RBIOS32(i) ((RBIOS16(i)) | (RBIOS16((i)+2) << 16))
>  
> +#include "amdgpu_reset.h"
> +
>  /*
>   * ASICs macro.
>   */
> --- linux-next-20260427.orig/drivers/gpu/drm/amd/amdgpu/amdgpu_reset.h
> +++ linux-next-20260427/drivers/gpu/drm/amd/amdgpu/amdgpu_reset.h
> @@ -46,6 +46,47 @@ enum AMDGPU_RESET_SRCS {
>  	AMDGPU_RESET_SRC_USERQ,
>  };
>  
> +/**
> + * enum amd_reset_method - Methods for resetting AMD GPU devices
> + *
> + * @AMD_RESET_METHOD_NONE: The device will not be reset.
> + * @AMD_RESET_METHOD_LEGACY: Method reserved for SI, CIK and VI ASICs.
> + * @AMD_RESET_METHOD_MODE0: Reset the entire ASIC. Not currently available for
> + *                          the any device.
> + * @AMD_RESET_METHOD_MODE1: Resets all IP blocks on the ASIC (SDMA, GFX, VCN,
> + *                   etc.) individually. Suitable only for some discrete GPU,
> + *                   not available for all ASICs.
> + * @AMD_RESET_METHOD_MODE2: Resets a lesser level of IPs compared to MODE1.
> + *                   Which IPs are reset depends on the ASIC. Notably doesn't
> + *                   reset IPs shared with the CPU on APUs or the memory
> + *                   controllers (so VRAM is not lost). Not available on all
> + *                   ASICs.
> + * @AMD_RESET_METHOD_LINK: Triggers SW-UP link reset on other GPUs
> + * @AMD_RESET_METHOD_BACO: BACO (Bus Alive, Chip Off) method powers off and on
> + *                   the card but without powering off the PCI bus. Suitable
> + *                   only for discrete GPUs.
> + * @AMD_RESET_METHOD_PCI: Does a full bus reset using core Linux subsystem
> + *                   PCI reset and does a secondary bus reset or FLR,
> + *                   depending on what the underlying hardware supports.
> + * @AMD_RESET_METHOD_ON_INIT: Does a device reset during the driver init
> + *                   sequence.
> + *
> + * Methods available for AMD GPU driver for resetting the device. Not all
> + * methods are suitable for every device. User can override the method using
> + * module parameter `reset_method`.
> + */
> +enum amd_reset_method {
> +	AMD_RESET_METHOD_NONE = -1,
> +	AMD_RESET_METHOD_LEGACY = 0,
> +	AMD_RESET_METHOD_MODE0,
> +	AMD_RESET_METHOD_MODE1,
> +	AMD_RESET_METHOD_MODE2,
> +	AMD_RESET_METHOD_LINK,
> +	AMD_RESET_METHOD_BACO,
> +	AMD_RESET_METHOD_PCI,
> +	AMD_RESET_METHOD_ON_INIT,
> +};
> +
>  struct amdgpu_reset_context {
>  	enum amd_reset_method method;
>  	struct amdgpu_device *reset_req_dev;
> @@ -56,6 +97,20 @@ struct amdgpu_reset_context {
>  	enum AMDGPU_RESET_SRCS src;
>  };
>  
> +struct amdgpu_reset_control {
> +	void *handle;
> +	struct work_struct reset_work;
> +	struct mutex reset_lock;
> +	struct amdgpu_reset_handler *(
> +		*reset_handlers)[AMDGPU_RESET_MAX_HANDLERS];
> +	atomic_t in_reset;
> +	enum amd_reset_method active_reset;
> +	struct amdgpu_reset_handler *(*get_reset_handler)(
> +		struct amdgpu_reset_control *reset_ctl,
> +		struct amdgpu_reset_context *context);
> +	void (*async_reset)(struct work_struct *work);
> +};
> +
>  struct amdgpu_reset_handler {
>  	enum amd_reset_method reset_method;
>  	int (*prepare_env)(struct amdgpu_reset_control *reset_ctl,
> @@ -72,20 +127,6 @@ struct amdgpu_reset_handler {
>  	int (*do_reset)(struct amdgpu_device *adev);
>  };
>  
> -struct amdgpu_reset_control {
> -	void *handle;
> -	struct work_struct reset_work;
> -	struct mutex reset_lock;
> -	struct amdgpu_reset_handler *(
> -		*reset_handlers)[AMDGPU_RESET_MAX_HANDLERS];
> -	atomic_t in_reset;
> -	enum amd_reset_method active_reset;
> -	struct amdgpu_reset_handler *(*get_reset_handler)(
> -		struct amdgpu_reset_control *reset_ctl,
> -		struct amdgpu_reset_context *context);
> -	void (*async_reset)(struct work_struct *work);
> -};
> -
>  
>  enum amdgpu_reset_domain_type {
>  	SINGLE_DEVICE,