Re: [PATCH v5 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 a4a9326d5b47d5886718e595e77013dc5431312b
Author: Rob Clark <robin.clark@oss.qualcomm.com>

drm/msm: Import adreno_snapshot.h

This commit imports adreno_snapshot.h, based on kgsl_snapshot.h from the
downstream KMD, to be reused for 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 @@

[ ... ]

> +/**
> + * 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 v4 [1], running scripts/kernel-doc on
drivers/gpu/drm/msm/adreno/adreno_snapshot.h produces several kernel-doc
parser warnings.

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

In struct adreno_snapshot_trace_buffer, the top-level comment header omits
the struct keyword ("adreno_snapshot_trace_buffer:" instead of "struct
adreno_snapshot_trace_buffer -"), which causes kernel-doc to treat it as a
function prototype and fail. Additionally, the inline comment for the
segment member is a copy-paste duplicate of @dbgc_ctrl rather than
@segment.

Finally, struct adreno_snapshot_eventlog and struct
adreno_snapshot_gmu_version use inline /** @member: ... */ kernel-doc
comments on their fields without a preceding /** struct ... */ kernel-doc
header on the enclosing structures.

Could these comments be updated to follow standard kernel-doc syntax (or
converted to regular /* ... */ comments if kernel-doc generation is not
intended)?

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

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