[PATCH] docs: dma-api: require checking DMA mask setup errors

[PATCH] docs: dma-api: require checking DMA mask setup errors

[Ruizhe Zhou]

The DMA HOWTO says dma_set_mask_and_coherent() cannot fail for
DMA_BIT_MASK(64), and more generally for masks wider than 32 bits. It
consequently recommends calls to discard the check for return value.

The generic direct-DMA path does accept every mask of at least 32 bits,
but that is not an API-wide success guarantee. Backend callbacks can
reject wider masks: ibmebus_dma_supported() and
xen_grant_dma_supported() accept only DMA_BIT_MASK(64), so a 40-bit mask
fails.

Even DMA_BIT_MASK(64) can fail when DMA setup is unavailable or
inconsistent. For example, dma_dummy_supported() rejects every mask.
acpi_dma_configure_id() installs dma_dummy_ops and returns success when
the DMA attribute is DEV_DMA_NOT_SUPPORTED. DMA configuration can
therefore succeed while leaving the device with a backend that rejects
every mask. The PowerPC legacy IOMMU backend also rejects a mask when
no IOMMU table is available, and the default IOMMU path rejects
conflicting dma_ops state.

Failure is therefore not limited to an unsupported address width.
Ignoring the return value could let a driver continue with an unusable
DMA backend.

At the same time, failure of a wider mask does not indicate that a
narrower one can succeed. Clarify for DMA driver authors that they should
select the mask matching the device's actual addressing capability, call
the mask setter once, and treat an error as a DMA setup failure. Update
the examples accordingly.

Fixes: f7ae20f2fc4e ("docs: dma: correct dma_set_mask() sample code")
Link: https://lore.kernel.org/all/AEEA1wBuK97oyrSN8q4l4KpK.3.1788520536000.Hmail.zhouruizhe@resnics.com/
Signed-off-by: Ruizhe Zhou <zhouruizhe@resnics.com>
---
This follows the discussion linked above about retaining the error check
when removing narrower-mask fallbacks. Is there an invariant that makes
these failure paths unreachable for drivers calling
dma_set_mask_and_coherent(), or should the HOWTO retain the check as
shown here? Feedback from DMA maintainers would be appreciated.

 Documentation/core-api/dma-api-howto.rst | 39 ++++++++++++------------
 1 file changed, 20 insertions(+), 19 deletions(-)

diff --git a/Documentation/core-api/dma-api-howto.rst b/Documentation/core-api/dma-api-howto.rst
index e97743ab0f26..a28be86666da 100644
--- a/Documentation/core-api/dma-api-howto.rst
+++ b/Documentation/core-api/dma-api-howto.rst
@@ -237,11 +237,11 @@ device struct of your device is embedded in the bus-specific device struct of
 your device.  For example, &pdev->dev is a pointer to the device struct of a
 PCI device (pdev is a pointer to the PCI device struct of your device).

-These calls usually return zero to indicate your device can perform DMA
-properly on the machine given the address mask you provided, but they might
-return an error if the mask is too small to be supportable on the given
-system.  If it returns non-zero, your device cannot perform DMA properly on
-this platform, and attempting to do so will result in undefined behavior.
+These calls return zero to indicate your device can perform DMA properly on
+the machine given the address mask you provided.  They return an error if the
+requested mask cannot be used with the device or if the device is not capable
+of DMA.  If a call returns non-zero, your device cannot perform DMA properly
+on this platform, and attempting to do so will result in undefined behavior.
 You must not use DMA on this device unless the dma_set_mask family of
 functions has returned success.

@@ -264,23 +264,24 @@ The 24-bit addressing device would do something like this::

 The standard 64-bit addressing device would do something like this::

-	dma_set_mask_and_coherent(dev, DMA_BIT_MASK(64))
-
-dma_set_mask_and_coherent() never return fail when DMA_BIT_MASK(64). Typical
-error code like::
+	if (dma_set_mask_and_coherent(dev, DMA_BIT_MASK(64))) {
+		dev_warn(dev, "mydev: No suitable DMA available\n");
+		goto ignore_this_device;
+	}

-	/* Wrong code */
-	if (dma_set_mask_and_coherent(dev, DMA_BIT_MASK(64)))
-		dma_set_mask_and_coherent(dev, DMA_BIT_MASK(32))
+Failure to set a 32-bit or wider DMA mask must not be treated as an indication
+that retrying a narrower mask can succeed.  Drivers must select the mask based
+on the device's actual DMA addressing capability and treat failure to set that
+mask as a DMA setup failure.  For example, a device supporting either 32-bit
+or 64-bit addressing would do something like this::

