Re: [PATCH v4 4/4] dmaengine: add union chan_dev for dma_chan::dev for clarity

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] Kernel-doc build warning introduced by removing the `@dev:` documentation tag while retaining `dev` in the structure.
--

commit 0443f99a737aae399ea7d93dad586cf7543a34af
Author: Frank Li <Frank.Li@nxp.com>

dmaengine: add union chan_dev for dma_chan::dev for clarity

This commit introduces an anonymous union in struct dma_chan to provide 
a chan_dev member alongside the existing dev member, clarifying its purpose as 
the per-channel device. It also updates the kernel-doc to document chan_dev 
instead of dev.

> diff --git a/include/linux/dmaengine.h b/include/linux/dmaengine.h
> index 33aa1bfc8fb84..c3a49a33307c6 100644
> --- a/include/linux/dmaengine.h
> +++ b/include/linux/dmaengine.h
> @@ -325,7 +325,8 @@ struct dma_router {
>   * @lock: protect between config and prepare transfer when driver have not
>   *	  implemented callback device_prep_config_sg().
>   * @chan_id: channel ID for sysfs
> - * @dev: class device for sysfs
> + * @chan_dev: class channel device for sysfs, some device use it for per-channel
> + *            IOMMU mapping.
>   * @name: backlink name for sysfs
>   * @dbg_client_name: slave name for debugfs in format:

[ ... ]

> @@ -351,7 +352,14 @@ struct dma_chan {
>  
>  	/* sysfs */
>  	int chan_id;
> -	struct dma_chan_dev *dev;
> +	union {
> +		struct dma_chan_dev *chan_dev;
> +		/*
> +		 * Use chan_dev; dev will be removed once all users are
> +		 * converted.
> +		 */
> +		struct dma_chan_dev *dev;
> +	};

[Severity: Low]
Does this removal of the @dev kernel-doc tag trigger a kernel-doc build 
warning?

Since the dev member is kept inside an anonymous union for backward 
compatibility, and the kernel-doc parser flattens anonymous unions, it 
typically expects all non-private members to be explicitly documented. 

Would it be better to retain the @dev documentation tag with a note 
indicating it is deprecated, or mark it as private to avoid the build 
warning?

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260909-dma-chan_dev-rename-v4-0-d8fb6892a70f@nxp.com?part=4