From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-13.1 required=3.0 tests=BAYES_00, DKIM_ADSP_CUSTOM_MED,DKIM_INVALID,DKIM_SIGNED,FREEMAIL_FORGED_FROMDOMAIN, FREEMAIL_FROM,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,NICE_REPLY_A,SPF_HELO_NONE,SPF_PASS, URIBL_RED,USER_AGENT_SANE_1 autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id BD9ADC4338F for ; Sun, 25 Jul 2021 20:15:28 +0000 (UTC) Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by mail.kernel.org (Postfix) with ESMTP id 3B5EE60EB4 for ; Sun, 25 Jul 2021 20:15:27 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 3B5EE60EB4 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=gmail.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=kvack.org Received: by kanga.kvack.org (Postfix) id 1FA406B006C; Sun, 25 Jul 2021 16:15:27 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 1AB068D0002; Sun, 25 Jul 2021 16:15:27 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 071B58D0001; Sun, 25 Jul 2021 16:15:27 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from forelay.hostedemail.com (smtprelay0028.hostedemail.com [216.40.44.28]) by kanga.kvack.org (Postfix) with ESMTP id DAC6B6B006C for ; Sun, 25 Jul 2021 16:15:26 -0400 (EDT) Received: from smtpin18.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by forelay03.hostedemail.com (Postfix) with ESMTP id 66B218249980 for ; Sun, 25 Jul 2021 20:15:26 +0000 (UTC) X-FDA: 78402215052.18.8606D26 Received: from mail-wr1-f41.google.com (mail-wr1-f41.google.com [209.85.221.41]) by imf01.hostedemail.com (Postfix) with ESMTP id 1D1B7503BF10 for ; Sun, 25 Jul 2021 20:15:25 +0000 (UTC) Received: by mail-wr1-f41.google.com with SMTP id l18so855015wrv.5 for ; Sun, 25 Jul 2021 13:15:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=subject:to:cc:references:from:message-id:date:user-agent :mime-version:in-reply-to:content-language:content-transfer-encoding; bh=/BNEul6Wi0Aotg0RFtiwPfulYe7lefwQCeOZkh4PSE0=; b=oRqvXYzJzh+GnEhWJ/MCkXi/KZ7eWYKjRkWcopXGRWzIbsK3OK0MFL9nsjssG/hggh GfHlp092bfSTmWKJpVccZKxPxcyeCL1wNpdImG0BRtnKtMeAs9VI7GEPgHDcQv5Bz8ty O0toxyblzbMlJ7SgInWLCRp3BkTf39lBXcXqgH3g+Lrpb32g/RaKTCjSjrZdQQtLEK6I SFqHRjWcAs9WftgYy5lMntD8GMUuZu4exPzvLMkVqMwoFTN4RfUppqChr9JAEcm39GPD W40fIWuF6HtsfqGpZn/HUZZurEU4Ee39Aq+pm+n37tYyr8C/HenpAaoZn18HljGheMMz kGCA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:subject:to:cc:references:from:message-id:date :user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=/BNEul6Wi0Aotg0RFtiwPfulYe7lefwQCeOZkh4PSE0=; b=swzI17+a3siH3baWpeOAubEpHQLlImeDjQQoITD5yrdf4+k0RYqM9oiVFHws0yAM+3 9v5lXUBD7tyHQ3rYjw4J1VrZTVbClQp8uYbqFm2SsgAUA8BO33ngjjGKsh6aqhkQtc+g 7aufw8KEkL7aWIvWm/aPSplxRmsF5mRH8nUo7Dpbg/0XxUu0DUdeQr/FpdkXlMZK2TdH yLwNKXiybTQ+qvSzJcnLm5mR+VA8YrLuF732AsKCQg40z9sfO6g31XQocEyFxUAegM8F I11vBcivc3VDmVqpVQSpkD4x50pyszkTyVK8PdrCDcoyuBWuzkaS2uS7mZmkQcpubZNa 6Iwg== X-Gm-Message-State: AOAM531sy0DHZ9KBeer9tTVKTUYNpn+n8EVm3FbTzw0g3LlACqL/PjXp 3jND8me1fF7OCTOe3loj2bvRe2ZUr/U= X-Google-Smtp-Source: ABdhPJzKDfR4Fh52ptEExnWIEX7Z68KI4VTyXTJP5lNDswtbqdkCo9FHNIHJK9WTv/Kicz/E1Q6yzw== X-Received: by 2002:a5d:4312:: with SMTP id h18mr16067165wrq.170.1627244124840; Sun, 25 Jul 2021 13:15:24 -0700 (PDT) Received: from [10.8.0.150] ([195.53.121.100]) by smtp.gmail.com with ESMTPSA id a8sm39912002wrt.61.2021.07.25.13.15.23 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Sun, 25 Jul 2021 13:15:24 -0700 (PDT) Subject: Re: [PATCH v1] madvise.2: Document MADV_POPULATE_READ and MADV_POPULATE_WRITE To: Pankaj Gupta , David Hildenbrand Cc: linux-man@vger.kernel.org, Michael Kerrisk , Andrew Morton , Michal Hocko , Oscar Salvador , Jann Horn , Mike Rapoport , Linux API , Linux MM References: <20210712083917.16361-1-david@redhat.com> From: "Alejandro Colomar (man-pages)" Message-ID: <51ec094e-e402-d8a4-d65f-24b8d7929707@gmail.com> Date: Sun, 25 Jul 2021 22:15:22 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.11.0 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Authentication-Results: imf01.hostedemail.com; dkim=pass header.d=gmail.com header.s=20161025 header.b=oRqvXYzJ; spf=pass (imf01.hostedemail.com: domain of alxmanpages@gmail.com designates 209.85.221.41 as permitted sender) smtp.mailfrom=alxmanpages@gmail.com; dmarc=pass (policy=none) header.from=gmail.com X-Rspamd-Server: rspam05 X-Rspamd-Queue-Id: 1D1B7503BF10 X-Stat-Signature: yc5x8ymdukouqntdtwtrn9qe7hpoap1u X-HE-Tag: 1627244125-178314 Content-Transfer-Encoding: quoted-printable 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: Hi David, Pankaj, On 7/12/21 11:58 AM, Pankaj Gupta wrote: >> MADV_POPULATE_READ and MADV_POPULATE_WRITE have been merged into >> upstream Linux via commit 4ca9b3859dac ("mm/madvise: introduce >> MADV_POPULATE_(READ|WRITE) to prefault page tables"), part of v5.14-rc= 1. >> >> Let's document the behavior and error conditions of these new madvise(= ) >> options. Please see a couple of comments below. >> >> Cc: Alejandro Colomar >> Cc: Michael Kerrisk >> Cc: Andrew Morton >> Cc: Michal Hocko >> Cc: Oscar Salvador >> Cc: Jann Horn >> Cc: Mike Rapoport >> Cc: Linux API >> Cc: linux-mm@kvack.org >> Signed-off-by: David Hildenbrand > Acked-by: Pankaj Gupta Thanks for the acked by! Cheers, Alex >> --- >> man2/madvise.2 | 80 ++++++++++++++++++++++++++++++++++++++++++++++++= ++ >> 1 file changed, 80 insertions(+) >> >> diff --git a/man2/madvise.2 b/man2/madvise.2 >> index f1f384c0c..3ec8c53a7 100644 >> --- a/man2/madvise.2 >> +++ b/man2/madvise.2 >> @@ -469,6 +469,59 @@ If a page is file-backed and dirty, it will be wr= itten back to the backing >> storage. >> The advice might be ignored for some pages in the range when it is n= ot >> applicable. >> +.TP >> +.BR MADV_POPULATE_READ " (since Linux 5.14) s/$/"/ >> +Populate (prefault) page tables readable for the whole range without = actually See the following extract from man-pages(7): $ man 7 man-pages | sed -n '/Use semantic newlines/,/^$/p'; Use semantic newlines In the source of a manual page, new sentences should be started on new lines, and long sentences should split into lines at clause breaks (commas, semicolons, colons, and so on). This convention, sometimes known as "semantic new=E2=80=90 lines", makes it easier to see the effect of patches, which often operate at the level of individual sentences or sen=E2=80=90 tence clauses. >> +reading. Depending on the underlying mapping, map the shared zeropage= , >> +preallocate memory or read the underlying file; files with holes migh= t or >> +might not preallocate blocks. >> +Do not generate >> +.B SIGBUS >> +when populating fails, return an error instead. >> +.IP >> +If >> +.B MADV_POPULATE_READ >> +succeeds, all page tables have been populated (prefaulted) readable o= nce. >> +If >> +.B MADV_POPULATE_READ >> +fails, some page tables might have been populated. >> +.IP >> +.B MADV_POPULATE_READ >> +cannot be applied to mappings without read permissions >> +and special mappings marked with the kernel-internal >> +.B VM_PFNMAP >> +and >> +.BR VM_IO . >> +.IP >> +Note that with >> +.BR MADV_POPULATE_READ , >> +the process can be killed at any moment when the system runs out of m= emory. >> +.TP >> +.BR MADV_POPULATE_WRITE " (since Linux 5.14) s/$/"/ >> +Populate (prefault) page tables writable for the whole range without = actually >> +writing. Depending on the underlying mapping, preallocate memory or r= ead the >=20 > Is this read or write? > just reading and trying to understand :) >=20 >> +underlying file; files with holes will preallocate blocks. >> +Do not generate >> +.B SIGBUS >> +when populating fails, return an error instead. >> +.IP >> +If >> +.B MADV_POPULATE_WRITE >> +succeeds, all page tables have been populated (prefaulted) writable o= nce. >> +If >> +.B MADV_POPULATE_WRITE >> +fails, some page tables might have been populated. >> +.IP >> +.B MADV_POPULATE_WRITE >> +cannot be applied to mappings without write permissions >> +and special mappings marked with the kernel-internal >> +.B VM_PFNMAP >> +and >> +.BR VM_IO . >> +.IP >> +Note that >> +.BR MADV_POPULATE_WRITE , >> +the process can be killed at any moment when the system runs out of m= emory. >> .SH RETURN VALUE >> On success, >> .BR madvise () >> @@ -533,6 +586,17 @@ or >> .BR VM_PFNMAP >> ranges. >> .TP >> +.B EINVAL >> +.I advice >> +is >> +.B MADV_POPULATE_READ >> +or >> +.BR MADV_POPULATE_WRITE , >> +but the specified address range includes ranges with insufficient per= missions, >> +.B VM_IO >> +or >> +.BR VM_PFNMAP. >> +.TP >> .B EIO >> (for >> .BR MADV_WILLNEED ) >> @@ -548,6 +612,14 @@ Not enough memory: paging in failed. >> Addresses in the specified range are not currently >> mapped, or are outside the address space of the process. >> .TP >> +.B ENOMEM >> +.I advice >> +is >> +.B MADV_POPULATE_READ >> +or >> +.BR MADV_POPULATE_WRITE , >> +but populating (prefaulting) page tables failed. >> +.TP >> .B EPERM >> .I advice >> is >> @@ -555,6 +627,14 @@ is >> but the caller does not have the >> .B CAP_SYS_ADMIN >> capability. >> +.TP >> +.B EHWPOISON >> +.I advice >> +is >> +.B MADV_POPULATE_READ >> +or >> +.BR MADV_POPULATE_WRITE , >> +and a HW poisoned page is encountered. >> .SH VERSIONS >> Since Linux 3.18, >> .\" commit d3ac21cacc24790eb45d735769f35753f5b56ceb >> -- >> 2.31.1 >> >> --=20 Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/