// SPDX-License-Identifier: GPL-2.0 // Copyright (C) 2025 Google LLC. //! Logic for closing files in a deferred manner. //! //! This file could make sense to have in `kernel::fs`, but it was rejected for being too //! Binder-specific. use core::mem::MaybeUninit; use kernel::{ alloc::{AllocError, Flags}, bindings, prelude::*, }; /// Helper used for closing file descriptors in a way that is safe even if the file is currently /// held using `fdget`. /// /// Additional motivation can be found in commit 80cd795630d6 ("binder: fix use-after-free due to /// ksys_close() during fdget()") and in the comments on `binder_do_fd_close`. pub(crate) struct DeferredFdCloser { inner: KBox, } /// SAFETY: This just holds an allocation with no real content, so there's no safety issue with /// moving it across threads. unsafe impl Send for DeferredFdCloser {} /// SAFETY: This just holds an allocation with no real content, so there's no safety issue with /// moving it across threads. unsafe impl Sync for DeferredFdCloser {} /// # Invariants /// /// If the `file` pointer is non-null, then it points at a `struct file` and owns a refcount to /// that file. #[repr(C)] struct DeferredFdCloserInner { twork: MaybeUninit, file: *mut bindings::file, } impl DeferredFdCloser { /// Create a new [`DeferredFdCloser`]. pub(crate) fn new(flags: Flags) -> Result { Ok(Self { // INVARIANT: The `file` pointer is null, so the type invariant does not apply. inner: KBox::new( DeferredFdCloserInner { twork: MaybeUninit::uninit(), file: core::ptr::null_mut(), }, flags, )?, }) } /// Schedule a task work that closes the file descriptor when this task returns to userspace. /// /// Fails if this is called from a context where we cannot run work when returning to /// userspace. (E.g., from a kthread.) pub(crate) fn close_fd(self, fd: u32) -> Result<(), DeferredFdCloseError> { use bindings::task_work_notify_mode_TWA_RESUME as TWA_RESUME; // In this method, we schedule the task work before closing the file. This is because // scheduling a task work is fallible, and we need to know whether it will fail before we // attempt to close the file. // Task works are not available on kthreads. let current = kernel::current!(); // Check if this is a kthread. // SAFETY: Reading `flags` from a task is always okay. if unsafe { ((*current.as_ptr()).flags & bindings::PF_KTHREAD) != 0 } { return Err(DeferredFdCloseError::TaskWorkUnavailable); } // Transfer ownership of the box's allocation to a raw pointer. This disables the // destructor, so we must manually convert it back to a KBox to drop it. // // Until we convert it back to a `KBox`, there are no aliasing requirements on this // pointer. let inner = KBox::into_raw(self.inner); // The `callback_head` field is first in the struct, so this cast correctly gives us a // pointer to the field. let callback_head = inner.cast::(); // SAFETY: This pointer offset operation does not go out-of-bounds. let file_field = unsafe { core::ptr::addr_of_mut!((*inner).file) }; let current = current.as_ptr(); // SAFETY: This function currently has exclusive access to the `DeferredFdCloserInner`, so // it is okay for us to perform unsynchronized writes to its `callback_head` field. unsafe { bindings::init_task_work(callback_head, Some(Self::do_close_fd)) }; // SAFETY: This inserts the `DeferredFdCloserInner` into the task workqueue for the current // task. If this operation is successful, then this transfers exclusive ownership of the // `callback_head` field to the C side until it calls `do_close_fd`, and we don't touch or // invalidate the field during that time. // // When the C side calls `do_close_fd`, the safety requirements of that method are // satisfied because when a task work is executed, the callback is given ownership of the // pointer. // // The file pointer is currently null. If it is changed to be non-null before `do_close_fd` // is called, then that change happens due to the write at the end of this function, and // that write has a safety comment that explains why the refcount can be dropped when // `do_close_fd` runs. let res = unsafe { bindings::task_work_add(current, callback_head, TWA_RESUME) }; if res != 0 { // SAFETY: Scheduling the task work failed, so we still have ownership of the box, so // we may destroy it. unsafe { drop(KBox::from_raw(inner)) }; return Err(DeferredFdCloseError::TaskWorkUnavailable); } // This removes the fd from the fd table in `current`. The file is not fully closed until // `filp_close` is called. We are given ownership of one refcount to the file. // // SAFETY: This is safe no matter what `fd` is. If the `fd` is valid (that is, if the // pointer is non-null), then we call `filp_close` on the returned pointer as required by // `file_close_fd`. let file = unsafe { bindings::file_close_fd(fd) }; if file.is_null() { // We don't clean up the task work since that might be expensive if the task work queue // is long. Just let it execute and let it clean up for itself. return Err(DeferredFdCloseError::BadFd); } // Acquire a second refcount to the file. // // SAFETY: The `file` pointer points at a file with a non-zero refcount. unsafe { bindings::get_file(file) }; // This method closes the fd, consuming one of our two refcounts. There could be active // light refcounts created from that fd, so we must ensure that the file has a positive // refcount for the duration of those active light refcounts. We do that by holding on to // the second refcount until the current task returns to userspace. // // SAFETY: The `file` pointer is valid. Passing `current->files` as the file table to close // it in is correct, since we just got the `fd` from `file_close_fd` which also uses // `current->files`. // // Note: fl_owner_t is currently a void pointer. unsafe { bindings::filp_close(file, (*current).files as bindings::fl_owner_t) }; // We update the file pointer that the task work is supposed to fput. This transfers // ownership of our last refcount. // // INVARIANT: This changes the `file` field of a `DeferredFdCloserInner` from null to // non-null. This doesn't break the type invariant for `DeferredFdCloserInner` because we // still own a refcount to the file, so we can pass ownership of that refcount to the // `DeferredFdCloserInner`. // // When `do_close_fd` runs, it must be safe for it to `fput` the refcount. However, this is // the case because all light refcounts that are associated with the fd we closed // previously must be dropped when `do_close_fd`, since light refcounts must be dropped // before returning to userspace. // // SAFETY: Task works are executed on the current thread right before we return to // userspace, so this write is guaranteed to happen before `do_close_fd` is called, which // means that a race is not possible here. unsafe { *file_field = file }; Ok(()) } /// # Safety /// /// The provided pointer must point at the `twork` field of a `DeferredFdCloserInner` stored in /// a `KBox`, and the caller must pass exclusive ownership of that `KBox`. Furthermore, if the /// file pointer is non-null, then it must be okay to release the refcount by calling `fput`. unsafe extern "C" fn do_close_fd(inner: *mut bindings::callback_head) { // SAFETY: The caller just passed us ownership of this box. let inner = unsafe { KBox::from_raw(inner.cast::()) }; if !inner.file.is_null() { // SAFETY: By the type invariants, we own a refcount to this file, and the caller // guarantees that dropping the refcount now is okay. unsafe { bindings::fput(inner.file) }; } // The allocation is freed when `inner` goes out of scope. } } /// Represents a failure to close an fd in a deferred manner. #[derive(Copy, Clone, Debug, Eq, PartialEq)] pub(crate) enum DeferredFdCloseError { /// Closing the fd failed because we were unable to schedule a task work. TaskWorkUnavailable, /// Closing the fd failed because the fd does not exist. BadFd, } impl From for Error { fn from(err: DeferredFdCloseError) -> Error { match err { DeferredFdCloseError::TaskWorkUnavailable => ESRCH, DeferredFdCloseError::BadFd => EBADF, } } }