fedora core 6 1.2949 + vserver 2.2.0

[linux-2.6.git] / Documentation / DMA-mapping.txt

diff --git a/Documentation/DMA-mapping.txt b/Documentation/DMA-mapping.txt
index 6845574..028614c 100644 (file)
--- a/Documentation/DMA-mapping.txt
+++ b/Documentation/DMA-mapping.txt
@@ -58,11 +58,15 @@ translating each of those pages back to a kernel address using
 something like __va().  [ EDIT: Update this when we integrate
 Gerd Knorr's generic code which does this. ]
 
 something like __va().  [ EDIT: Update this when we integrate
 Gerd Knorr's generic code which does this. ]
 

-This rule also means that you may not use kernel image addresses
-(ie. items in the kernel's data/text/bss segment, or your driver's)
-nor may you use kernel stack addresses for DMA.  Both of these items
-might be mapped somewhere entirely different than the rest of physical
-memory.
+This rule also means that you may use neither kernel image addresses
+(items in data/text/bss segments), nor module image addresses, nor
+stack addresses for DMA.  These could all be mapped somewhere entirely
+different than the rest of physical memory.  Even if those classes of
+memory could physically work with DMA, you'd need to ensure the I/O
+buffers were cacheline-aligned.  Without that, you'd see cacheline
+sharing problems (data corruption) on CPUs with DMA-incoherent caches.
+(The CPU could write to one word, DMA would write to a different one
+in the same cache line, and one of them could be overwritten.)

 
 Also, this means that you cannot take the return of a kmap()
 call and DMA to/from that.  This is similar to vmalloc().
 
 Also, this means that you cannot take the return of a kmap()
 call and DMA to/from that.  This is similar to vmalloc().


@@ -103,7 +107,7 @@ The query is performed via a call to pci_set_dma_mask():
 
        int pci_set_dma_mask(struct pci_dev *pdev, u64 device_mask);
 
 
        int pci_set_dma_mask(struct pci_dev *pdev, u64 device_mask);
 

-The query for consistent allocations is performed via a a call to
+The query for consistent allocations is performed via a call to

 pci_set_consistent_dma_mask():
 
        int pci_set_consistent_dma_mask(struct pci_dev *pdev, u64 device_mask);
 pci_set_consistent_dma_mask():
 
        int pci_set_consistent_dma_mask(struct pci_dev *pdev, u64 device_mask);


@@ -113,7 +117,7 @@ device_mask is a bit mask describing which bits of a PCI address your
 device supports.  It returns zero if your card can perform DMA
 properly on the machine given the address mask you provided.
 
 device supports.  It returns zero if your card can perform DMA
 properly on the machine given the address mask you provided.
 

-If it returns non-zero, your device can not perform DMA properly on
+If it returns non-zero, your device cannot perform DMA properly on

 this platform, and attempting to do so will result in undefined
 behavior.  You must either use a different mask, or not use DMA.
 
 this platform, and attempting to do so will result in undefined
 behavior.  You must either use a different mask, or not use DMA.
 


@@ -194,11 +198,13 @@ document for how to handle this case.
 Finally, if your device can only drive the low 24-bits of
 address during PCI bus mastering you might do something like:
 
 Finally, if your device can only drive the low 24-bits of
 address during PCI bus mastering you might do something like:
 

-       if (pci_set_dma_mask(pdev, 0x00ffffff)) {
+       if (pci_set_dma_mask(pdev, DMA_24BIT_MASK)) {

                printk(KERN_WARNING
                       "mydev: 24-bit DMA addressing not available.\n");
                goto ignore_this_device;
        }
                printk(KERN_WARNING
                       "mydev: 24-bit DMA addressing not available.\n");
                goto ignore_this_device;
        }

+[Better use DMA_24BIT_MASK instead of 0x00ffffff.
+See linux/include/dma-mapping.h for reference.]

 
 When pci_set_dma_mask() is successful, and returns zero, the PCI layer
 saves away this mask you have provided.  The PCI layer will use this
 
 When pci_set_dma_mask() is successful, and returns zero, the PCI layer
 saves away this mask you have provided.  The PCI layer will use this


@@ -210,7 +216,7 @@ functions (for example a sound card provides playback and record
 functions) and the various different functions have _different_
 DMA addressing limitations, you may wish to probe each mask and
 only provide the functionality which the machine can handle.  It
 functions) and the various different functions have _different_
 DMA addressing limitations, you may wish to probe each mask and
 only provide the functionality which the machine can handle.  It

-is important that the last call to pci_set_dma_mask() be for the 
+is important that the last call to pci_set_dma_mask() be for the

 most specific mask.
 
 Here is pseudo-code showing how this might be done:
 most specific mask.
 
 Here is pseudo-code showing how this might be done:


@@ -282,6 +288,11 @@ There are two types of DMA mappings:
 
              in order to get correct behavior on all platforms.
 
 
              in order to get correct behavior on all platforms.
 

+            Also, on some platforms your driver may need to flush CPU write
+            buffers in much the same way as it needs to flush write buffers
+            found in PCI bridges (such as by reading a register's value
+            after writing it).
+

 - Streaming DMA mappings which are usually mapped for one DMA transfer,
   unmapped right after it (unless you use pci_dma_sync_* below) and for which
   hardware can optimize for sequential accesses.
 - Streaming DMA mappings which are usually mapped for one DMA transfer,
   unmapped right after it (unless you use pci_dma_sync_* below) and for which
   hardware can optimize for sequential accesses.


@@ -301,6 +312,9 @@ There are two types of DMA mappings:
 
 Neither type of DMA mapping has alignment restrictions that come
 from PCI, although some devices may have such restrictions.
 
 Neither type of DMA mapping has alignment restrictions that come
 from PCI, although some devices may have such restrictions.

+Also, systems with caches that aren't DMA-coherent will work better
+when the underlying buffers don't share cache lines with other data.
+

 
                 Using Consistent DMA mappings.
 
 
                 Using Consistent DMA mappings.
 


@@ -684,12 +698,12 @@ these interfaces.  Remember that, as defined, consistent mappings are
 always going to be SAC addressable.
 
 The first thing your driver needs to do is query the PCI platform
 always going to be SAC addressable.
 
 The first thing your driver needs to do is query the PCI platform

-layer with your devices DAC addressing capabilities:
+layer if it is capable of handling your devices DAC addressing
+capabilities:

 
 

-       int pci_dac_set_dma_mask(struct pci_dev *pdev, u64 mask);
+       int pci_dac_dma_supported(struct pci_dev *hwdev, u64 mask);

 
 

-This routine behaves identically to pci_set_dma_mask.  You may not
-use the following interfaces if this routine fails.
+You may not use the following interfaces if this routine fails.

 
 Next, DMA addresses using this API are kept track of using the
 dma64_addr_t type.  It is guaranteed to be big enough to hold any
 
 Next, DMA addresses using this API are kept track of using the
 dma64_addr_t type.  It is guaranteed to be big enough to hold any