[libc][SysMMan] implement mincore

[SchrodingerZhu]

Implement mincore as specified in https://man7.org/linux/man-pages/man2/mincore.2.html

[llvmbot]

@llvm/pr-subscribers-libc

Author: Schrodinger ZHU Yifan (SchrodingerZhu)

Changes

---

Full diff: https://github.com/llvm/llvm-project/pull/73704.diff

11 Files Affected:

• (modified) libc/config/linux/aarch64/entrypoints.txt (+1)
• (modified) libc/config/linux/riscv/entrypoints.txt (+1)
• (modified) libc/config/linux/x86_64/entrypoints.txt (+1)
• (modified) libc/spec/linux.td (+14-1)
• (modified) libc/spec/spec.td (+2)
• (modified) libc/src/sys/mman/CMakeLists.txt (+7)
• (modified) libc/src/sys/mman/linux/CMakeLists.txt (+13)
• (added) libc/src/sys/mman/linux/mincore.cpp (+28)
• (added) libc/src/sys/mman/mincore.h (+20)
• (modified) libc/test/src/sys/mman/linux/CMakeLists.txt (+16)
• (added) libc/test/src/sys/mman/linux/mincore_test.cpp (+98)

diff --git a/libc/config/linux/aarch64/entrypoints.txt b/libc/config/linux/aarch64/entrypoints.txt
index 284feb7b99096ec..941c1e04ea20b6f 100644
--- a/libc/config/linux/aarch64/entrypoints.txt
+++ b/libc/config/linux/aarch64/entrypoints.txt
@@ -136,6 +136,7 @@ set(TARGET_LIBC_ENTRYPOINTS
     libc.src.sys.mman.mprotect
     libc.src.sys.mman.munmap
     libc.src.sys.mman.posix_madvise
+    libc.src.sys.mman.mincore
 
     # sys/random.h entrypoints
     libc.src.sys.random.getrandom
diff --git a/libc/config/linux/riscv/entrypoints.txt b/libc/config/linux/riscv/entrypoints.txt
index a5f0c91e32d0810..5849dd68cc03263 100644
--- a/libc/config/linux/riscv/entrypoints.txt
+++ b/libc/config/linux/riscv/entrypoints.txt
@@ -142,6 +142,7 @@ set(TARGET_LIBC_ENTRYPOINTS
     libc.src.sys.mman.mprotect
     libc.src.sys.mman.munmap
     libc.src.sys.mman.posix_madvise
+    libc.src.sys.mman.mincore
 
     # sys/random.h entrypoints
     libc.src.sys.random.getrandom
diff --git a/libc/config/linux/x86_64/entrypoints.txt b/libc/config/linux/x86_64/entrypoints.txt
index 63aa7473115a08e..dbac381a64e87be 100644
--- a/libc/config/linux/x86_64/entrypoints.txt
+++ b/libc/config/linux/x86_64/entrypoints.txt
@@ -142,6 +142,7 @@ set(TARGET_LIBC_ENTRYPOINTS
     libc.src.sys.mman.mprotect
     libc.src.sys.mman.munmap
     libc.src.sys.mman.posix_madvise
+    libc.src.sys.mman.mincore
 
     # sys/random.h entrypoints
     libc.src.sys.random.getrandom
diff --git a/libc/spec/linux.td b/libc/spec/linux.td
index ba5f99c12ecd116..eab0a987b920cd9 100644
--- a/libc/spec/linux.td
+++ b/libc/spec/linux.td
@@ -76,7 +76,20 @@ def Linux : StandardSpec<"Linux"> {
 
   HeaderSpec SysMMan = HeaderSpec<
       "sys/mman.h",
-      [Macro<"MAP_ANONYMOUS">]
+      [Macro<"MAP_ANONYMOUS">],
+      [], // Types
+      [], // Enumerations
+      [
+        FunctionSpec<
+            "mincore",
+            RetValSpec<IntType>,
+            [
+              ArgSpec<VoidPtr>,
+              ArgSpec<SizeTType>,
+              ArgSpec<UnsignedCharPtr>,
+            ]
+        >,
+      ]  // Functions
   >;
 
 
diff --git a/libc/spec/spec.td b/libc/spec/spec.td
index b0d5511a4f087ee..3df3fc30f5e2b58 100644
--- a/libc/spec/spec.td
+++ b/libc/spec/spec.td
@@ -49,6 +49,7 @@ def FloatType : NamedType<"float">;
 def DoubleType : NamedType<"double">;
 def LongDoubleType : NamedType<"long double">;
 def CharType : NamedType<"char">;
+def UnsignedCharType : NamedType<"unsigned char">;
 
 // TODO: Add compatibility layer to use C23 type _Float128 if possible.
 def Float128Type : NamedType<"__float128">;
@@ -109,6 +110,7 @@ def IntPtr : PtrType<IntType>;
 def RestrictedIntPtr : RestrictedPtrType<IntType>;
 def FloatPtr : PtrType<FloatType>;
 def DoublePtr : PtrType<DoubleType>;
+def UnsignedCharPtr : PtrType<UnsignedCharType>;
 
 def SigHandlerT : NamedType<"__sighandler_t">;
 
diff --git a/libc/src/sys/mman/CMakeLists.txt b/libc/src/sys/mman/CMakeLists.txt
index e336bfd5d6dbc6e..2d17429a26b457b 100644
--- a/libc/src/sys/mman/CMakeLists.txt
+++ b/libc/src/sys/mman/CMakeLists.txt
@@ -36,3 +36,10 @@ add_entrypoint_object(
   DEPENDS
     .${LIBC_TARGET_OS}.posix_madvise
 )
+
+add_entrypoint_object(
+  mincore
+  ALIAS
+  DEPENDS
+    .${LIBC_TARGET_OS}.mincore
+)
diff --git a/libc/src/sys/mman/linux/CMakeLists.txt b/libc/src/sys/mman/linux/CMakeLists.txt
index 163e7dead8887ab..ce0cda7f2227708 100644
--- a/libc/src/sys/mman/linux/CMakeLists.txt
+++ b/libc/src/sys/mman/linux/CMakeLists.txt
@@ -61,3 +61,16 @@ add_entrypoint_object(
     libc.include.sys_syscall
     libc.src.__support.OSUtil.osutil
 )
+
+add_entrypoint_object(
+  mincore
+  SRCS
+    mincore.cpp
+  HDRS
+    ../mincore.h
+  DEPENDS
+    libc.include.sys_mman
+    libc.include.sys_syscall
+    libc.src.__support.OSUtil.osutil
+    libc.src.errno.errno
+)
diff --git a/libc/src/sys/mman/linux/mincore.cpp b/libc/src/sys/mman/linux/mincore.cpp
new file mode 100644
index 000000000000000..bfe73ccdaee6dad
--- /dev/null
+++ b/libc/src/sys/mman/linux/mincore.cpp
@@ -0,0 +1,28 @@
+//===---------- Linux implementation of the POSIX mmap function -----------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "src/sys/mman/mincore.h"
+
+#include "src/__support/OSUtil/syscall.h" // For internal syscall function.
+
+#include "src/errno/libc_errno.h"
+#include <sys/syscall.h> // For syscall numbers.
+
+namespace LIBC_NAMESPACE {
+
+LLVM_LIBC_FUNCTION(int, mincore, (void *addr, size_t len, unsigned char *vec)) {
+  long ret = syscall_impl(SYS_mincore, reinterpret_cast<long>(addr), len,
+                          reinterpret_cast<long>(vec));
+  if (ret < 0) {
+    libc_errno = static_cast<int>(-ret);
+    return -1;
+  }
+  return 0;
+}
+
+} // namespace LIBC_NAMESPACE
diff --git a/libc/src/sys/mman/mincore.h b/libc/src/sys/mman/mincore.h
new file mode 100644
index 000000000000000..403afaeb6af970c
--- /dev/null
+++ b/libc/src/sys/mman/mincore.h
@@ -0,0 +1,20 @@
+//===-- Implementation header for mincore function --------------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_LIBC_SRC_SYS_MMAN_MINCORE_H
+#define LLVM_LIBC_SRC_SYS_MMAN_MINCORE_H
+
+#include <sys/mman.h> // For size_t
+
+namespace LIBC_NAMESPACE {
+
+int mincore(void *addr, size_t len, unsigned char *vec);
+
+} // namespace LIBC_NAMESPACE
+
+#endif // LLVM_LIBC_SRC_SYS_MMAN_MINCORE_H
diff --git a/libc/test/src/sys/mman/linux/CMakeLists.txt b/libc/test/src/sys/mman/linux/CMakeLists.txt
index 66743be175fed1d..5402ae030b345c6 100644
--- a/libc/test/src/sys/mman/linux/CMakeLists.txt
+++ b/libc/test/src/sys/mman/linux/CMakeLists.txt
@@ -62,3 +62,19 @@ add_libc_unittest(
     libc.src.sys.mman.posix_madvise
     libc.test.UnitTest.ErrnoSetterMatcher
 )
+
+add_libc_unittest(
+  mincore_test
+  SUITE
+    libc_sys_mman_unittests
+  SRCS
+    mincore_test.cpp
+  DEPENDS
+    libc.include.sys_mman
+    libc.src.errno.errno
+    libc.src.sys.mman.mmap
+    libc.src.sys.mman.munmap
+    libc.src.sys.mman.madvise
+    libc.src.sys.mman.mincore
+    libc.test.UnitTest.ErrnoSetterMatcher
+)
diff --git a/libc/test/src/sys/mman/linux/mincore_test.cpp b/libc/test/src/sys/mman/linux/mincore_test.cpp
new file mode 100644
index 000000000000000..02199947e4308ae
--- /dev/null
+++ b/libc/test/src/sys/mman/linux/mincore_test.cpp
@@ -0,0 +1,98 @@
+//===-- Unittests for mmap and munmap -------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "src/errno/libc_errno.h"
+#include "src/sys/mman/madvise.h"
+#include "src/sys/mman/mincore.h"
+#include "src/sys/mman/mmap.h"
+#include "src/sys/mman/munmap.h"
+#include "test/UnitTest/ErrnoSetterMatcher.h"
+#include "test/UnitTest/LibcTest.h"
+#include "test/UnitTest/Test.h"
+
+#include <linux/param.h> // For EXEC_PAGESIZE
+#include <sys/mman.h>
+
+using LIBC_NAMESPACE::testing::ErrnoSetterMatcher::Fails;
+using LIBC_NAMESPACE::testing::ErrnoSetterMatcher::Succeeds;
+
+TEST(LlvmLibcMincoreTest, UnMappedMemory) {
+  libc_errno = 0;
+  unsigned char vec;
+  int res = LIBC_NAMESPACE::mincore(nullptr, 1, &vec);
+  EXPECT_THAT(res, Fails(ENOMEM, -1));
+}
+
+TEST(LlvmLibcMincoreTest, InvalidVec) {
+  void *addr = LIBC_NAMESPACE::mmap(nullptr, EXEC_PAGESIZE, PROT_READ,
+                                    MAP_ANONYMOUS | MAP_PRIVATE, -1, 0);
+  EXPECT_NE(addr, MAP_FAILED);
+  EXPECT_EQ(reinterpret_cast<unsigned long>(addr) % EXEC_PAGESIZE, 0ul);
+  libc_errno = 0;
+  int res = LIBC_NAMESPACE::mincore(addr, 1, nullptr);
+  EXPECT_THAT(res, Fails(EFAULT, -1));
+  EXPECT_THAT(LIBC_NAMESPACE::munmap(addr, EXEC_PAGESIZE), Succeeds());
+}
+
+TEST(LlvmLibcMincoreTest, UnalignedAddr) {
+  void *addr = LIBC_NAMESPACE::mmap(nullptr, EXEC_PAGESIZE, PROT_READ,
+                                    MAP_ANONYMOUS | MAP_PRIVATE, -1, 0);
+  EXPECT_NE(addr, MAP_FAILED);
+  EXPECT_EQ(reinterpret_cast<unsigned long>(addr) % EXEC_PAGESIZE, 0ul);
+  libc_errno = 0;
+  int res = LIBC_NAMESPACE::mincore(static_cast<char *>(addr) + 1, 1, nullptr);
+  EXPECT_THAT(res, Fails(EINVAL, -1));
+  EXPECT_THAT(LIBC_NAMESPACE::munmap(addr, EXEC_PAGESIZE), Succeeds());
+}
+
+TEST(LlvmLibcMincoreTest, NoError) {
+  void *addr = LIBC_NAMESPACE::mmap(nullptr, EXEC_PAGESIZE, PROT_READ,
+                                    MAP_ANONYMOUS | MAP_PRIVATE, -1, 0);
+  EXPECT_NE(addr, MAP_FAILED);
+  EXPECT_EQ(reinterpret_cast<unsigned long>(addr) % EXEC_PAGESIZE, 0ul);
+  unsigned char vec;
+  libc_errno = 0;
+  int res = LIBC_NAMESPACE::mincore(static_cast<char *>(addr), 1, &vec);
+  EXPECT_THAT(res, Succeeds());
+  EXPECT_THAT(LIBC_NAMESPACE::munmap(addr, EXEC_PAGESIZE), Succeeds());
+}
+
+#if defined(MADV_PAGEOUT)
+TEST(LlvmLibcMincoreTest, PageOut) {
+  unsigned char vec;
+  void *addr =
+      LIBC_NAMESPACE::mmap(nullptr, EXEC_PAGESIZE, PROT_READ | PROT_WRITE,
+                           MAP_ANONYMOUS | MAP_PRIVATE, -1, 0);
+  EXPECT_NE(addr, MAP_FAILED);
+  EXPECT_EQ(reinterpret_cast<unsigned long>(addr) % EXEC_PAGESIZE, 0ul);
+
+  // touch the page
+  {
+    static_cast<char *>(addr)[0] = 0;
+    libc_errno = 0;
+    int res = LIBC_NAMESPACE::mincore(static_cast<char *>(addr), 1, &vec);
+    EXPECT_EQ(vec, static_cast<unsigned char>(1));
+    EXPECT_THAT(res, Succeeds());
+  }
+
+  // page out the memory
+  {
+    libc_errno = 0;
+    EXPECT_THAT(LIBC_NAMESPACE::madvise(addr, EXEC_PAGESIZE, MADV_PAGEOUT),
+                Succeeds());
+
+    libc_errno = 0;
+    int res =
+        LIBC_NAMESPACE::mincore(static_cast<char *>(addr), EXEC_PAGESIZE, &vec);
+    EXPECT_EQ(vec, static_cast<unsigned char>(0));
+    EXPECT_THAT(res, Succeeds());
+  }
+
+  EXPECT_THAT(LIBC_NAMESPACE::munmap(addr, EXEC_PAGESIZE), Succeeds());
+}
+#endif

[nickdesaulniers]

LGTM;

from the man pages:

The vec argument must point to an array containing at least
(length+PAGE_SIZE-1) / PAGE_SIZE bytes.

what happens when that's not the case? Should you add a test for that?

[SchrodingerZhu]

@nickdesaulniers tests added. There is another thing:

On return, the least significant bit of each byte will be set if the corresponding page is currently resident in memory, and be clear otherwise. (The settings of the other bits in each byte are undefined; these bits are reserved for possible later use.)

Hence, I should only check the LSB, which is corrected in my last commit.

[SchrodingerZhu]

merge this?