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 F39FEC43219 for ; Mon, 17 Oct 2022 17:55:34 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 902026B007D; Mon, 17 Oct 2022 13:55:34 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 88C146B007E; Mon, 17 Oct 2022 13:55:34 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 669986B0080; Mon, 17 Oct 2022 13:55:34 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0013.hostedemail.com [216.40.44.13]) by kanga.kvack.org (Postfix) with ESMTP id 507696B007D for ; Mon, 17 Oct 2022 13:55:34 -0400 (EDT) Received: from smtpin27.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay03.hostedemail.com (Postfix) with ESMTP id E1FCCA0941 for ; Mon, 17 Oct 2022 17:55:33 +0000 (UTC) X-FDA: 80031193746.27.2C0385B Received: from mail-pj1-f73.google.com (mail-pj1-f73.google.com [209.85.216.73]) by imf07.hostedemail.com (Postfix) with ESMTP id 77CB34002D for ; Mon, 17 Oct 2022 17:55:33 +0000 (UTC) Received: by mail-pj1-f73.google.com with SMTP id mp3-20020a17090b190300b0020af8232049so4773688pjb.9 for ; Mon, 17 Oct 2022 10:55:33 -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=9okyg4TxaGr0Wo6DVcaSxPtBJAbQVCSpwbsXFn49vpU=; b=B/VP0B1nCEzdRoZcax9PTsCLDH3r24qt1iRdmWvlrjLxQiOXj1wr/rxqCDqOfAg0LP RWgqWFyjeWxAU4jyMvEfxNxWKpD2/OwsMoCi4bYF6NJ1wV8xOkzUaxpZRXJniqwzEYy7 q34Q3d8W6kCaGDW0tMvh2CG6UISW2Rv9X8zeq0raUo09xB40yc2BWT7jqngEG372WL/X FuI+uOEYAClitf4iL9KGoEpqbU17OQq2A1bNvABB6zE+/j54qNtaUZZgp0IvUshSdvZA IEDpXOJfebXqIrY1aB+WYo8mlr3yvG88m8JMNPs+e6H6kkQODDq7UdLDvIM51qQLgRvd V53g== 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=9okyg4TxaGr0Wo6DVcaSxPtBJAbQVCSpwbsXFn49vpU=; b=faWZfkxjRn6EMjuIxXjvDeQeB2yOMGfg3BRcSST0WqeCpKGXAPFtr5LQPxiU3judzJ cOKg5/9lObaVLagw0wTrdcfHiOA5hQM7isXsLVVvRj3LBiK2iNEJfae0RAM2iNG/qkem jqiBe4AAo90pX89IN0hllEe/ZB/FAUpbFQUKlGTGNeFEKQbOMHblGYo7rVK/pGdSOUxx lq/jrvnpHL06UsOD5Hwbico9FXIvrirDdOzRXHXDA1+VT86Z9JH9RpE52xpreRT4CdGc qQ+4DZL/ICj8fcPU1R40H8hhpUReYm8ChOvzFvbn4aWItRfDtIzIsqilIeVtoIjV92Kd bTBg== X-Gm-Message-State: ACrzQf2T7OBjEpIlzPpKcrn3GG16jO4Nvo6gPU7uKBaCb+5CncruaPD9 8XDVQsDa17yEEgnK6HDrKMEkf49I/Q1V X-Google-Smtp-Source: AMsMyM5NJSC69gJSADJnOqqIrSWtoQccfj+i9MuTgOiBs2sxbicoi9Z8TRpTa2gEOrozU3pDLyI30ziWkuQg X-Received: from zokeefe3.c.googlers.com ([fda3:e722:ac3:cc00:7f:e700:c0a8:1b6]) (user=zokeefe job=sendgmr) by 2002:a17:90b:1c06:b0:20a:f070:9f3c with SMTP id oc6-20020a17090b1c0600b0020af0709f3cmr15227035pjb.151.1666029332618; Mon, 17 Oct 2022 10:55:32 -0700 (PDT) Date: Mon, 17 Oct 2022 10:55:23 -0700 In-Reply-To: <20221017175523.2048887-1-zokeefe@google.com> Mime-Version: 1.0 References: <20221017175523.2048887-1-zokeefe@google.com> X-Mailer: git-send-email 2.38.0.413.g74048e4d9e-goog Message-ID: <20221017175523.2048887-5-zokeefe@google.com> Subject: [PATCH man-pages 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 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1666029333; a=rsa-sha256; cv=none; b=rKpwyIK+8o4SPWwkzkguNZIIsEl3qHp9Z9KpE5FHygAx64YGsxbBlW9DNjyQxLNfGMV1kB EqRr64sCjtCMO9d1PB2DsLTQ+h0tp8EEtJohvQ4eXgfCILpWq4HkvAJGOIKH0ESeRXDGq7 LJVBLPfX0+Q9l9YOIEGf0LResYMFZyM= ARC-Authentication-Results: i=1; imf07.hostedemail.com; dkim=pass header.d=google.com header.s=20210112 header.b="B/VP0B1n"; spf=pass (imf07.hostedemail.com: domain of 3FJdNYwcKCJkSHD77879HH9E7.5HFEBGNQ-FFDO35D.HK9@flex--zokeefe.bounces.google.com designates 209.85.216.73 as permitted sender) smtp.mailfrom=3FJdNYwcKCJkSHD77879HH9E7.5HFEBGNQ-FFDO35D.HK9@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=1666029333; 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=9okyg4TxaGr0Wo6DVcaSxPtBJAbQVCSpwbsXFn49vpU=; b=PEE/TbHAjAlA3cCpbMWx1LRgkKqkkuihMjvEpymCZ+om4zgHChlmdpqXDpVtYqKAHty8wg QAbhBIeI0UoZUF8egfKecYGJMh80/C2HeAklzmFU+vk5GxtxX14ORylDjtgbPu0oekPWta TIAxTpLT9gH/f88QRluPyulegskhvms= X-Rspam-User: Authentication-Results: imf07.hostedemail.com; dkim=pass header.d=google.com header.s=20210112 header.b="B/VP0B1n"; spf=pass (imf07.hostedemail.com: domain of 3FJdNYwcKCJkSHD77879HH9E7.5HFEBGNQ-FFDO35D.HK9@flex--zokeefe.bounces.google.com designates 209.85.216.73 as permitted sender) smtp.mailfrom=3FJdNYwcKCJkSHD77879HH9E7.5HFEBGNQ-FFDO35D.HK9@flex--zokeefe.bounces.google.com; dmarc=pass (policy=reject) header.from=google.com X-Stat-Signature: xjbt1ibtjgm3818ougszkw3f1cjx5uym X-Rspamd-Queue-Id: 77CB34002D X-Rspamd-Server: rspam10 X-HE-Tag: 1666029333-283322 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 | 91 +++++++++++++++++++++++++++++++++++++++++- man2/process_madvise.2 | 10 +++++ 2 files changed, 99 insertions(+), 2 deletions(-) diff --git a/man2/madvise.2 b/man2/madvise.2 index adfe24c24..7da44fac4 100644 --- a/man2/madvise.2 +++ b/man2/madvise.2 @@ -384,9 +384,10 @@ set (see .BR prctl (2) ). .IP The -.B MADV_HUGEPAGE -and +.BR MADV_HUGEPAGE , .B MADV_NOHUGEPAGE +and +.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 @@ -399,6 +400,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 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-backed pages +(including tmpfs (see +.BR tmpfs (5)), +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 @@ -618,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 @@ -715,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