userfaultfd 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c4c0a7c4dc065c872850b1c6d1cec3c19130f606c7ecad76efc0403e84418693
+  data.tar.gz: 718b058ac60f5abff6c5f66d22b9e7a38c82c4b704490f669762c16994bdbba1
+SHA512:
+  metadata.gz: 138ef38522fc668d6e92ec41d38f05451eece15f5518949c2197bf6020ebf3839cd193ad0f22fc8a9bfe84dc2c2f3d94766b18beb8f630da220b25974b57aca9
+  data.tar.gz: 0ce48388e31b212bcd9553cdd3243fd6d20c6a9071f311613e212b2767c85c6c5e2c1d6b0d01130728097c9a017449a1da81858ec197e6ee51a3da396f7fae1a

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,142 @@
+# userfaultfd
+
+Ruby bindings for Linux `userfaultfd(2)`, with mmap-backed regions and handlers that avoid blocking Ruby's Global VM Lock (GVL).
+
+## The deadlock rule
+
+A Ruby thread must never touch registered memory through a raw pointer while a Ruby callback is expected to resolve the fault. The faulting thread keeps the GVL, so the callback cannot run.
+
+Use one of these supported arrangements:
+
+- `Region#read` / `Region#write`: the C extension releases the GVL around memory access.
+- A forked faulting process: the parent callback has a separate GVL. `UFFD_FEATURE_EVENT_FORK` also requires `CAP_SYS_PTRACE`; check `enabled_features`.
+- A native `:zero_fill`, `:backing_file`, or `:prefilled` handler: the handler never enters Ruby.
+
+See [docs/gvl-and-page-faults.md](docs/gvl-and-page-faults.md) for the full failure sequence and implementation details.
+
+## Requirements
+
+- Linux 4.11 or newer with `CONFIG_USERFAULTFD`
+- Ruby 3.2 or newer
+- A C compiler; the Linux 4.11 baseline UAPI is bundled for build hosts without `linux/userfaultfd.h`
+- Permission through `/dev/userfaultfd`, or the `userfaultfd(2)` syscall with `UFFD_USER_MODE_ONLY`
+
+The gem tries `/dev/userfaultfd` first and falls back to the syscall. Requiring the gem succeeds on unsupported systems; `UserfaultFD.supported?` returns `false`, and opening a descriptor raises `UserfaultFD::UnsupportedError` or the relevant `Errno::*` permission error. Linux before 5.11 does not understand `UFFD_USER_MODE_ONLY`; an appropriately permitted caller can explicitly use `user_mode_only: false` with `.supported?`, `.features`, and `.new`. This opts into kernel-originated faults and is never automatic.
+
+## Installation
+
+```ruby
+gem "userfaultfd"
+```
+
+Then run `bundle install`. The `userfaultfd` RubyGems name was unclaimed when this project was initialized; until it is published, use the repository source in your Gemfile.
+
+## Native zero fill
+
+This mode is safe even when the main Ruby thread faults:
+
+```ruby
+require "userfaultfd"
+
+region = UserfaultFD::Region.new(size: 64 * 1024 * 1024)
+uffd = UserfaultFD.new(features: [])
+uffd.register(region, mode: :missing)
+handler = uffd.start_handler(mode: :zero_fill)
+
+data = region.read(0, region.size)
+raise "not zero" unless data == "\0".b * region.size
+
+handler.stop
+uffd.close
+region.unmap
+```
+
+## Ruby callback in one process
+
+`Region#read` releases the GVL, allowing the handler's Ruby block to run:
+
+```ruby
+page_size = UserfaultFD::Region.allocate.page_size
+region = UserfaultFD::Region.new(size: page_size)
+uffd = UserfaultFD.new(features: [])
+uffd.register(region, mode: :missing)
+handler = uffd.start_handler do |event|
+  event.copy("x" * region.page_size) if event.is_a?(UserfaultFD::Fault)
+end
+
+region.read(0, region.page_size) #=> "x" * page_size
+
+handler.stop
+uffd.close
+region.unmap
+```
+
+## Forked faulting process
+
+When permitted, `UserfaultFD.new` enables `EVENT_FORK` by default. A native event reader consumes the fork event without waiting for the GVL, then delivers `ForkEvent` and child faults to the Ruby handler.
+
+```ruby
+page_size = UserfaultFD::Region.allocate.page_size
+region = UserfaultFD::Region.new(size: page_size)
+uffd = UserfaultFD.new
+raise "EVENT_FORK needs CAP_SYS_PTRACE" unless uffd.enabled_features.include?(:event_fork)
+
+uffd.register(region, mode: :missing)
+handler = uffd.start_handler do |event|
+  case event
+  when UserfaultFD::Fault
+    event.copy("child".ljust(region.page_size, "\0"))
+  when UserfaultFD::ForkEvent
+    # The handler monitors and closes event.child_uffd automatically.
+  end
+end
+
+pid = fork { exit!(region.read(0, 5) == "child" ? 0 : 1) }
+Process.wait(pid)
+
+handler.stop
+uffd.close
+region.unmap
+```
+
+## Other operations
+
+- `Fault#zero`, `#copy`, `#wake`, `#continue`, `#poison`, and `#move`
+- `UserfaultFD#writeprotect` with `mode: [:missing, :wp]`
+- `Region#madvise(:dontneed)` to drop page-table entries and `:remove` to discard shared pages
+- `mode: :backing_file, io: file` for native lazy file loading
+- `mode: :prefilled, source: region` for native copies from another region
+- `ForkEvent`, `RemapEvent`, `RemoveEvent`, and `UnmapEvent`
+- `UserfaultFD.features` for kernel capabilities and `#enabled_features` for this descriptor
+
+Optional ioctls raise `UnsupportedError` when they are absent from the build headers or running kernel.
+
+## Unsupported and constrained environments
+
+| Environment | Result |
+|---|---|
+| macOS, BSD, Windows | `require` works; `supported?` is `false` |
+| Linux before 4.11 or without `CONFIG_USERFAULTFD` | Unsupported |
+| Linux 4.11–5.10 | An appropriately permitted caller must explicitly pass `user_mode_only: false` |
+| Docker with the default seccomp profile | The syscall is commonly blocked; allow `userfaultfd` or use an accessible `/dev/userfaultfd` |
+| Docker Desktop / WSL2 | Depends on the VM kernel, config, device, and seccomp policy rather than the guest userspace alone |
+| Linux with `vm.unprivileged_userfaultfd=0` | User-mode-only faults still work on kernels that honor `UFFD_USER_MODE_ONLY`; fork events require `CAP_SYS_PTRACE` |
+| GitHub-hosted runners | Unit tests run; system tests skip when the host policy denies userfaultfd |
+| Kernels before 6.6 / 6.8 | `POISON` / `MOVE` capabilities are absent |
+
+Never register Ruby's object heap. Registered memory must come from `UserfaultFD::Region`; otherwise GC or ordinary Ruby code can fault while holding the GVL.
+
+## Development
+
+```sh
+rake compile
+rake test:unit
+rake test:system
+rbs -I sig validate
+```
+
+System examples use timeouts because an unresolved page fault intentionally blocks its faulting process. The kernel matrix runner is in `tools/vm`.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/docs/gvl-and-page-faults.md

