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 Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by smtp.lore.kernel.org (Postfix) with ESMTP id 0B842C433FE for ; Tue, 1 Nov 2022 20:22:16 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 9F58D6B0071; Tue, 1 Nov 2022 16:22:15 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 9A5AC8E0001; Tue, 1 Nov 2022 16:22:15 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 8460F6B0074; Tue, 1 Nov 2022 16:22:15 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0010.hostedemail.com [216.40.44.10]) by kanga.kvack.org (Postfix) with ESMTP id 6EFE56B0071 for ; Tue, 1 Nov 2022 16:22:15 -0400 (EDT) Received: from smtpin06.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay08.hostedemail.com (Postfix) with ESMTP id 2F98214035D for ; Tue, 1 Nov 2022 20:22:15 +0000 (UTC) X-FDA: 80085995430.06.EBDB86F Received: from mail-lf1-f52.google.com (mail-lf1-f52.google.com [209.85.167.52]) by imf27.hostedemail.com (Postfix) with ESMTP id 3FD044000E for ; Tue, 1 Nov 2022 20:22:12 +0000 (UTC) Received: by mail-lf1-f52.google.com with SMTP id f37so24961479lfv.8 for ; Tue, 01 Nov 2022 13:22:12 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20210112; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=32gM9ij9ReudQCMZz8UHpUlimPf8ouoSZGi1g3QA/ck=; b=kfSJ6o5b7gVwwJXjjh2G15BwWSSl/TuxFMCUhelWwtYwb5rmPcOPbFXcCq5TxhHnb7 0njYZWozFu43j6Pj3mfTCLUNnFYiNg34jJLGob6yZPiMfEXufRUFM7nN+BrbTlvhGATL X/GUGHrdB91kLbKOehE81NqbbWmmpPv1WdHFo2vZm7zEMpAW9VIsB/zrgdq9e6Mb6J/+ 3ajEj0KWo77lytpWP5EywqrxKVM+AoL2PKXuyNYqVcDM8SwhTN5k7HsMg1QUXHLYXbnZ ALsNz8CIWB4J430YRaYrvxBYPXxipF9QEr9alJz6GFG6Q9mc2beAITeWs+65kp4Y5pAk +rNA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=32gM9ij9ReudQCMZz8UHpUlimPf8ouoSZGi1g3QA/ck=; b=KgK5OSFm7aAb5WaA/djcadmzw6uaIhxLBk0rFyjn12ZJZKoj2ZVFg5XBt7Mwv368Kw aws57WRkgv3NwqeT8qprtqjtwFrrOCw0ar5eHhApM4wSxYilZlYPwTDcDFFykHnsBal/ JSElZk3811zbtD1Azc2PceyZOpWFypxL9+c0vXXth1lqUDg9LFQ8CmlBEwOe3lTWb3jI NKG8Ksia6X8gc+4ROJLoFwzPUes68waalIJgX9OyschF+EIS/lNbvBzI0t5uzmsWhJVe 46YsewcU1+1Hkj7UOEIdLjFJJFKbvPrA1VKs8JeEHdO6yiblnnfabRp3nPMMm2sHeL6p 6ecQ== X-Gm-Message-State: ACrzQf1KNvnpyM7trQ/3D4s0tO39veQ+fMU6k/QM1qfXHQ1x7+2h50vY HOuoGzfpiXbwSeCg1rvd5iAOMuLeCjZsr2IMEd9O3g== X-Google-Smtp-Source: AMsMyM766m4i2Ov5WZI57Hw8BxcLJ63yKovdNuYMc0YW4F7Bz0c+CRyiuljCAedMq9EzFtVCXmg+yO7KKJ3nfWt978U= X-Received: by 2002:a19:6708:0:b0:4ae:d9b4:bd31 with SMTP id b8-20020a196708000000b004aed9b4bd31mr92670lfc.645.1667334131267; Tue, 01 Nov 2022 13:22:11 -0700 (PDT) MIME-Version: 1.0 References: <20221101150323.89743-1-zokeefe@google.com> In-Reply-To: From: "Zach O'Keefe" Date: Tue, 1 Nov 2022 13:21:34 -0700 Message-ID: Subject: Re: [PATCH man-pages v5] madvise.2: add documentation for MADV_COLLAPSE To: Alejandro Colomar Cc: Yang Shi , linux-mm@kvack.org, linux-man@vger.kernel.org, Michael Kerrisk Content-Type: text/plain; charset="UTF-8" ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1667334133; h=from:from:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=32gM9ij9ReudQCMZz8UHpUlimPf8ouoSZGi1g3QA/ck=; b=yJkK5pQiPpyH41xVgqwii1H3MmLWB3MOMt0JD49P0tSoUSzADN43sBZ30ho1bLNjSTb4lk zUSiRneyNPt4zQYtpz7dqgO4mAI99TvHiq1plC4Y1s1HKcBlW8B7dZEbD94TBm843sgH5W klecLI1RhQ2FB0ntFtjHPrTiZOG9JkM= ARC-Authentication-Results: i=1; imf27.hostedemail.com; dkim=pass header.d=google.com header.s=20210112 header.b=kfSJ6o5b; spf=pass (imf27.hostedemail.com: domain of zokeefe@google.com designates 209.85.167.52 as permitted sender) smtp.mailfrom=zokeefe@google.com; dmarc=pass (policy=reject) header.from=google.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1667334133; a=rsa-sha256; cv=none; b=I3+jLSVAzSh7coO7V2CNO/e585+++KS/wMdbcYmpLbnqoNNFKphd6S+UsimGOg9AlQWQAR pkAjeHyoDpzoF+oqP9kXKtSqR83G4TulFKBrfnLBFZAhNZXGzbR914ddtC0pYVnmdL0LBY 5bSEfQN13/NanifsjM3hMB2ks4W7SpU= Authentication-Results: imf27.hostedemail.com; dkim=pass header.d=google.com header.s=20210112 header.b=kfSJ6o5b; spf=pass (imf27.hostedemail.com: domain of zokeefe@google.com designates 209.85.167.52 as permitted sender) smtp.mailfrom=zokeefe@google.com; dmarc=pass (policy=reject) header.from=google.com X-Stat-Signature: a7ib81n3dhfcb8uwxtnguadhwjeugjsp X-Rspam-User: X-Rspamd-Server: rspam11 X-Rspamd-Queue-Id: 3FD044000E X-HE-Tag: 1667334132-359161 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: Hey Alex! On Tue, Nov 1, 2022 at 8:47 AM Alejandro Colomar wrote: > > Hi Zach! > > On 11/1/22 16:03, Zach OKeefe wrote: > > From: Zach O'Keefe > > > > Linux 6.1 introduced MADV_COLLAPSE in upstream commit 7d8faaf15545 > > ("mm/madvise: introduce MADV_COLLAPSE sync hugepage collapse") and > > upstream commit 34488399fa08 ("mm/madvise: add file and shmem support to > > MADV_COLLAPSE"). Update the man-pages for madvise(2) and > > process_madvise(2). > > > > Link: https://lore.kernel.org/linux-mm/20220922224046.1143204-1-zokeefe@google.com/ > > Link: https://lore.kernel.org/linux-mm/20220706235936.2197195-1-zokeefe@google.com/ > > Signed-off-by: Zach O'Keefe > > Patch applied. > See a minor edit below for curiosity. > It was very nice to get this patch set improved and applied! > Awesome! Very excited to see it in :) > Cheers, > > Alex > > > --- > > > > v4[1] -> v5 > > - Rebased to latest master > > - (Alejandro Colomar) Applied diff to remove spurious file and fix > > semantic newlines. > > - (Alejandro Colomar) Reworded documentation describing behavior of > > setting errno when multiple hugepage-aligned/sized regions fail to > > collapse. > > > > v3[2] -> v4 > > - Rebased to latest master > > - (Alejandro Colomar) Fixed weird, non-ascii chars: e2 80 99 -> "'" > > - (Alejandro Colomar) Replaced .BR with .B directive when the entire > > line was bold (no non-bold part) > > > > [1] https://lore.kernel.org/linux-man/20221031225500.3994542-1-zokeefe@google.com/ > > [2] https://lore.kernel.org/linux-man/bb3b5c3c-3966-ea1a-6d84-4f7f3afa37ca@gmail.com/T/#u > > > > man2/madvise.2 | 91 +++++++++++++++++++++++++++++++++++++++++- > > man2/process_madvise.2 | 10 +++++ > > 2 files changed, 99 insertions(+), 2 deletions(-) > > > > diff --git a/man2/madvise.2 b/man2/madvise.2 > > index edf805740..038e6023d 100644 > > --- a/man2/madvise.2 > > +++ b/man2/madvise.2 > > @@ -386,9 +386,10 @@ set (see > > .BR prctl (2)). > > .IP > > The > > -.B MADV_HUGEPAGE > > +.BR MADV_HUGEPAGE , > > +.BR MADV_NOHUGEPAGE , > > and > > -.B MADV_NOHUGEPAGE > > +.B MADV_COLLAPSE > > operations are available only if the kernel was configured with > > .B CONFIG_TRANSPARENT_HUGEPAGE > > and file/shmem memory is only supported if the kernel was configured with > > @@ -401,6 +402,82 @@ and > > .I length > > will not be backed by transparent hugepages. > > .TP > > +.BR MADV_COLLAPSE " (since Linux 6.1)" > > +.\" commit 7d8faaf155454f8798ec56404faca29a82689c77 > > +.\" commit 34488399fa08faaf664743fa54b271eb6f9e1321 > > +Perform a best-effort synchronous collapse of > > +the native pages mapped by the memory range > > +into Transparent Huge Pages (THPs). > > +.B MADV_COLLAPSE > > +operates on the current state of memory of the calling process and > > +makes no persistent changes or guarantees on how pages will be mapped, > > +constructed, > > +or faulted in the future. > > +.IP > > +.B MADV_COLLAPSE > > +supports private anonymous pages (see > > +.BR mmap (2)), > > +shmem pages, > > +and file-backed pages. > > +See > > +.B MADV_HUGEPAGE > > +for general information on memory requirements for THP. > > +If the range provided spans multiple VMAs, > > +the semantics of the collapse over each VMA is independent from the others. > > +If collapse of a given huge page-aligned/sized region fails, > > +the operation may continue to attempt collapsing > > +the remainder of the specified memory. > > +.B MADV_COLLAPSE > > +will automatically clamp the provided range to be hugepage-aligned. > > +.IP > > +All non-resident pages covered by the range > > +will first be swapped/faulted-in, > > +before being copied onto a freshly allocated hugepage. > > +If the native pages compose the same PTE-mapped hugepage, > > +and are suitably aligned, > > +allocation of a new hugepage may be elided and > > +collapse may happen in-place. > > +Unmapped pages will have their data directly initialized to 0 > > +in the new hugepage. > > +However, > > +for every eligible hugepage-aligned/sized region to be collapsed, > > +at least one page must currently be backed by physical memory. > > +.IP > > +.B MADV_COLLAPSE > > +is independent of any sysfs > > +(see > > +.BR sysfs (5)) > > +setting under > > +.IR /sys/kernel/mm/transparent_hugepage , > > +both in terms of determining THP eligibility, > > +and allocation semantics. > > +See Linux kernel source file > > +.I Documentation/admin\-guide/mm/transhuge.rst > > +for more information. > > +.B MADV_COLLAPSE > > +also ignores > > +.B huge= > > +tmpfs mount when operating on tmpfs files. > > +Allocation for the new hugepage may enter direct reclaim and/or compaction, > > +regardless of VMA flags > > +(though > > +.B VM_NOHUGEPAGE > > +is still respected). > > +.IP > > +When the system has multiple NUMA nodes, > > +the hugepage will be allocated from > > +the node providing the most native pages. > > +.IP > > +If all hugepage-sized/aligned regions covered by the provided range were > > +either successfully collapsed, > > +or were already PMD-mapped THPs, > > +this operation will be deemed successful. > > +Note that this doesn't guarantee anything about > > +other possible mappings of the memory. > > +In the event multiple hugepage-aligned/sized areas fail to collapse, > > +only the most recently-failed code will be set in > > I slightly changed the use of hyphens above with the following diff: > > diff --git a/man2/madvise.2 b/man2/madvise.2 > index 038e6023d..331465cfc 100644 > --- a/man2/madvise.2 > +++ b/man2/madvise.2 > @@ -475,7 +475,7 @@ .SS Linux-specific advice values > Note that this doesn't guarantee anything about > other possible mappings of the memory. > In the event multiple hugepage-aligned/sized areas fail to collapse, > -only the most recently-failed code will be set in > +only the most-recently\[en]failed code will be set in > .IR errno . > .TP > .BR MADV_DONTDUMP " (since Linux 3.4)" > > > Rationale: > > Appreciate the change, and thanks for the link -- very subtle. The differences between various dashes (which I was only made aware of by yourself) is still a little unclear to me. Again, thank you so much for your patience and help throughout this process -- I really appreciate it. Best, Zach > > > +.IR errno . > > +.TP > > .BR MADV_DONTDUMP " (since Linux 3.4)" > > .\" commit 909af768e88867016f427264ae39d27a57b6a8ed > > .\" commit accb61fe7bb0f5c2a4102239e4981650f9048519 > > @@ -620,6 +697,11 @@ A kernel resource was temporarily unavailable. > > .B EBADF > > The map exists, but the area maps something that isn't a file. > > .TP > > +.B EBUSY > > +(for > > +.BR MADV_COLLAPSE ) > > +Could not charge hugepage to cgroup: cgroup limit exceeded. > > +.TP > > .B EFAULT > > .I advice > > is > > @@ -717,6 +799,11 @@ maximum resident set size. > > Not enough memory: paging in failed. > > .TP > > .B ENOMEM > > +(for > > +.BR MADV_COLLAPSE ) > > +Not enough memory: could not allocate hugepage. > > +.TP > > +.B ENOMEM > > Addresses in the specified range are not currently > > mapped, or are outside the address space of the process. > > .TP > > diff --git a/man2/process_madvise.2 b/man2/process_madvise.2 > > index ac98850a9..92878286b 100644 > > --- a/man2/process_madvise.2 > > +++ b/man2/process_madvise.2 > > @@ -73,6 +73,10 @@ argument is one of the following values: > > See > > .BR madvise (2). > > .TP > > +.B MADV_COLLAPSE > > +See > > +.BR madvise (2). > > +.TP > > .B MADV_PAGEOUT > > See > > .BR madvise (2). > > @@ -173,6 +177,12 @@ The caller does not have permission to access the address space of the process > > .TP > > .B ESRCH > > The target process does not exist (i.e., it has terminated and been waited on). > > +.PP > > +See > > +.BR madvise (2) > > +for > > +.IR advice -specific > > +errors. > > .SH VERSIONS > > This system call first appeared in Linux 5.10. > > .\" commit ecb8ac8b1f146915aa6b96449b66dd48984caacc > > -- >