Re: [PATCH v4 24/25] dmaengine: sdxi: MSI/MSI-X vector allocation and mapping

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] dmaengine: sdxi: incomplete kernel-doc comments in sdxi.h
--

commit fccd22f95bf4bdc550267ac2709b80e00e1e9267
Author: Nathan Lynch <nathan.lynch@amd.com>

dmaengine: sdxi: MSI/MSI-X vector allocation and mapping

This commit allocates MSI/MSI-X vectors for the SDXI error log interrupt
and client contexts, tracking non-reserved vectors with an IDA. It also
adds helpers to allocate, free, and map device-relative vector indices to
Linux IRQ numbers via a new get_irq bus operation.

> diff --git a/drivers/dma/sdxi/sdxi.h b/drivers/dma/sdxi/sdxi.h
> index aaa43eab00b33..07044d837d9af 100644
> --- a/drivers/dma/sdxi/sdxi.h
> +++ b/drivers/dma/sdxi/sdxi.h

[ ... ]

> @@ -69,6 +90,38 @@ struct sdxi_dev {
>  	const struct sdxi_bus_ops *bus_ops;
>  };
>  
> +/**
> + * sdxi_alloc_vector() - Allocate an interrupt vector.
> + *
> + * A vector that will have the same lifetime as the device does not
> + * need to be released explicitly. Otherwise the vector must be
> + * released with sdxi_free_vector().
> + */
> +static inline int sdxi_alloc_vector(struct sdxi_dev *sdxi)
> +{
> +	return ida_alloc_range(&sdxi->vectors, SDXI_MIN_VECTORS,
> +			       sdxi->nr_vectors - 1, GFP_KERNEL);
> +}
> +
> +/**
> + * sdxi_free_vector() - Release a previously allocated index.
> + */
> +static inline void sdxi_free_vector(struct sdxi_dev *sdxi, unsigned int nr)
> +{
> +	ida_free(&sdxi->vectors, nr);
> +}
> +
> +/**
> + * sdxi_vector_to_irq() - Translate an allocated interrupt vector to
> + *                        Linux IRQ number suitable for passing to
> + *                        request_irq() et al.
> + */
> +static inline int sdxi_vector_to_irq(struct sdxi_dev *sdxi, unsigned int nr)
> +{
> +	WARN_ON_ONCE(!ida_exists(&sdxi->vectors, nr));
> +	return sdxi->bus_ops->get_irq(sdxi, nr);
> +}

[Severity: Low]
sdxi_alloc_vector(), sdxi_free_vector(), and sdxi_vector_to_irq() in
drivers/dma/sdxi/sdxi.h use the /** kernel-doc comment marker without
describing the @sdxi and @nr parameters or including Return: sections for
sdxi_alloc_vector() and sdxi_vector_to_irq().

Running scripts/kernel-doc on drivers/dma/sdxi/sdxi.h (for example via
make HEADER_CHECK=drivers/dma/sdxi headercheck) emits kernel-doc warnings
for the undescribed parameters and missing return value descriptions.

Should these comments document @sdxi, @nr, and Return:, or use regular /*
comments instead?

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20261103-sdxi-base-v4-0-3668ccc7aab8@amd.com?part=24