[PATCH] drm/amdgpu: amdgpu.h: fix all kernel-doc warnings

[PATCH] drm/amdgpu: amdgpu.h: fix all kernel-doc warnings

[Randy Dunlap]

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'

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 |   39 ++++++++++++++------------
 1 file changed, 21 insertions(+), 18 deletions(-)

--- linux-next-20260227.orig/drivers/gpu/drm/amd/amdgpu/amdgpu.h
+++ linux-next-20260227/drivers/gpu/drm/amd/amdgpu/amdgpu.h
@@ -462,7 +462,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
@@ -540,23 +540,26 @@ struct amdgpu_allowed_register_entry {
  * 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.
+ * @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

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

[Christian König]

On 2/28/26 08:18, Randy Dunlap wrote:
> Use the struct keyword for kernel-doc struct comments.
> Use the correct enum names in enum amd_reset_method.
> 
> This eliminates these warnings:

I was expecting that there would be a few more.

...
> 
> 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 |   39 ++++++++++++++------------
>  1 file changed, 21 insertions(+), 18 deletions(-)
> 
> --- linux-next-20260227.orig/drivers/gpu/drm/amd/amdgpu/amdgpu.h
> +++ linux-next-20260227/drivers/gpu/drm/amd/amdgpu/amdgpu.h
> @@ -462,7 +462,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
> @@ -540,23 +540,26 @@ struct amdgpu_allowed_register_entry {
>   * 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.
> + * @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.

Looks like a good idea in general, but I'm really wondering why we have the define in amdgpu.h in the first place.

While at it please move the enum to amdgpu_reset.h and eventually only forward declare it in amdgpu.h

Apart from that the patch looks good to me.

Thanks,
Christian.

>   *
>   * Methods available for AMD GPU driver for resetting the device. Not all
>   * methods are suitable for every device. User can override the method using

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

[Claude Code Review Bot]

Patch Review

**Fix 1 — struct keyword:**

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

Correct. The kernel-doc parser requires `struct amdgpu_wb` to associate the comment with the struct definition that follows. Without it, kernel-doc cannot understand the prototype, producing the warning at line 477.

**Fix 2 — enum value names:**

The old doc used short names like `@AMD_RESET_LEGACY`, `@AMD_RESET_MODE0`, etc., but the actual enum values in the tree are `AMD_RESET_METHOD_LEGACY`, `AMD_RESET_METHOD_MODE0`, etc. The patch updates all doc entries to match:

```
- * @AMD_RESET_LEGACY: Method reserved for SI, CIK and VI ASICs.
+ * @AMD_RESET_METHOD_LEGACY: Method reserved for SI, CIK and VI ASICs.
```

(and similarly for MODE0, MODE1, MODE2, LINK, BACO, PCI)

This is correct — I verified against the current tree (`amdgpu.h` lines 567–577) that all enum values use the `AMD_RESET_METHOD_` prefix.

**Fix 3 — new enum value documentation:**

```
+ * @AMD_RESET_METHOD_ON_INIT: Does a device reset during the driver init
+ *			  sequence.
```

The enum value `AMD_RESET_METHOD_ON_INIT` exists at line 576 in the tree but was previously undocumented. Adding this entry eliminates the corresponding kernel-doc warning.

**Minor nit (non-blocking):** The alignment of the continuation line for `AMD_RESET_METHOD_ON_INIT` uses tabs aligning to column ~27, while `AMD_RESET_METHOD_PCI` above it aligns its continuation slightly differently (columns 26 vs 27). This is cosmetic and within acceptable variation for kernel-doc comments.

**Another pre-existing nit (non-blocking):** The description for `AMD_RESET_METHOD_MODE0` still contains the phrasing "Not currently available for the any device" — the word "the" is superfluous ("for any device" would be correct). This existed before the patch and is not introduced by it, but the author could fix it while touching these lines.

**Verdict:** The patch is correct and complete. All kernel-doc warnings listed in the commit message are addressed. No functional code is changed.

---
Generated by Claude Code Patch Reviewer

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

[Claude Code Review Bot]

Overall Series Review

Subject: drm/amdgpu: amdgpu.h: fix all kernel-doc warnings
Author: Randy Dunlap <rdunlap@infradead.org>
Patches: 2
Reviewed: 2026-03-03T14:34:13.510119

---

This is a single-patch series from Randy Dunlap fixing kernel-doc warnings in `drivers/gpu/drm/amd/amdgpu/amdgpu.h`. The patch addresses two issues:

1. A missing `struct` keyword in the kernel-doc comment for `amdgpu_wb`.
2. Mismatched enum value names in the kernel-doc for `enum amd_reset_method` — the doc used the old short names (e.g., `AMD_RESET_LEGACY`) while the actual enum values use the `AMD_RESET_METHOD_` prefix (e.g., `AMD_RESET_METHOD_LEGACY`). The patch also adds a missing doc entry for `AMD_RESET_METHOD_ON_INIT`.

The patch is straightforward and correct. It is a documentation-only fix with no functional change.

**Recommendation: Accept / Reviewed-by worthy.**

---
Generated by Claude Code Patch Reviewer