From patchwork Fri Apr 1 06:11:08 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: NeilBrown X-Patchwork-Id: 12797925 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by smtp.lore.kernel.org (Postfix) with ESMTP id 829A4C433F5 for ; Fri, 1 Apr 2022 06:11:36 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id A9D636B0073; Fri, 1 Apr 2022 02:11:25 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id A4C246B0075; Fri, 1 Apr 2022 02:11:25 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 913938D0001; Fri, 1 Apr 2022 02:11:25 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from forelay.hostedemail.com (smtprelay0244.hostedemail.com [216.40.44.244]) by kanga.kvack.org (Postfix) with ESMTP id 816ED6B0073 for ; Fri, 1 Apr 2022 02:11:25 -0400 (EDT) Received: from smtpin16.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by forelay05.hostedemail.com (Postfix) with ESMTP id 33E551831A9F3 for ; Fri, 1 Apr 2022 06:11:15 +0000 (UTC) X-FDA: 79307287710.16.3FFDBC8 Received: from smtp-out2.suse.de (smtp-out2.suse.de [195.135.220.29]) by imf12.hostedemail.com (Postfix) with ESMTP id B30E240010 for ; Fri, 1 Apr 2022 06:11:14 +0000 (UTC) Received: from imap2.suse-dmz.suse.de (imap2.suse-dmz.suse.de [192.168.254.74]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-521) server-digest SHA512) (No client certificate requested) by smtp-out2.suse.de (Postfix) with ESMTPS id 4B1761FCFE; Fri, 1 Apr 2022 06:11:13 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_rsa; t=1648793473; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=Aoj4r4viFslO1DDiR9In4xWGea8lsy82pkp6YsvrMzA=; b=azw3hKyNgUivcyyoiSwosZClCFBsouwbO/hvqjdHCXYbneGHOVzychvgmjTwXHD9MXQpEq Jsxt2VDUA41mH0hiNq2KTeBLyFmxP5FSDE0WnkF1c1jhCi/jvLcwHQ+uPD77CRajB8xb5W +oouyUILN3zo7QwVveJjXVsP2cagpR4= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_ed25519; t=1648793473; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=Aoj4r4viFslO1DDiR9In4xWGea8lsy82pkp6YsvrMzA=; b=SYKFJAj86m1SlYe37iPpqtCNsUM8JjJcspAu52eFCOvU+7Io2I33uDWamwwPMyisoVxYB1 JRIG3Xw9sRFNIiAA== Received: from imap2.suse-dmz.suse.de (imap2.suse-dmz.suse.de [192.168.254.74]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-521) server-digest SHA512) (No client certificate requested) by imap2.suse-dmz.suse.de (Postfix) with ESMTPS id DAF0F132C1; Fri, 1 Apr 2022 06:11:11 +0000 (UTC) Received: from dovecot-director2.suse.de ([192.168.254.65]) by imap2.suse-dmz.suse.de with ESMTPSA id xhv6JH+XRmLcAQAAMHmgww (envelope-from ); Fri, 01 Apr 2022 06:11:11 +0000 MIME-Version: 1.0 From: "NeilBrown" To: Andrew Morton Cc: Jonathan Corbet , Linux Memory Management List , linux-doc@vger.kernel.org Subject: [PATCH] MM: minor improvements to readahead documentation Date: Fri, 01 Apr 2022 17:11:08 +1100 Message-id: <164879346851.25542.18299715584610241983@noble.neil.brown.name> X-Rspamd-Server: rspam09 X-Rspam-User: X-Stat-Signature: 661fhsf89tdr3xgoexxkas8qhf7p7ntq Authentication-Results: imf12.hostedemail.com; dkim=pass header.d=suse.de header.s=susede2_rsa header.b=azw3hKyN; dkim=pass header.d=suse.de header.s=susede2_ed25519 header.b=SYKFJAj8; dmarc=pass (policy=none) header.from=suse.de; spf=pass (imf12.hostedemail.com: domain of neilb@suse.de designates 195.135.220.29 as permitted sender) smtp.mailfrom=neilb@suse.de X-Rspamd-Queue-Id: B30E240010 X-HE-Tag: 1648793474-498657 X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: - use "readahead" consistently - not "read-ahead" or "read ahead". - clarify some sections that, on reflection, weren't very clear - minor punctuation/spelling fixes. Signed-off-by: NeilBrown --- mm/readahead.c | 39 ++++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/mm/readahead.c b/mm/readahead.c index d3a47546d17d..83f4345a400d 100644 --- a/mm/readahead.c +++ b/mm/readahead.c @@ -18,24 +18,24 @@ * it. In that case a simple ->readpage() will be requested. * * Readahead is triggered when an application read request (whether a - * systemcall or a page fault) finds that the requested page is not in + * system call or a page fault) finds that the requested page is not in * the page cache, or that it is in the page cache and has the * %PG_readahead flag set. This flag indicates that the page was loaded - * as part of a previous read-ahead request and now that it has been - * accessed, it is time for the next read-ahead. + * as part of a previous readahead request and now that it has been + * accessed, it is time for the next readahead. * * Each readahead request is partly synchronous read, and partly async - * read-ahead. This is reflected in the struct file_ra_state which + * readahead. This is reflected in the struct file_ra_state which * contains ->size being to total number of pages, and ->async_size - * which is the number of pages in the async section. The first page in - * this async section will have %PG_readahead set as a trigger for a - * subsequent read ahead. Once a series of sequential reads has been - * established, there should be no need for a synchronous component and - * all read ahead request will be fully asynchronous. + * which is the number of pages in the async section. The %PG_readahead + * flag will be set on the first page in this async section as a trigger + * for a subsequent readahead. Once a series of sequential reads has + * been established, there should be no need for a synchronous component + * and all readahead requests will be fully asynchronous. * * When either of the triggers causes a readahead, three numbers need to - * be determined: the start of the region, the size of the region, and - * the size of the async tail. + * be determined: the start of the region to read, the size of the + * region, and the size of the async tail. * * The start of the region is simply the first page address at or after * the accessed address, which is not currently populated in the page @@ -45,7 +45,7 @@ * was explicitly requested from the determined request size, unless * this would be less than zero - then zero is used. NOTE THIS * CALCULATION IS WRONG WHEN THE START OF THE REGION IS NOT THE ACCESSED - * PAGE. + * PAGE. ALSO THIS CALCULATION IS NOT USED CONSISTENTLY. * * The size of the region is normally determined from the size of the * previous readahead which loaded the preceding pages. This may be @@ -65,13 +65,14 @@ * larger than the current request, and it is not scaled up, unless it * is at the start of file. * - * In general read ahead is accelerated at the start of the file, as + * In general, readahead is accelerated at the start of the file, as * reads from there are often sequential. There are other minor - * adjustments to the read ahead size in various special cases and these + * adjustments to the readahead size in various special cases and these * are best discovered by reading the code. * - * The above calculation determines the readahead, to which any requested - * read size may be added. + * The above calculation, based on the previous readahead size, + * determines the size of the readahead, to which any requested read + * size may be added. * * Readahead requests are sent to the filesystem using the ->readahead() * address space operation, for which mpage_readahead() is a canonical @@ -82,7 +83,7 @@ * from this will be final. * * ->readahead() will generally call readahead_page() repeatedly to get - * each page from those prepared for read ahead. It may fail to read a + * each page from those prepared for readahead. It may fail to read a * page by: * * * not calling readahead_page() sufficiently many times, effectively @@ -107,9 +108,9 @@ * In this case it is best to use delete_from_page_cache() to remove the * pages from the page cache as is automatically done for pages that * were not fetched with readahead_page(). This will allow a - * subsequent synchronous read ahead request to try them again. If they + * subsequent synchronous readahead request to try them again. If they * are left in the page cache, then they will be read individually using - * ->readpage(). + * ->readpage() which may be less efficient. * */