Skip to contentSkip to conversation

iov_iter: Add a function to extract a page list from an iterator

PATCH In review David Howells 1 participant 2 messages Jan 19, 2023

Subsystems (4)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 iov_iter: Add a function to extract a page list from an iterator

Add a function, iov_iter_extract_pages(), to extract a list of pages from an iterator. The pages may be returned with a reference added or a pin added or neither, depending on the type of iterator and the direction of transfer. The caller must pass FOLL_READ_FROM_MEM or FOLL_WRITE_TO_MEM as part of gup_flags to indicate how the iterator contents are to be used.

Add a second function, iov_iter_extract_mode(), to determine how the cleanup should be done.

There are three cases:

(1) Transfer *into* an ITER_IOVEC or ITER_UBUF iterator.

Extracted pages will have pins obtained on them (but not references) so that fork() doesn't CoW the pages incorrectly whilst the I/O is in progress.

iov_iter_extract_mode() will return FOLL_PIN for this case. The caller should use something like unpin_user_page() to dispose of the page.

(2) Transfer is *out of* an ITER_IOVEC or ITER_UBUF iterator.

Extracted pages will have references obtained on them, but not pins.

iov_iter_extract_mode() will return FOLL_GET. The caller should use something like put_page() for page disposal.

(3) Any other sort of iterator.

No refs or pins are obtained on the page, the assumption is made that the caller will manage page retention. ITER_ALLOW_P2PDMA is not permitted.

iov_iter_extract_mode() will return 0. The pages don't need additional disposal.

---

Notes:
ver #7)
- Switch to passing in iter-specific flags rather than FOLL_* flags.
- Use READ_FROM_ITER/WRITE_TO_ITER to indicate direction.
- Use ITER_ALLOW_P2PDMA to request FOLL_PCI_P2PDMA.
- Disallow use of ITER_ALLOW_P2PDMA with non-user-backed iter.

ver #6)
- Add back the function to indicate the cleanup mode.
- Drop the cleanup_mode return arg to iov_iter_extract_pages().
- Pass FOLL_SOURCE/DEST_BUF in gup_flags. Check this against the iter data_source.

ver #4)
- Use ITER_SOURCE/DEST instead of WRITE/READ.
- Allow additional FOLL_* flags, such as FOLL_PCI_P2PDMA to be passed in.

ver #3)
- Switch to using EXPORT_SYMBOL_GPL to prevent indirect 3rd-party access to get/pin_user_pages_fast()[1].

 include/linux/uio.h |  28 ++++
 lib/iov_iter.c      | 370 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 398 insertions(+)
include/linux/uio.h +28 -0
index 4348d37c008b..bac0852de820 100644
@@ -356,4 +356,32 @@ static inline void iov_iter_ubuf(struct iov_iter *i, unsigned int direction,
 #define WRITE_TO_ITER		0x02	/* We will be writing data to the iterator */
 #define ITER_ALLOW_P2PDMA	0x04	/* Allow P2PDMA on the extracted pages */
 
+ssize_t iov_iter_extract_pages(struct iov_iter *i, struct page ***pages,
+			       size_t maxsize, unsigned int maxpages,
+			       unsigned int extract_flags, size_t *offset0);
+
+/**
+ * iov_iter_extract_mode - Indicate how pages from the iterator will be retained
+ * @iter: The iterator
+ * @gup_flags: How the iterator is to be used (FOLL_WRITE_TO/READ_FROM_MEM)
+ *
+ * Examine the iterator and the gup_flags and indicate by returning FOLL_PIN,
+ * FOLL_GET or 0 as to how, if at all, pages extracted from the iterator will
+ * be retained by the extraction function.
+ *
+ * FOLL_GET indicates that the pages will have a reference taken on them that
+ * the caller must put.  This can be done for DMA/async DIO write from a page.
+ *
+ * FOLL_PIN indicates that the pages will have a pin placed in them that the
+ * caller must unpin.  This is must be done for DMA/async DIO read to a page to
+ * avoid CoW problems in fork.
+ *
+ * 0 indicates that no measures are taken and that it's up to the caller to
+ * retain the pages.
+ */
+#define iov_iter_extract_mode(iter, gup_flags) \
+	(user_backed_iter(iter) ?				\
+	 (gup_flags & FOLL_IO_DIR_MASK) == FOLL_READ_FROM_MEM ?	\
+	 FOLL_GET : FOLL_PIN : 0)
+
 #endif
lib/iov_iter.c +370 -0

373 lines not on this page · raw message

Signature · 1 line
2.39.0
#1 lore raw

Apologies - this was only meant to be sent to myself. Seems git send-email's --suppress-cc=cc option disables confirmation mode.

David