mm: document and polish read-ahead code

Add some "big-picture" documentation for read-ahead and polish the code to make it fit this documentation. The meaning of ->async_size is clarified to match its name. i.e. Any request to ->readahead() has a sync part and an async part. The caller will wait for the sync pages to complete, but will not wait for the async pages. The first async page is still marked PG_readahead Note that the current function names page_cache_sync_ra() and page_cache_async_ra() are misleading. All ra request are partly sync and partly async, so either part can be empty. A page_cache_sync_ra() request will usually set ->async_size non-zero, implying it is not all synchronous. When a non-zero req_count is passed to page_cache_async_ra(), the implication is that some prefix of the request is synchronous, though the calculation made there is incorrect - I haven't tried to fix it.

NeilBrown committed 4 years ago

Commit 84dacdb1 parent bf507034 files · +133 −10Browse files

Unified · Split

4 files

Documentation/core-api/mm-api.rst +17 −2
Documentation/filesystems/vfs.rst +10 −6
include/linux/fs.h +7 −2
mm/readahead.c +99 −0

Documentation/core-api/mm-api.rst+17−2

@@ -58,15 +58,30 @@ Virtually Contiguous Mappings · 57 unmodified lines
58	58	File Mapping and Page Cache
59	59	===========================
60	60
61		−.. kernel-doc:: mm/readahead.c
62		− :export:
	61	+Filemap
	62	+-------
63	63
64	64	.. kernel-doc:: mm/filemap.c
65	65	:export:
66	66
	67	+Readahead
	68	+---------
	69	+
	70	+.. kernel-doc:: mm/readahead.c
	71	+ :doc: Readahead Overview
	72	+
	73	+.. kernel-doc:: mm/readahead.c
	74	+ :export:
	75	+
	76	+Writeback
	77	+---------
	78	+
67	79	.. kernel-doc:: mm/page-writeback.c
68	80	:export:
69	81
	82	+Truncate
	83	+--------
	84	+
70	85	.. kernel-doc:: mm/truncate.c
71	86	:export:
72	87

Documentation/filesystems/vfs.rst+10−6

@@ -806,12 +806,16 @@ cache in your filesystem. The following members are defined: · 805 unmodified lines
806	806	object. The pages are consecutive in the page cache and are
807	807	locked. The implementation should decrement the page refcount
808	808	after starting I/O on each page. Usually the page will be
809		− unlocked by the I/O completion handler. If the filesystem decides
810		− to stop attempting I/O before reaching the end of the readahead
811		− window, it can simply return. The caller will decrement the page
812		− refcount and unlock the remaining pages for you. Set PageUptodate
813		− if the I/O completes successfully. Setting PageError on any page
814		− will be ignored; simply unlock the page if an I/O error occurs.
	809	+ unlocked by the I/O completion handler. The set of pages are
	810	+ divided into some sync pages followed by some async pages,
	811	+ rac->ra->async_size gives the number of async pages. The
	812	+ filesystem should attempt to read all sync pages but may decide
	813	+ to stop once it reaches the async pages. If it does decide to
	814	+ stop attempting I/O, it can simply return. The caller will
	815	+ remove the remaining pages from the address space, unlock them
	816	+ and decrement the page refcount. Set PageUptodate if the I/O
	817	+ completes successfully. Setting PageError on any page will be
	818	+ ignored; simply unlock the page if an I/O error occurs.
815	819
816	820	``readpages``
817	821	called by the VM to read pages associated with the address_space

include/linux/fs.h+7−2

