Re: [PATCH v2 1/1] docs: dma: correct dma_set_mask() sample code

[Frank Li <Frank.li@oss.nxp.com>]

On Sun, Aug 16, 2026 at 07:10:44AM +0200, Michal Pecio wrote:
> [You don't often get email from michal.pecio@gmail.com. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
>
> Hi,
>
> > There are bunch of codes in driver like
> >
> >        if (dma_set_mask_and_coherent(dev, DMA_BIT_MASK(64)))
> >                dma_set_mask_and_coherent(dev, DMA_BIT_MASK(32))
> >
> > Actually it is wrong because if dma_set_mask_and_coherent(64) fails,
> > dma_set_mask_and_coherent(32) will fail for the same reason.
>
> I encountered similar driver code and found it similarly suspicious.
> I arrived here searching for reasons to convince myself (and relevant
> maintainers) that removing this is indeed the right thing to do.
>
> But I have a few remaining questions and remarks.
>
> > And dma_set_mask_and_coherent(64) never returns failure.
>
> No realistic chance of the dev->dma_mask check (below) giving -EIO?

dma_mask is pointer, which already initilized by bus driver before call to
probe.

For example

https://elixir.bootlin.com/linux/v7.1.8/source/drivers/base/platform.c#L634

If you find one, which bus driver have not init it, please high light it.

So far safe check !dev->dma_mask is reduntant.

>
> > According to the definition of dma_set_mask(), it indicates the width
> > of address that device DMA can access. If it can access 64-bit
> > address, it must access 32-bit address inherently. So only need set
> > biggest address width.
> >
> > See below code fragment:
> >
> > dma_set_mask(mask)
> > {
> >       mask = (dma_addr_t)mask;
> >
> >       if (!dev->dma_mask || !dma_supported(dev, mask))
> >               return -EIO;
> >
> >       arch_dma_set_mask(dev, mask);
> >       *dev->dma_mask = mask;
> >       return 0;
> > }
> >
> > dma_supported() will call dma_direct_supported or iommux's
> > dma_supported call back function.
>
> Aapparently, it may also use some 'dma_map_ops' and there is a bunch
> of those spread over drivers/ and arch/. But I gather they are expected
> to behave similarly as the functions named above?

I grep it and checked at that time, all return 1 when >= 32. Now more
powerfull check tools avaible, you can double check it.

>
> > --- a/Documentation/core-api/dma-api-howto.rst
> > +++ b/Documentation/core-api/dma-api-howto.rst
> >
> > +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::
> > +
> > +     /* Wrong code */
> > +     if (dma_set_mask_and_coherent(dev, DMA_BIT_MASK(64)))
> > +             dma_set_mask_and_coherent(dev, DMA_BIT_MASK(32))
> > +
> > +dma_set_mask_and_coherent() will never return failure when bigger then 32.
> > +So typical code like::
> > +
> > +     /* 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));
> > +
>
> This text is unclear. Two sentences begin with "Typical error code",
> then some code is quoted, and the sentences are cut abruptly without
> actually making any statement about the code in question.

Sorry, I still not understand what your means.

Anyways, now dt's "dma-ranges" is more userful now.

Frank

>
> Thanks,
> Michal
>