Re: [PATCH 3/3] dma-mapping: better document dma_addr_t and DMA_MAPPING_ERROR

['Christoph Hellwig']

On Tue, Sep 22, 2020 at 01:56:46PM +, David Laight wrote:
> > +/*
> > + * A dma_addr_t can hold any valid DMA or bus address for the platform.  
> > It can
> > + * be given to a device to use as a DMA source or target.  A CPU cannot
> > + * reference a dma_addr_t directly because there may be translation 
> > between its
> > + * physical address space and the bus address space.
> 
> It can't access it 'directly' because it isn't a virtual address
> 
> > + *
> > + * DMA_MAPPING_ERROR is the magic error code if a mapping failed.  It 
> > should not
> > + * be used directly in drivers, but checked for using dma_mapping_error()
> > + * instead.
> > + */
> 
> I think it might be worth adding:
> 
> A dma_addr_t value may be device dependant and differ from the
> 'physical address' of the memory.

This is what I've committed:

 * A dma_addr_t can hold any valid DMA or bus address for the platform.  It can
 * be given to a device to use as a DMA source or target.  It is specific to a
 * given device and there may be a translation between the CPU physical address
 * space and the bus address space.
___
iommu mailing list
iommu@lists.linux-foundation.org
https://lists.linuxfoundation.org/mailman/listinfo/iommu

RE: [PATCH 3/3] dma-mapping: better document dma_addr_t and DMA_MAPPING_ERROR

[David Laight]

From: Christoph Hellwig
> Sent: 22 September 2020 14:40
...
> @@ -131,6 +125,16 @@ struct dma_map_ops {
>   unsigned long (*get_merge_boundary)(struct device *dev);
>  };
> 
> +/*
> + * A dma_addr_t can hold any valid DMA or bus address for the platform.  It 
> can
> + * be given to a device to use as a DMA source or target.  A CPU cannot
> + * reference a dma_addr_t directly because there may be translation between 
> its
> + * physical address space and the bus address space.

It can't access it 'directly' because it isn't a virtual address

> + *
> + * DMA_MAPPING_ERROR is the magic error code if a mapping failed.  It should 
> not
> + * be used directly in drivers, but checked for using dma_mapping_error()
> + * instead.
> + */

I think it might be worth adding:

A dma_addr_t value may be device dependant and differ from the
'physical address' of the memory.

David

-
Registered Address Lakeside, Bramley Road, Mount Farm, Milton Keynes, MK1 1PT, 
UK
Registration No: 1397386 (Wales)

___
iommu mailing list
iommu@lists.linux-foundation.org
https://lists.linuxfoundation.org/mailman/listinfo/iommu

[PATCH 3/3] dma-mapping: better document dma_addr_t and DMA_MAPPING_ERROR

[Christoph Hellwig]

Move the comment documenting dma_addr_t away from the dma_map_ops
definition which isn't very related to it, and toward DMA_MAPPING_ERROR,
which is somewhat related.  Add a little blurb about DMA_MAPPING_ERROR
as well.

Signed-off-by: Christoph Hellwig 
---
 include/linux/dma-mapping.h | 16 ++--
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/include/linux/dma-mapping.h b/include/linux/dma-mapping.h
index 51e93d44b826c8..c4395cf7e265dd 100644
--- a/include/linux/dma-mapping.h
+++ b/include/linux/dma-mapping.h
@@ -67,12 +67,6 @@
  */
 #define DMA_ATTR_PRIVILEGED(1UL << 9)
 
-/*
- * A dma_addr_t can hold any valid DMA or bus address for the platform.
- * It can be given to a device to use as a DMA source or target.  A CPU cannot
- * reference a dma_addr_t directly because there may be translation between
- * its physical address space and the bus address space.
- */
 struct dma_map_ops {
void* (*alloc)(struct device *dev, size_t size,
dma_addr_t *dma_handle, gfp_t gfp,
@@ -131,6 +125,16 @@ struct dma_map_ops {
unsigned long (*get_merge_boundary)(struct device *dev);
 };
 
+/*
+ * A dma_addr_t can hold any valid DMA or bus address for the platform.  It can
+ * be given to a device to use as a DMA source or target.  A CPU cannot
+ * reference a dma_addr_t directly because there may be translation between its
+ * physical address space and the bus address space.
+ *
+ * DMA_MAPPING_ERROR is the magic error code if a mapping failed.  It should 
not
+ * be used directly in drivers, but checked for using dma_mapping_error()
+ * instead.
+ */
 #define DMA_MAPPING_ERROR  (~(dma_addr_t)0)
 
 extern const struct dma_map_ops dma_virt_ops;
-- 
2.28.0

___
iommu mailing list
iommu@lists.linux-foundation.org
https://lists.linuxfoundation.org/mailman/listinfo/iommu