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

[Ruizhe Zhou]

>From: Christoph Hellwig <hch@xxxxxx>
>Date: 2026-09-07 13:47:33
>To:  Ruizhe Zhou <zhouruizhe@xxxxxxxxxxx>
>Cc:  Marek Szyprowski <m.szyprowski@xxxxxxxxxxx>,Robin Murphy <robin.murphy@xxxxxxx>,Jonathan Corbet <corbet@xxxxxxx>,Christoph Hellwig <hch@xxxxxx>,Frank Li <Frank.li@xxxxxxxxxxx>,Shuah Khan <skhan@xxxxxxxxxxxxxxxxxxx>,Randy Dunlap <rd>unlap@xxxxxxxxxxxxx>,linux-doc@xxxxxxxxxxxxxxx,iommu@xxxxxxxxxxxxxxx,linux-kernel@xxxxxxxxxxxxxxx
>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().