Improve DMA API sg_sync function documentation
Subsystems (2)
cover Improve DMA API sg_sync function documentation
Hi,
This set of two patches improves DMA API function documentation for cache sync functions operating on scatterlists and fixes related comments in the ARM implementation.
Signature · 2 lines
Kind regards, Sakari
PATCH 1/2 Documentation: DMA API: Be more explicit that nents is always the same
From: Sakari Ailus <[email protected]>
The nents argument to the DMA API functions operating on scatterlists is always the same. The documentation used different argument names and the matter was not mentioned in Documentation/DMA-API-HOWTO.txt at all. Fix these.
--- Documentation/DMA-API-HOWTO.txt | 5 +++++ Documentation/DMA-API.txt | 6 +++--- 2 files changed, 8 insertions(+), 3 deletions(-)
Documentation/DMA-API-HOWTO.txt +5 -0
@@ -681,6 +681,11 @@ or: as appropriate. +PLEASE NOTE: The 'nents' argument to dma_sync_sg_for_cpu() and + dma_sync_sg_for_device() must be the same passed to + dma_map_sg(). It is _NOT_ the count returned by + dma_map_sg(). + After the last DMA transfer call one of the DMA unmap routines dma_unmap_{single,sg}(). If you don't touch the data from the first dma_map_*() call till dma_unmap_*(), then you don't have to call the
Documentation/DMA-API.txt +3 -3
@@ -340,7 +340,7 @@ accessed sg->address and sg->length as shown above. void dma_unmap_sg(struct device *dev, struct scatterlist *sg, - int nhwentries, enum dma_data_direction direction) + int nents, enum dma_data_direction direction) Unmap the previously mapped scatter/gather list. All the parameters must be the same as those and passed in to the scatter/gather mapping
@@ -356,10 +356,10 @@ void dma_sync_single_for_device(struct device *dev, dma_addr_t dma_handle, size_t size, enum dma_data_direction direction) void -dma_sync_sg_for_cpu(struct device *dev, struct scatterlist *sg, int nelems, +dma_sync_sg_for_cpu(struct device *dev, struct scatterlist *sg, int nents, enum dma_data_direction direction) void -dma_sync_sg_for_device(struct device *dev, struct scatterlist *sg, int nelems, +dma_sync_sg_for_device(struct device *dev, struct scatterlist *sg, int nents, enum dma_data_direction direction) Synchronise a single contiguous or scatter/gather mapping for the CPU
Signature · 1 line
2.1.0.231.g7484e3b
Jonathan Corbet
maintainerRe: [PATCH 1/2] Documentation: DMA API: Be more explicit that nents is always the same
Quoted 4 lines · On Wed, 23 Sep 2015 14:41:09 +0300 Sakari Ailus <[email protected]>…
The nents argument to the DMA API functions operating on scatterlists is always the same. The documentation used different argument names and the matter was not mentioned in
Documentation/DMA-API-HOWTO.txtat all. Fix these.
OK, I've taken this one into the docs tree. Part 2 needs to go in via an ARM maintainer, and should probably make an appearance on the ARM list.
Thanks,
jon
Re: [PATCH 1/2] Documentation: DMA API: Be more explicit that nents is always the same
Quoted 10 lines · Jonathan Corbet
Quoted 4 lines · On Wed, 23 Sep 2015 14:41:09 +0300 Sakari Ailus <[email protected]>…
The nents argument to the DMA API functions operating on scatterlists is always the same. The documentation used different argument names and the matter was not mentioned in
Documentation/DMA-API-HOWTO.txtat all. Fix these.OK, I've taken this one into the docs tree. Part 2 needs to go in via an ARM maintainer, and should probably make an appearance on the ARM list.
Good point. I'll submit it there.
Thanks!
Signature · 2 lines
Sakari Ailus e-mail: [email protected] XMPP: [email protected]
PATCH 2/2 arm: mm: Fix comments in sg_sync functions
In reply to Sakari AilusThe comment on the usage of arm_dma_sync_sg_for_cpu(), arm_dma_sync_sg_for_device(), arm_iommu_sync_sg_for_cpu() and arm_iommu_sync_sg_for_device() functions wrongly noted that the "nelems" parameter is the number of sglist entries returned by dma_map_sg(), while this must be the number of entiries passed to dma_map_sg() instead.
--- arch/arm/mm/dma-mapping.c | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
arch/arm/mm/dma-mapping.c +4 -4
@@ -958,7 +958,7 @@ void arm_dma_unmap_sg(struct device *dev, struct scatterlist *sg, int nents,* arm_dma_sync_sg_for_cpu * @dev: valid struct device pointer, or NULL for ISA and EISA-like devices * @sg: list of buffers -* @nents: number of buffers to map (returned from dma_map_sg) +* @nents: number of buffers to sync (same as was passed to dma_map_sg) * @dir: DMA transfer direction (same as was passed to dma_map_sg) */ void arm_dma_sync_sg_for_cpu(struct device *dev, struct scatterlist *sg,
@@ -977,7 +977,7 @@ void arm_dma_sync_sg_for_cpu(struct device *dev, struct scatterlist *sg,* arm_dma_sync_sg_for_device * @dev: valid struct device pointer, or NULL for ISA and EISA-like devices * @sg: list of buffers -* @nents: number of buffers to map (returned from dma_map_sg) +* @nents: number of buffers to sync (same as was passed to dma_map_sg) * @dir: DMA transfer direction (same as was passed to dma_map_sg) */ void arm_dma_sync_sg_for_device(struct device *dev, struct scatterlist *sg,
@@ -1672,7 +1672,7 @@ void arm_iommu_unmap_sg(struct device *dev, struct scatterlist *sg, int nents,* arm_iommu_sync_sg_for_cpu * @dev: valid struct device pointer * @sg: list of buffers -* @nents: number of buffers to map (returned from dma_map_sg) +* @nents: number of buffers to sync (same as was passed to dma_map_sg) * @dir: DMA transfer direction (same as was passed to dma_map_sg) */ void arm_iommu_sync_sg_for_cpu(struct device *dev, struct scatterlist *sg,
@@ -1690,7 +1690,7 @@ void arm_iommu_sync_sg_for_cpu(struct device *dev, struct scatterlist *sg,* arm_iommu_sync_sg_for_device * @dev: valid struct device pointer * @sg: list of buffers -* @nents: number of buffers to map (returned from dma_map_sg) +* @nents: number of buffers to sync (same as was passed to dma_map_sg) * @dir: DMA transfer direction (same as was passed to dma_map_sg) */ void arm_iommu_sync_sg_for_device(struct device *dev, struct scatterlist *sg,
Signature · 1 line
2.1.0.231.g7484e3b