Preview of MADV_POPULATE documentation, which is still under discussion: https://lkml.kernel.org/r/20210217154844.12392-1-da...@redhat.com
Once/if merged, there will be an official patch to man-page folks. Cc: Andrew Morton <a...@linux-foundation.org> Cc: Arnd Bergmann <a...@arndb.de> Cc: Michal Hocko <mho...@suse.com> Cc: Oscar Salvador <osalva...@suse.de> Cc: Matthew Wilcox (Oracle) <wi...@infradead.org> Cc: Andrea Arcangeli <aarca...@redhat.com> Cc: Minchan Kim <minc...@kernel.org> Cc: Jann Horn <ja...@google.com> Cc: Jason Gunthorpe <j...@ziepe.ca> Cc: Dave Hansen <dave.han...@intel.com> Cc: Hugh Dickins <hu...@google.com> Cc: Rik van Riel <r...@surriel.com> Cc: Michael S. Tsirkin <m...@redhat.com> Cc: Kirill A. Shutemov <kirill.shute...@linux.intel.com> Cc: Vlastimil Babka <vba...@suse.cz> Cc: Richard Henderson <r...@twiddle.net> Cc: Ivan Kokshaysky <i...@jurassic.park.msu.ru> Cc: Matt Turner <matts...@gmail.com> Cc: Thomas Bogendoerfer <tsbog...@alpha.franken.de> Cc: "James E.J. Bottomley" <james.bottom...@hansenpartnership.com> Cc: Helge Deller <del...@gmx.de> Cc: Chris Zankel <ch...@zankel.net> Cc: Max Filippov <jcmvb...@gmail.com> Cc: Mike Kravetz <mike.krav...@oracle.com> Cc: Rolf Eike Beer <eike-ker...@sf-tec.de> Cc: linux-al...@vger.kernel.org Cc: linux-m...@vger.kernel.org Cc: linux-par...@vger.kernel.org Cc: linux-xte...@linux-xtensa.org Cc: linux-a...@vger.kernel.org Cc: Linux API <linux-...@vger.kernel.org> Signed-off-by: David Hildenbrand <da...@redhat.com> --- 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
