[v4,4/4] dmaengine: add union chan_dev for dma_chan::dev for clarity
Commit Message
From: Frank Li <Frank.Li@nxp.com>
The current dma_chan structure contains both "device" and "dev". So
chan->device->dev refers to the DMA engine device.
chan->dev->device refers to the per-channel device instance.
Their similar naming makes the distinction unclear and increases reader
confusion.
Add union dma_chan::chan_dev to make its purpose explicit and clearly
identify it as the per-channel device. After all user switch to chan_dev,
union and dma_chan::dev will be removed.
Update the kernel-doc accordingly. Besides its sysfs usage, the per-channel
device is also used by some DMA engine drivers for IOMMU mapping and
therefore deserves a more accurate description.
No functional change intended.
Reviewed-by: Logan Gunthorpe <logang@deltatee.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: Frank Li <Frank.Li@nxp.com>
---
there are other user use it outside drivers/dma/ directory.
---
drivers/dma/dmaengine.c | 14 +++++++-------
drivers/dma/tegra186-gpc-dma.c | 2 +-
drivers/dma/ti/k3-udma.c | 4 ++--
include/linux/dmaengine.h | 18 +++++++++++++-----
4 files changed, 23 insertions(+), 15 deletions(-)
Comments
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?
@@ -1083,8 +1083,8 @@ static int __dma_async_device_channel_register(struct dma_device *device,
chan->local = alloc_percpu(typeof(*chan->local));
if (!chan->local)
return -ENOMEM;
- chan->dev = kzalloc_obj(*chan->dev);
- if (!chan->dev) {
+ chan->chan_dev = kzalloc_obj(*chan->chan_dev);
+ if (!chan->chan_dev) {
rc = -ENOMEM;
goto err_free_local;
}
@@ -1103,8 +1103,8 @@ static int __dma_async_device_channel_register(struct dma_device *device,
dmaengine_chan_dev(chan)->class = &dma_devclass;
dmaengine_chan_dev(chan)->parent = device->dev;
- chan->dev->chan = chan;
- chan->dev->dev_id = device->dev_id;
+ chan->chan_dev->chan = chan;
+ chan->chan_dev->dev_id = device->dev_id;
spin_lock_init(&chan->lock);
if (!name)
@@ -1122,7 +1122,7 @@ static int __dma_async_device_channel_register(struct dma_device *device,
err_out_ida:
ida_free(&device->chan_ida, chan->chan_id);
err_free_dev:
- kfree(chan->dev);
+ kfree(chan->chan_dev);
err_free_local:
free_percpu(chan->local);
chan->local = NULL;
@@ -1155,7 +1155,7 @@ static void __dma_async_device_channel_unregister(struct dma_device *device,
__func__, chan->client_count);
mutex_lock(&dma_list_mutex);
device->chancnt--;
- chan->dev->chan = NULL;
+ chan->chan_dev->chan = NULL;
mutex_unlock(&dma_list_mutex);
ida_free(&device->chan_ida, chan->chan_id);
device_unregister(dmaengine_chan_dev(chan));
@@ -1290,7 +1290,7 @@ int dma_async_device_register(struct dma_device *device)
if (chan->local == NULL)
continue;
mutex_lock(&dma_list_mutex);
- chan->dev->chan = NULL;
+ chan->chan_dev->chan = NULL;
mutex_unlock(&dma_list_mutex);
device_unregister(dmaengine_chan_dev(chan));
free_percpu(chan->local);
@@ -1554,7 +1554,7 @@ static int tegra_dma_probe(struct platform_device *pdev)
return dev_err_probe(chdev, -EINVAL,
"Failed to get stream ID for channel %d\n", tdc->id);
- chan->dev->chan_dma_dev = true;
+ chan->chan_dev->chan_dma_dev = true;
}
/* program stream-id for this channel */
@@ -426,12 +426,12 @@ static void k3_configure_chan_coherency(struct dma_chan *chan, u32 asel)
if (asel == 0) {
/* No special handling for the channel */
- chan->dev->chan_dma_dev = false;
+ chan->chan_dev->chan_dma_dev = false;
dev_clear_dma_coherent(chan_dev);
chan_dev->dma_parms = NULL;
} else if (asel == 14 || asel == 15) {
- chan->dev->chan_dma_dev = true;
+ chan->chan_dev->chan_dma_dev = true;
dev_set_dma_coherent(chan_dev);
dma_coerce_mask_and_coherent(chan_dev, DMA_BIT_MASK(48));
@@ -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:
* dev_name(requester's dev):channel name, for example: "2b00000.mcasp:tx"
@@ -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;
+ };
const char *name;
#ifdef CONFIG_DEBUG_FS
char *dbg_client_name;
@@ -532,7 +540,7 @@ struct dma_slave_caps {
static inline const char *dma_chan_name(struct dma_chan *chan)
{
- return dev_name(&chan->dev->device);
+ return dev_name(&chan->chan_dev->device);
}
/**
@@ -1805,12 +1813,12 @@ dmaengine_get_direction_text(enum dma_transfer_direction dir)
static inline struct device *dmaengine_chan_dev(struct dma_chan *chan)
{
- return &chan->dev->device;
+ return &chan->chan_dev->device;
}
static inline struct device *dmaengine_get_dma_device(struct dma_chan *chan)
{
- if (chan->dev->chan_dma_dev)
+ if (chan->chan_dev->chan_dma_dev)
return dmaengine_chan_dev(chan);
return chan->device->dev;