History

lib/scatterlist: Provide a DMA page iterator

Commit 2db76d7c3c6d ("lib/scatterlist: sg_page_iter: support sg lists w/o backing pages") introduced the sg_page_iter_dma_address() function without providing a way to use it in the general case. If the sg_dma_len() is not equal to the sg length callers cannot safely use the for_each_sg_page/sg_page_iter_dma_address combination. Resolve this API mistake by providing a DMA specific iterator, for_each_sg_dma_page(), that uses the right length so sg_page_iter_dma_address() works as expected with all sglists. A new iterator type is introduced to provide compile-time safety against wrongly mixing accessors and iterators.

Jason Gunthorpe committed 7 years ago

Commit d901b271 parent f368ff15 files · +76 −12Browse files

Showing the changes to include/linux (1 of 5 files). Show all

Unified · Split

include/linux/scatterlist.h+40−9
@@ -339,12 +339,12 @@ int sg_alloc_table_chained(struct sg_table *table, int nents, · 338 unmodified lines
339339 /*
340340 * sg page iterator
341341 *
342− * Iterates over sg entries page-by-page. On each successful iteration,
343− * you can call sg_page_iter_page(@piter) and sg_page_iter_dma_address(@piter)
344− * to get the current page and its dma address. @piter->sg will point to the
345− * sg holding this page and @piter->sg_pgoffset to the page's page offset
346− * within the sg. The iteration will stop either when a maximum number of sg
347− * entries was reached or a terminating sg (sg_last(sg) == true) was reached.
342+ * Iterates over sg entries page-by-page. On each successful iteration, you
343+ * can call sg_page_iter_page(@piter) to get the current page and its dma
344+ * address. @piter->sg will point to the sg holding this page and
345+ * @piter->sg_pgoffset to the page's page offset within the sg. The iteration
346+ * will stop either when a maximum number of sg entries was reached or a
347+ * terminating sg (sg_last(sg) == true) was reached.
348348 */
349349 struct sg_page_iter {
350350 struct scatterlist *sg; /* sg holding the page */
@@ -356,7 +356,19 @@ struct sg_page_iter { · 5 unmodified lines
356356 * next step */
357357 };
358358
359+/*
360+ * sg page iterator for DMA addresses
361+ *
362+ * This is the same as sg_page_iter however you can call
363+ * sg_page_iter_dma_address(@dma_iter) to get the page's DMA
364+ * address. sg_page_iter_page() cannot be called on this iterator.
365+ */
366+struct sg_dma_page_iter {
367+ struct sg_page_iter base;
368+};
369+
359370 bool __sg_page_iter_next(struct sg_page_iter *piter);
371+bool __sg_page_iter_dma_next(struct sg_dma_page_iter *dma_iter);
360372 void __sg_page_iter_start(struct sg_page_iter *piter,
361373 struct scatterlist *sglist, unsigned int nents,
362374 unsigned long pgoffset);
@@ -372,11 +384,13 @@ static inline struct page *sg_page_iter_page(struct sg_page_iter *piter) · 9 unmodified lines
372384 /**
373385 * sg_page_iter_dma_address - get the dma address of the current page held by
374386 * the page iterator.
375− * @piter: page iterator holding the page
387+ * @dma_iter: page iterator holding the page
376388 */
377−static inline dma_addr_t sg_page_iter_dma_address(struct sg_page_iter *piter)
389+static inline dma_addr_t
390+sg_page_iter_dma_address(struct sg_dma_page_iter *dma_iter)
378391 {
379− return sg_dma_address(piter->sg) + (piter->sg_pgoffset << PAGE_SHIFT);
392+ return sg_dma_address(dma_iter->base.sg) +
393+ (dma_iter->base.sg_pgoffset << PAGE_SHIFT);
380394 }
381395
382396 /**
@@ -385,11 +399,28 @@ static inline dma_addr_t sg_page_iter_dma_address(struct sg_page_iter *piter) · 2 unmodified lines
385399 * @piter: page iterator to hold current page, sg, sg_pgoffset
386400 * @nents: maximum number of sg entries to iterate over
387401 * @pgoffset: starting page offset
402+ *
403+ * Callers may use sg_page_iter_page() to get each page pointer.
388404 */
389405 #define for_each_sg_page(sglist, piter, nents, pgoffset) \
390406 for (__sg_page_iter_start((piter), (sglist), (nents), (pgoffset)); \
391407 __sg_page_iter_next(piter);)
392408
409+/**
410+ * for_each_sg_dma_page - iterate over the pages of the given sg list
411+ * @sglist: sglist to iterate over
412+ * @dma_iter: page iterator to hold current page
413+ * @dma_nents: maximum number of sg entries to iterate over, this is the value
414+ * returned from dma_map_sg
415+ * @pgoffset: starting page offset
416+ *
417+ * Callers may use sg_page_iter_dma_address() to get each page's DMA address.
418+ */
419+#define for_each_sg_dma_page(sglist, dma_iter, dma_nents, pgoffset) \
420+ for (__sg_page_iter_start(&(dma_iter)->base, sglist, dma_nents, \
421+ pgoffset); \
422+ __sg_page_iter_dma_next(dma_iter);)
423+
393424 /*
394425 * Mapping sg iterator
395426 *

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t