iov_iter: Add a function to extract a page list from an iterator
Subsystems (4)
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
@@ -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
Apologies - this was only meant to be sent to myself. Seems git send-email's --suppress-cc=cc option disables confirmation mode.
David