-dma_set_mask_and_coherent() will never return failure when bigger than 32.
-So typical code like::
+	u64 mask;

-	/* Recommended code */
-	if (support_64bit)
-		dma_set_mask_and_coherent(dev, DMA_BIT_MASK(64));
-	else
-		dma_set_mask_and_coherent(dev, DMA_BIT_MASK(32));
+	mask = support_64bit ? DMA_BIT_MASK(64) : DMA_BIT_MASK(32);
+	if (dma_set_mask_and_coherent(dev, mask)) {
+		dev_warn(dev, "mydev: No suitable DMA available\n");
+		goto ignore_this_device;
+	}

 If the device only supports 32-bit addressing for descriptors in the
 coherent allocations, but supports full 64-bits for streaming mappings

base-commit: ab2704c2a884028fd12d455cf27a9585aefe2961
--
2.27.0

Re: [PATCH] docs: dma-api: require checking DMA mask setup errors

[Christoph Hellwig]

On Mon, Sep 07, 2026 at 01:44:00PM +0800, Ruizhe Zhou wrote:
> The DMA HOWTO says dma_set_mask_and_coherent() cannot fail for
> DMA_BIT_MASK(64), and more generally for masks wider than 32 bits. It
> consequently recommends calls to discard the check for return value.
> 
> The generic direct-DMA path does accept every mask of at least 32 bits,
> but that is not an API-wide success guarantee. Backend callbacks can
> reject wider masks: ibmebus_dma_supported() and
> xen_grant_dma_supported() accept only DMA_BIT_MASK(64), so a 40-bit mask
> fails.

Please fix them as they break the very sensible API guarantees
instead of officially sanctioning this behavior.

> 
> Even DMA_BIT_MASK(64) can fail when DMA setup is unavailable or
> inconsistent. For example, dma_dummy_supported() rejects every mask.

So?  Did you actually try to understand this code or is this just dumb
agent work?

Re:Re: [PATCH] docs: dma-api: require checking DMA mask setup errors

[Ruizhe Zhou]

>From: Christoph Hellwig <hch@lst.de>
>Date: 2026-09-07 13:47:33
>To:  Ruizhe Zhou <zhouruizhe@resnics.com>
>Cc:  Marek Szyprowski <m.szyprowski@samsung.com>,Robin Murphy <robin.murphy@arm.com>,Jonathan Corbet <corbet@lwn.net>,Christoph Hellwig <hch@lst.de>,Frank Li <Frank.li@oss.nxp.com>,Shuah Khan <skhan@linuxfoundation.org>,Randy Dunlap <rd>unlap@infradead.org>,linux-doc@vger.kernel.org,iommu@lists.linux.dev,linux-kernel@vger.kernel.org
>Subject: Re: [PATCH] docs: dma-api: require checking DMA mask setup errors>On Mon, Sep 07, 2026 at 01:44:00PM +0800, Ruizhe Zhou wrote:
>> The DMA HOWTO says dma_set_mask_and_coherent() cannot fail for
>> DMA_BIT_MASK(64), and more generally for masks wider than 32 bits. It
>> consequently recommends calls to discard the check for return value.
>> 
>> The generic direct-DMA path does accept every mask of at least 32 bits,
>> but that is not an API-wide success guarantee. Backend callbacks can
>> reject wider masks: ibmebus_dma_supported() and
>> xen_grant_dma_supported() accept only DMA_BIT_MASK(64), so a 40-bit mask
>> fails.
>
>Please fix them as they break the very sensible API guarantees
>instead of officially sanctioning this behavior.

I'm sending this because my audit tells me that there are multiple cases
where a >32 bit set mask call would fail. And that directly contradicts the
document. I have no clue that these multiple backends break the
API guarantee, and whether these backends are required to do what they do now. 
Maybe we should cc the people that maintain these and get their input?
Moreover, I'm sending this to ask one specific thing:
According to my audit, >32 bit set op can fail, which means that drivers should
check their return value, which happens to be the behaviour adopted by most
in-tree drivers, which contradicts the HOWTO guide. Should the driver retain the
return value check or not?

>
>> 
>> Even DMA_BIT_MASK(64) can fail when DMA setup is unavailable or
>> inconsistent. For example, dma_dummy_supported() rejects every mask.
>
>So?  Did you actually try to understand this code or is this just dumb
>agent work?
>

Yes, and to my best understandings that this means "DMA being unavailable".
And that is another reason for drivers to check the return value of
dma_set_mask_and_coherent().