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

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

[Randy Dunlap]

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

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

[Christian König]

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,

Claude review: drm/amdgpu: amdgpu{_reset}.h: fix all kernel-doc warnings

[Claude Code Review Bot]

Overall Series Review

Subject: drm/amdgpu: amdgpu{_reset}.h: fix all kernel-doc warnings
Author: Randy Dunlap <rdunlap@infradead.org>
Patches: 2
Reviewed: 2026-04-28T14:07:09.903313

---

This is a single-patch series by Randy Dunlap (v3) that fixes kernel-doc warnings in `amdgpu.h` and `amdgpu_reset.h`. The patch makes three changes: (1) adds the missing `struct` keyword to the `amdgpu_wb` kernel-doc comment, (2) moves the `enum amd_reset_method` from `amdgpu.h` to `amdgpu_reset.h` and fixes the doc tag names to match the actual enum values, and (3) reorders `struct amdgpu_reset_control` relative to `struct amdgpu_reset_handler` in `amdgpu_reset.h`.

The kernel-doc fixes themselves are correct. However, the patch has a likely **build breakage** in the drm-next tree and an unexplained structural change.

---

---
Generated by Claude Code Patch Reviewer

Claude review: drm/amdgpu: amdgpu{_reset}.h: fix all kernel-doc warnings

[Claude Code Review Bot]

Patch Review

**Kernel-doc fixes (correct):**

The `struct` keyword fix is straightforward and correct:
```c
- * amdgpu_wb - This struct is used for small GPU memory allocation.
+ * struct amdgpu_wb - This struct is used for small GPU memory allocation.
```

The enum doc tag renames are correct — the old doc used short names like `@AMD_RESET_LEGACY` while the actual enum values are `AMD_RESET_METHOD_LEGACY`. The patch also adds the previously undocumented `@AMD_RESET_METHOD_ON_INIT` entry:
```c
+ * @AMD_RESET_METHOD_ON_INIT: Does a device reset during the driver init
+ *                   sequence.
```

**Potential build breakage with `#include` placement:**

In the drm-next tree, `struct amdgpu_asic_funcs` at `amdgpu.h:610` uses the enum:
```c
enum amd_reset_method (*reset_method)(struct amdgpu_device *adev);
```

The patch removes the enum from its original position (around line 567) and adds `#include "amdgpu_reset.h"` much later in the file, after the RBIOS macros (~line 1375):
```c
 #define RBIOS32(i) ((RBIOS16(i)) | (RBIOS16((i)+2) << 16))

+#include "amdgpu_reset.h"
```

Since C does not support forward declarations of enums, `struct amdgpu_asic_funcs` at line 610 would reference an undefined type — the enum definition (now in `amdgpu_reset.h`) isn't available until ~line 1375. This should be a compile error. The patch might build against the author's linux-next tree if `struct amdgpu_asic_funcs` was modified there, but it will not work against drm-next as-is.

If the `#include` must stay in `amdgpu.h`, it should be placed **before** `struct amdgpu_asic_funcs`, ideally near the top of the file with the other local includes (lines 59–101). The v2 changelog says "The simpler method causes build errors" — likely because `amdgpu_reset.h` already `#include`s `amdgpu.h` (line 27), creating a circular dependency. This is the root problem: fixing it properly would require breaking the circular include between `amdgpu.h` and `amdgpu_reset.h`, not burying the include deep in the file to sidestep ordering.

**Circular include:**

Adding `#include "amdgpu_reset.h"` to `amdgpu.h` while `amdgpu_reset.h` already has `#include "amdgpu.h"` creates a circular dependency. The include guards prevent infinite recursion, but the approach is fragile — correctness depends on which file is included first and exactly where in the file each cross-include appears. This should at minimum be acknowledged in the commit message.

**Unexplained struct reordering:**

The patch moves `struct amdgpu_reset_control` ahead of `struct amdgpu_reset_handler` in `amdgpu_reset.h`. This change is not mentioned in the commit message and is not related to fixing kernel-doc warnings. Both structs reference each other only via pointers, so the reorder is safe in practice, but unexplained changes should not be mixed in with doc fixes. If there is a reason (e.g., putting it closer to the enum it uses), it should be stated.

**Minor: preserved typo in documentation:**

The moved doc block preserves a minor grammatical error from the original:
```c
+ * @AMD_RESET_METHOD_MODE0: Reset the entire ASIC. Not currently available for
+ *                          the any device.
```
Should be "for any device" (drop "the"). Worth fixing while touching this block.

**Summary:** The kernel-doc tag fixes are correct and welcome, but the include placement likely breaks the build against drm-next, and the circular include / struct reordering need to be addressed or at least justified. I'd suggest either moving the `#include` to before the first use of the enum (and dealing with the resulting circular include issues properly) or using a forward declaration approach with a separate header for just the enum.

