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 331E9C433FE for ; Tue, 18 Oct 2022 23:51:12 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id B328D6B0075; Tue, 18 Oct 2022 19:51:11 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id AE2426B0078; Tue, 18 Oct 2022 19:51:11 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 90CD56B007B; Tue, 18 Oct 2022 19:51:11 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0011.hostedemail.com [216.40.44.11]) by kanga.kvack.org (Postfix) with ESMTP id 82CA66B0075 for ; Tue, 18 Oct 2022 19:51:11 -0400 (EDT) Received: from smtpin04.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay10.hostedemail.com (Postfix) with ESMTP id 564C6C04AF for ; Tue, 18 Oct 2022 23:51:11 +0000 (UTC) X-FDA: 80035718742.04.29CDFFE Received: from mail-pj1-f74.google.com (mail-pj1-f74.google.com [209.85.216.74]) by imf24.hostedemail.com (Postfix) with ESMTP id EFA9D180039 for ; Tue, 18 Oct 2022 23:51:10 +0000 (UTC) Received: by mail-pj1-f74.google.com with SMTP id ls4-20020a17090b350400b0020d63c0efb9so12654291pjb.0 for ; Tue, 18 Oct 2022 16:51:10 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20210112; h=content-transfer-encoding:cc:to:from:subject:message-id:references :mime-version:in-reply-to:date:from:to:cc:subject:date:message-id :reply-to; bh=Wa2g3vVRf9EsfQ4YJX+6nAuXP5rzS4A1qWB6UcnBf+U=; b=cahjfRHFbQveHoBBGFhmb9H7O6gdo1yNeIEY7sByptjQK8btNk2zV99SWYIi8+N7WC NUEG5L3MbI2MrIydRkT/evDo+uxczlj0rKW6kfRIhSM05xVfrdDeqQsllbSACG1HXqQZ /RKXTJrT0BntcQ8HHL5VucJYJTWsiEH2eoSo9RX66v4K3IzbZMmtFQvr2dP+qufvV4PD gEocUnJJcrN91bhRDYHGlQGH/7g2NPptyVBjzTSRBLIA1RVBByV1fhGywGOeDDEY/O43 dT5iQHWbqy4TkkSQQ2pevngYdp1enoJ0RncXwCPEZUabBM7vy/qYOFASZjTw9/z8kRiE DhBw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:cc:to:from:subject:message-id:references :mime-version:in-reply-to:date:x-gm-message-state:from:to:cc:subject :date:message-id:reply-to; bh=Wa2g3vVRf9EsfQ4YJX+6nAuXP5rzS4A1qWB6UcnBf+U=; b=E6xg3JcmeY5kIilVba1YV3NrnmjvM2j1k4H0VX0m1lHkMAkcPIfKWCt22xTFb3qA26 bBQ8ecr2m4GL3mvW8KONWEd0/afzngMA/FWxWtZ/RN80rZBo9rHU04hQ1drto4ZcBi4D 4TMidtpqC0LpvrlWgLOIhAH9XS5KL7awIUMybrgjmHGj2YU98yUcVtcULDhEsWROIJrv bubqOdNnsORapqGRfmwLdtstAx6PkWP4JwWUsg6q9cHjAMP2cUWQqP3O/TaiQMW76Bj0 qWaYNSBJeWeNcJ6zIJjvyHWJHB+Y7WBG0iA3alcToXmjDP6kkGph58t9uJ7ykn1txytY McuA== X-Gm-Message-State: ACrzQf3YrNR6XaJm0q/eWF/phfR4nRNeLNzc6Yq/eKbWAfabSGSQVxqp J4oFksl+XIM/MsHalcxe8sexq5FW/Fgz X-Google-Smtp-Source: AMsMyM5xVpx73tkBDwDIZ3grYpYv2TxLSc3VjInsqis+R6Uih/QybkKKk5f4nUNXrHpKSyTf1ldljkjjhmTj X-Received: from zokeefe3.c.googlers.com ([fda3:e722:ac3:cc00:7f:e700:c0a8:1b6]) (user=zokeefe job=sendgmr) by 2002:a17:90a:f284:b0:20d:8287:9342 with SMTP id fs4-20020a17090af28400b0020d82879342mr6438846pjb.25.1666137070059; Tue, 18 Oct 2022 16:51:10 -0700 (PDT) Date: Tue, 18 Oct 2022 16:50:51 -0700 In-Reply-To: <20221018235051.152548-1-zokeefe@google.com> Mime-Version: 1.0 References: <20221018235051.152548-1-zokeefe@google.com> X-Mailer: git-send-email 2.38.0.413.g74048e4d9e-goog Message-ID: <20221018235051.152548-5-zokeefe@google.com> Subject: [PATCH man-pages v2 4/4] madvise.2: add documentation for MADV_COLLAPSE From: Zach OKeefe To: Alejandro Colomar , Michael Kerrisk Cc: Yang Shi , linux-mm@kvack.org, linux-man@vger.kernel.org, "Zach O'Keefe" Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1666137071; a=rsa-sha256; cv=none; b=bbRmTPP6C+5gjta36yoZtGZP8tPe6zZQW3sH2MurLVd5qeA2CihcxqXROJQwYVaTO6W2tF muytHQ4tpAysulfPSDlHG7hlKqjQdVapWtLU63gnNV4BbbGXoxeqF5m0brCzTVy0oY9E4y 7yMH94+TOwiyuRnQid1mi9x5rHCofY4= ARC-Authentication-Results: i=1; imf24.hostedemail.com; dkim=pass header.d=google.com header.s=20210112 header.b=cahjfRHF; spf=pass (imf24.hostedemail.com: domain of 37jtPYwcKCMM8xtnnonpxxpun.lxvurw36-vvt4jlt.x0p@flex--zokeefe.bounces.google.com designates 209.85.216.74 as permitted sender) smtp.mailfrom=37jtPYwcKCMM8xtnnonpxxpun.lxvurw36-vvt4jlt.x0p@flex--zokeefe.bounces.google.com; dmarc=pass (policy=reject) header.from=google.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1666137071; 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:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=Wa2g3vVRf9EsfQ4YJX+6nAuXP5rzS4A1qWB6UcnBf+U=; b=uW382lNeSV5y0ozndfL0d0mdv9ERX13jbFyEI7agMvWxPMSFwHAs3y1sWaxEN3HQ2V/t7L OlQ5LeP0gzshUhpAfw6hoG6XEr/u5hFvklpEoIsLPwnQAO21WjHXpiz0plSo6jLVVdfi7H 8KnompyaJMp1fTzH4eT473jW1OZghHE= X-Stat-Signature: bufxrxbwktdu1s3dbmsfnh883twin9qh X-Rspamd-Queue-Id: EFA9D180039 X-Rspam-User: X-Rspamd-Server: rspam03 Authentication-Results: imf24.hostedemail.com; dkim=pass header.d=google.com header.s=20210112 header.b=cahjfRHF; spf=pass (imf24.hostedemail.com: domain of 37jtPYwcKCMM8xtnnonpxxpun.lxvurw36-vvt4jlt.x0p@flex--zokeefe.bounces.google.com designates 209.85.216.74 as permitted sender) smtp.mailfrom=37jtPYwcKCMM8xtnnonpxxpun.lxvurw36-vvt4jlt.x0p@flex--zokeefe.bounces.google.com; dmarc=pass (policy=reject) header.from=google.com X-HE-Tag: 1666137070-803256 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: 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@goo= gle.com/ Link: https://lore.kernel.org/linux-mm/20220706235936.2197195-1-zokeefe@goo= gle.com/ Signed-off-by: Zach O'Keefe --- man2/madvise.2 | 90 +++++++++++++++++++++++++++++++++++++++++- man2/process_madvise.2 | 10 +++++ 2 files changed, 98 insertions(+), 2 deletions(-) diff --git a/man2/madvise.2 b/man2/madvise.2 index df3413cc8..b03fc731d 100644 --- a/man2/madvise.2 +++ b/man2/madvise.2 @@ -385,9 +385,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 @@ -400,6 +401,81 @@ 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 t= he +memory range into Transparent Huge Pages (THPs). +.B MADV_COLLAPSE +operates on the current state of memory of the calling process and makes n= o +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 +.BR 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. +.BR MADV_COLLAPSE +also ignores +.B huge=3D +tmpfs mount when operating on tmpfs files. +Allocation for the new hugepage may enter direct reclaim and/or compaction= , +regardless of VMA flags +(though +.BR 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=E2=80=99t guarantee anything about other possible map= pings of +the memory. +Also note that many failures might have occurred since the operation may +continue to collapse in the event collapse of a single hugepage-sized/alig= ned +region fails. +.TP .BR MADV_DONTDUMP " (since Linux 3.4)" .\" commit 909af768e88867016f427264ae39d27a57b6a8ed .\" commit accb61fe7bb0f5c2a4102239e4981650f9048519 @@ -619,6 +695,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 @@ -716,6 +797,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 7bee1a098..900210106 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). @@ -170,6 +174,12 @@ The caller does not have permission to access the addr= ess 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 --=20 2.38.0.413.g74048e4d9e-goog