Re: [PATCH] ipr: don't doublefree pages from scatterlist

[Brian King <brking@us.ibm.com>]

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@us.ibm.com>
---

 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
_