---
Generated by Claude Code Patch Reviewer

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

[Randy Dunlap]

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)
I moved the enum to amdgpu_reset.h and then #included amdgpu_reset.h
in amdgpu.h. The simpler method causes build errors.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
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-20260304.orig/drivers/gpu/drm/amd/amdgpu/amdgpu.h
+++ linux-next-20260304/drivers/gpu/drm/amd/amdgpu/amdgpu.h
@@ -463,7 +463,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
@@ -537,44 +537,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;
@@ -1371,6 +1333,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-20260304.orig/drivers/gpu/drm/amd/amdgpu/amdgpu_reset.h
+++ linux-next-20260304/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,

Claude review: drm/amdgpu: amdgpu{_reset}.h: fix all kernel-doc warnings

[Claude Code Review Bot]

Patch Review

**Doc fix for `amdgpu_wb` — Correct:**

```c
- * amdgpu_wb - This struct is used for small GPU memory allocation.
+ * struct amdgpu_wb - This struct is used for small GPU memory allocation.
```

Straightforward and correct. The `struct` keyword is required by kernel-doc.

**Enum doc name fixes — Correct:**

The doc comments now use `@AMD_RESET_METHOD_LEGACY`, `@AMD_RESET_METHOD_MODE0`, etc., matching the actual enum member names. Previously the docs used shortened names (`@AMD_RESET_LEGACY`, `@AMD_RESET_MODE0`) that didn't match. The new `@AMD_RESET_METHOD_ON_INIT` description is also a good addition — it was previously undocumented.

**Circular include / forward reference issue — Problem:**

`amdgpu_reset.h` includes `amdgpu.h` at line 27:
```c
#include "amdgpu.h"
```

The patch adds `#include "amdgpu_reset.h"` near line 1335 of `amdgpu.h`:
```c
+#include "amdgpu_reset.h"
```

But `enum amd_reset_method` is used at `amdgpu.h:572`:
```c
enum amd_reset_method (*reset_method)(struct amdgpu_device *adev);
```

When a compilation unit includes `amdgpu.h` first, the compiler reaches line 572 (the `reset_method` function pointer using `enum amd_reset_method`) before the `#include "amdgpu_reset.h"` at line 1335 where the enum is now defined. The enum type is used ~760 lines before it becomes visible.

GCC may tolerate this as a GNU extension (implicit forward declaration of the enum), but it's not clean C and may produce warnings with stricter compilers. A better approach would be to either:
- Place the `#include "amdgpu_reset.h"` before the struct that uses the enum (but this requires care with the circular dependency), or
- Add a forward declaration of the enum before its first use, or
- Break the circular dependency by having `amdgpu_reset.h` not include `amdgpu.h` and instead use forward declarations for the types it needs.

**Unexplained struct reorder in `amdgpu_reset.h`:**

The patch moves `struct amdgpu_reset_control` above `struct amdgpu_reset_handler`. This reordering is not mentioned in the commit message and doesn't fix any kernel-doc warning. Both structs reference each other only through pointers, so the order doesn't matter for compilation, but the change adds unnecessary noise to the diff. If there's a reason for this move, it should be documented in the commit message.

**Minor nit in comment text:**

The MODE0 description still has "the any device" (carried over from the original):
```
 * @AMD_RESET_METHOD_MODE0: Reset the entire ASIC. Not currently available for
 *                          the any device.
```
Should be "any device" (drop the extra "the"). Since this patch is already touching these comments, it would be a good opportunity to fix this typo.

---
Generated by Claude Code Patch Reviewer

Claude review: drm/amdgpu: amdgpu{_reset}.h: fix all kernel-doc warnings

[Claude Code Review Bot]

Overall Series Review

Subject: drm/amdgpu: amdgpu{_reset}.h: fix all kernel-doc warnings
Author: Randy Dunlap <rdunlap@infradead.org>
Patches: 1
Reviewed: 2026-03-05T13:13:38.346272

---

This is a single patch (v2) that fixes kernel-doc warnings in `amdgpu.h` and `amdgpu_reset.h`. It addresses three things: (1) adding the missing `struct` keyword to the `amdgpu_wb` doc comment, (2) updating enum member names in the `amd_reset_method` doc to match the actual code (`AMD_RESET_METHOD_*` instead of `AMD_RESET_*`), and (3) moving the `enum amd_reset_method` definition from `amdgpu.h` to `amdgpu_reset.h` per reviewer feedback. The doc fixes are correct, but the include placement creates a problematic ordering issue, and there's an unexplained struct reorder.

---
Generated by Claude Code Patch Reviewer