Preview of MADV_POPULATE documentation, which is still under discussion: https://lkml.kernel.org/r/20210217154844.12392-1-david@xxxxxxxxxx Once/if merged, there will be an official patch to man-page folks. Cc: Andrew Morton <akpm@xxxxxxxxxxxxxxxxxxxx> Cc: Arnd Bergmann <arnd@xxxxxxxx> Cc: Michal Hocko <mhocko@xxxxxxxx> Cc: Oscar Salvador <osalvador@xxxxxxx> Cc: Matthew Wilcox (Oracle) <willy@xxxxxxxxxxxxx> Cc: Andrea Arcangeli <aarcange@xxxxxxxxxx> Cc: Minchan Kim <minchan@xxxxxxxxxx> Cc: Jann Horn <jannh@xxxxxxxxxx> Cc: Jason Gunthorpe <jgg@xxxxxxxx> Cc: Dave Hansen <dave.hansen@xxxxxxxxx> Cc: Hugh Dickins <hughd@xxxxxxxxxx> Cc: Rik van Riel <riel@xxxxxxxxxxx> Cc: Michael S. Tsirkin <mst@xxxxxxxxxx> Cc: Kirill A. Shutemov <kirill.shutemov@xxxxxxxxxxxxxxx> Cc: Vlastimil Babka <vbabka@xxxxxxx> Cc: Richard Henderson <rth@xxxxxxxxxxx> Cc: Ivan Kokshaysky <ink@xxxxxxxxxxxxxxxxxxxx> Cc: Matt Turner <mattst88@xxxxxxxxx> Cc: Thomas Bogendoerfer <tsbogend@xxxxxxxxxxxxxxxx> Cc: "James E.J. Bottomley" <James.Bottomley@xxxxxxxxxxxxxxxxxxxxx> Cc: Helge Deller <deller@xxxxxx> Cc: Chris Zankel <chris@xxxxxxxxxx> Cc: Max Filippov <jcmvbkbc@xxxxxxxxx> Cc: Mike Kravetz <mike.kravetz@xxxxxxxxxx> Cc: Rolf Eike Beer <eike-kernel@xxxxxxxxx> Cc: linux-alpha@xxxxxxxxxxxxxxx Cc: linux-mips@xxxxxxxxxxxxxxx Cc: linux-parisc@xxxxxxxxxxxxxxx Cc: linux-xtensa@xxxxxxxxxxxxxxxx Cc: linux-arch@xxxxxxxxxxxxxxx Cc: Linux API <linux-api@xxxxxxxxxxxxxxx> Signed-off-by: David Hildenbrand <david@xxxxxxxxxx> --- man2/madvise.2 | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/man2/madvise.2 b/man2/madvise.2 index 2af407212..ff08768a3 100644 --- a/man2/madvise.2 +++ b/man2/madvise.2 @@ -469,6 +469,48 @@ If a page is file-backed and dirty, it will be written back to the backing storage. The advice might be ignored for some pages in the range when it is not applicable. +.TP +.BR MADV_POPULATE " (since Linux 5.13) +Populate (prefault) page tables for the whole range. +Depending on the underlying mapping, preallocate memory or read the +underlying file. +Do not generate +.B SIGBUS +when populating fails, return an error instead. +The populate semantics match +.BR MAP_POPULATE +(see +.BR mmap (2)) +with the exception that +.B MADV_POPULATE +fails if there is a proplem populating page tables. +.B MADV_POPULATE +simulates user space access to all pages in the range without actually +reading/writing the pages. +For private, writable mappings, simulate a write access; for all other +mappings, simulate a read access. +.IP +If +.B MADV_POPULATE +succeeds, all page tables have been populated (prefaulted) once. +If +.B MADV_POPULATE +fails, some page tables might have been populated. +.IP +.B MADV_POPULATE +cannot be applied to +.B PROT_NONE +and special mappings marked with the kernel-internal +.B VM_PFNMAP +and +.BR VM_IO . +.IP +Note that +.B MADV_POPULATE +will ignore any poisoned pages in the range. +Similar to +.BR MAP_POPULATE , +it cannot protect from the OOM (Out Of Memory) handler killing the process. .SH RETURN VALUE On success, .BR madvise () @@ -533,6 +575,17 @@ or .BR VM_PFNMAP ranges. .TP +.B EINVAL +.I advice +is +.BR MADV_POPULATE , +but the specified address range includes +.BR PROT_NONE , +.B VM_IO +or +.B VM_PFNMAP +ranges. +.TP .B EIO (for .BR MADV_WILLNEED ) @@ -548,6 +601,12 @@ 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 +.BR MADV_POPULATE , +but populating (prefaulting) page tables failed. +.TP .B EPERM .I advice is -- 2.29.2
