From patchwork Tue Oct 18 23:50:51 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Zach O'Keefe X-Patchwork-Id: 13011210 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" 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@google.com/ Link: https://lore.kernel.org/linux-mm/20220706235936.2197195-1-zokeefe@google.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 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 +.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= +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’t guarantee anything about other possible mappings 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/aligned +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 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