@@ -930,10 +930,15 @@ struct fown_struct { · 929 unmodified lines
930	930	* struct file_ra_state - Track a file's readahead state.
931	931	* @start: Where the most recent readahead started.
932	932	* @size: Number of pages read in the most recent readahead.
933		− * @async_size: Start next readahead when this many pages are left.
934		− * @ra_pages: Maximum size of a readahead request.
	933	+ * @async_size: Numer of pages that were/are not needed immediately
	934	+ * and so were/are genuinely "ahead". Start next readahead when
	935	+ * the first of these pages is accessed.
	936	+ * @ra_pages: Maximum size of a readahead request, copied from the bdi.
935	937	* @mmap_miss: How many mmap accesses missed in the page cache.
936	938	* @prev_pos: The last byte in the most recent read request.
	939	+ *
	940	+ * When this structure is passed to ->readahead(), the "most recent"
	941	+ * readahead means the current readahead.
937	942	*/
938	943	struct file_ra_state {
939	944	pgoff_t start;

mm/readahead.c+99−0

@@ -8,6 +8,105 @@ · 7 unmodified lines
8	8	* Initial version.
9	9	*/
10	10
	11	+/**
	12	+ * DOC: Readahead Overview
	13	+ *
	14	+ * Readahead is used to read content into the page cache before it is
	15	+ * explicitly requested by the application. Readahead only ever
	16	+ * attempts to read pages that are not yet in the page cache. If a
	17	+ * page is present but not up-to-date, readahead will not try to read
	18	+ * it. In that case a simple ->readpage() will be requested.
	19	+ *
	20	+ * Readahead is triggered when an application read request (whether a
	21	+ * systemcall or a page fault) finds that the requested page is not in
	22	+ * the page cache, or that it is in the page cache and has the
	23	+ * %PG_readahead flag set. This flag indicates that the page was loaded
	24	+ * as part of a previous read-ahead request and now that it has been
	25	+ * accessed, it is time for the next read-ahead.
	26	+ *
	27	+ * Each readahead request is partly synchronous read, and partly async
	28	+ * read-ahead. This is reflected in the struct file_ra_state which
	29	+ * contains ->size being to total number of pages, and ->async_size
	30	+ * which is the number of pages in the async section. The first page in
	31	+ * this async section will have %PG_readahead set as a trigger for a
	32	+ * subsequent read ahead. Once a series of sequential reads has been
	33	+ * established, there should be no need for a synchronous component and
	34	+ * all read ahead request will be fully asynchronous.
	35	+ *
	36	+ * When either of the triggers causes a readahead, three numbers need to
	37	+ * be determined: the start of the region, the size of the region, and
	38	+ * the size of the async tail.
	39	+ *
	40	+ * The start of the region is simply the first page address at or after
	41	+ * the accessed address, which is not currently populated in the page
	42	+ * cache. This is found with a simple search in the page cache.
	43	+ *
	44	+ * The size of the async tail is determined by subtracting the size that
	45	+ * was explicitly requested from the determined request size, unless
	46	+ * this would be less than zero - then zero is used. NOTE THIS
	47	+ * CALCULATION IS WRONG WHEN THE START OF THE REGION IS NOT THE ACCESSED
	48	+ * PAGE.
	49	+ *
	50	+ * The size of the region is normally determined from the size of the
	51	+ * previous readahead which loaded the preceding pages. This may be
	52	+ * discovered from the struct file_ra_state for simple sequential reads,
	53	+ * or from examining the state of the page cache when multiple
	54	+ * sequential reads are interleaved. Specifically: where the readahead
	55	+ * was triggered by the %PG_readahead flag, the size of the previous
	56	+ * readahead is assumed to be the number of pages from the triggering
	57	+ * page to the start of the new readahead. In these cases, the size of
	58	+ * the previous readahead is scaled, often doubled, for the new
	59	+ * readahead, though see get_next_ra_size() for details.
	60	+ *
	61	+ * If the size of the previous read cannot be determined, the number of
	62	+ * preceding pages in the page cache is used to estimate the size of
	63	+ * a previous read. This estimate could easily be misled by random
	64	+ * reads being coincidentally adjacent, so it is ignored unless it is
	65	+ * larger than the current request, and it is not scaled up, unless it
	66	+ * is at the start of file.
	67	+ *
	68	+ * In general read ahead is accelerated at the start of the file, as
	69	+ * reads from there are often sequential. There are other minor
	70	+ * adjustments to the read ahead size in various special cases and these
	71	+ * are best discovered by reading the code.
	72	+ *
	73	+ * The above calculation determines the readahead, to which any requested
	74	+ * read size may be added.
	75	+ *
	76	+ * Readahead requests are sent to the filesystem using the ->readahead()
	77	+ * address space operation, for which mpage_readahead() is a canonical
	78	+ * implementation. ->readahead() should normally initiate reads on all
	79	+ * pages, but may fail to read any or all pages without causing an IO
	80	+ * error. The page cache reading code will issue a ->readpage() request
	81	+ * for any page which ->readahead() does not provided, and only an error
	82	+ * from this will be final.
	83	+ *
	84	+ * ->readahead() will generally call readahead_page() repeatedly to get
	85	+ * each page from those prepared for read ahead. It may fail to read a
	86	+ * page by:
	87	+ *
	88	+ * * not calling readahead_page() sufficiently many times, effectively
	89	+ * ignoring some pages, as might be appropriate if the path to
	90	+ * storage is congested.
	91	+ *
	92	+ * * failing to actually submit a read request for a given page,
	93	+ * possibly due to insufficient resources, or
	94	+ *
	95	+ * * getting an error during subsequent processing of a request.
	96	+ *
	97	+ * In the last two cases, the page should be unlocked to indicate that
	98	+ * the read attempt has failed. In the first case the page will be
	99	+ * unlocked by the caller.
	100	+ *
	101	+ * Those pages not in the final ``async_size`` of the request should be
	102	+ * considered to be important and ->readahead() should not fail them due
	103	+ * to congestion or temporary resource unavailability, but should wait
	104	+ * for necessary resources (e.g. memory or indexing information) to
	105	+ * become available. Pages in the final ``async_size`` may be
	106	+ * considered less urgent and failure to read them is more acceptable.
	107	+ * They will eventually be read individually using ->readpage().
	108	+ */
	109	+
11	110	#include <linux/kernel.h>
12	111	#include <linux/dax.h>
13	112	#include <linux/gfp.h>

mm: document and polish read-ahead code

Keyboard shortcuts

General

Issues and pull requests

Issues, pull requests and Inbox

Repository code