aboutsummaryrefslogtreecommitdiff
path: root/Documentation/DMA-API.txt
diff options
context:
space:
mode:
authorFUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>2010-03-10 15:23:31 -0800
committerLinus Torvalds <torvalds@linux-foundation.org>2010-03-12 15:52:42 -0800
commit0acedc124aca35f5cce9d4ee288dc372bf517e09 (patch)
tree699113a95be38de29457d0cc71139d9c82efba3e /Documentation/DMA-API.txt
parentf41b177157718abe9a93868bb76e47d4a6f3681d (diff)
dma-mapping.h: add the dma_unmap state API
Adds the following macros: DECLARE_DMA_UNMAP_ADDR(ADDR_NAME) DECLARE_DMA_UNMAP_LEN(LEN_NAME) dma_unmap_addr(PTR, ADDR_NAME) dma_unmap_addr_set(PTR, ADDR_NAME, VAL) dma_unmap_len(PTR, LEN_NAME) dma_unmap_len_set(PTR, LEN_NAME, VAL) The API corresponds to the pci_unmap state API. We'll move to this new generic API from the PCI specific API in the long term. As include/asm-generic/pci-dma-compat.h does, the pci_unmap API simply calls the new generic API for some time. Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp> Cc: James Bottomley <James.Bottomley@suse.de> Cc: David S. Miller <davem@davemloft.net> Cc: Jesse Barnes <jbarnes@virtuousgeek.org> Cc: Arnd Bergmann <arnd@arndb.de> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Diffstat (limited to 'Documentation/DMA-API.txt')
-rw-r--r--Documentation/DMA-API.txt58
1 files changed, 58 insertions, 0 deletions
diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt
index 364a6cb444a..29a48fbae77 100644
--- a/Documentation/DMA-API.txt
+++ b/Documentation/DMA-API.txt
@@ -472,6 +472,64 @@ void whizco_dma_map_sg_attrs(struct device *dev, dma_addr_t dma_addr,
....
+Part Ie - Optimizing Unmap State Space Consumption
+--------------------------------
+
+On some platforms, dma_unmap_{single,page}() is simply a nop.
+Therefore, keeping track of the mapping address and length is a waste
+of space. Instead of filling your drivers up with ifdefs and the like
+to "work around" this (which would defeat the whole purpose of a
+portable API) the following facilities are provided.
+
+Actually, instead of describing the macros one by one, we'll
+transform some example code.
+
+1) Use DEFINE_DMA_UNMAP_{ADDR,LEN} in state saving structures.
+ Example, before:
+
+ struct ring_state {
+ struct sk_buff *skb;
+ dma_addr_t mapping;
+ __u32 len;
+ };
+
+ after:
+
+ struct ring_state {
+ struct sk_buff *skb;
+ DEFINE_DMA_UNMAP_ADDR(mapping);
+ DEFINE_DMA_UNMAP_LEN(len);
+ };
+
+2) Use dma_unmap_{addr,len}_set to set these values.
+ Example, before:
+
+ ringp->mapping = FOO;
+ ringp->len = BAR;
+
+ after:
+
+ dma_unmap_addr_set(ringp, mapping, FOO);
+ dma_unmap_len_set(ringp, len, BAR);
+
+3) Use dma_unmap_{addr,len} to access these values.
+ Example, before:
+
+ dma_unmap_single(dev, ringp->mapping, ringp->len,
+ DMA_FROM_DEVICE);
+
+ after:
+
+ dma_unmap_single(dev,
+ dma_unmap_addr(ringp, mapping),
+ dma_unmap_len(ringp, len),
+ DMA_FROM_DEVICE);
+
+It really should be self-explanatory. We treat the ADDR and LEN
+separately, because it is possible for an implementation to only
+need the address in order to perform the unmap operation.
+
+
Part II - Advanced dma_ usage
-----------------------------