James Bottomley wrote: > On Mon, 2006-02-06 at 16:45 +0000, Hugh Dickins wrote: >> But I'd also want James or someone to clarify the paragraph >> "Please note that the sg cannot be mapped again if it has been mapped once. >> The mapping process is allowed to destroy information in the sg." >> which I took as explicitly allowing what x86_64 does in gart_map_sg. >> I thought James had a scenario in mind which demands this wholesale >> destruction, but it seems not; and I now read that first sentence as >> saying the sg must be unmapped before it can be mapped a second time, >> not that it can only be mapped once. >> >> And add a paragraph explaining that really the one array of scatterlist >> entries should be regarded as two arrays of possibly different lengths, >> the page,offset,length array and the dma_address,dma_length array: >> because entries of the latter may be coalesced, so that in the end >> the dma_address in a scatterlength entry may bear no relation to the >> page pointer in that same entry, but to the page pointer in a later entry. >> Though it gets hard to explain given that not all architectures coalesce, >> so may not even have a separate dma_length field; or use different naming. >> If you can express this better than I, please do! > > Yes, I added that piece after the x86_64 problem. The original x86_64 > bug was that you couldn't do dma_map_sg() then dma_unmap_sg() then > dma_map_sg() on the same scatterlist (the map was destroying information > which wasn't restored on the unmap, so the second map produced an > incorrect scatterlist), which was causing a bug in all SCSI drivers > (because that's the way SCSI requeueing works). Here is a second try at a documentation update. Any takers to fixup x86_64? Brian -- Brian King eServer Storage I/O IBM Linux Technology Center
The current pci_map_sg API is a bit unclear what it is allowed to modify in the passed scatterlist when coalescing entries. Clarify the pci_map_sg API to prevent it from modifying the page, offset, and length fields in the scatterlist. Signed-off-by: Brian King <brking@xxxxxxxxxx> --- linux-2.6-bjking1/Documentation/DMA-API.txt | 5 +++-- linux-2.6-bjking1/Documentation/DMA-mapping.txt | 5 ++++- 2 files changed, 7 insertions(+), 3 deletions(-) diff -puN Documentation/DMA-mapping.txt~dma_mapping_clarification Documentation/DMA-mapping.txt --- linux-2.6/Documentation/DMA-mapping.txt~dma_mapping_clarification 2006-02-06 13:05:52.000000000 -0600 +++ linux-2.6-bjking1/Documentation/DMA-mapping.txt 2006-02-06 13:05:52.000000000 -0600 @@ -513,7 +513,10 @@ consecutive sglist entries can be merged ends and the second one starts on a page boundary - in fact this is a huge advantage for cards which either cannot do scatter-gather or have very limited number of scatter-gather entries) and returns the actual number -of sg entries it mapped them to. On failure 0 is returned. +of sg entries it mapped them to. The implementation is free to do this +by modifying the scatterlist fields specified for DMA. The scatterlist +fields used as an input to this function (i.e. page, offset, and length) +will NOT be modified. On failure 0 is returned. Then you should loop count times (note: this can be less than nents times) and use sg_dma_address() and sg_dma_len() macros where you previously diff -puN Documentation/DMA-API.txt~dma_mapping_clarification Documentation/DMA-API.txt --- linux-2.6/Documentation/DMA-API.txt~dma_mapping_clarification 2006-02-06 13:06:17.000000000 -0600 +++ linux-2.6-bjking1/Documentation/DMA-API.txt 2006-02-06 13:07:40.000000000 -0600 @@ -318,8 +318,9 @@ than <nents> passed in if the block laye elements of the scatter/gather list are physically adjacent and thus may be mapped with a single entry). -Please note that the sg cannot be mapped again if it has been mapped once. -The mapping process is allowed to destroy information in the sg. +Please note that the sg can be mapped again, as long as it is unmapped +first. The mapping process is only allowed to modify the scatterlist +fields related to DMA. As with the other mapping interfaces, dma_map_sg can fail. When it does, 0 is returned and a driver must take appropriate action. It is _
