Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/ieee1394...

[pandora-kernel.git] / Documentation / DMA-API.txt

diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt
index b939ebb..d8b63d1 100644 (file)
--- a/Documentation/DMA-API.txt
+++ b/Documentation/DMA-API.txt
@@ -145,7 +145,7 @@ Part Ic - DMA addressing limitations
 int
 dma_supported(struct device *dev, u64 mask)
 int
 int
 dma_supported(struct device *dev, u64 mask)
 int

-pci_dma_supported(struct device *dev, u64 mask)
+pci_dma_supported(struct pci_dev *hwdev, u64 mask)

 
 Checks to see if the device can support DMA to the memory described by
 mask.
 
 Checks to see if the device can support DMA to the memory described by
 mask.


@@ -189,7 +189,7 @@ dma_addr_t
 dma_map_single(struct device *dev, void *cpu_addr, size_t size,
                      enum dma_data_direction direction)
 dma_addr_t
 dma_map_single(struct device *dev, void *cpu_addr, size_t size,
                      enum dma_data_direction direction)
 dma_addr_t

-pci_map_single(struct device *dev, void *cpu_addr, size_t size,
+pci_map_single(struct pci_dev *hwdev, void *cpu_addr, size_t size,

                      int direction)
 
 Maps a piece of processor virtual memory so it can be accessed by the
                      int direction)
 
 Maps a piece of processor virtual memory so it can be accessed by the


@@ -298,10 +298,10 @@ recommended that you never use these unless you really know what the
 cache width is.
 
 int
 cache width is.
 
 int

-dma_mapping_error(dma_addr_t dma_addr)
+dma_mapping_error(struct device *dev, dma_addr_t dma_addr)

 
 int
 
 int

-pci_dma_mapping_error(dma_addr_t dma_addr)
+pci_dma_mapping_error(struct pci_dev *hwdev, dma_addr_t dma_addr)

 
 In some circumstances dma_map_single and dma_map_page will fail to create
 a mapping. A driver can check for these errors by testing the returned
 
 In some circumstances dma_map_single and dma_map_page will fail to create
 a mapping. A driver can check for these errors by testing the returned


@@ -395,6 +395,71 @@ Notes:  You must do this:
 
 See also dma_map_single().
 
 
 See also dma_map_single().
 

+dma_addr_t
+dma_map_single_attrs(struct device *dev, void *cpu_addr, size_t size,
+                    enum dma_data_direction dir,
+                    struct dma_attrs *attrs)
+
+void
+dma_unmap_single_attrs(struct device *dev, dma_addr_t dma_addr,
+                      size_t size, enum dma_data_direction dir,
+                      struct dma_attrs *attrs)
+
+int
+dma_map_sg_attrs(struct device *dev, struct scatterlist *sgl,
+                int nents, enum dma_data_direction dir,
+                struct dma_attrs *attrs)
+
+void
+dma_unmap_sg_attrs(struct device *dev, struct scatterlist *sgl,
+                  int nents, enum dma_data_direction dir,
+                  struct dma_attrs *attrs)
+
+The four functions above are just like the counterpart functions
+without the _attrs suffixes, except that they pass an optional
+struct dma_attrs*.
+
+struct dma_attrs encapsulates a set of "dma attributes". For the
+definition of struct dma_attrs see linux/dma-attrs.h.
+
+The interpretation of dma attributes is architecture-specific, and
+each attribute should be documented in Documentation/DMA-attributes.txt.
+
+If struct dma_attrs* is NULL, the semantics of each of these
+functions is identical to those of the corresponding function
+without the _attrs suffix. As a result dma_map_single_attrs()
+can generally replace dma_map_single(), etc.
+
+As an example of the use of the *_attrs functions, here's how
+you could pass an attribute DMA_ATTR_FOO when mapping memory
+for DMA:
+
+#include <linux/dma-attrs.h>
+/* DMA_ATTR_FOO should be defined in linux/dma-attrs.h and
+ * documented in Documentation/DMA-attributes.txt */
+...
+
+       DEFINE_DMA_ATTRS(attrs);
+       dma_set_attr(DMA_ATTR_FOO, &attrs);
+       ....
+       n = dma_map_sg_attrs(dev, sg, nents, DMA_TO_DEVICE, &attr);
+       ....
+
+Architectures that care about DMA_ATTR_FOO would check for its
+presence in their implementations of the mapping and unmapping
+routines, e.g.:
+
+void whizco_dma_map_sg_attrs(struct device *dev, dma_addr_t dma_addr,
+                            size_t size, enum dma_data_direction dir,
+                            struct dma_attrs *attrs)
+{
+       ....
+       int foo =  dma_get_attr(DMA_ATTR_FOO, attrs);
+       ....
+       if (foo)
+               /* twizzle the frobnozzle */
+       ....
+

 
 Part II - Advanced dma_ usage
 -----------------------------
 
 Part II - Advanced dma_ usage
 -----------------------------