@@ -0,0 +1,58 @@
+# GVL and userfaultfd page faults
+
+## Why the naive Ruby callback deadlocks
+
+The kernel suspends a thread that faults on a registered page until another thread resolves the event. If ordinary Ruby code performs that access through a raw pointer, the suspended thread still owns the GVL:
+
+1. Ruby thread A touches the registered address while holding the GVL.
+2. The kernel suspends A and publishes `UFFD_EVENT_PAGEFAULT`.
+3. Handler thread B reads the event.
+4. B needs the GVL before it can invoke the Ruby block.
+5. A cannot release the GVL until the fault is resolved, while B cannot resolve it until A releases the GVL.
+
+`spec/system/userfaultfd_spec.rb` fixes this behavior as an intentional test: a child process performs a `Fiddle::Pointer` read, the test confirms it remains blocked for two seconds, then sends `SIGKILL`. The timeout and process isolation prevent a failed test from hanging the suite.
+
+## Arrangement B: GVL-free memory access
+
+`Region#read` and `Region#write` copy memory inside `rb_thread_call_without_gvl`. A native event-reader thread moves kernel messages into a pipe. The Ruby handler can therefore acquire the GVL, create `Fault` objects, and call `UFFDIO_COPY` or `UFFDIO_ZEROPAGE`.
+
+The resolution ioctls also run without the GVL. Strings passed to `Fault#copy` are copied into C-owned memory first, so Ruby GC cannot move or free the source while the ioctl is running.
+
+## Arrangement A: process separation and fork events
+
+Fork handling has an extra cycle: `EVENT_FORK` must be read before `fork(2)` completes, but the Ruby thread invoking `fork` holds the GVL. A Ruby event-reader thread therefore cannot make progress.
+
+The extension uses a C event-reader thread that never enters Ruby while polling the parent and child descriptors. It reads `EVENT_FORK`, starts monitoring the child fd, and writes fixed-size records to a pipe. Once `fork` returns and Ruby can schedule again, the handler converts those records into `ForkEvent` and `Fault` objects.
+
+This requires `UFFD_FEATURE_EVENT_FORK`, which the kernel restricts with `CAP_SYS_PTRACE`. `UserfaultFD.new` tries to enable it and falls back to a descriptor without fork events on `EPERM`; callers must check `enabled_features` before using the fork arrangement.
+
+## Arrangement C: native handlers
+
+The native modes resolve missing faults entirely in a pthread:
+
+- `zero_fill` issues `UFFDIO_ZEROPAGE`.
+- `backing_file` uses `pread` and `UFFDIO_COPY`.
+- `prefilled` copies from a second mmap-backed `Region`.
+
+No Ruby callback or Ruby-managed buffer is involved. These modes are the appropriate choice for fault rates that a Ruby callback cannot sustain.
+
+## Boundaries
+
+- Do not register the Ruby heap.
+- Do not dereference `Region#to_ptr` from Ruby while using a Ruby handler.
+- A handler monitors at most 64 fork descendants. An epoll-backed dynamic set is the upgrade path if external process fan-out exceeds that ceiling.
+- Native handlers currently service the descriptor on which they started; use the Ruby handler/event reader for fork descendants.
+- Always stop handlers before closing descriptors or unmapping regions.
+
+## Permission survey
+
+`vm.unprivileged_userfaultfd` is a host-kernel setting, not a reliable property of the userspace distribution. Current [upstream kernel documentation](https://www.kernel.org/doc/html/latest/admin-guide/sysctl/vm.html#unprivileged-userfaultfd) and [Debian's packaged kernel documentation](https://sources.debian.org/src/linux/6.12.96-1/Documentation/admin-guide/sysctl/vm.rst) document a default of `0`: unprivileged callers must use `UFFD_USER_MODE_ONLY`. Ubuntu's [userfaultfd man page](https://manpages.ubuntu.com/manpages/jammy/man2/userfaultfd.2.html) likewise documents `EPERM` when the value is `0` and the caller lacks `CAP_SYS_PTRACE`.
+
+Cloud images, administrators, and container hosts can override that value, and containers observe the host kernel rather than the image's `/etc/os-release`. The gem therefore probes the real syscall instead of guessing from a distribution name. Diagnose a target with:
+
+```sh
+cat /proc/sys/vm/unprivileged_userfaultfd
+grep USERFAULTFD /boot/config-"$(uname -r)" 2>/dev/null
+```
+
+On Linux 5.11 and newer, the default `user_mode_only: true` remains usable when the sysctl is `0`. Linux 4.11–5.10 requires the explicitly less restrictive `user_mode_only: false` and whatever privilege or sysctl policy that kernel enforces.

data/examples/dirty_tracking.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "userfaultfd"
+
+abort "write-protect faults are unavailable" unless UserfaultFD.features.include?(:pagefault_flag_wp)
+
+page_size = UserfaultFD::Region.allocate.page_size
+region = UserfaultFD::Region.new(size: page_size)
+uffd = UserfaultFD.new(features: [:pagefault_flag_wp])
+uffd.register(region, mode: %i[missing wp])
+dirty_pages = []
+handler = uffd.start_handler do |event|
+  next unless event.is_a?(UserfaultFD::Fault)
+
+  if event.wp?
+    dirty_pages << event.address
+    uffd.writeprotect(region, enabled: false)
+  else
+    event.zero
+  end
+end
+
+region.read(0, 1)
+uffd.writeprotect(region, enabled: true)
+region.write(0, "changed")
+puts "dirty pages: #{dirty_pages.length}"
+
+handler.stop
+uffd.close
+region.unmap

data/examples/lazy_mmap.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "userfaultfd"
+
+path = ARGV.fetch(0)
+file = File.open(path, "rb")
+page_size = UserfaultFD::Region.allocate.page_size
+size = [((file.size + page_size - 1) / page_size) * page_size, page_size].max
+region = UserfaultFD::Region.new(size: size)
+uffd = UserfaultFD.new(features: [])
+uffd.register(region, mode: :missing)
+handler = uffd.start_handler(mode: :backing_file, io: file)
+
+puts region.read(0, [file.size, page_size].min)
+
+handler.stop
+uffd.close
+region.unmap
+file.close

data/examples/oom_canary.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "userfaultfd"
+
+required = %i[poison event_fork]
+abort "UFFDIO_POISON and EVENT_FORK are required" unless (required - UserfaultFD.features).empty?
+
+page_size = UserfaultFD::Region.allocate.page_size
+region = UserfaultFD::Region.new(size: page_size)
+uffd = UserfaultFD.new(features: required)
+uffd.register(region, mode: :missing)
+handler = uffd.start_handler do |event|
+  event.poison if event.is_a?(UserfaultFD::Fault)
+end
+
+pid = fork do
+  Process.setrlimit(Process::RLIMIT_CORE, 0)
+  region.read(0, 1)
+  exit! 0
+end
+Process.wait(pid)
+puts "child status: #{$?}"
+
+handler.stop
+uffd.close
+region.unmap

data/examples/post_copy_migration.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "socket"
+require "userfaultfd"
+
+page_size = UserfaultFD::Region.allocate.page_size
+region = UserfaultFD::Region.new(size: page_size)
+uffd = UserfaultFD.new
+abort "EVENT_FORK requires CAP_SYS_PTRACE" unless uffd.enabled_features.include?(:event_fork)
+
+sender, receiver = Socket.pair(:UNIX, :STREAM)
+sender.write("migrated".ljust(page_size, "\0"))
+uffd.register(region, mode: :missing)
+handler = uffd.start_handler do |event|
+  event.copy(receiver.read(page_size)) if event.is_a?(UserfaultFD::Fault)
+end
+
+pid = fork do
+  STDOUT.write("#{region.read(0, 8)}\n")
+  STDOUT.flush
+  exit! 0
+end
+Process.wait(pid)
+
+handler.stop
+uffd.close
+region.unmap
+sender.close
+receiver.close

data/ext/userfaultfd/compat.h

@@ -0,0 +1,237 @@
+#ifndef USERFAULTFD_COMPAT_H
+#define USERFAULTFD_COMPAT_H
+
+#ifdef __linux__
+# include <stdint.h>
+# include <sys/ioctl.h>
+
+# ifdef HAVE_LINUX_USERFAULTFD_H
+#  include <linux/userfaultfd.h>
+# else
+/* Linux 4.11 baseline UAPI for build hosts without userfaultfd.h. */
+#  define UFFD_API UINT64_C(0xAA)
+
+#  define _UFFDIO_REGISTER 0x00
+#  define _UFFDIO_UNREGISTER 0x01
+#  define _UFFDIO_WAKE 0x02
+#  define _UFFDIO_COPY 0x03
+#  define _UFFDIO_ZEROPAGE 0x04
+#  define _UFFDIO_WRITEPROTECT 0x06
+#  define _UFFDIO_CONTINUE 0x07
+#  define _UFFDIO_API 0x3F
+#  define UFFDIO 0xAA
+
+struct uffd_msg {
+    uint8_t event;
+    uint8_t reserved1;
+    uint16_t reserved2;
+    uint32_t reserved3;
+    union {
+        struct {
+            uint64_t flags;
+            uint64_t address;
+            union { uint32_t ptid; } feat;
+        } pagefault;
+        struct { uint32_t ufd; } fork;
+        struct { uint64_t from, to, len; } remap;
+        struct { uint64_t start, end; } remove;
+        struct { uint64_t reserved1, reserved2, reserved3; } reserved;
+    } arg;
+} __attribute__((packed));
+
+#  define UFFD_EVENT_PAGEFAULT 0x12
+#  define UFFD_EVENT_FORK 0x13
+#  define UFFD_EVENT_REMAP 0x14
+#  define UFFD_EVENT_REMOVE 0x15
+#  define UFFD_EVENT_UNMAP 0x16
+
+#  define UFFD_PAGEFAULT_FLAG_WRITE (1 << 0)
+#  define UFFD_PAGEFAULT_FLAG_WP (1 << 1)
+#  define UFFD_PAGEFAULT_FLAG_MINOR (1 << 2)
+
+struct uffdio_api { uint64_t api, features, ioctls; };
+#  define UFFD_FEATURE_PAGEFAULT_FLAG_WP (UINT64_C(1) << 0)
+#  define UFFD_FEATURE_EVENT_FORK (UINT64_C(1) << 1)
+#  define UFFD_FEATURE_EVENT_REMAP (UINT64_C(1) << 2)
+#  define UFFD_FEATURE_EVENT_REMOVE (UINT64_C(1) << 3)
+#  define UFFD_FEATURE_MISSING_HUGETLBFS (UINT64_C(1) << 4)
+#  define UFFD_FEATURE_MISSING_SHMEM (UINT64_C(1) << 5)
+#  define UFFD_FEATURE_EVENT_UNMAP (UINT64_C(1) << 6)
+#  define UFFD_FEATURE_SIGBUS (UINT64_C(1) << 7)
+#  define UFFD_FEATURE_THREAD_ID (UINT64_C(1) << 8)
+
+struct uffdio_range { uint64_t start, len; };
+struct uffdio_register {
+    struct uffdio_range range;
+    uint64_t mode, ioctls;
+};
+#  define UFFDIO_REGISTER_MODE_MISSING (UINT64_C(1) << 0)
+#  define UFFDIO_REGISTER_MODE_WP (UINT64_C(1) << 1)
+#  define UFFDIO_REGISTER_MODE_MINOR (UINT64_C(1) << 2)
+
+struct uffdio_copy {
+    uint64_t dst, src, len, mode;
+    int64_t copy;
+};
+#  define UFFDIO_COPY_MODE_DONTWAKE (UINT64_C(1) << 0)
+
+struct uffdio_zeropage {
+    struct uffdio_range range;
+    uint64_t mode;
+    int64_t zeropage;
+};
+#  define UFFDIO_ZEROPAGE_MODE_DONTWAKE (UINT64_C(1) << 0)
+
+struct uffdio_writeprotect {
+    struct uffdio_range range;
+    uint64_t mode;
+};
+#  define UFFDIO_WRITEPROTECT_MODE_WP (UINT64_C(1) << 0)
+
+struct uffdio_continue {
+    struct uffdio_range range;
+    uint64_t mode;
+    int64_t mapped;
+};
+#  define UFFDIO_CONTINUE_MODE_DONTWAKE (UINT64_C(1) << 0)
+
+#  define UFFDIO_API _IOWR(UFFDIO, _UFFDIO_API, struct uffdio_api)
+#  define UFFDIO_REGISTER _IOWR(UFFDIO, _UFFDIO_REGISTER, struct uffdio_register)
+#  define UFFDIO_UNREGISTER _IOR(UFFDIO, _UFFDIO_UNREGISTER, struct uffdio_range)
+#  define UFFDIO_WAKE _IOR(UFFDIO, _UFFDIO_WAKE, struct uffdio_range)
+#  define UFFDIO_COPY _IOWR(UFFDIO, _UFFDIO_COPY, struct uffdio_copy)
+#  define UFFDIO_ZEROPAGE _IOWR(UFFDIO, _UFFDIO_ZEROPAGE, struct uffdio_zeropage)
+#  define UFFDIO_WRITEPROTECT _IOWR(UFFDIO, _UFFDIO_WRITEPROTECT, struct uffdio_writeprotect)
+#  define UFFDIO_CONTINUE _IOWR(UFFDIO, _UFFDIO_CONTINUE, struct uffdio_continue)
+# endif
+
+# ifndef UFFD_USER_MODE_ONLY
+#  define UFFD_USER_MODE_ONLY 1
+# endif
+
+/* Keep old or absent build headers feature-complete; the kernel still probes support. */
+# ifndef UFFD_PAGEFAULT_FLAG_WP
+#  define UFFD_PAGEFAULT_FLAG_WP (1 << 1)
+# endif
+# ifndef UFFD_PAGEFAULT_FLAG_MINOR
+#  define UFFD_PAGEFAULT_FLAG_MINOR (1 << 2)
+# endif
+# ifndef UFFD_FEATURE_PAGEFAULT_FLAG_WP
+#  define UFFD_FEATURE_PAGEFAULT_FLAG_WP (UINT64_C(1) << 0)
+# endif
+# ifndef UFFD_FEATURE_EVENT_FORK
+#  define UFFD_FEATURE_EVENT_FORK (UINT64_C(1) << 1)
+# endif
+# ifndef UFFD_FEATURE_EVENT_REMAP
+#  define UFFD_FEATURE_EVENT_REMAP (UINT64_C(1) << 2)
+# endif
+# ifndef UFFD_FEATURE_EVENT_REMOVE
+#  define UFFD_FEATURE_EVENT_REMOVE (UINT64_C(1) << 3)
+# endif
+# ifndef UFFD_FEATURE_MISSING_HUGETLBFS
+#  define UFFD_FEATURE_MISSING_HUGETLBFS (UINT64_C(1) << 4)
+# endif
+# ifndef UFFD_FEATURE_MISSING_SHMEM
+#  define UFFD_FEATURE_MISSING_SHMEM (UINT64_C(1) << 5)
+# endif
+# ifndef UFFD_FEATURE_EVENT_UNMAP
+#  define UFFD_FEATURE_EVENT_UNMAP (UINT64_C(1) << 6)
+# endif
+# ifndef UFFD_FEATURE_SIGBUS
+#  define UFFD_FEATURE_SIGBUS (UINT64_C(1) << 7)
+# endif
+# ifndef UFFD_FEATURE_THREAD_ID
+#  define UFFD_FEATURE_THREAD_ID (UINT64_C(1) << 8)
+# endif
+# ifndef UFFD_FEATURE_MINOR_HUGETLBFS
+#  define UFFD_FEATURE_MINOR_HUGETLBFS (UINT64_C(1) << 9)
+# endif
+# ifndef UFFD_FEATURE_MINOR_SHMEM
+#  define UFFD_FEATURE_MINOR_SHMEM (UINT64_C(1) << 10)
+# endif
+# ifndef UFFD_FEATURE_EXACT_ADDRESS
+#  define UFFD_FEATURE_EXACT_ADDRESS (UINT64_C(1) << 11)
+# endif
+# ifndef UFFD_FEATURE_WP_HUGETLBFS_SHMEM
+#  define UFFD_FEATURE_WP_HUGETLBFS_SHMEM (UINT64_C(1) << 12)
+# endif
+# ifndef UFFD_FEATURE_WP_UNPOPULATED
+#  define UFFD_FEATURE_WP_UNPOPULATED (UINT64_C(1) << 13)
+# endif
+# ifndef UFFD_FEATURE_POISON
+#  define UFFD_FEATURE_POISON (UINT64_C(1) << 14)
+# endif
+# ifndef UFFD_FEATURE_WP_ASYNC
+#  define UFFD_FEATURE_WP_ASYNC (UINT64_C(1) << 15)
+# endif
+# ifndef UFFD_FEATURE_MOVE
+#  define UFFD_FEATURE_MOVE (UINT64_C(1) << 16)
+# endif
+
+# ifndef UFFDIO_REGISTER_MODE_WP
+#  define UFFDIO_REGISTER_MODE_WP (UINT64_C(1) << 1)
+# endif
+# ifndef UFFDIO_REGISTER_MODE_MINOR
+#  define UFFDIO_REGISTER_MODE_MINOR (UINT64_C(1) << 2)
+# endif
+
+# ifndef UFFDIO_WRITEPROTECT
+#  ifndef _UFFDIO_WRITEPROTECT
+#   define _UFFDIO_WRITEPROTECT 0x06
+#  endif
+struct uffdio_writeprotect {
+    struct uffdio_range range;
+    uint64_t mode;
+};
+#  define UFFDIO_WRITEPROTECT_MODE_WP (UINT64_C(1) << 0)
+#  define UFFDIO_WRITEPROTECT _IOWR(UFFDIO, _UFFDIO_WRITEPROTECT, struct uffdio_writeprotect)
+# endif
+
+# ifndef UFFDIO_CONTINUE
+#  ifndef _UFFDIO_CONTINUE
+#   define _UFFDIO_CONTINUE 0x07
+#  endif
+struct uffdio_continue {
+    struct uffdio_range range;
+    uint64_t mode;
+    int64_t mapped;
+};
+#  define UFFDIO_CONTINUE_MODE_DONTWAKE (UINT64_C(1) << 0)
+#  define UFFDIO_CONTINUE _IOWR(UFFDIO, _UFFDIO_CONTINUE, struct uffdio_continue)
+# endif
+
+# ifndef UFFDIO_POISON
+#  ifndef _UFFDIO_POISON
+#   define _UFFDIO_POISON 0x08
+#  endif
+struct uffdio_poison {
+    struct uffdio_range range;
+    uint64_t mode;
+    int64_t updated;
+};
+#  define UFFDIO_POISON_MODE_DONTWAKE (UINT64_C(1) << 0)
+#  define UFFDIO_POISON _IOWR(UFFDIO, _UFFDIO_POISON, struct uffdio_poison)
+# endif
+
+# ifndef UFFDIO_MOVE
+#  ifndef _UFFDIO_MOVE
+#   define _UFFDIO_MOVE 0x05
+#  endif
+struct uffdio_move {
+    uint64_t dst, src, len, mode;
+    int64_t move;
+};
+#  define UFFDIO_MOVE_MODE_DONTWAKE (UINT64_C(1) << 0)
+#  define UFFDIO_MOVE _IOWR(UFFDIO, _UFFDIO_MOVE, struct uffdio_move)
+# endif
+
+/* Added in Linux 5.19. Old headers still build and use the syscall path. */
+# ifndef USERFAULTFD_IOC
+#  define USERFAULTFD_IOC 0xAA
+# endif
+# ifndef USERFAULTFD_IOC_NEW
+#  define USERFAULTFD_IOC_NEW _IO(USERFAULTFD_IOC, 0x00)
+# endif
+#endif
+
+#endif

data/ext/userfaultfd/constants.c

@@ -0,0 +1,102 @@
+/* Generated by rake gen:constants. Do not edit. */
+#include "ruby.h"
+#include "extconf.h"
+
+#ifdef __linux__
+# include "compat.h"
+# define UFFD_CONST(name) rb_define_const(klass, #name, ULL2NUM(name))
+#else
+# define UFFD_CONST(name) ((void)0)
+#endif
+
+void
+userfaultfd_define_constants(VALUE klass)
+{
+#ifdef UFFD_API
+    UFFD_CONST(UFFD_API);
+#endif
+#ifdef UFFD_EVENT_PAGEFAULT
+    UFFD_CONST(UFFD_EVENT_PAGEFAULT);
+#endif
+#ifdef UFFD_EVENT_FORK
+    UFFD_CONST(UFFD_EVENT_FORK);
+#endif
+#ifdef UFFD_EVENT_REMAP
+    UFFD_CONST(UFFD_EVENT_REMAP);
+#endif
+#ifdef UFFD_EVENT_REMOVE
+    UFFD_CONST(UFFD_EVENT_REMOVE);
+#endif
+#ifdef UFFD_EVENT_UNMAP
+    UFFD_CONST(UFFD_EVENT_UNMAP);
+#endif
+#ifdef UFFD_PAGEFAULT_FLAG_WRITE
+    UFFD_CONST(UFFD_PAGEFAULT_FLAG_WRITE);
+#endif
+#ifdef UFFD_PAGEFAULT_FLAG_WP
+    UFFD_CONST(UFFD_PAGEFAULT_FLAG_WP);
+#endif
+#ifdef UFFD_PAGEFAULT_FLAG_MINOR
+    UFFD_CONST(UFFD_PAGEFAULT_FLAG_MINOR);
+#endif
+#ifdef UFFD_FEATURE_PAGEFAULT_FLAG_WP
+    UFFD_CONST(UFFD_FEATURE_PAGEFAULT_FLAG_WP);
+#endif
+#ifdef UFFD_FEATURE_EVENT_FORK
+    UFFD_CONST(UFFD_FEATURE_EVENT_FORK);
+#endif
+#ifdef UFFD_FEATURE_EVENT_REMAP
+    UFFD_CONST(UFFD_FEATURE_EVENT_REMAP);
+#endif
+#ifdef UFFD_FEATURE_EVENT_REMOVE
+    UFFD_CONST(UFFD_FEATURE_EVENT_REMOVE);
+#endif
+#ifdef UFFD_FEATURE_EVENT_UNMAP
+    UFFD_CONST(UFFD_FEATURE_EVENT_UNMAP);
+#endif
+#ifdef UFFD_FEATURE_MISSING_HUGETLBFS
+    UFFD_CONST(UFFD_FEATURE_MISSING_HUGETLBFS);
+#endif
+#ifdef UFFD_FEATURE_MISSING_SHMEM
+    UFFD_CONST(UFFD_FEATURE_MISSING_SHMEM);
+#endif
+#ifdef UFFD_FEATURE_SIGBUS
+    UFFD_CONST(UFFD_FEATURE_SIGBUS);
+#endif
+#ifdef UFFD_FEATURE_THREAD_ID
+    UFFD_CONST(UFFD_FEATURE_THREAD_ID);
+#endif
+#ifdef UFFD_FEATURE_MINOR_HUGETLBFS
+    UFFD_CONST(UFFD_FEATURE_MINOR_HUGETLBFS);
+#endif
+#ifdef UFFD_FEATURE_MINOR_SHMEM
+    UFFD_CONST(UFFD_FEATURE_MINOR_SHMEM);
+#endif
+#ifdef UFFD_FEATURE_EXACT_ADDRESS
+    UFFD_CONST(UFFD_FEATURE_EXACT_ADDRESS);
+#endif
+#ifdef UFFD_FEATURE_WP_HUGETLBFS_SHMEM
+    UFFD_CONST(UFFD_FEATURE_WP_HUGETLBFS_SHMEM);
+#endif
+#ifdef UFFD_FEATURE_WP_UNPOPULATED
+    UFFD_CONST(UFFD_FEATURE_WP_UNPOPULATED);
+#endif
+#ifdef UFFD_FEATURE_POISON
+    UFFD_CONST(UFFD_FEATURE_POISON);
+#endif
+#ifdef UFFD_FEATURE_WP_ASYNC
+    UFFD_CONST(UFFD_FEATURE_WP_ASYNC);
+#endif
+#ifdef UFFD_FEATURE_MOVE
+    UFFD_CONST(UFFD_FEATURE_MOVE);
+#endif
+#ifdef UFFDIO_REGISTER_MODE_MISSING
+    UFFD_CONST(UFFDIO_REGISTER_MODE_MISSING);
+#endif
+#ifdef UFFDIO_REGISTER_MODE_WP
+    UFFD_CONST(UFFDIO_REGISTER_MODE_WP);
+#endif
+#ifdef UFFDIO_REGISTER_MODE_MINOR
+    UFFD_CONST(UFFDIO_REGISTER_MODE_MINOR);
+#endif
+}

data/ext/userfaultfd/extconf.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+have_header("linux/userfaultfd.h")
+have_header("sys/ioctl.h")
+have_header("sys/syscall.h")
+have_func("syscall", "unistd.h")
+have_library("pthread")
+
+create_header
+create_makefile("userfaultfd/userfaultfd")