Skip to main content

strat9_kernel/syscall/
fork.rs

1//! `fork()` syscall implementation with copy-on-write (COW).
2//!
3//! This module implements the `fork()` syscall, which creates a new child process by cloning the
4//! calling process. The child gets a copy of the parent's address space, but the actual physical
5//! memory is shared between parent and child until either of them writes to it, at which point
6//! the kernel transparently creates a private copy for the writing process (copy-on-write).
7//!
8//! The main entry point is `sys_fork`, which performs the necessary checks, clones the address space
9//! with COW semantics, and creates a new `Task` for the child process. The
10//! `handle_cow_fault` function is called from the page fault handler when a write fault occurs on a COW page, and it resolves the fault by either making the page writable (if the faulting process is the sole owner) or by copying the page to a new frame and updating the mapping.
11//!
12//! Source : https://man7.org/linux/man2/fork.2.html
13//!          https://man7.org/linux/man2/vfork.2.html
14//!          https://man7.org/linux/man2/clone.2.html
15//!
16//! TODO: implement `vfork()` and `clone()` with more fine-grained control over sharing.
17//!
18//! COW :
19//!   https://en.wikipedia.org/wiki/Copy-on-write
20//!   https://lwn.net/Articles/531114/
21//!   
22//!   
23//!   
24//!
25
26use crate::{
27    memory::{resolve_handle, AddressSpace, EffectiveMapping, VmaPageSize},
28    process::{
29        current_task_clone,
30        scheduler::add_task_with_parent,
31        signal::{SigActionData, SigStack, SignalSet},
32        task::{CpuContext, KernelStack, Pid, SyncUnsafeCell, Task},
33        TaskId, TaskState,
34    },
35    syscall::{error::SyscallError, SyscallFrame},
36};
37use alloc::{boxed::Box, sync::Arc};
38use core::{
39    mem::offset_of,
40    sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering},
41};
42use x86_64::structures::paging::mapper::TranslateResult;
43/// Result returned by [`sys_fork`].
44pub struct ForkResult {
45    pub child_pid: Pid,
46}
47
48/// Performs the local invlpg operation.
49#[inline]
50fn local_invlpg(vaddr: u64) {
51    // Local TLB invalidation is sufficient here: this kernel currently runs
52    // one task per user address space (no shared user CR3 across CPUs).
53    crate::arch::x86_64::tlb::local_page(x86_64::VirtAddr::new(vaddr));
54}
55
56#[repr(C)]
57#[derive(Clone, Copy)]
58struct ForkUserContext {
59    r15: u64,
60    r14: u64,
61    r13: u64,
62    r12: u64,
63    rbp: u64,
64    rbx: u64,
65    r11: u64,
66    r10: u64,
67    r9: u64,
68    r8: u64,
69    rsi: u64,
70    rdi: u64,
71    rdx: u64,
72    rcx: u64,
73    user_rip: u64,
74    user_cs: u64,
75    user_rflags: u64,
76    user_rsp: u64,
77    user_ss: u64,
78}
79
80const OFF_R15: usize = offset_of!(ForkUserContext, r15);
81const OFF_R14: usize = offset_of!(ForkUserContext, r14);
82const OFF_R13: usize = offset_of!(ForkUserContext, r13);
83const OFF_R12: usize = offset_of!(ForkUserContext, r12);
84const OFF_RBP: usize = offset_of!(ForkUserContext, rbp);
85const OFF_RBX: usize = offset_of!(ForkUserContext, rbx);
86const OFF_R11: usize = offset_of!(ForkUserContext, r11);
87const OFF_R10: usize = offset_of!(ForkUserContext, r10);
88const OFF_R9: usize = offset_of!(ForkUserContext, r9);
89const OFF_R8: usize = offset_of!(ForkUserContext, r8);
90const OFF_RSI: usize = offset_of!(ForkUserContext, rsi);
91const OFF_RDI: usize = offset_of!(ForkUserContext, rdi);
92const OFF_RDX: usize = offset_of!(ForkUserContext, rdx);
93const OFF_RCX: usize = offset_of!(ForkUserContext, rcx);
94const OFF_USER_RIP: usize = offset_of!(ForkUserContext, user_rip);
95const OFF_USER_CS: usize = offset_of!(ForkUserContext, user_cs);
96const OFF_USER_RFLAGS: usize = offset_of!(ForkUserContext, user_rflags);
97const OFF_USER_RSP: usize = offset_of!(ForkUserContext, user_rsp);
98const OFF_USER_SS: usize = offset_of!(ForkUserContext, user_ss);
99
100/// Child bootstrap: restore user register snapshot and enter Ring 3.
101extern "C" fn fork_child_start(ctx_ptr: u64) -> ! {
102    let boxed = unsafe { Box::from_raw(ctx_ptr as *mut ForkUserContext) };
103    let ctx = *boxed;
104    unsafe { fork_iret_from_ctx(&ctx as *const ForkUserContext) }
105}
106
107/// Performs the fork iret from ctx operation.
108#[unsafe(naked)]
109unsafe extern "C" fn fork_iret_from_ctx(_ctx: *const ForkUserContext) -> ! {
110    core::arch::naked_asm!(
111        // Mask IRQs before touching GS. The user RFLAGS frame re-enables IF.
112        "cli",
113        "mov rsi, rdi",
114
115        // ===== Build IRET frame FIRST, using r8 as scratch ===========
116        // (r8 has not been restored yet, so we can clobber it safely)
117        "mov r8, [rsi + {off_user_ss}]",
118        "push r8",                            // SS
119        "mov r8, [rsi + {off_user_rsp}]",
120        "push r8",                            // user RSP
121        "mov r8, [rsi + {off_user_rflags}]",
122        "push r8",                            // user RFLAGS
123        "mov r8, [rsi + {off_user_cs}]",
124        "push r8",                            // CS
125        "mov r8, [rsi + {off_user_rip}]",
126        "push r8",                            // user RIP
127
128        // ===== Now restore ALL general-purpose registers============
129        "mov r15, [rsi + {off_r15}]",
130        "mov r14, [rsi + {off_r14}]",
131        "mov r13, [rsi + {off_r13}]",
132        "mov r12, [rsi + {off_r12}]",
133        "mov rbp, [rsi + {off_rbp}]",
134        "mov rbx, [rsi + {off_rbx}]",
135        "mov r11, [rsi + {off_r11}]",
136        "mov r10, [rsi + {off_r10}]",
137        "mov r9,  [rsi + {off_r9}]",
138        "mov r8,  [rsi + {off_r8}]",          // r8 now gets its correct value
139        "mov rdx, [rsi + {off_rdx}]",
140        "mov rcx, [rsi + {off_rcx}]",
141        "mov rdi, [rsi + {off_rdi}]",
142        "mov rax, 0",                         // child fork() returns 0
143        "mov rsi, [rsi + {off_rsi}]",         // rsi restored last
144        "swapgs",
145        "iretq",
146        off_r15 = const OFF_R15,
147        off_r14 = const OFF_R14,
148        off_r13 = const OFF_R13,
149        off_r12 = const OFF_R12,
150        off_rbp = const OFF_RBP,
151        off_rbx = const OFF_RBX,
152        off_r11 = const OFF_R11,
153        off_r10 = const OFF_R10,
154        off_r9 = const OFF_R9,
155        off_r8 = const OFF_R8,
156        off_rsi = const OFF_RSI,
157        off_rdi = const OFF_RDI,
158        off_rdx = const OFF_RDX,
159        off_rcx = const OFF_RCX,
160        off_user_rip = const OFF_USER_RIP,
161        off_user_cs = const OFF_USER_CS,
162        off_user_rflags = const OFF_USER_RFLAGS,
163        off_user_rsp = const OFF_USER_RSP,
164        off_user_ss = const OFF_USER_SS,
165    );
166}
167
168/// Performs the build child task operation.
169fn build_child_task(
170    parent: &Arc<Task>,
171    child_as: Arc<AddressSpace>,
172    bootstrap_ctx: Box<ForkUserContext>,
173) -> Result<Arc<Task>, SyscallError> {
174    let kernel_stack =
175        KernelStack::allocate(Task::DEFAULT_STACK_SIZE).map_err(|_| SyscallError::OutOfMemory)?;
176    let context = CpuContext::new(fork_child_start as *const () as u64, &kernel_stack);
177
178    let parent_caps = unsafe { (&*parent.process.capabilities.get()).clone() };
179    let parent_fd = unsafe { (&*parent.process.fd_table.get()).clone_for_fork() };
180    let parent_blocked = parent.blocked_signals.clone();
181    let parent_actions: [SigActionData; 64] = unsafe { *parent.process.signal_actions.get() };
182    let parent_sigstack: Option<SigStack> = unsafe { *parent.signal_stack.get() };
183    let interrupt_frame = crate::syscall::SyscallFrame {
184        r15: bootstrap_ctx.r15,
185        r14: bootstrap_ctx.r14,
186        r13: bootstrap_ctx.r13,
187        r12: bootstrap_ctx.r12,
188        rbp: bootstrap_ctx.rbp,
189        rbx: bootstrap_ctx.rbx,
190        r11: bootstrap_ctx.r11,
191        r10: bootstrap_ctx.r10,
192        r9: bootstrap_ctx.r9,
193        r8: bootstrap_ctx.r8,
194        rsi: bootstrap_ctx.rsi,
195        rdi: bootstrap_ctx.rdi,
196        rdx: bootstrap_ctx.rdx,
197        rcx: bootstrap_ctx.rcx,
198        rax: 0,
199        iret_rip: bootstrap_ctx.user_rip,
200        iret_cs: bootstrap_ctx.user_cs,
201        iret_rflags: bootstrap_ctx.user_rflags,
202        iret_rsp: bootstrap_ctx.user_rsp,
203        iret_ss: bootstrap_ctx.user_ss,
204    };
205
206    let (pid, tid, tgid) = Task::allocate_process_ids();
207    child_as.set_owner_pid(pid);
208    let task = Arc::new(Task {
209        id: TaskId::new(),
210        pid,
211        tid,
212        tgid,
213        pgid: AtomicU32::new(parent.pgid.load(Ordering::Relaxed)),
214        sid: AtomicU32::new(parent.sid.load(Ordering::Relaxed)),
215        uid: AtomicU32::new(parent.uid.load(Ordering::Relaxed)),
216        euid: AtomicU32::new(parent.euid.load(Ordering::Relaxed)),
217        gid: AtomicU32::new(parent.gid.load(Ordering::Relaxed)),
218        egid: AtomicU32::new(parent.egid.load(Ordering::Relaxed)),
219        state: core::sync::atomic::AtomicU8::new(TaskState::Ready as u8),
220        priority: parent.priority,
221        context: SyncUnsafeCell::new(context),
222        resume_kind: SyncUnsafeCell::new(crate::process::task::ResumeKind::RetFrame),
223        interrupt_rsp: AtomicU64::new(0),
224        kernel_stack,
225        user_stack: None,
226
227        name: "fork-child",
228        process: alloc::sync::Arc::new(crate::process::process::Process {
229            pid,
230            address_space: crate::process::task::SyncUnsafeCell::new(child_as),
231            address_space_lock: crate::sync::SpinLock::new(()),
232            fd_table: crate::process::task::SyncUnsafeCell::new(parent_fd),
233            capabilities: crate::process::task::SyncUnsafeCell::new(parent_caps),
234            signal_actions: crate::process::task::SyncUnsafeCell::new(parent_actions),
235            brk: core::sync::atomic::AtomicU64::new(
236                parent
237                    .process
238                    .brk
239                    .load(core::sync::atomic::Ordering::Relaxed),
240            ),
241            mmap_hint: core::sync::atomic::AtomicU64::new(
242                parent
243                    .process
244                    .mmap_hint
245                    .load(core::sync::atomic::Ordering::Relaxed),
246            ),
247            cwd: crate::process::task::SyncUnsafeCell::new(
248                unsafe { &*parent.process.cwd.get() }.clone(),
249            ),
250            // POSIX: cwd_fd IS inherited (capability to the CWD directory).
251            cwd_fd: core::sync::atomic::AtomicU64::new(
252                parent
253                    .process
254                    .cwd_fd
255                    .load(core::sync::atomic::Ordering::Relaxed),
256            ),
257            umask: core::sync::atomic::AtomicU32::new(
258                parent
259                    .process
260                    .umask
261                    .load(core::sync::atomic::Ordering::Relaxed),
262            ),
263        }),
264        // POSIX: pending signals are NOT inherited by the child.
265        pending_signals: SignalSet::new(),
266        // POSIX: signal mask IS inherited.
267        blocked_signals: parent_blocked,
268        irq_signal_delivery_blocked: AtomicBool::new(false),
269        signal_stack: SyncUnsafeCell::new(parent_sigstack),
270        itimers: crate::process::timer::ITimers::new(),
271        wake_pending: AtomicBool::new(false),
272        wake_deadline_ns: AtomicU64::new(0),
273        trampoline_entry: AtomicU64::new(0),
274        trampoline_stack_top: AtomicU64::new(0),
275        trampoline_arg0: AtomicU64::new(0),
276        ticks: AtomicU64::new(0),
277        sched_policy: SyncUnsafeCell::new(parent.sched_policy()),
278        home_cpu: AtomicUsize::new(usize::MAX),
279        vruntime: AtomicU64::new(parent.vruntime()),
280        fair_rq_generation: AtomicU64::new(0),
281        fair_on_rq: AtomicBool::new(false),
282        // POSIX: clear_child_tid is NOT inherited : child starts with 0.
283        clear_child_tid: AtomicU64::new(0),
284        robust_list_head: AtomicU64::new(0),
285        robust_list_len: AtomicUsize::new(0),
286        // POSIX: cwd IS inherited.
287        // POSIX: umask IS inherited.
288        // FS.base: child starts with 0 (its own TLS not yet set up).
289        user_fs_base: AtomicU64::new(0),
290        fpu_state: {
291            let parent_fpu = unsafe { &*parent.fpu_state.get() };
292            let mut child_fpu = crate::process::task::ExtendedState::new();
293            child_fpu.copy_from(parent_fpu);
294            SyncUnsafeCell::new(child_fpu)
295        },
296        xcr0_mask: AtomicU64::new(parent.xcr0_mask.load(core::sync::atomic::Ordering::Relaxed)),
297        rt_link: intrusive_collections::LinkedListLink::new(),
298    });
299
300    // CpuContext initial stack layout: r15, r14, r13(arg), r12(entry), rbp, rbx, ret
301    unsafe {
302        let ctx = &mut *task.context.get();
303        let frame = ctx.saved_rsp as *mut u64;
304        *frame.add(2) = Box::into_raw(bootstrap_ctx) as u64;
305    }
306
307    task.seed_interrupt_frame(interrupt_frame);
308
309    Ok(task)
310}
311
312/// SYS_PROC_FORK (302): fork with copy-on-write address-space cloning.
313pub fn sys_fork(frame: &SyscallFrame) -> Result<ForkResult, SyscallError> {
314    let parent = current_task_clone().ok_or(SyscallError::PermissionDenied)?;
315
316    // 1. Sanity check: cannot fork a kernel thread.
317    if parent.is_kernel() {
318        log::warn!("fork: attempt to fork kernel thread '{}'", parent.name);
319        return Err(SyscallError::PermissionDenied);
320    }
321
322    // 2. Capability check: check if task is restricted from forking.
323    // For now, we allow fork for all user processes unless restricted.
324    // TODO: implement ResourceType::Process/Task restricted capabilities.
325
326    let parent_as = parent.process.address_space_arc();
327
328    // 3. Memory check: ensure parent has actual user-space mappings.
329    if !parent_as.has_user_mappings() {
330        log::warn!(
331            "fork: attempt to fork task '{}' with no user mappings",
332            parent.name
333        );
334        return Err(SyscallError::InvalidArgument);
335    }
336
337    let child_as = parent_as
338        .clone_cow()
339        .map_err(|_| SyscallError::OutOfMemory)?;
340
341    let child_user_ctx = Box::new(ForkUserContext {
342        r15: frame.r15,
343        r14: frame.r14,
344        r13: frame.r13,
345        r12: frame.r12,
346        rbp: frame.rbp,
347        rbx: frame.rbx,
348        r11: frame.r11,
349        r10: frame.r10,
350        r9: frame.r9,
351        r8: frame.r8,
352        rsi: frame.rsi,
353        rdi: frame.rdi,
354        rdx: frame.rdx,
355        rcx: frame.rcx,
356        user_rip: frame.iret_rip,
357        user_cs: frame.iret_cs,
358        user_rflags: frame.iret_rflags,
359        user_rsp: frame.iret_rsp,
360        user_ss: frame.iret_ss,
361    });
362
363    let child_task = build_child_task(&parent, child_as, child_user_ctx)?;
364    let child_pid = child_task.pid;
365    add_task_with_parent(child_task, parent.id);
366
367    Ok(ForkResult { child_pid })
368}
369
370/// Called from the page fault handler when a write fault occurs on a present page.
371/// Returns Ok(()) if the fault was successfully handled (COW resolution),
372/// or Err if it wasn't a COW fault (real access violation).
373pub fn handle_cow_fault(virt_addr: u64, address_space: &AddressSpace) -> Result<(), &'static str> {
374    use crate::memory::paging::BuddyFrameAllocator;
375    use x86_64::{
376        structures::paging::{Mapper, Page, PageTableFlags, Size2MiB, Size4KiB, Translate},
377        VirtAddr,
378    };
379
380    let mapping = address_space
381        .effective_mapping_containing(virt_addr)
382        .ok_or("Page not mapped")?;
383    let page_start = mapping.start;
384    let page = Page::<Size4KiB>::containing_address(VirtAddr::new(page_start));
385
386    // SAFETY: we are in an exception handler, address space is active.
387    let mut mapper = unsafe { address_space.mapper() };
388
389    // Check if page is mapped and has COW flag.
390    let (phys_frame_addr, flags) = match mapper.translate(VirtAddr::new(page_start)) {
391        TranslateResult::Mapped {
392            frame,
393            offset: _,
394            flags,
395        } => (frame.start_address(), flags),
396        _ => return Err("Page not mapped"),
397    };
398
399    // We use BIT_9 as software COW flag
400    const COW_BIT: PageTableFlags = PageTableFlags::BIT_9;
401
402    if !flags.contains(COW_BIT) {
403        return Err("Not a COW page");
404    }
405
406    let old_handle = mapping.handle;
407    let refcount = crate::memory::cow::handle_get_refcount(old_handle);
408
409    if refcount == 1 {
410        // Case 1: we are the sole owner. Just make it writable.
411        let new_flags = (flags | PageTableFlags::WRITABLE) & !COW_BIT;
412
413        unsafe {
414            match mapping.page_size {
415                VmaPageSize::Small => mapper
416                    .update_flags(page, new_flags)
417                    .map_err(|_| "Failed to update 4K flags")?
418                    .flush(),
419                VmaPageSize::Huge => mapper
420                    .update_flags(
421                        Page::<Size2MiB>::containing_address(VirtAddr::new(page_start)),
422                        new_flags | PageTableFlags::HUGE_PAGE,
423                    )
424                    .map_err(|_| "Failed to update 2M flags")?
425                    .flush(),
426            }
427        }
428        let tracked_flags = match mapping.page_size {
429            VmaPageSize::Small => new_flags,
430            VmaPageSize::Huge => new_flags | PageTableFlags::HUGE_PAGE,
431        };
432        let _ = address_space.update_effective_mapping_flags(page_start, tracked_flags);
433        // Only the current CPU can hold this CR3 in the current design.
434        local_invlpg(virt_addr);
435        return Ok(());
436    }
437
438    // Case 2: shared page. Copy to new frame.
439    let mut frame_allocator = BuddyFrameAllocator;
440    let order = match mapping.page_size {
441        VmaPageSize::Small => 0,
442        VmaPageSize::Huge => 9,
443    };
444    let copy_bytes = mapping.page_size.bytes() as usize;
445    let new_frame = crate::sync::with_irqs_disabled(|token| {
446        if order == 0 {
447            crate::memory::allocate_frame(token)
448        } else {
449            crate::memory::allocate_phys_contiguous(token, order)
450        }
451    })
452    .map_err(|_| "OOM during COW copy")?;
453
454    // Copy content
455    unsafe {
456        let src = crate::memory::phys_to_virt(phys_frame_addr.as_u64()) as *const u8;
457        let dst = crate::memory::phys_to_virt(new_frame.start_address.as_u64()) as *mut u8;
458        core::ptr::copy_nonoverlapping(src, dst, copy_bytes);
459    }
460
461    // Update mapping to new frame, Writable, no COW
462    let new_flags = (flags | PageTableFlags::WRITABLE) & !COW_BIT;
463    let tracked_flags = match mapping.page_size {
464        VmaPageSize::Small => new_flags,
465        VmaPageSize::Huge => new_flags | PageTableFlags::HUGE_PAGE,
466    };
467    let new_handle = resolve_handle(new_frame.start_address);
468
469    // Replace existing mapping (present+COW) by the private writable mapping.
470    let remap_res: Result<(), &'static str> = match mapping.page_size {
471        VmaPageSize::Small => {
472            let old_unmapped = mapper
473                .unmap(page)
474                .map_err(|_| "Failed to unmap old 4K COW frame")?
475                .0;
476            debug_assert_eq!(old_unmapped.start_address(), phys_frame_addr);
477            unsafe {
478                mapper.map_to(
479                    page,
480                    x86_64::structures::paging::PhysFrame::<Size4KiB>::containing_address(
481                        new_frame.start_address,
482                    ),
483                    new_flags,
484                    &mut frame_allocator,
485                )
486            }
487            .map(|flush| flush.flush())
488            .map_err(|_| "Failed to map new 4K COW frame")
489        }
490        VmaPageSize::Huge => {
491            let huge_page = Page::<Size2MiB>::containing_address(VirtAddr::new(page_start));
492            let old_unmapped = mapper
493                .unmap(huge_page)
494                .map_err(|_| "Failed to unmap old 2M COW frame")?
495                .0;
496            debug_assert_eq!(old_unmapped.start_address(), phys_frame_addr);
497            unsafe {
498                mapper.map_to(
499                    huge_page,
500                    x86_64::structures::paging::PhysFrame::<Size2MiB>::containing_address(
501                        new_frame.start_address,
502                    ),
503                    tracked_flags,
504                    &mut frame_allocator,
505                )
506            }
507            .map(|flush| flush.flush())
508            .map_err(|_| "Failed to map new 2M COW frame")
509        }
510    };
511    if remap_res.is_err() {
512        match mapping.page_size {
513            VmaPageSize::Small => unsafe {
514                let _ = mapper.map_to(
515                    page,
516                    x86_64::structures::paging::PhysFrame::<Size4KiB>::containing_address(
517                        phys_frame_addr,
518                    ),
519                    flags,
520                    &mut frame_allocator,
521                );
522            },
523            VmaPageSize::Huge => unsafe {
524                let huge_page = Page::<Size2MiB>::containing_address(VirtAddr::new(page_start));
525                let _ = mapper.map_to(
526                    huge_page,
527                    x86_64::structures::paging::PhysFrame::<Size2MiB>::containing_address(
528                        phys_frame_addr,
529                    ),
530                    flags,
531                    &mut frame_allocator,
532                );
533            },
534        }
535        crate::sync::with_irqs_disabled(|token| {
536            if order == 0 {
537                crate::memory::free_frame(token, new_frame);
538            } else {
539                crate::memory::free_phys_contiguous(token, new_frame, order);
540            }
541        });
542        return Err(remap_res.err().unwrap_or("Failed to map new COW frame"));
543    }
544
545    // The new private frame is the sole owner; set refcount=1 directly.
546    // BuddyFrameAllocator returns a raw frame (refcount still REFCOUNT_UNUSED).
547    // frame_inc_ref would wrap REFCOUNT_UNUSED to 0 : use set_refcount instead.
548    crate::memory::cow::handle_init_ref(new_handle);
549
550    if address_space
551        .register_effective_mapping(EffectiveMapping {
552            start: page_start,
553            cap_id: mapping.cap_id,
554            handle: new_handle,
555            flags: tracked_flags,
556            page_size: mapping.page_size,
557        })
558        .is_err()
559    {
560        match mapping.page_size {
561            VmaPageSize::Small => {
562                let _ = mapper.unmap(page);
563                let _ = unsafe {
564                    mapper.map_to(
565                        page,
566                        x86_64::structures::paging::PhysFrame::<Size4KiB>::containing_address(
567                            phys_frame_addr,
568                        ),
569                        flags,
570                        &mut frame_allocator,
571                    )
572                }
573                .map(|flush| flush.flush());
574            }
575            VmaPageSize::Huge => {
576                let huge_page = Page::<Size2MiB>::containing_address(VirtAddr::new(page_start));
577                let _ = mapper.unmap(huge_page);
578                let _ = unsafe {
579                    mapper.map_to(
580                        huge_page,
581                        x86_64::structures::paging::PhysFrame::<Size2MiB>::containing_address(
582                            phys_frame_addr,
583                        ),
584                        flags,
585                        &mut frame_allocator,
586                    )
587                }
588                .map(|flush| flush.flush());
589            }
590        }
591        crate::sync::with_irqs_disabled(|token| {
592            if order == 0 {
593                crate::memory::free_frame(token, new_frame);
594            } else {
595                crate::memory::free_phys_contiguous(token, new_frame, order);
596            }
597        });
598        return Err("Failed to track new COW mapping");
599    }
600
601    // Only the current CPU can hold this CR3 in the current design.
602    local_invlpg(virt_addr);
603
604    // Replacing the effective mapping at the same address already unregisters
605    // the previous mapping identity for old_handle. There is no transient pin
606    // to drop in this path.
607
608    Ok(())
609}