docs: dma: correct dma_set_mask() sample code
Subsystems (4)
Frank Li
maintainerPATCH v2 1/1 docs: dma: correct dma_set_mask() sample code
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.
And dma_set_mask_and_coherent(64) never returns failure.
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.
int dma_direct_supported(struct device *dev, u64 mask)
{
u64 min_mask = (max_pfn - 1) << PAGE_SHIFT;
/*
* Because 32-bit DMA masks are so common we expect every architecture
* to be able to satisfy them - either by not supporting more physical
* memory, or by providing a ZONE_DMA32. If neither is the case, the
* architecture needs to use an IOMMU instead of the direct mapping.
*/
if (mask >= DMA_BIT_MASK(32))
return 1;
...
}The iommux's dma_supported() actually means iommu requires devices's minimized dma capability.
An example:
static int sba_dma_supported( struct device *dev, u64 mask)()
{
...
* check if mask is >= than the current max IO Virt Address
* The max IO Virt address will *always* < 30 bits.
*/
return((int)(mask >= (ioc->ibase - 1 +
(ioc->pdir_size / sizeof(u64) * IOVP_SIZE) )));
...
}1 means supported. 0 means unsupported.
Correct document to make it more clear and provide correct sample code.
---
Notes:
Change from v1 to v2:
- fixed typo, review by Randy Dunlap
Documentation/core-api/dma-api-howto.rst | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-)
Documentation/core-api/dma-api-howto.rst +22 -2
@@ -203,13 +203,33 @@ setting the DMA mask fails. In this manner, if a user of your driver reports that performance is bad or that the device is not even detected, you can ask them for the kernel messages to find out exactly why. -The standard 64-bit addressing device would do something like this:: +The 24-bit addressing device would do something like this:: - if (dma_set_mask_and_coherent(dev, DMA_BIT_MASK(64))) { + if (dma_set_mask_and_coherent(dev, DMA_BIT_MASK(24))) { dev_warn(dev, "mydev: No suitable DMA available\n"); goto ignore_this_device; } +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)); + If the device only supports 32-bit addressing for descriptors in the coherent allocations, but supports full 64-bits for streaming mappings it would look like this::
Signature · 1 line
2.34.1
This looks good to me:
Jon, do you want to pick this up through the Documentation tree, or should I take it through the dma-mapping tree?
Jonathan Corbet
maintainerQuoted 6 lines · Christoph Hellwig
This looks good to me:
Reviewed-by Christoph Hellwig <[email protected]>Jon, do you want to pick this up through the Documentation tree, or should I take it through the dma-mapping tree?
I'm going though my patch queue right now, as it happens, so I'll just go ahead and apply it.
Thanks,
jon
Quoted 97 lines · Frank Li
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.And
dma_set_mask_and_coherent(64)never returns failure.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 calldma_direct_supportedor iommux'sdma_supportedcall back function.int
dma_direct_supported(struct device *dev, u64 mask){ u64 min_mask = (max_pfn - 1) << PAGE_SHIFT; /* * Because 32-bit DMA masks are so common we expect every architecture * to be able to satisfy them - either by not supporting more physical * memory, or by providing a ZONE_DMA32. If neither is the case, the * architecture needs to use an IOMMU instead of the direct mapping. */ if (mask >= DMA_BIT_MASK(32)) return 1; ... }The iommux's
dma_supported()actually means iommu requires devices's minimized dma capability.An example:
static int
sba_dma_supported( struct device *dev, u64 mask)(){ ... * check if mask is >= than the current max IO Virt Address * The max IO Virt address will *always* < 30 bits. */ return((int)(mask >= (ioc->ibase - 1 + (ioc->pdir_size / sizeof(u64) * IOVP_SIZE) ))); ... }1 means supported. 0 means unsupported.
Correct document to make it more clear and provide correct sample code.
Signed-off-by Frank Li <[email protected]>---
Notes:
Change from v1 to v2:
- fixed typo, review by Randy DunlapDocumentation/core-api/dma-api-howto.rst | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-)Documentation/core-api/dma-api-howto.rst +4
-2@@ -203,13 +203,33 @@ setting the DMA mask fails. In this manner, if a user of your driver reports that performance is bad or that the device is not even detected, you can ask them for the kernel messages to find out exactly why. -The standard 64-bit addressing device would do something like this:: +The 24-bit addressing device would do something like this:: - if (dma_set_mask_and_coherent(dev, DMA_BIT_MASK(64))) { + if (dma_set_mask_and_coherent(dev, DMA_BIT_MASK(24))) { dev_warn(dev, "mydev: No suitable DMA available\n"); goto ignore_this_device; } +The standard 64-bit addressing device would do something like this:: +
Documentation/core-api/dma-api-howto.rst setting the DMA mask fails. In this manner, if a user of your driver reports · line 224
Quoted 10 lines
Documentation/core-api/dma-api-howto.rst +10
-0+ 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.
Nit:
s/then/than/
Quoted 14 lines
Documentation/core-api/dma-api-howto.rst +8
-0+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)); + If the device only supports 32-bit addressing for descriptors in the coherent allocations, but supports full 64-bits for streaming mappings it would look like this::Signature · 1 line
2.34.1
Jonathan Corbet
maintainerQuoted 4 lines · Niklas Cassel
Quoted 1 line
+dma_set_mask_and_coherent() will never return failure when bigger then 32.
Nit:
s/then/than/
I hadn't pushed anything yet, so I took the liberty of going and fixing this one, thanks.
jon
Hi,
Quoted 7 lines
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.
Quoted 1 line
And
dma_set_mask_and_coherent(64)never returns failure.
No realistic chance of the dev->dma_mask check (below) giving -EIO?
Quoted 19 lines
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; }
Quoted 2 lines
dma_supported()will calldma_direct_supportedor iommux'sdma_supportedcall 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?
Quoted 13 lines
Documentation/core-api/dma-api-howto.rst +10
-0+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))
Documentation/core-api/dma-api-howto.rst setting the DMA mask fails. In this manner, if a user of your driver reports · line 232
Quoted 10 lines
Documentation/core-api/dma-api-howto.rst +10
-0+ +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.
Thanks,
Michal
Quoted 16 lines · Michal Pecio
[You don't often get email from [email protected]. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
Hi,
Quoted 7 lines
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.
Quoted 5 lines
But I have a few remaining questions and remarks.
Quoted 1 line
And
dma_set_mask_and_coherent(64)never returns failure.No realistic chance of the
dev->dma_maskcheck (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.
Quoted 20 lines
Quoted 20 lines
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; }
Quoted 6 lines
Quoted 2 lines
dma_supported()will calldma_direct_supportedor iommux'sdma_supportedcall back function.Aapparently, it may also use some '
dma_map_ops' and there is a bunch of those spread overdrivers/andarch/. 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.
Quoted 20 lines
Quoted 20 lines
Documentation/core-api/dma-api-howto.rst +16
-0+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)
Quoted 8 lines
Documentation/core-api/dma-api-howto.rst setting the DMA mask fails. In this manner, if a user of your driver reports · line 232
Quoted 4 lines
Documentation/core-api/dma-api-howto.rst +4
-0+ 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
Quoted 4 lines
Thanks,
Michal
Quoted 16 lines · Frank Li
Quoted 1 line · Michal Pecio
No realistic chance of the
dev->dma_maskcheck (below) giving-EIO?
dma_maskis 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.
Quoted 3 lines
Quoted 2 lines
dma_supported()will calldma_direct_supportedor iommux'sdma_supportedcall back function.
Quoted 6 lines
Quoted 3 lines
Aapparently, it may also use some '
dma_map_ops' and there is a bunch of those spread overdrivers/andarch/. 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.
Thank you. Sounds like it should work then, though I think that checking return status won't harm, just to cover unusual cases like regression in some obscure arch or people with buggy out of tree patches (which they "forget" to mention they are using).
Regards,
Michal
Quoted 23 lines · Michal Pecio
[You don't often get email from [email protected]. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
Quoted 20 lines · Frank Li
Quoted 1 line · Michal Pecio
No realistic chance of the
dev->dma_maskcheck (below) giving-EIO?
dma_maskis 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.
Quoted 6 lines
Quoted 2 lines
dma_supported()will calldma_direct_supportedor iommux'sdma_supportedcall back function.Aapparently, it may also use some '
dma_map_ops' and there is a bunch of those spread overdrivers/andarch/. But I gather they are expected to behave similarly as the functions named above?
Quoted 7 lines
Quoted 2 lines
I grep it and checked at that time, all return 1 when >= 32. Now more powerfull check tools avaible, you can double check it.
Thank you. Sounds like it should work then, though I think that checking return status won't harm, just to cover unusual cases like regression in some obscure arch or people with buggy out of tree patches (which they "forget" to mention they are using).
Now, prefer don't check when >= 32 to keep code clean.
Frank
Quoted 3 lines
Regards,
Michal