mm: document read_pages and simplify usage
Subsystems (3)
cover mm: document read_pages and simplify usage
Add a kerneldoc for read_pages() to formalize an invariant and then use it to simplify the callers in page_cache_ra_unbounded().
Frederick Mayle (2):
mm/readahead: add kerneldoc for read_pages mm/readahead: simplify page_cache_ra_unbounded loop counter reset
mm/readahead.c | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-)
base-commit: 972c53e0ec3abfc6f5fe2cb503640710fb23cf95
Signature · 1 line
2.54.0.563.g4f69b47b94-goog
PATCH 1/2 mm/readahead: add kerneldoc for read_pages
Formalize one of the invariants provided by the current implementation so that callers can depend on it, as discussed in [1].
--- mm/readahead.c | 11 +++++++++++ 1 file changed, 11 insertions(+)
mm/readahead.c +11 -0
@@ -146,6 +146,17 @@ file_ra_state_init(struct file_ra_state *ra, struct address_space *mapping) }EXPORT_SYMBOL_GPL (file_ra_state_init); +/** +* read_pages() - Start IO for a contiguous range of allocated folios in the +* page cache. +* @rac: Readahead control. +* +* When read_pages() returns, it is guaranteed that all of the folios will have +* been processed or removed so that ``readahead_count(rac) == 0``. However, +* that does not imply that ``readahead_index(rac)`` will be updated to point +* to the end of the originally requested range because, for example, the +* filesystem may expand the range upwards. +*/ static void read_pages (struct readahead_control *rac) {const struct address_space_operations *aops = rac->mapping->a_ops;
Signature · 1 line
2.54.0.563.g4f69b47b94-goog
Matthew Wilcox
maintainerRe: [PATCH 1/2] mm/readahead: add kerneldoc for read_pages
Quoted 2 lines · Frederick Mayle
Formalize one of the invariants provided by the current implementation so that callers can depend on it, as discussed in [1].
We don't normally write kerneldoc for static functions. I'm not sure why Andrew told you to do this. I have no objection to adding documentation, but I don't think it should be marked as kerneldoc. And if it's not kerneldoc, it doesn't have to be written in such a stifling style.
Andrew Morton
maintainerRe: [PATCH 1/2] mm/readahead: add kerneldoc for read_pages
Quoted 9 lines · On Tue, 12 May 2026 22:05:34 +0100 Matthew Wilcox <[email protected]> wrote:
Quoted 2 lines · Frederick Mayle
Formalize one of the invariants provided by the current implementation so that callers can depend on it, as discussed in [1].
We don't normally write kerneldoc for static functions. I'm not sure why Andrew told you to do this. I have no objection to adding documentation, but I don't think it should be marked as kerneldoc. And if it's not kerneldoc, it doesn't have to be written in such a stifling style.
I'm OK either way. The main point here is that [2/2] relies on unobvious and possibly fragile behaviour of read_pages().
Re: [PATCH 1/2] mm/readahead: add kerneldoc for read_pages
In reply to Matthew WilcoxQuoted 10 lines · Matthew Wilcox
Quoted 2 lines · Frederick Mayle
Formalize one of the invariants provided by the current implementation so that callers can depend on it, as discussed in [1].
We don't normally write kerneldoc for static functions. I'm not sure why Andrew told you to do this. I have no objection to adding documentation, but I don't think it should be marked as kerneldoc. And if it's not kerneldoc, it doesn't have to be written in such a stifling style.
If it isn't a kerneldoc, I can delete the essentially redundant argument line. Besides that, I think the stifling style might just be me. Let me know if there is something specific you don't like.
PATCH 2/2 mm/readahead: simplify page_cache_ra_unbounded loop counter reset
In reply to Frederick MayleMinor cleanup, no behavior change intended.
read_pages ensures that ractl->_nr_pages is zero before it returns, so the ractl->_nr_pages term in these expressions contributes nothing. This seems to have been true since the statements were introduced in commit f615bd5c4725f ("mm/readahead: Handle ractl nr_pages being modified").
The new expression has an intuitive explanation. When filesystems perform readahead, they increment ractl->_index by the number of pages processed, so, after read_pages returns, ractl->_index points to the first page after those already processed. index points to the first page considered in the loop. So, ractl->_index - index is the number of pages processed by the loop so far.
--- mm/readahead.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
mm/readahead.c +2 -2
@@ -281,7 +281,7 @@ void page_cache_ra_unbounded(struct readahead_control *ractl,*/ read_pages (ractl); ractl->_index += min_nrpages; - i = ractl->_index + ractl->_nr_pages - index; + i = ractl->_index - index;continue ; }
@@ -297,7 +297,7 @@ void page_cache_ra_unbounded(struct readahead_control *ractl,break ;read_pages (ractl); ractl->_index += min_nrpages; - i = ractl->_index + ractl->_nr_pages - index; + i = ractl->_index - index;continue ; }if (i == mark)
Signature · 1 line
2.54.0.563.g4f69b47b94-goog
This is a combined v2 of the following patches. Sorry that I didn't send it as such.
https://lore.kernel.org/r/[email protected]/
https://lore.kernel.org/r/[email protected]/
Quoted 16 lines · Frederick Mayle
Add a kerneldoc for
read_pages()to formalize an invariant and then use it to simplify the callers inpage_cache_ra_unbounded().Frederick Mayle (2):
mm/readahead: add kerneldoc forread_pagesmm/readahead: simplifypage_cache_ra_unboundedloop counter resetmm/readahead.c | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-)base-commit:
972c53e0ec3abfc6f5fe2cb503640710fb23cf95--
2.54.0.563.g4f69b47b94-goog