Various Rust bindings for files
Subsystems (4)
Alice Ryhl
maintainercover Various Rust bindings for files
This contains bindings for various file related things that binder needs to use.
I would especially like feedback on the SAFETY comments. Particularly, the safety comments in patch 4 and 5 are non-trivial. For example:
* In patch 4, I claim that passing POLLHUP|POLLFREE to __wake_up is enough to ensure that we can now destroy the wait_list without risking any use-after-frees, even if we have registered it with epoll. Is that correct?
* In patch 5, I implement a utility for closing fds that might be held using fdget. This is rather non-trivial, and I would be happy to hear suggestions about alternate solutions.
This patch is based on top of
https://lore.kernel.org/all/[email protected]/
which is currently the top commit on rust-next.
Alice Ryhl (2):
rust: file: add bindings for poll_table
rust: file: add DeferredFdCloser
Wedson Almeida Filho (3):
rust: file: add bindings for struct file
rust: cred: add Rust bindings for struct cred
rust: file: add FileDescriptorReservation
rust/bindings/bindings_helper.h | 8 + rust/bindings/lib.rs | 1 + rust/helpers.c | 36 ++++ rust/kernel/cred.rs | 66 +++++++ rust/kernel/file.rs | 331 ++++++++++++++++++++++++++++++++ rust/kernel/file/poll_table.rs | 93 +++++++++ rust/kernel/lib.rs | 2 + rust/kernel/sync/condvar.rs | 2 +- 8 files changed, 538 insertions(+), 1 deletion(-) create mode 100644 rust/kernel/cred.rs create mode 100644 rust/kernel/file.rs create mode 100644 rust/kernel/file/poll_table.rs
base-commit: 341faf2b45ba266d52c1ca886c4ffca52d666786
Signature · 1 line
2.41.0.255.g8b1d071c50-goog
Alice Ryhl
maintainerRFC PATCH 1/5 rust: file: add bindings for `struct file`
From: Wedson Almeida Filho <[email protected]>
Using these bindings it becomes possible to access files from drivers written in Rust. This patch only adds support for accessing the flags, and for managing the refcount of the file.
---
In this patch, I am defining an error type called BadFdError. I'd like your thoughts on doing it this way vs just using the normal Error type.
Pros:
* The type system makes it clear that the function can only fail with EBADF, and that no other errors are possible.
* Since the compiler knows that ARef<Self> cannot be null and that BadFdError has only one possible value, the return type of File::from_fd is represented as a pointer with null being an error.
Cons:
* Defining additional error types involves boilerplate.
* The return type becomes a tagged union, making it larger than a pointer.
* The question mark operator will only utilize the From trait once, which prevents you from using the question mark operator on BadFdError in methods that return some third error type that the kernel Error is convertible into.
rust/bindings/bindings_helper.h | 2 + rust/helpers.c | 7 ++ rust/kernel/file.rs | 176 ++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 1 + 4 files changed, 186 insertions(+) create mode 100644 rust/kernel/file.rs
rust/kernel/file.rs new file +176 -0
@@ -0,0 +1,176 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Files and file descriptors. +//! +//! C headers: [`include/linux/fs.h`](../../../../include/linux/fs.h) and +//! [`include/linux/file.h`](../../../../include/linux/file.h) + +use crate ::{ + bindings, + error::{code::*,Error ,Result }, + types::{ARef ,AlwaysRefCounted ,Opaque }, +}; +use core::ptr; + +/// Flags associated with a [`File`]. +pub mod flags { +/// File is opened in append mode. +pub const O_APPEND :u32 = bindings::O_APPEND ; + +/// Signal-driven I/O is enabled. +pub const O_ASYNC :u32 = bindings::FASYNC ; + +/// Close-on-exec flag is set. +pub const O_CLOEXEC :u32 = bindings::O_CLOEXEC ; + +/// File was created if it didn't already exist. +pub const O_CREAT :u32 = bindings::O_CREAT ; + +/// Direct I/O is enabled for this file. +pub const O_DIRECT :u32 = bindings::O_DIRECT ; + +/// File must be a directory. +pub const O_DIRECTORY :u32 = bindings::O_DIRECTORY ; + +/// Like [`O_SYNC`] except metadata is not synced. +pub const O_DSYNC :u32 = bindings::O_DSYNC ; + +/// Ensure that this file is created with the `open(2)` call. +pub const O_EXCL :u32 = bindings::O_EXCL ; + +/// Large file size enabled (`off64_t` over `off_t`). +pub const O_LARGEFILE :u32 = bindings::O_LARGEFILE ; + +/// Do not update the file last access time. +pub const O_NOATIME :u32 = bindings::O_NOATIME ; + +/// File should not be used as process's controlling terminal. +pub const O_NOCTTY :u32 = bindings::O_NOCTTY ; + +/// If basename of path is a symbolic link, fail open. +pub const O_NOFOLLOW :u32 = bindings::O_NOFOLLOW ; + +/// File is using nonblocking I/O. +pub const O_NONBLOCK :u32 = bindings::O_NONBLOCK ; + +/// Also known as `O_NDELAY`. +/// +/// This is effectively the same flag as [`O_NONBLOCK`] on all architectures +/// except SPARC64. +pub const O_NDELAY :u32 = bindings::O_NDELAY ; + +/// Used to obtain a path file descriptor. +pub const O_PATH :u32 = bindings::O_PATH ; + +/// Write operations on this file will flush data and metadata. +pub const O_SYNC :u32 = bindings::O_SYNC ; + +/// This file is an unnamed temporary regular file. +pub const O_TMPFILE :u32 = bindings::O_TMPFILE ; + +/// File should be truncated to length 0. +pub const O_TRUNC :u32 = bindings::O_TRUNC ; + +/// Bitmask for access mode flags. +/// +/// # Examples +/// +/// ``` +/// use kernel::file; +/// # fn do_something() {} +/// # let flags = 0; +/// if (flags & file::flags::O_ACCMODE) == file::flags::O_RDONLY { +/// do_something(); +/// } +/// ``` +pub const O_ACCMODE :u32 = bindings::O_ACCMODE ; + +/// File is read only. +pub const O_RDONLY :u32 = bindings::O_RDONLY ; + +/// File is write only. +pub const O_WRONLY :u32 = bindings::O_WRONLY ; + +/// File can be both read and written. +pub const O_RDWR :u32 = bindings::O_RDWR ; +} + +/// Wraps the kernel's `struct file`. +/// +/// # Invariants +/// +/// Instances of this type are always ref-counted, that is, a call to `get_file` ensures that the +/// allocation remains valid at least until the matching call to `fput`. +#[repr(transparent)] +pub struct File (Opaque <bindings::file >); + +// SAFETY: By design, the only way to access a `File` is via an immutable reference or an `ARef`. +// This means that the only situation in which a `File` can be accessed mutably is when the +// refcount drops to zero and the destructor runs. It is safe for that to happen on any thread, so +// it is ok for this type to be `Send`. +unsafe impl Send for File {} + +// SAFETY: It's OK to access `File` through shared references from other threads because we're +// either accessing properties that don't change or that are properly synchronised by C code. +unsafe impl Sync for File {} + +impl File { +/// Constructs a new `struct file` wrapper from a file descriptor. +/// +/// The file descriptor belongs to the current process. +pub fn from_fd (fd:u32 ) ->Result <ARef <Self >,BadFdError > { +// SAFETY: FFI call, there are no requirements on `fd`. +let ptr = ptr::NonNull ::new (unsafe { bindings::fget (fd) }).ok_or (BadFdError )?; + +// SAFETY: `fget` increments the refcount before returning. +Ok (unsafe {ARef ::from_raw (ptr.cast ()) }) + } + +/// Creates a reference to a [`File`] from a valid pointer. +/// +/// # Safety +/// +/// The caller must ensure that `ptr` points at a valid file and that its refcount does not +/// reach zero until after the end of the lifetime 'a. +pub unsafe fn from_ptr <'a>(ptr: *const bindings::file ) -> &'aFile { +// SAFETY: The safety requirements guarantee the validity of the dereference, while the +// `File` type being transparent makes the cast ok. +unsafe { &*ptr.cast () } + } + +/// Returns the flags associated with the file. +/// +/// The flags are a combination of the constants in [`flags`]. +pub fn flags (&self) ->u32 { +// SAFETY: The file is valid because the shared reference guarantees a nonzero refcount. +// +// This uses a volatile read because C code may be modifying this field in parallel using +// non-atomic unsynchronized writes. This corresponds to how the C macro READ_ONCE is +// implemented. +unsafe { core::ptr::addr_of!((*self.0 .get ()).f_flags).read_volatile () } + } +} + +// SAFETY: The type invariants guarantee that `File` is always ref-counted. +unsafe impl AlwaysRefCounted for File { +fn inc_ref (&self) { +// SAFETY: The existence of a shared reference means that the refcount is nonzero. +unsafe { bindings::get_file (self.0 .get ()) }; + } + +unsafe fn dec_ref (obj: ptr::NonNull <Self >) { +// SAFETY: The safety requirements guarantee that the refcount is nonzero. +unsafe { bindings::fput (obj.cast ().as_ptr ()) } + } +} + +/// Represents the EBADF error code. +/// +/// Used for methods that can only fail with EBADF. +pub struct BadFdError ; + +impl From <BadFdError >for Error { +fn from (_:BadFdError ) ->Error { +EBADF + } +}
rust/kernel/lib.rs +1 -0
@@ -32,6 +32,7 @@mod allocator;mod build_assert;pub mod error; +pub mod file;pub mod init;pub mod ioctl;pub mod prelude;
rust/bindings/bindings_helper.h +2 -0
@@ -7,6 +7,8 @@*/ #include <linux/errname.h> +#include <linux/file.h> +#include <linux/fs.h> #include <linux/slab.h> #include <linux/refcount.h> #include <linux/wait.h>
rust/helpers.c +7 -0
@@ -24,6 +24,7 @@#include <linux/build_bug.h> #include <linux/err.h> #include <linux/errname.h> +#include <linux/fs.h> #include <linux/mutex.h> #include <linux/refcount.h> #include <linux/sched/signal.h>
@@ -137,6 +138,12 @@ void rust_helper_put_task_struct(struct task_struct *t) }EXPORT_SYMBOL_GPL (rust_helper_put_task_struct); +struct file *rust_helper_get_file (struct file *f) +{ +return get_file (f); +} +EXPORT_SYMBOL_GPL (rust_helper_get_file); +/* * We use `bindgen`'s `--size_t-is-usize` option to bind the C `size_t` type * as the Rust `usize` type, so we can use it in contexts where Rust
Signature · 1 line
2.41.0.255.g8b1d071c50-goog
Re: [RFC PATCH v1 1/5] rust: file: add bindings for `struct file`
Quoted 23 lines · Alice Ryhl
From: Wedson Almeida Filho <[email protected]>
Using these bindings it becomes possible to access files from drivers written in Rust. This patch only adds support for accessing the flags, and for managing the refcount of the file.
Signed-off-by Wedson Almeida Filho <[email protected]>Co-Developed-by Daniel Xu <[email protected]>Signed-off-by Daniel Xu <[email protected]>Co-Developed-by Alice Ryhl <[email protected]>Signed-off-by Alice Ryhl <[email protected]>---
In this patch, I am defining an error type calledBadFdError. I'd like your thoughts on doing it this way vs just using the normalErrortype.Pros:
* The type system makes it clear that the function can only fail with EBADF, and that no other errors are possible.
* Since the compiler knows thatARef<Self>cannot be null and thatBadFdErrorhas only one possible value, the return type ofFile::from_fdis represented as a pointer with null being an error.
Quoted 4 lines
Cons:
* Defining additional error types involves boilerplate.
* The return type becomes a tagged union, making it larger than a pointer.
These two are kinda passable, as a impl_null_ptr_err macro can be opted to implement error types from nulls. Also if we consider that File::from_fd isn't going to be called a gorillion times a second or a recursive call is done, then I'd say that the tagged union won't bring any other problems, except that a compiler optim is skipped.
Quoted 4 lines
* The question mark operator will only utilize the
Fromtrait once, which prevents you from using the question mark operator onBadFdErrorin methods that return some third error type that the kernelErroris convertible into.
Although, I want this to be mentioned in the doc of BadFdError as this cannot be overlooked when said usage of ? is done.
rust/helpers.c
Quoted 13 lines
rust/bindings/bindings_helper.h | 2 + rust/helpers.c | 7 ++ rust/kernel/file.rs | 176 ++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 1 + 4 files changed, 186 insertions(+)create mode 100644
rust/kernel/file.rs[...]
rust/bindings/bindings_helper.h +0
-0rust/helpers.c +0
-0
This one is making my head spin, shouldn't they go first?
Alice Ryhl
maintainerRFC PATCH 2/5 rust: cred: add Rust bindings for `struct cred`
In reply to Alice RyhlFrom: Wedson Almeida Filho <[email protected]>
Make it possible to access credentials from Rust drivers. In particular, this patch makes it possible to get the id for the security context of a given file.
--- rust/bindings/bindings_helper.h | 2 + rust/helpers.c | 22 +++++++++++ rust/kernel/cred.rs | 66 +++++++++++++++++++++++++++++++++ rust/kernel/file.rs | 15 ++++++++ rust/kernel/lib.rs | 1 + 5 files changed, 106 insertions(+) create mode 100644 rust/kernel/cred.rs
rust/kernel/cred.rs new file +66 -0
@@ -0,0 +1,66 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Credentials management. +//! +//! C header: [`include/linux/cred.h`](../../../../include/linux/cred.h) +//! +//! Reference: <https://www.kernel.org/doc/html/latest/security/credentials.html> + +use crate ::{ + bindings, + types::{AlwaysRefCounted ,Opaque }, +}; + +/// Wraps the kernel's `struct cred`. +/// +/// # Invariants +/// +/// Instances of this type are always ref-counted, that is, a call to `get_cred` ensures that the +/// allocation remains valid at least until the matching call to `put_cred`. +#[repr(transparent)] +pub struct Credential (pub (crate )Opaque <bindings::cred >); + +// SAFETY: By design, the only way to access a `Credential` is via an immutable reference or an +// `ARef`. This means that the only situation in which a `Credential` can be accessed mutably is +// when the refcount drops to zero and the destructor runs. It is safe for that to happen on any +// thread, so it is ok for this type to be `Send`. +unsafe impl Send for Credential {} + +// SAFETY: It's OK to access `Credential` through shared references from other threads because +// we're either accessing properties that don't change or that are properly synchronised by C code. +unsafe impl Sync for Credential {} + +impl Credential { +/// Creates a reference to a [`Credential`] from a valid pointer. +/// +/// # Safety +/// +/// The caller must ensure that `ptr` is valid and remains valid for the lifetime of the +/// returned [`Credential`] reference. +pub unsafe fn from_ptr <'a>(ptr: *const bindings::cred ) -> &'aCredential { +// SAFETY: The safety requirements guarantee the validity of the dereference, while the +// `Credential` type being transparent makes the cast ok. +unsafe { &*ptr.cast () } + } + +/// Get the id for this security context. +pub fn get_secid (&self) ->u32 { +let mut secid =0 ; +// SAFETY: The invariants of this type ensures that the pointer is valid. +unsafe { bindings::security_cred_getsecid (self.0 .get (), &mut secid) }; + secid + } +} + +// SAFETY: The type invariants guarantee that `Credential` is always ref-counted. +unsafe impl AlwaysRefCounted for Credential { +fn inc_ref (&self) { +// SAFETY: The existence of a shared reference means that the refcount is nonzero. +unsafe { bindings::get_cred (self.0 .get ()) }; + } + +unsafe fn dec_ref (obj: core::ptr::NonNull <Self >) { +// SAFETY: The safety requirements guarantee that the refcount is nonzero. +unsafe { bindings::put_cred (obj.cast ().as_ptr ()) }; + } +}
rust/kernel/file.rs +15 -0
@@ -7,6 +7,7 @@use crate ::{ bindings, + cred::Credential , error::{code::*,Error ,Result }, types::{ARef ,AlwaysRefCounted ,Opaque }, };
@@ -138,6 +139,20 @@ pub unsafe fn from_ptr<'a>(ptr: *const bindings::file) -> &'a File {unsafe { &*ptr.cast () } } +/// Returns the credentials of the task that originally opened the file. +pub fn cred (&self) -> &Credential { +// SAFETY: The file is valid because the shared reference guarantees a nonzero refcount. +// +// This uses a volatile read because C code may be modifying this field in parallel using +// non-atomic unsynchronized writes. This corresponds to how the C macro READ_ONCE is +// implemented. +let ptr =unsafe { core::ptr::addr_of!((*self.0 .get ()).f_cred).read_volatile () }; +// SAFETY: The lifetimes of `self` and `Credential` are tied, so it is guaranteed that +// the credential pointer remains valid (because the file is still alive, and it doesn't +// change over the lifetime of a file). +unsafe {Credential ::from_ptr (ptr) } + } +/// Returns the flags associated with the file. /// /// The flags are a combination of the constants in [`flags`].
rust/kernel/lib.rs +1 -0
@@ -31,6 +31,7 @@#[cfg(not(testlib))] mod allocator;mod build_assert; +pub mod cred;pub mod error;pub mod file;pub mod init;
rust/bindings/bindings_helper.h +2 -0
@@ -6,9 +6,11 @@* Sorted alphabetically. */ +#include <linux/cred.h> #include <linux/errname.h> #include <linux/file.h> #include <linux/fs.h> +#include <linux/security.h> #include <linux/slab.h> #include <linux/refcount.h> #include <linux/wait.h>
rust/helpers.c +22 -0
@@ -22,12 +22,14 @@#include <linux/bug.h> #include <linux/build_bug.h> +#include <linux/cred.h> #include <linux/err.h> #include <linux/errname.h> #include <linux/fs.h> #include <linux/mutex.h> #include <linux/refcount.h> #include <linux/sched/signal.h> +#include <linux/security.h> #include <linux/spinlock.h> #include <linux/wait.h>
@@ -144,6 +146,26 @@ struct file *rust_helper_get_file(struct file *f) }EXPORT_SYMBOL_GPL (rust_helper_get_file); +const struct cred *rust_helper_get_cred (const struct cred *cred) +{ +return get_cred (cred); +} +EXPORT_SYMBOL_GPL (rust_helper_get_cred); + +void rust_helper_put_cred (const struct cred *cred) +{ +put_cred (cred); +} +EXPORT_SYMBOL_GPL (rust_helper_put_cred); + +#ifndef CONFIG_SECURITY +void rust_helper_security_cred_getsecid (const struct cred *c,u32 *secid) +{ +security_cred_getsecid (c, secid); +} +EXPORT_SYMBOL_GPL (rust_helper_security_cred_getsecid); +#endif +/* * We use `bindgen`'s `--size_t-is-usize` option to bind the C `size_t` type * as the Rust `usize` type, so we can use it in contexts where Rust
Signature · 1 line
2.41.0.255.g8b1d071c50-goog
Alice Ryhl
maintainerRFC PATCH 3/5 rust: file: add `FileDescriptorReservation`
In reply to Alice RyhlFrom: Wedson Almeida Filho <[email protected]>
This allows the creation of a file descriptor in two steps: first, we reserve a slot for it, then we commit or drop the reservation. The first step may fail (e.g., the current process ran out of available slots), but commit and drop never fail (and are mutually exclusive).
--- rust/kernel/file.rs | 61 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 60 insertions(+), 1 deletion(-)
rust/kernel/file.rs +60 -1
@@ -11,7 +11,7 @@ error::{code::*, Error, Result}, types::{ARef, AlwaysRefCounted, Opaque}, }; -use core::ptr; +use core::{marker::PhantomData , ptr};/// Flags associated with a [`File`]. pub mod flags {
@@ -179,6 +179,65 @@ unsafe fn dec_ref(obj: ptr::NonNull<Self>) { } } +/// A file descriptor reservation. +/// +/// This allows the creation of a file descriptor in two steps: first, we reserve a slot for it, +/// then we commit or drop the reservation. The first step may fail (e.g., the current process ran +/// out of available slots), but commit and drop never fail (and are mutually exclusive). +/// +/// # Invariants +/// +/// The fd stored in this struct must correspond to a reserved file descriptor of the current task. +pub struct FileDescriptorReservation { + fd:u32 , +/// Prevent values of this type from being moved to a different task. +/// +/// This is necessary because the C FFI calls assume that `current` is set to the task that +/// owns the fd in question. + _not_send_sync:PhantomData <*mut ()>, +} + +impl FileDescriptorReservation { +/// Creates a new file descriptor reservation. +pub fn new (flags:u32 ) ->Result <Self > { +// SAFETY: FFI call, there are no safety requirements on `flags`. +let fd:i32 =unsafe { bindings::get_unused_fd_flags (flags) }; +if fd <0 { +return Err (Error ::from_errno (fd)); + } +Ok (Self { + fd: fdas _ , + _not_send_sync:PhantomData , + }) + } + +/// Returns the file descriptor number that was reserved. +pub fn reserved_fd (&self) ->u32 { + self.fd + } + +/// Commits the reservation. +/// +/// The previously reserved file descriptor is bound to `file`. +pub fn commit (self, file:ARef <File >) { +// SAFETY: `self.fd` was previously returned by `get_unused_fd_flags`, and `file.ptr` is +// guaranteed to have an owned ref count by its type invariants. +unsafe { bindings::fd_install (self.fd, file.0 .get ()) }; + +// `fd_install` consumes both the file descriptor and the file reference, so we cannot run +// the destructors. + core::mem::forget (self); + core::mem::forget (file); + } +} + +impl Drop for FileDescriptorReservation { +fn drop (&mut self) { +// SAFETY: `self.fd` was returned by a previous call to `get_unused_fd_flags`. +unsafe { bindings::put_unused_fd (self.fd) }; + } +} +/// Represents the EBADF error code. /// /// Used for methods that can only fail with EBADF.
Signature · 1 line
2.41.0.255.g8b1d071c50-goog
Re: [RFC PATCH v1 3/5] rust: file: add `FileDescriptorReservation`
Quoted 12 lines · Alice Ryhl
From: Wedson Almeida Filho <[email protected]>
This allows the creation of a file descriptor in two steps: first, we reserve a slot for it, then we commit or drop the reservation. The first step may fail (e.g., the current process ran out of available slots), but commit and drop never fail (and are mutually exclusive).
Co-Developed-by Alice Ryhl <[email protected]>Signed-off-by Wedson Almeida Filho <[email protected]>Signed-off-by Alice Ryhl <[email protected]>---
[...]
rust/kernel/file.rs unsafe fn dec_ref(obj: ptr::NonNull<Self>) { · line 186
Quoted 5 lines
rust/kernel/file.rs +5
-0+/// A file descriptor reservation. +/// +/// This allows the creation of a file descriptor in two steps: first, we reserve a slot for it, +/// then we commit or drop the reservation. The first step may fail (e.g., the current process ran +/// out of available slots), but commit and drop never fail (and are mutually exclusive).
This "drop" suggests to me that there was a method that it does said action, and indeed it is Drop::drop. But if I look at the doc comment of commit then it doesn't look that these two are mutex.
/// Commits the reservation.
///
/// The previously reserved file descriptor is bound to `file`.I'd put a mention that FileDescriptorReservation gets forgotten when commit is called so then it clears up that it's mutex with drop.
Quoted 8 lines
rust/kernel/file.rs +6
-0+/// +/// # Invariants +/// +/// The fd stored in this struct must correspond to a reserved file descriptor of the current task. +pub struct FileDescriptorReservation { +}
Alice Ryhl
maintainerRFC PATCH 4/5 rust: file: add bindings for `poll_table`
In reply to Alice RyhlThese bindings make it possible to register a struct poll_table with a CondVar so that notifying the condition variable will mark a given file as notified in the poll table.
This patch introduces a wrapper around CondVar (which is just a wrapper around wait_list) rather than extending CondVar itself because using the condition variable with poll tables makes it necessary to use POLLHUP | POLLFREE to clear the wait list when the condition variable is destroyed.
This is not necessary with the ordinary CondVar because all of its methods will borrow the CondVar for longer than the duration in which it enqueues something to the wait list. This is not the case when registering a PollTable.
--- rust/bindings/bindings_helper.h | 2 + rust/bindings/lib.rs | 1 + rust/kernel/file.rs | 3 ++ rust/kernel/file/poll_table.rs | 93 +++++++++++++++++++++++++++++++++ rust/kernel/sync/condvar.rs | 2 +- 5 files changed, 100 insertions(+), 1 deletion(-) create mode 100644 rust/kernel/file/poll_table.rs
rust/kernel/file/poll_table.rs new file +93 -0
@@ -0,0 +1,93 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Utilities for working with `struct poll_table`. + +use crate ::{ + bindings, + file::File , + prelude::*, + sync::{CondVar ,LockClassKey }, + types::Opaque , +}; +use core::ops::Deref ; + +/// Creates a [`PollCondVar`] initialiser with the given name and a newly-created lock class. +#[macro_export] +macro_rules! new_poll_condvar { + ($($name:literal)?) => { + $crate::file::PollCondVar ::new ($crate::optional_name!($($name)?), $crate::static_lock_class!()) + }; +} + +/// Wraps the kernel's `struct poll_table`. +#[repr(transparent)] +pub struct PollTable (Opaque <bindings::poll_table >); + +impl PollTable { +/// Creates a reference to a [`PollTable`] from a valid pointer. +/// +/// # Safety +/// +/// The caller must ensure that for the duration of 'a, the pointer will point at a valid poll +/// table, and that it is only accessed via the returned reference. +pub unsafe fn from_ptr <'a>(ptr: *mut bindings::poll_table ) -> &'amut PollTable { +// SAFETY: The safety requirements guarantee the validity of the dereference, while the +// `PollTable` type being transparent makes the cast ok. +unsafe { &mut *ptr.cast () } + } + +fn get_qproc (&self) -> bindings::poll_queue_proc { +let ptr = self.0 .get (); +// SAFETY: The `ptr` is valid because it originates from a reference, and the `_qproc` +// field is not modified concurrently with this call. +unsafe { (*ptr)._qproc } + } + +/// Register this [`PollTable`] with the provided [`PollCondVar`], so that it can be notified +/// using the condition variable. +pub fn register_wait (&mut self, file: &File , cv: &PollCondVar ) { +if let Some (qproc) = self.get_qproc () { +// SAFETY: The pointers to `self` and `file` are valid because they are references. +// +// Before the wait list is destroyed, the destructor of `PollCondVar` will clear +// everything in the wait list, so the wait list is not used after it is freed. +unsafe {qproc (file.0 .get ()as _ , cv.wait_list.get (), self.0 .get ()) }; + } + } +} + +/// A wrapper around [`CondVar`] that makes it usable with [`PollTable`]. +/// +/// [`CondVar`]: crate::sync::CondVar +#[pin_data( PinnedDrop )] +pub struct PollCondVar { +#[pin] + inner:CondVar , +} + +impl PollCondVar { +/// Constructs a new condvar initialiser. +#[allow(clippy::new_ret_no_self)] +pub fn new (name: &'staticCStr , key: &'staticLockClassKey ) ->impl PinInit <Self > { +pin_init! (Self { + inner <-CondVar ::new (name, key), + }) + } +} + +// Make the `CondVar` methods callable on `PollCondVar`. +impl Deref for PollCondVar { +type Target =CondVar ; + +fn deref (&self) -> &CondVar { + &self.inner + } +} + +#[pinned_drop] +impl PinnedDrop for PollCondVar { +fn drop (self:Pin <&mut Self >) { +// Clear anything registered using `register_wait`. + self.inner.notify (1 , bindings::POLLHUP | bindings::POLLFREE ); + } +}
rust/kernel/sync/condvar.rs +1 -1
@@ -144,7 +144,7 @@ pub fn wait_uninterruptible<T: ?Sized, B: Backend>(&self, guard: &mut Guard<'_, }/// Calls the kernel function to notify the appropriate number of threads with the given flags. -fn notify (&self, count:i32 , flags:u32 ) { +pub (crate )fn notify (&self, count:i32 , flags:u32 ) {// SAFETY: `wait_list` points to valid memory. unsafe { bindings::__wake_up(
rust/kernel/file.rs +3 -0
@@ -13,6 +13,9 @@ };use core::{marker::PhantomData , ptr}; +mod poll_table; +pub use self::poll_table::{PollCondVar ,PollTable }; +/// Flags associated with a [`File`]. pub mod flags {/// File is opened in append mode.
rust/bindings/bindings_helper.h +2 -0
@@ -10,6 +10,7 @@#include <linux/errname.h> #include <linux/file.h> #include <linux/fs.h> +#include <linux/poll.h> #include <linux/security.h> #include <linux/slab.h> #include <linux/refcount.h>
@@ -19,3 +20,4 @@/* `bindgen` gets confused at certain things. */ const gfp_t BINDINGS_GFP_KERNEL =GFP_KERNEL ;const gfp_t BINDINGS___GFP_ZERO = __GFP_ZERO; +const __poll_t BINDINGS_POLLFREE =POLLFREE ;
rust/bindings/lib.rs +1 -0
@@ -51,3 +51,4 @@ mod bindings_helper {pub const GFP_KERNEL :gfp_t =BINDINGS_GFP_KERNEL ;pub const __GFP_ZERO:gfp_t =BINDINGS___GFP_ZERO ; +pub const POLLFREE :__poll_t =BINDINGS_POLLFREE ;
Signature · 1 line
2.41.0.255.g8b1d071c50-goog
Alice Ryhl
maintainerRFC PATCH 5/5 rust: file: add `DeferredFdCloser`
In reply to Alice RyhlThis adds a new type called DeferredFdCloser that can be used to close files by their fd in a way that is safe even if the file is currently held using fdget.
This is done by grabbing an extra refcount to the file and dropping it in a task work once we return to userspace.
See comments on binder_do_fd_close and commit 80cd795630d65 for motivation.
---
This is an implementation of binder_deferred_fd_close in Rust.
I think the fact that binder needs to close fds in this way raises the question of how we want the Rust APIs for closing files to look. Apparently, fdget is not just used in easily reviewable regions, but also around things like the ioctl syscall, meaning that all ioctls must abide by the fdget safety requirements.
rust/bindings/bindings_helper.h | 2 + rust/helpers.c | 7 +++ rust/kernel/file.rs | 80 ++++++++++++++++++++++++++++++++- 3 files changed, 88 insertions(+), 1 deletion(-)
rust/kernel/file.rs +79 -1
@@ -11,7 +11,8 @@ error::{code::*, Error, Result}, types::{ARef, AlwaysRefCounted, Opaque}, }; -use core::{marker::PhantomData , ptr}; +use alloc::boxed::Box ; +use core::{alloc::AllocError , marker::PhantomData , mem, ptr};mod poll_table;pub use self::poll_table::{PollCondVar ,PollTable };
@@ -241,6 +242,83 @@ fn drop(&mut self) { } } +/// Helper used for closing file descriptors in a way that is safe even if the file is currently +/// held using `fdget`. +/// +/// See comments on `binder_do_fd_close` and commit `80cd795630d65`. +pub struct DeferredFdCloser { + inner:Box <DeferredFdCloserInner >, +} + +/// 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 {} +unsafe impl Sync for DeferredFdCloser {} + +#[repr( C )] +struct DeferredFdCloserInner { + twork: mem::MaybeUninit <bindings::callback_head >, + file: *mut bindings::file , +} + +impl DeferredFdCloser { +/// Create a new `DeferredFdCloser`. +pub fn new () ->Result <Self ,AllocError > { +Ok (Self { + inner:Box ::try_new (DeferredFdCloserInner { + twork: mem::MaybeUninit ::uninit (), + file: core::ptr::null_mut (), + })?, + }) + } + +/// Schedule a task work that closes the file descriptor when this task returns to userspace. +pub fn close_fd (mut self, fd:u32 ) { +let file =unsafe { bindings::close_fd_get_file (fd) }; +if !file.is_null () { + self.inner.file = file; + +// SAFETY: Since DeferredFdCloserInner is `#[repr(C)]`, casting the pointers gives a +// pointer to the `twork` field. +let inner =Box ::into_raw (self.inner)as *mut bindings::callback_head ; + +// SAFETY: Getting a pointer to current is always safe. +let current =unsafe { bindings::get_current () }; +// SAFETY: The `file` pointer points at a valid file. +unsafe { bindings::get_file (file) }; +// SAFETY: Due to the above `get_file`, even if the current task holds an `fdget` to +// this file right now, the refcount will not drop to zero until after it is released +// with `fdput`. This is because when using `fdget`, you must always use `fdput` before +// returning to userspace, and our task work runs after any `fdget` users have returned +// to user space. +// +// Note: fl_owner_t is currently a void pointer. +unsafe { bindings::filp_close (file, currentas bindings::fl_owner_t ) }; +// SAFETY: The `inner` pointer is compatible with the `do_close_fd` method. +// +// The call to `task_work_add` can't fail, because we are scheduling the task work to +// the current task. +unsafe { + bindings::init_task_work (inner,Some (Self ::do_close_fd)); + bindings::task_work_add (current, inner, bindings::task_work_notify_mode_TWA_RESUME); + } + }else { +// Free the allocation. +drop (self.inner); + } + } + +unsafe extern "C" fn do_close_fd (inner: *mut bindings::callback_head ) { +// SAFETY: In `close_fd` we use this method together with a pointer that originates from a +// `Box<DeferredFdCloserInner>`, and we have just been given ownership of that allocation. +let inner =unsafe {Box ::from_raw (inneras *mut DeferredFdCloserInner ) }; +// SAFETY: This drops a refcount we acquired in `close_fd`. +unsafe { bindings::fput (inner.file) }; +// Free the allocation. +drop (inner); + } +} +/// Represents the EBADF error code. /// /// Used for methods that can only fail with EBADF.
rust/bindings/bindings_helper.h +2 -0
@@ -8,6 +8,7 @@#include <linux/cred.h> #include <linux/errname.h> +#include <linux/fdtable.h> #include <linux/file.h> #include <linux/fs.h> #include <linux/poll.h>
@@ -16,6 +17,7 @@#include <linux/refcount.h> #include <linux/wait.h> #include <linux/sched.h> +#include <linux/task_work.h> /* `bindgen` gets confused at certain things. */ const gfp_t BINDINGS_GFP_KERNEL =GFP_KERNEL ;
rust/helpers.c +7 -0
@@ -31,6 +31,7 @@#include <linux/sched/signal.h> #include <linux/security.h> #include <linux/spinlock.h> +#include <linux/task_work.h> #include <linux/wait.h> __noreturn void rust_helper_BUG (void )
@@ -166,6 +167,12 @@ void rust_helper_security_cred_getsecid(const struct cred *c, u32 *secid)EXPORT_SYMBOL_GPL (rust_helper_security_cred_getsecid);#endif +void rust_helper_init_task_work (struct callback_head *twork,task_work_func_t func) +{ +init_task_work (twork, func); +} +EXPORT_SYMBOL_GPL (rust_helper_init_task_work); +/* * We use `bindgen`'s `--size_t-is-usize` option to bind the C `size_t` type * as the Rust `usize` type, so we can use it in contexts where Rust
Signature · 1 line
2.41.0.255.g8b1d071c50-goog
Re: [RFC PATCH v1 5/5] rust: file: add `DeferredFdCloser`
Hi Alice,
A quick comment on referencing commits:
Quoted 3 lines · Alice Ryhl
See comments on
binder_do_fd_closeand commit80cd795630d65for motivation.
The convention is to write these commit references like this:
commit 80cd795630d6 ("binder: fix use-after-free due toksys_close() during fdget()")
I recommend generating them with a Git pretty format -- see the config in the bottom part of the section at
https://docs.kernel.org/process/submitting-patches.html#describe-your-changes.
Also, given it is a kernel convention, please avoid the Markdown backticks in this case.
Quoted 1 line
+/// See comments on
binder_do_fd_closeand commit80cd795630d65.
Same here, i.e. in comments and documentation too (and emails too, especially if not referenced elsewhere).
While I am at it, a few other notes below too I noticed:
Quoted 1 line
+ /// Create a new
DeferredFdCloser.
[DeferredFdCloser]
rust/kernel/file.rs fn drop(&mut self) { · line 278
Quoted 4 lines
rust/kernel/file.rs +4
-0+/// Schedule a task work that closes the file descriptor when this task returns to userspace. +pub fn close_fd (mut self, fd:u32 ) { +let file =unsafe { bindings::close_fd_get_file (fd) }; +if !file.is_null () {
Please use the early return style here, if possible, to unindent all this.
Quoted 1 line
+ // SAFETY: Since DeferredFdCloserInner is
#[repr(C)], casting the pointers gives a
DeferredFdCloserInner
Quoted 1 line
+ // Note:
fl_owner_tis currently a void pointer.
fl_owner_t
rust/kernel/file.rs fn drop(&mut self) { · line 304
Quoted 8 lines
rust/kernel/file.rs +8
-0+// SAFETY: The `inner` pointer is compatible with the `do_close_fd` method. +// +// The call to `task_work_add` can't fail, because we are scheduling the task work to +// the current task. +unsafe { + bindings::init_task_work (inner,Some (Self ::do_close_fd)); + bindings::task_work_add (current, inner, bindings::task_work_notify_mode_TWA_RESUME); + }
Should this block be split?
Quoted 3 lines
/// Represents the EBADF error code.
///
/// Used for methods that can only fail with EBADF.
Doclink them if possible; otherwise EBADF.
Cheers,
Miguel
Re: [RFC PATCH v1 5/5] rust: file: add `DeferredFdCloser`
In reply to Alice RyhlQuoted 9 lines · Alice Ryhl
This adds a new type called
DeferredFdCloserthat can be used to close files by their fd in a way that is safe even if the file is currently held usingfdget.This is done by grabbing an extra refcount to the file and dropping it in a task work once we return to userspace.
See comments on
binder_do_fd_closeand commit80cd795630d65for motivation.
Please provide links, at least for the doc comment.
rust/kernel/file.rs fn drop(&mut self) { · line 248
Quoted 9 lines
Signed-off-by Alice Ryhl <[email protected]>---
[...]rust/kernel/file.rs +4
-0+/// Helper used for closing file descriptors in a way that is safe even if the file is currently +/// held using `fdget`. +/// +/// See comments on `binder_do_fd_close` and commit `80cd795630d65`.
Ditto.
Quoted 5 lines
rust/kernel/file.rs +4
-0+pub struct DeferredFdCloser { + inner:Box <DeferredFdCloserInner >, +} +
Re: [RFC PATCH v1 5/5] rust: file: add `DeferredFdCloser`
Quoted 2 lines · Martin Rodriguez Reboredo
Please provide links, at least for the doc comment.
If you mean for the commit, then we should follow the kernel convention instead. Please see my reply to Alice above.
Quoted 1 line
Ditto.
For code, we are also using the same convention.
Cheers,
Miguel
Re: [RFC PATCH v1 5/5] rust: file: add `DeferredFdCloser`
Quoted 3 lines · Miguel Ojeda
If you mean for the commit, then we should follow the kernel convention instead. Please see my reply to Alice above.
One extra note: if it is a external repository, then yes, I would definitely recommend adding a Link because readers may not be able to easily git show the hash. But if it is the kernel tree, then it is not needed.
Cheers,
Miguel
Re: [RFC PATCH v1 5/5] rust: file: add `DeferredFdCloser`
Quoted 6 lines · Miguel Ojeda
Quoted 3 lines · Miguel Ojeda
If you mean for the commit, then we should follow the kernel convention instead. Please see my reply to Alice above.
Quoted 7 lines
One extra note: if it is a external repository, then yes, I would definitely recommend adding a
Linkbecause readers may not be able to easilygit showthe hash. But if it is the kernel tree, then it is not needed.Cheers,
Miguel
Gotcha
-> Martin