[RFC 14/19] mm/mlock: add API specification for munlockall

Sasha Levin
2025-06-14T13:49:13Z

Add kernel API specification for the munlockall() system call.

Signed-off-by: Sasha Levin <sashal@kernel.org>
---
mm/mlock.c | 120 +++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 120 insertions(+)

diff --git a/mm/mlock.c b/mm/mlock.c
index ef691adc78ad7..80f51e932aa95 100644
--- a/mm/mlock.c
+++ b/mm/mlock.c
@@ -1299,6 +1299,126 @@ SYSCALL_DEFINE1(mlockall, int, flags)
return ret;
}

+
+DEFINE_KERNEL_API_SPEC(sys_munlockall)
+ KAPI_DESCRIPTION("Unlock all process pages")
+ KAPI_LONG_DESC("Unlocks all pages mapped into the process address space and "
+ "clears the MCL_FUTURE flag if set.")
+ KAPI_CONTEXT(KAPI_CTX_PROCESS | KAPI_CTX_SLEEPABLE)
+
+ /* No parameters - this is a SYSCALL_DEFINE0 */
+ .param_count = 0,
+
+ /* Return specification */
+ KAPI_RETURN("long", "0 on success, negative error code on failure")
+ .type = KAPI_TYPE_INT,
+ .check_type = KAPI_RETURN_ERROR_CHECK,
+ .success_value = 0,
+ KAPI_RETURN_END
+
+ /* Error codes */
+ KAPI_ERROR(0, -EINTR, "EINTR", "Interrupted by signal", "The operation was interrupted by a signal before completion.")
+ KAPI_ERROR(1, -ENOMEM, "ENOMEM", "Memory operation failed", "Failed to modify memory mappings (should not normally occur).")
+
+ /* Signal specifications */
+ KAPI_SIGNAL(0, 0, "FATAL_SIGNALS", KAPI_SIGNAL_RECEIVE, KAPI_SIGNAL_ACTION_RETURN)
+ KAPI_SIGNAL_CONDITION("Fatal signal pending during mmap_write_lock_killable")
+ KAPI_SIGNAL_DESC("Fatal signals (SIGKILL, SIGTERM, etc.) can interrupt the operation when acquiring mmap_write_lock_killable(), causing -EINTR return")
+ KAPI_SIGNAL_RESTARTABLE
+ KAPI_SIGNAL_END
+
+ /* Side effects */
+ KAPI_SIDE_EFFECT(0, KAPI_EFFECT_MODIFY_STATE,
+ "all process memory",
+ "Unlocks all pages, making entire address space swappable")
+ KAPI_EFFECT_REVERSIBLE
+ KAPI_EFFECT_CONDITION("Process had locked pages")
+ KAPI_SIDE_EFFECT_END
+
+ KAPI_SIDE_EFFECT(1, KAPI_EFFECT_MODIFY_STATE,
+ "mm->def_flags",
+ "Clears VM_LOCKED from default flags for future mappings")
+ KAPI_EFFECT_REVERSIBLE
+ KAPI_EFFECT_CONDITION("MCL_FUTURE was previously set")
+ KAPI_SIDE_EFFECT_END
+
+ KAPI_SIDE_EFFECT(2, KAPI_EFFECT_MODIFY_STATE,
+ "mm->locked_vm",
+ "Resets process locked memory counter to zero")
+ KAPI_EFFECT_REVERSIBLE
+ KAPI_SIDE_EFFECT_END
+
+ KAPI_SIDE_EFFECT(3, KAPI_EFFECT_MODIFY_STATE,
+ "all VMA flags",
+ "Clears VM_LOCKED and VM_LOCKONFAULT from all VMAs")
+ KAPI_EFFECT_REVERSIBLE
+ KAPI_SIDE_EFFECT_END
+
+ KAPI_SIDE_EFFECT(4, KAPI_EFFECT_MODIFY_STATE,
+ "page flags",
+ "Clears PG_mlocked flag from all locked pages")
+ KAPI_EFFECT_CONDITION("Pages had PG_mlocked set")
+ KAPI_SIDE_EFFECT_END
+
+ KAPI_SIDE_EFFECT(5, KAPI_EFFECT_MODIFY_STATE,
+ "LRU lists",
+ "Moves all pages from unevictable to normal LRU lists")
+ KAPI_EFFECT_CONDITION("Pages were on unevictable list")
+ KAPI_SIDE_EFFECT_END
+
+ /* State transitions */
+ KAPI_STATE_TRANS(0, "all memory pages",
+ "locked in RAM", "swappable",
+ "All pages in process become eligible for swap out")
+ KAPI_STATE_TRANS_END
+
+ KAPI_STATE_TRANS(1, "future mappings",
+ "auto-locked", "normal",
+ "New mappings will no longer be automatically locked")
+ KAPI_STATE_TRANS_COND("MCL_FUTURE was set")
+ KAPI_STATE_TRANS_END
+
+ KAPI_STATE_TRANS(2, "all VMA flags",
+ "VM_LOCKED set", "VM_LOCKED cleared",
+ "All virtual memory areas no longer marked as locked")
+ KAPI_STATE_TRANS_END
+
+ KAPI_STATE_TRANS(3, "process statistics",
+ "all memory locked", "no memory locked",
+ "Entire locked memory accounting reset to zero")
+ KAPI_STATE_TRANS_END
+
+ KAPI_STATE_TRANS(4, "page LRU status",
+ "unevictable list", "active/inactive list",
+ "All pages moved to normal LRU lists for reclaim")
+ KAPI_STATE_TRANS_COND("Pages were mlocked")
+ KAPI_STATE_TRANS_END
+
+ /* Locking information */
+ KAPI_LOCK(0, "mmap_lock", KAPI_LOCK_RWLOCK)
+ KAPI_LOCK_DESC("Process memory map write lock")
+ KAPI_LOCK_ACQUIRED
+ KAPI_LOCK_RELEASED
+ KAPI_LOCK_DESC("Protects VMA modifications during munlockall operation")
+ KAPI_LOCK_END
+
+ KAPI_LOCK(1, "lru_lock", KAPI_LOCK_SPINLOCK)
+ KAPI_LOCK_DESC("Per-memcg LRU list lock")
+ KAPI_LOCK_ACQUIRED
+ KAPI_LOCK_RELEASED
+ KAPI_LOCK_DESC("Taken when moving all pages from unevictable to normal LRU lists")
+ KAPI_LOCK_END
+
+ .error_count = 2,
+ .since_version = "2.0",
+ .signal_count = 1,
+ .side_effect_count = 6,
+ .state_trans_count = 5,
+ .lock_count = 2,
+ .examples = "munlockall(); // Unlock all pages",
+ .notes = "Clears VM_LOCKED and VM_LOCKONFAULT from all VMAs and mm->def_flags",
+KAPI_END_SPEC;
+
SYSCALL_DEFINE0(munlockall)
{
int ret;
--
2.39.5