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

[Claude Code Review Bot <claude-review@example.com>]

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