diff options
author | FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp> | 2010-03-10 15:23:17 -0800 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2010-03-12 15:52:40 -0800 |
commit | 9705ef7ec8c67a62474291bb4b235927bdf702db (patch) | |
tree | 8669ef53a193398ab1a4be4be6778efc05feaa0b | |
parent | 039956e9199b71ea673954e025f52f319110ca58 (diff) | |
download | linux-3.10-9705ef7ec8c67a62474291bb4b235927bdf702db.tar.gz linux-3.10-9705ef7ec8c67a62474291bb4b235927bdf702db.tar.bz2 linux-3.10-9705ef7ec8c67a62474291bb4b235927bdf702db.zip |
DMA-API.txt: add dma_sync_single/sg API description
This adds the description of the following eight function:
dma_sync_single_for_cpu
pci_dma_sync_single_for_cpu
dma_sync_single_for_device
pci_dma_sync_single_for_device
dma_sync_sg_for_cpu
pci_dma_sync_sg_for_cpu
dma_sync_sg_for_device
pci_dma_sync_sg_for_device
It was unclear that the API permits a partial sync (some network drivers
already do though). I made it clear that the sync_single API can do a
partial sync but the sync_sg API can't.
We could do a partial sync with the sync_sg API too, however, it's
difficult for driver writers to correctly use the sync_sg API for a
partial sync since the scatterlists passed in to the mapping API can't be
modified. It's unlikely that driver writers want to do a partial sync
with the sync_sg API (because the sync_sg API are usually used for block
drivers). So I think that it's better to forbid a partial sync with the
sync_sg API.
Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>
Acked-by: David Miller <davem@davemloft.net>
Acked-by: James Bottomley <James.Bottomley@suse.de>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
-rw-r--r-- | Documentation/DMA-API.txt | 42 |
1 files changed, 42 insertions, 0 deletions
diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt index bb0e75e368b..c8db3d0dba5 100644 --- a/Documentation/DMA-API.txt +++ b/Documentation/DMA-API.txt @@ -364,6 +364,48 @@ API. Note: <nents> must be the number you passed in, *not* the number of physical entries returned. +void +dma_sync_single_for_cpu(struct device *dev, dma_addr_t dma_handle, size_t size, + enum dma_data_direction direction) +void +pci_dma_sync_single_for_cpu(struct pci_dev *hwdev, dma_addr_t dma_handle, + size_t size, int direction) +void +dma_sync_single_for_device(struct device *dev, dma_addr_t dma_handle, size_t size, + enum dma_data_direction direction) +void +pci_dma_sync_single_for_device(struct pci_dev *hwdev, dma_addr_t dma_handle, + size_t size, int direction) +void +dma_sync_sg_for_cpu(struct device *dev, struct scatterlist *sg, int nelems, + enum dma_data_direction direction) +void +pci_dma_sync_sg_for_cpu(struct pci_dev *hwdev, struct scatterlist *sg, + int nelems, int direction) +void +dma_sync_sg_for_device(struct device *dev, struct scatterlist *sg, int nelems, + enum dma_data_direction direction) +void +pci_dma_sync_sg_for_device(struct pci_dev *hwdev, struct scatterlist *sg, + int nelems, int direction) + +Synchronise a single contiguous or scatter/gather mapping for the cpu +and device. With the sync_sg API, all the parameters must be the same +as those passed into the single mapping API. With the sync_single API, +you can use dma_handle and size parameters that aren't identical to +those passed into the single mapping API to do a partial sync. + +Notes: You must do this: + +- Before reading values that have been written by DMA from the device + (use the DMA_FROM_DEVICE direction) +- After writing values that will be written to the device using DMA + (use the DMA_TO_DEVICE) direction +- before *and* after handing memory to the device if the memory is + DMA_BIDIRECTIONAL + +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, |