[PATCH v2] madvise.2: Document MADV_POPULATE_READ and MADV_POPULATE_WRITE
From: David Hildenbrand <hidden>
Date: 2021-08-16 08:19:37
Also in:
linux-api, linux-mm
Subsystem:
the rest · Maintainer:
Linus Torvalds
MADV_POPULATE_READ and MADV_POPULATE_WRITE have been merged into
upstream Linux via commit 4ca9b3859dac ("mm/madvise: introduce
MADV_POPULATE_(READ|WRITE) to prefault page tables"), part of v5.14-rc1.
Further, commit eb2faa513c24 ("mm/madvise: report SIGBUS as -EFAULT for
MADV_POPULATE_(READ|WRITE)"), part of v5.14-rc6, made sure that SIGBUS is
converted to -EFAULT instead of -EINVAL.
Let's document the behavior and error conditions of these new madvise()
options.
Acked-by: Pankaj Gupta <redacted>
Cc: Alejandro Colomar <redacted>
Cc: Michael Kerrisk <redacted>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: Michal Hocko <mhocko@suse.com>
Cc: Oscar Salvador <osalvador@suse.de>
Cc: Jann Horn <jannh@google.com>
Cc: Mike Rapoport <rppt@kernel.org>
Cc: Linux API <redacted>
Cc: linux-mm@kvack.org
Signed-off-by: David Hildenbrand <redacted>
---
v1 -> v2:
- Use semantic newlines in all cases
- Add two missing "
- Document -EFAULT handling
- Rephrase some parts to make it more generic: VM_PFNMAP and VM_IO are only
examples for special mappings
---
man2/madvise.2 | 107 +++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 107 insertions(+)
diff --git a/man2/madvise.2 b/man2/madvise.2
index f1f384c0c..f6cea9ad2 100644
--- a/man2/madvise.2
+++ b/man2/madvise.2@@ -469,6 +469,72 @@ 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_READ " (since Linux 5.14)" +Populate (prefault) page tables readable for the whole range without actually +reading memory. +Depending on the underlying mapping, +map the shared zeropage, +preallocate memory or read the underlying file; +files with holes might or might not preallocate blocks. +Do not generate +.B SIGBUS +when populating fails, +return an error instead. +.IP +If +.B MADV_POPULATE_READ +succeeds, +all page tables have been populated (prefaulted) readable once. +If +.B MADV_POPULATE_READ +fails, +some page tables might have been populated. +.IP +.B MADV_POPULATE_READ +cannot be applied to mappings without read permissions +and special mappings, +for example, +marked with the kernel-internal +.B VM_PFNMAP +and +.BR VM_IO . +.IP +Note that with +.BR MADV_POPULATE_READ , +the process can be killed at any moment when the system runs out of memory. +.TP +.BR MADV_POPULATE_WRITE " (since Linux 5.14)" +Populate (prefault) page tables writable for the whole range without actually +writing memory. +Depending on the underlying mapping, +preallocate memory or read the underlying file; +files with holes will preallocate blocks. +Do not generate +.B SIGBUS +when populating fails, +return an error instead. +.IP +If +.B MADV_POPULATE_WRITE +succeeds, +all page tables have been populated (prefaulted) writable once. +If +.B MADV_POPULATE_WRITE +fails, some page tables might have been populated. +.IP +.B MADV_POPULATE_WRITE +cannot be applied to mappings without write permissions +and special mappings, +for example, +marked with the kernel-internal +.B VM_PFNMAP +and +.BR VM_IO . +.IP +Note that with +.BR MADV_POPULATE_WRITE , +the process can be killed at any moment when the system runs out of memory. .SH RETURN VALUE On success, .BR madvise ()
@@ -490,6 +556,17 @@ A kernel resource was temporarily unavailable. .B EBADF The map exists, but the area maps something that isn't a file. .TP +.B EFAULT +.I advice +is +.B MADV_POPULATE_READ +or +.BR MADV_POPULATE_WRITE , +and populating (prefaulting) page tables failed because a +.B SIGBUS +would have been generated on actual memory access and the reason is not a +HW poisoned page. +.TP .B EINVAL .I addr is not page-aligned or
@@ -533,6 +610,18 @@ or .BR VM_PFNMAP ranges. .TP +.B EINVAL +.I advice +is +.B MADV_POPULATE_READ +or +.BR MADV_POPULATE_WRITE , +but the specified address range includes ranges with insufficient permissions +or incompatible mappings such as +.B VM_IO +or +.BR VM_PFNMAP. +.TP .B EIO (for .BR MADV_WILLNEED )
@@ -548,6 +637,15 @@ 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 +.B MADV_POPULATE_READ +or +.BR MADV_POPULATE_WRITE , +and populating (prefaulting) page tables failed because there was not enough +memory. +.TP .B EPERM .I advice is
@@ -555,6 +653,15 @@ is but the caller does not have the .B CAP_SYS_ADMIN capability. +.TP +.B EHWPOISON +.I advice +is +.B MADV_POPULATE_READ +or +.BR MADV_POPULATE_WRITE , +and populating (prefaulting) page tables failed because a HW poisoned page +was encountered. .SH VERSIONS Since Linux 3.18, .\" commit d3ac21cacc24790eb45d735769f35753f5b56ceb
--
2.31.1