Re: [PATCH v6 01/15] drm/msm: Import adreno_snapshot.h

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] drm/msm/adreno: malformed kernel-doc comments in adreno_snapshot.h
--

commit cce63614223b6a3b321ff4a500f669844fe5791c
Author: Rob Clark <robin.clark@oss.qualcomm.com>

drm/msm: Import adreno_snapshot.h

This commit imports adreno_snapshot.h, containing snapshot data structures
and section definitions based on downstream kgsl_snapshot.h for reuse in
gen8 devcoredump support.

> diff --git a/drivers/gpu/drm/msm/adreno/adreno_snapshot.h b/drivers/gpu/drm/msm/adreno/adreno_snapshot.h
> new file mode 100644
> index 0000000000000..f9956e0bc1d5f
> --- /dev/null
> +++ b/drivers/gpu/drm/msm/adreno/adreno_snapshot.h
> @@ -0,0 +1,321 @@

[ ... ]

> +#define TRACE_BUF_NUM_SIG 4
> +
> +/**
> + * enum trace_buffer_source - Bits to identify the source block of trace buffer information
> + * GX_DBGC : Signals captured from GX block
> + * CX_DBGC : Signals captured from CX block
> + */
> +enum trace_buffer_source {
> +	GX_DBGC = 1,
> +	CX_DBGC = 2,
> +};
> +
> +/**
> + * adreno_snapshot_trace_buffer: Header Information for the tracebuffer in snapshot.
> + */
> +struct adreno_snapshot_trace_buffer {
> +	/** @dbgc_ctrl: Identify source for trace */
> +	__u16 dbgc_ctrl;
> +	/** @dbgc_ctrl: Identify source for trace */
> +	__u16 segment;
> +	/** @granularity: The total number of segments in each packet */
> +	__u16 granularity;
> +	/** @ping_blk: Signal block */
> +	__u16 ping_blk[TRACE_BUF_NUM_SIG];
> +	/** @ping_idx: Signal Index */
> +	__u16 ping_idx[TRACE_BUF_NUM_SIG];
> +	/** @size: Number of bytes in the dump */
> +	__u32 size;
> +} __packed;
> +
> +#define SNAPSHOT_GPU_OBJECT_SHADER  1
> +#define SNAPSHOT_GPU_OBJECT_IB      2
> +#define SNAPSHOT_GPU_OBJECT_GENERIC 3
> +#define SNAPSHOT_GPU_OBJECT_DRAW    4
> +#define SNAPSHOT_GPU_OBJECT_GLOBAL  5
> +
> +struct adreno_snapshot_gpu_object_v2 {
> +	int type;      /* Type of GPU object */
> +	__u64 gpuaddr; /* GPU address of the object */
> +	__u64 ptbase;  /* Base for the pagetable the GPU address is valid in */
> +	__u64 size;    /* Size of the object (in dwords) */
> +} __packed;
> +
> +struct adreno_snapshot_eventlog {
> +	/** @type: Type of the event log buffer */
> +	__u16 type;
> +	/** @version: Version of the event log buffer */
> +	__u16 version;
> +	/** @size: Size of the eventlog buffer in bytes */
> +	u32 size;
> +} __packed;
> +
> +struct adreno_snapshot_gmu_version {
> +	/** @type: Type of the GMU version buffer */
> +	u32 type;
> +	/** @value: GMU FW version value */
> +	u32 value;
> +} __packed;

[Severity: Low]
As reported by Sashiko on v5 [1], running scripts/kernel-doc on
drivers/gpu/drm/msm/adreno/adreno_snapshot.h will trigger warnings due to a
few malformed kernel-doc comments here:

1. In enum trace_buffer_source, the GX_DBGC and CX_DBGC descriptions are
missing the leading @ prefix (@GX_DBGC: and @CX_DBGC:), causing kernel-doc
to warn that both enum values are not described.

2. Above struct adreno_snapshot_trace_buffer, the comment header omits the
struct keyword ("adreno_snapshot_trace_buffer:" instead of
"struct adreno_snapshot_trace_buffer -"), causing kernel-doc to parse it as
a function prototype and fail.

3. Inside struct adreno_snapshot_trace_buffer, the inline comment for the
segment member is duplicated as @dbgc_ctrl instead of @segment, overwriting
the dbgc_ctrl description and leaving segment undocumented.

4. Both struct adreno_snapshot_eventlog and struct adreno_snapshot_gmu_version
use inline /** @member: ... */ kernel-doc comments without a top-level
/** struct ... */ kernel-doc comment on the enclosing structures.

Could these comments be updated to match the expected kernel-doc format (or
converted to regular comments if kernel-doc generation is not intended)?

[1] https://lore.kernel.org/r/20261102220405.30730-2-robin.clark@oss.qualcomm.com

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20261105203057.66520-1-robin.clark@oss.qualcomm.com?part=1