Skip to contentSkip to conversation

Rust support for mm_struct, vm_area_struct, and mmap

PATCH Superseded Alice Ryhl 3 participants 34 messages Nov 20, 2024 – Nov 22, 2024

Subsystems (4)

v8 of 16 Superseded Latest is v16 →

lore
Share & tools
lore

Alice Ryhl

author maintainer
#0 lore raw

v8 cover Rust support for mm_struct, vm_area_struct, and mmap

This updates the vm_area_struct support to use the approach we discussed at LPC where there are several different Rust wrappers for vm_area_struct depending on the kind of access you have to the vma. Each case allows a different set of operations on the vma.

This series depends on vfs.rust.file and char-misc-next which are scheduled to land upstream in the current merge window.

---
Changes in v8:
- Split series into more commits to ease review.
- Improve read locks based on Lorenzo's doc: either the mmap or vma lock can be used.
- Get rid of mmap write lock because it's possible to avoid the need for it.
- Do not allow invalid flag combinations on VmAreaNew.
- Link to v7: https://lore.kernel.org/r/[email protected]

Changes in v7:
- Make the mmap read/write lock guards respect strict owner semantics.
- Link to v6: https://lore.kernel.org/r/[email protected]

Changes in v6:
- Introduce VmArea{Ref,Mut,New} distinction.
- Add a second patchset for miscdevice.
- Rebase on char-misc-next (currently on v6.12-rc2).
- Link to v5: https://lore.kernel.org/r/[email protected]

Changes in v5:
- Rename VmArea::from_raw_vma to from_raw.
- Use Pin for mutable VmArea references.
- Go through ARef::from in mmgrab_current.
- Link to v4: https://lore.kernel.org/r/[email protected]

Changes in v4:
- Pull out ARef::into_raw into a separate patch.
- Update invariants and struct documentation.
- Rename from_raw_mm to from_raw.
- Link to v3: https://lore.kernel.org/r/[email protected]

Changes in v3:
- Reorder entries in mm.rs.
- Use ARef for mmput_async helper.
- Clarify that VmArea requires you to hold the mmap read or write lock.
- Link to v2: https://lore.kernel.org/r/[email protected]

Changes in v2:
- mm.rs is redesigned from scratch making use of AsRef
- Add notes about whether destructors may sleep
- Rename Area to VmArea
- Link to v1: https://lore.kernel.org/r/[email protected]

---
Alice Ryhl (7):
mm: rust: add abstraction for struct mm_struct
mm: rust: add vm_area_struct methods that require read access
mm: rust: add vm_insert_page
mm: rust: add lock_vma_under_rcu
mm: rust: add mmput_async support
mm: rust: add VmAreaNew
rust: miscdevice: add mmap support

 rust/helpers/helpers.c    |   1 +
 rust/helpers/mm.c         |  50 ++++++
 rust/kernel/lib.rs        |   1 +
 rust/kernel/miscdevice.rs |  28 ++++
 rust/kernel/mm.rs         | 345 +++++++++++++++++++++++++++++++++++++++
 rust/kernel/mm/virt.rs    | 404 ++++++++++++++++++++++++++++++++++++++++++++++
 6 files changed, 829 insertions(+)

---
base-commit: 7f219f5002eb0ce2b12562127aeb0521bbf2146e
change-id: 20240723-vma-f80119f9fb35

Best regards,

Signature · 1 line
Alice Ryhl <[email protected]>
author maintainer
#1 lore raw

PATCH v8 1/7 mm: rust: add abstraction for struct mm_struct

These abstractions allow you to reference a struct mm_struct using both mmgrab and mmget refcounts. This is done using two Rust types:

* Mm - represents an mm_struct where you don't know anything about the value of mm_users.
* MmWithUser - represents an mm_struct where you know at compile time that mm_users is non-zero.

This allows us to encode in the type system whether a method requires that mm_users is non-zero or not. For instance, you can always call mmget_not_zero but you can only call mmap_read_lock when mm_users is non-zero.

---
 rust/helpers/helpers.c |   1 +
 rust/helpers/mm.c      |  39 +++++++++
 rust/kernel/lib.rs     |   1 +
 rust/kernel/mm.rs      | 219 +++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 260 insertions(+)
rust/helpers/helpers.c +1 -0
index 20a0c69d5cc7..60a488eb4efe 100644
@@ -13,6 +13,7 @@
 #include "build_bug.c"
 #include "err.c"
 #include "kunit.c"
+#include "mm.c"
 #include "mutex.c"
 #include "page.c"
 #include "rbtree.c"
rust/helpers/mm.c new file +39 -0
new file mode 100644
index 000000000000..7201747a5d31
@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: GPL-2.0
+
+#include <linux/mm.h>
+#include <linux/sched/mm.h>
+
+void rust_helper_mmgrab(struct mm_struct *mm)
+{
+	mmgrab(mm);
+}
+
+void rust_helper_mmdrop(struct mm_struct *mm)
+{
+	mmdrop(mm);
+}
+
+void rust_helper_mmget(struct mm_struct *mm)
+{
+	mmget(mm);
+}
+
+bool rust_helper_mmget_not_zero(struct mm_struct *mm)
+{
+	return mmget_not_zero(mm);
+}
+
+void rust_helper_mmap_read_lock(struct mm_struct *mm)
+{
+	mmap_read_lock(mm);
+}
+
+bool rust_helper_mmap_read_trylock(struct mm_struct *mm)
+{
+	return mmap_read_trylock(mm);
+}
+
+void rust_helper_mmap_read_unlock(struct mm_struct *mm)
+{
+	mmap_read_unlock(mm);
+}
rust/kernel/lib.rs +1 -0
index 66f5cde7f322..cc1963510cdf 100644
@@ -43,6 +43,7 @@
 pub mod kunit;
 pub mod list;
 pub mod miscdevice;
+pub mod mm;
 #[cfg(CONFIG_NET)]
 pub mod net;
 pub mod page;
rust/kernel/mm.rs new file +219 -0

219 lines not on this page · raw message

Signature · 1 line
2.47.0.371.ga323438b13-goog
#2 lore raw

Re: [PATCH v8 1/7] mm: rust: add abstraction for struct mm_struct

Quoted 8 lines · Alice Ryhl

These abstractions allow you to reference a struct mm_struct using both mmgrab and mmget refcounts. This is done using two Rust types:

* Mm - represents an mm_struct where you don't know anything about the value of mm_users.
* MmWithUser - represents an mm_struct where you know at compile time that mm_users is non-zero.

Quoted 4 lines

This allows us to encode in the type system whether a method requires that mm_users is non-zero or not. For instance, you can always call mmget_not_zero but you can only call mmap_read_lock when mm_users is non-zero.

It's kind of interesting to represent these things this way, I like the self-documenting element of that.

Quoted 2 lines

So obviously I'm not a rust person (yet... yet :) so from my side I can only look at things from an mm perspective conceptually. To avoid boring everyone I won't repeat this and instead you can take it as read.

I will obviously inevitably ask a TON of questions as a result of not being a rust person so, bear with me...

Quoted 54 lines
---
 rust/helpers/helpers.c |   1 +
 rust/helpers/mm.c      |  39 +++++++++
 rust/kernel/lib.rs     |   1 +
 rust/kernel/mm.rs      | 219 +++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 260 insertions(+)
rust/helpers/helpers.c +1 -0
index 20a0c69d5cc7..60a488eb4efe 100644
@@ -13,6 +13,7 @@
 #include "build_bug.c"
 #include "err.c"
 #include "kunit.c"
+#include "mm.c"
 #include "mutex.c"
 #include "page.c"
 #include "rbtree.c"
rust/helpers/mm.c new file +29 -0
new file mode 100644
index 000000000000..7201747a5d31
@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: GPL-2.0
+
+#include <linux/mm.h>
+#include <linux/sched/mm.h>
+
+void rust_helper_mmgrab(struct mm_struct *mm)
+{
+	mmgrab(mm);
+}
+
+void rust_helper_mmdrop(struct mm_struct *mm)
+{
+	mmdrop(mm);
+}
+
+void rust_helper_mmget(struct mm_struct *mm)
+{
+	mmget(mm);
+}
+
+bool rust_helper_mmget_not_zero(struct mm_struct *mm)
+{
+	return mmget_not_zero(mm);
+}
+
+void rust_helper_mmap_read_lock(struct mm_struct *mm)
+{
+	mmap_read_lock(mm);
+}

rust/helpers/mm.c line 39

Quoted 10 lines
rust/helpers/mm.c new file +10 -0
+
+bool rust_helper_mmap_read_trylock(struct mm_struct *mm)
+{
+	return mmap_read_trylock(mm);
+}
+
+void rust_helper_mmap_read_unlock(struct mm_struct *mm)
+{
+	mmap_read_unlock(mm);
+}

I guess at this point we're only interested in reading?

Quoted 38 lines
rust/kernel/lib.rs +1 -0
index 66f5cde7f322..cc1963510cdf 100644
@@ -43,6 +43,7 @@
 pub mod kunit;
 pub mod list;
 pub mod miscdevice;
+pub mod mm;
 #[cfg(CONFIG_NET)]
 pub mod net;
 pub mod page;
rust/kernel/mm.rs new file +20 -0
new file mode 100644
index 000000000000..84cba581edaa
@@ -0,0 +1,219 @@
+// SPDX-License-Identifier: GPL-2.0
+
+// Copyright (C) 2024 Google LLC.
+
+//! Memory management.
+//!
+//! C header: [`include/linux/mm.h`](srctree/include/linux/mm.h)
+
+use crate::{
+    bindings,
+    types::{ARef, AlwaysRefCounted, NotThreadSafe, Opaque},
+};
+use core::{ops::Deref, ptr::NonNull};
+
+/// A wrapper for the kernel's `struct mm_struct`.
+///
+/// Since `mm_users` may be zero, the associated address space may not exist anymore. You can use
+/// [`mmget_not_zero`] to be able to access the address space.
+///
+/// The `ARef<Mm>` smart pointer holds an `mmgrab` refcount. Its destructor may sleep.

rust/kernel/mm.rs line 30

Quoted 10 lines
rust/kernel/mm.rs new file +10 -0
+///
+/// # Invariants
+///
+/// Values of this type are always refcounted using `mmgrab`.
+///
+/// [`mmget_not_zero`]: Mm::mmget_not_zero
+#[repr(transparent)]
+pub struct Mm {
+    mm: Opaque<bindings::mm_struct>,
+}

Does this tie this type to the C struct mm_struct type?

Does 'Opaque' mean it is a pointer to a type which is 'opaque' in the sense that rust can't see into its internals?

Quoted 10 lines
rust/kernel/mm.rs new file +10 -0
+
+// SAFETY: It is safe to call `mmdrop` on another thread than where `mmgrab` was called.
+unsafe impl Send for Mm {}
+// SAFETY: All methods on `Mm` can be called in parallel from several threads.
+unsafe impl Sync for Mm {}
+
+// SAFETY: By the type invariants, this type is always refcounted.
+unsafe impl AlwaysRefCounted for Mm {
+    #[inline]
+    fn inc_ref(&self) {

rust/kernel/mm.rs line 50

Quoted 10 lines
rust/kernel/mm.rs new file +10 -0
+        // SAFETY: The pointer is valid since self is a reference.
+        unsafe { bindings::mmgrab(self.as_raw()) };
+    }
+
+    #[inline]
+    unsafe fn dec_ref(obj: NonNull<Self>) {
+        // SAFETY: The caller is giving up their refcount.
+        unsafe { bindings::mmdrop(obj.cast().as_ptr()) };
+    }
+}

Under what circumstances would these be taken? Same question for MmWthUser.

Quoted 6 lines
rust/kernel/mm.rs new file +6 -0
+
+/// A wrapper for the kernel's `struct mm_struct`.
+///
+/// This type is like [`Mm`], but with non-zero `mm_users`. It can only be used when `mm_users` can
+/// be proven to be non-zero at compile-time, usually because the relevant code holds an `mmget`
+/// refcount. It can be used to access the associated address space.

rust/kernel/mm.rs line 66

Quoted 10 lines
rust/kernel/mm.rs new file +10 -0
+///
+/// The `ARef<MmWithUser>` smart pointer holds an `mmget` refcount. Its destructor may sleep.
+///
+/// # Invariants
+///
+/// Values of this type are always refcounted using `mmget`. The value of `mm_users` is non-zero.
+#[repr(transparent)]
+pub struct MmWithUser {
+    mm: Mm,
+}

Why does Mm have this as a Opaque<bindings::mm_struct> and this sort of nests it?

Does this somehow amount to the same thing, or would you probably never actually reference this mm field?

Quoted 9 lines
rust/kernel/mm.rs new file +9 -0
+
+// SAFETY: It is safe to call `mmput` on another thread than where `mmget` was called.
+unsafe impl Send for MmWithUser {}
+// SAFETY: All methods on `MmWithUser` can be called in parallel from several threads.
+unsafe impl Sync for MmWithUser {}
+
+// SAFETY: By the type invariants, this type is always refcounted.
+unsafe impl AlwaysRefCounted for MmWithUser {
+    #[inline]

rust/kernel/mm.rs line 85

Quoted 10 lines
rust/kernel/mm.rs new file +10 -0
+    fn inc_ref(&self) {
+        // SAFETY: The pointer is valid since self is a reference.
+        unsafe { bindings::mmget(self.as_raw()) };
+    }
+
+    #[inline]
+    unsafe fn dec_ref(obj: NonNull<Self>) {
+        // SAFETY: The caller is giving up their refcount.
+        unsafe { bindings::mmput(obj.cast().as_ptr()) };
+    }

Hm, why is it we mmget(self.as_raw()) but mmput(obj.cast().as_ptr())?

Also I guess relatedly, why does one refer to &self and the other as a NonNull<Self>?

I'm guessing as a non-rust person a 'reference' is like a C++ reference in the sense that (well it is _assumed_ in C++ anyway) it acts like a pointer for the type which should never not be there, but we need .as_raw() to get the raw C pointer?

And I guess in the dec_ref() case we need the .cast().as_ptr() because obj 'boxes' around self (I guess equivalent to 'this' in C++ kinda) guaranteeing that it can provide non-null pointer to the current object?

rust/kernel/mm.rs line 96

Quoted 11 lines
rust/kernel/mm.rs new file +11 -0
+}
+
+// Make all `Mm` methods available on `MmWithUser`.
+impl Deref for MmWithUser {
+    type Target = Mm;
+
+    #[inline]
+    fn deref(&self) -> &Mm {
+        &self.mm
+    }
+}

I rubber ducked myself a bit on this, so I guess this makes it possible to dereference the object, and it

rust/kernel/mm.rs line 107

Quoted 11 lines
rust/kernel/mm.rs new file +11 -0
+
+// These methods are safe to call even if `mm_users` is zero.
+impl Mm {
+    /// Call `mmgrab` on `current.mm`.
+    #[inline]
+    pub fn mmgrab_current() -> Option<ARef<Mm>> {
+        // SAFETY: It's safe to get the `mm` field from current.
+        let mm = unsafe {
+            let current = bindings::get_current();
+            (*current).mm
+        };

I don't see an equivalent means of obtaining mm from current for MmWithUser, is that intentional, would there be another means of obtaining an mm? (perhaps via vma->vm_mm I guess?)

An aside -->

If we're grabbing from current, and this is non-NULL (i.e. not a kernel thread), this is kinda MmWithUser to _start out_ with, but I guess if you're grabbing the current one you might not expect it.

I guess one thing I want to point out (maybe here is wrong place) is that the usual way of interacting with current->mm is that we do _not_ increment mm->mm_count, mm->mm_users or any refernce count, as while we are in the kernel portion of the task, we are guaranteed the mm and the backing virtual address space will stick around.

With reference to MmWithUser, in fact, if you look up users of mmget()/mmput() it is pretty rare to do that.

So ideally we'd avoid doing this if we could (though having the semantics of grabbing a reference if we were to copy the object somehow again or hold its state or something would be nice).

I guess this might actually be tricky in rust, because we'd probably need to somehow express the current task's lifetime and tie this to that and... yeah.

<-- aside

rust/kernel/mm.rs line 116

Quoted 9 lines
rust/kernel/mm.rs new file +9 -0
+
+        if mm.is_null() {
+            return None;
+        }
+
+        // SAFETY: The value of `current->mm` is guaranteed to be null or a valid `mm_struct`. We
+        // just checked that it's not null. Furthermore, the returned `&Mm` is valid only for the
+        // duration of this function, and `current->mm` will stay valid for that long.
+        let mm = unsafe { Mm::from_raw(mm) };

Hm does mm now reference something with a different type, as in before it was a 'raw' pointer or such, and now it's a reference to an Mm right?

Also I guess the 'duration of this function' is because we put this in the 'Aref' smart pointer which kinda takes over the lifetime of the reference by wrapping it right?

I mean I'm not a rust person so actually I have no business _commenting_ on this :P as this may very well be idiomatic rust, but I'm just curious about this.

It's nitty but I feel like maybe we're somewhat overloading 'mm's here a bit though? As we have our wrapped Mm type and then an internal raw mm type. On the other hand, it's hard to now have horribly awkward and confusing naming here I guess, and perhaps this is fine.

Not a big deal though!

rust/kernel/mm.rs line 119

Quoted 3 lines
rust/kernel/mm.rs new file +3 -0
+
+        // This increments the refcount using `mmgrab`.
+        Some(ARef::from(mm))

So I get that Some() means this is like a discriminated union or such, where we can return None (as above) or Some, which contains the value is of type ARef<Mm>. And I guess this moves the 'lifetime' of mm which was previously with the function into that of the ARef<>?

Does the ARef<> 'just know' to use the AlwaysRefCounted methods?

rust/kernel/mm.rs line 126

Quoted 7 lines
rust/kernel/mm.rs new file +7 -0
+    }
+
+    /// Returns a raw pointer to the inner `mm_struct`.
+    #[inline]
+    pub fn as_raw(&self) -> *mut bindings::mm_struct {
+        self.mm.get()
+    }

I guess this .get() method is on the Opaque<> object and returns a raw ptr?

rust/kernel/mm.rs line 135

Quoted 9 lines
rust/kernel/mm.rs new file +9 -0
+
+    /// Obtain a reference from a raw pointer.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that `ptr` points at an `mm_struct`, and that it is not deallocated
+    /// during the lifetime 'a.
+    #[inline]
+    pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a Mm {

I'm guessing this funny 'a syntax, based on the comment, refers to the lifetime of the object?

rust/kernel/mm.rs line 137

Quoted 2 lines
rust/kernel/mm.rs new file +2 -0
+        // SAFETY: Caller promises that the pointer is valid for 'a. Layouts are compatible due to
+        // repr(transparent).

God I love these SAFETY comments (I mean actually, sorry I realise it's almost impossible to convey 'not sarcastically, actually' in text form :). Is that something that gets parsed somewhere, or a convention or?

I like that there is a discipline of expressing under what circumstances we are permitted to reference things.

rust/kernel/mm.rs line 143

Quoted 6 lines
rust/kernel/mm.rs new file +6 -0
+        unsafe { &*ptr.cast() }
+    }
+
+    /// Calls `mmget_not_zero` and returns a handle if it succeeds.
+    #[inline]
+    pub fn mmget_not_zero(&self) -> Option<ARef<MmWithUser>> {

I actually kinda love that this takes an mm and guarantees that you get an MmWithUser out of it which is implied by the fact this succeeds.

However as to the point above, I'm concerned that this might be seen as 'the way' to access an mm, i.e. mm.mmgrab_current().mmget_not_zero() or something.

Whereas, the usual way of referencing current->mm is to not increment any reference counts at all (assuming what you are doing resides in the same lifetime as the task).

Obviously if you step outside of that lifetime, then you _do_ have to pin the mm (nearly always you want to grab rather than get though in that circumstance).

rust/kernel/mm.rs line 149

Quoted 6 lines
rust/kernel/mm.rs new file +6 -0
+        // SAFETY: The pointer is valid since self is a reference.
+        let success = unsafe { bindings::mmget_not_zero(self.as_raw()) };
+
+        if success {
+            // SAFETY: We just created an `mmget` refcount.
+            Some(unsafe { ARef::from_raw(NonNull::new_unchecked(self.as_raw().cast())) })

When you do this, does it cause the reference count to increment, or does it assume it's already at 1?

Quoted 10 lines
rust/kernel/mm.rs new file +10 -0
+        } else {
+            None
+        }
+    }
+}
+
+// These methods require `mm_users` to be non-zero.
+impl MmWithUser {
+    /// Obtain a reference from a raw pointer.
+    ///

rust/kernel/mm.rs line 169

Quoted 10 lines
rust/kernel/mm.rs new file +10 -0
+    /// # Safety
+    ///
+    /// The caller must ensure that `ptr` points at an `mm_struct`, and that `mm_users` remains
+    /// non-zero for the duration of the lifetime 'a.
+    #[inline]
+    pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser {
+        // SAFETY: Caller promises that the pointer is valid for 'a. The layout is compatible due
+        // to repr(transparent).
+        unsafe { &*ptr.cast() }
+    }

I guess this is another means by which you can get the mm. I'd say an equivalent for getting from current is highly relevant.

rust/kernel/mm.rs line 180

Quoted 11 lines
rust/kernel/mm.rs new file +11 -0
+
+    /// Lock the mmap read lock.
+    #[inline]
+    pub fn mmap_read_lock(&self) -> MmapReadGuard<'_> {
+        // SAFETY: The pointer is valid since self is a reference.
+        unsafe { bindings::mmap_read_lock(self.as_raw()) };
+
+        // INVARIANT: We just acquired the read lock.
+        MmapReadGuard {
+            mm: self,
+            _nts: NotThreadSafe,

I'm sure this is a rusty thing, but curious as to why this is like that? What is '_nts', etc.?

Quoted 29 lines
rust/kernel/mm.rs new file +29 -0
+        }
+    }
+
+    /// Try to lock the mmap read lock.
+    #[inline]
+    pub fn mmap_read_trylock(&self) -> Option<MmapReadGuard<'_>> {
+        // SAFETY: The pointer is valid since self is a reference.
+        let success = unsafe { bindings::mmap_read_trylock(self.as_raw()) };
+
+        if success {
+            // INVARIANT: We just acquired the read lock.
+            Some(MmapReadGuard {
+                mm: self,
+                _nts: NotThreadSafe,
+            })
+        } else {
+            None
+        }
+    }
+}
+
+/// A guard for the mmap read lock.
+///
+/// # Invariants
+///
+/// This `MmapReadGuard` guard owns the mmap read lock.
+pub struct MmapReadGuard<'a> {
+    mm: &'a MmWithUser,
+    // `mmap_read_lock` and `mmap_read_unlock` must be called on the same thread

rust/kernel/mm.rs line 219

Quoted 10 lines
rust/kernel/mm.rs new file +10 -0
+    _nts: NotThreadSafe,
+}
+
+impl Drop for MmapReadGuard<'_> {
+    #[inline]
+    fn drop(&mut self) {
+        // SAFETY: We hold the read lock by the type invariants.
+        unsafe { bindings::mmap_read_unlock(self.mm.as_raw()) };
+    }
+}

Ah that's nice, an actual guard for it :) I'm guessing the fact this implements the guard implies that you _must_ hold the lock first right?

Quoted 4 lines

--
2.47.0.371.ga323438b13-goog

Sorry for the numerous questions, I'm afraid there'll be a lot of this for rust stuff for the time being. Perhaps advent of code will help improve things on the rust front for me ;)

author maintainer
#3 lore raw

Re: [PATCH v8 1/7] mm: rust: add abstraction for struct mm_struct

Quoted 86 lines · Lorenzo Stoakes
Quoted 8 lines · Alice Ryhl

These abstractions allow you to reference a struct mm_struct using both mmgrab and mmget refcounts. This is done using two Rust types:

* Mm - represents an mm_struct where you don't know anything about the value of mm_users.
* MmWithUser - represents an mm_struct where you know at compile time that mm_users is non-zero.

Quoted 4 lines

This allows us to encode in the type system whether a method requires that mm_users is non-zero or not. For instance, you can always call mmget_not_zero but you can only call mmap_read_lock when mm_users is non-zero.

It's kind of interesting to represent these things this way, I like the self-documenting element of that.

Quoted 2 lines

So obviously I'm not a rust person (yet... yet :) so from my side I can only look at things from an mm perspective conceptually. To avoid boring everyone I won't repeat this and instead you can take it as read.

I will obviously inevitably ask a TON of questions as a result of not being a rust person so, bear with me...

Quoted 58 lines
---
 rust/helpers/helpers.c |   1 +
 rust/helpers/mm.c      |  39 +++++++++
 rust/kernel/lib.rs     |   1 +
 rust/kernel/mm.rs      | 219 +++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 260 insertions(+)
rust/helpers/helpers.c +1 -0
index 20a0c69d5cc7..60a488eb4efe 100644
@@ -13,6 +13,7 @@
 #include "build_bug.c"
 #include "err.c"
 #include "kunit.c"
+#include "mm.c"
 #include "mutex.c"
 #include "page.c"
 #include "rbtree.c"
rust/helpers/mm.c new file +33 -0
new file mode 100644
index 000000000000..7201747a5d31
@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: GPL-2.0
+
+#include <linux/mm.h>
+#include <linux/sched/mm.h>
+
+void rust_helper_mmgrab(struct mm_struct *mm)
+{
+     mmgrab(mm);
+}
+
+void rust_helper_mmdrop(struct mm_struct *mm)
+{
+     mmdrop(mm);
+}
+
+void rust_helper_mmget(struct mm_struct *mm)
+{
+     mmget(mm);
+}
+
+bool rust_helper_mmget_not_zero(struct mm_struct *mm)
+{
+     return mmget_not_zero(mm);
+}
+
+void rust_helper_mmap_read_lock(struct mm_struct *mm)
+{
+     mmap_read_lock(mm);
+}
+
+bool rust_helper_mmap_read_trylock(struct mm_struct *mm)
+{
+     return mmap_read_trylock(mm);
Quoted 8 lines

rust/helpers/mm.c line 39

Quoted 6 lines
rust/helpers/mm.c new file +6 -0
+}
+
+void rust_helper_mmap_read_unlock(struct mm_struct *mm)
+{
+     mmap_read_unlock(mm);
+}

I guess at this point we're only interested in reading?

Yeah. The write lock would be very similar.

Quoted 51 lines
Quoted 38 lines
rust/kernel/lib.rs +1 -0
index 66f5cde7f322..cc1963510cdf 100644
@@ -43,6 +43,7 @@
 pub mod kunit;
 pub mod list;
 pub mod miscdevice;
+pub mod mm;
 #[cfg(CONFIG_NET)]
 pub mod net;
 pub mod page;
rust/kernel/mm.rs new file +20 -0
new file mode 100644
index 000000000000..84cba581edaa
@@ -0,0 +1,219 @@
+// SPDX-License-Identifier: GPL-2.0
+
+// Copyright (C) 2024 Google LLC.
+
+//! Memory management.
+//!
+//! C header: [`include/linux/mm.h`](srctree/include/linux/mm.h)
+
+use crate::{
+    bindings,
+    types::{ARef, AlwaysRefCounted, NotThreadSafe, Opaque},
+};
+use core::{ops::Deref, ptr::NonNull};
+
+/// A wrapper for the kernel's `struct mm_struct`.
+///
+/// Since `mm_users` may be zero, the associated address space may not exist anymore. You can use
+/// [`mmget_not_zero`] to be able to access the address space.
+///
+/// The `ARef<Mm>` smart pointer holds an `mmgrab` refcount. Its destructor may sleep.

rust/kernel/mm.rs line 30

Quoted 10 lines
rust/kernel/mm.rs new file +10 -0
+///
+/// # Invariants
+///
+/// Values of this type are always refcounted using `mmgrab`.
+///
+/// [`mmget_not_zero`]: Mm::mmget_not_zero
+#[repr(transparent)]
+pub struct Mm {
+    mm: Opaque<bindings::mm_struct>,
+}

Does this tie this type to the C struct mm_struct type?

Quoted 2 lines

Does 'Opaque' mean it is a pointer to a type which is 'opaque' in the sense that rust can't see into its internals?

This declaration defines a Rust type called Mm which has the same size, alignment, and contents as struct mm_struct. The purpose of Opaque is to tell Rust that it can't assume anything about the contents at all; we do that to leave it up to C.

For example, normally if you have an immutable reference &i32, then Rust is going to assume that the contents behind the reference are in fact immutable. Opaque turns that off, meaning that an &Opaque<i32> is allowed to reference an integer as it gets modified. It makes all access to the contents unsafe, though.

Note that Opaque is *not* a pointer type. We're going to be dealing with types like &Mm or ARef<Mm> where &_ and ARef<_> are two different kinds of pointers.

Quoted 13 lines
Quoted 13 lines
rust/kernel/mm.rs new file +13 -0
+// SAFETY: It is safe to call `mmdrop` on another thread than where `mmgrab` was called.
+unsafe impl Send for Mm {}
+// SAFETY: All methods on `Mm` can be called in parallel from several threads.
+unsafe impl Sync for Mm {}
+
+// SAFETY: By the type invariants, this type is always refcounted.
+unsafe impl AlwaysRefCounted for Mm {
+    #[inline]
+    fn inc_ref(&self) {
+        // SAFETY: The pointer is valid since self is a reference.
+        unsafe { bindings::mmgrab(self.as_raw()) };
+    }
+
Quoted 8 lines

rust/kernel/mm.rs line 50

Quoted 6 lines
rust/kernel/mm.rs new file +6 -0
+    #[inline]
+    unsafe fn dec_ref(obj: NonNull<Self>) {
+        // SAFETY: The caller is giving up their refcount.
+        unsafe { bindings::mmdrop(obj.cast().as_ptr()) };
+    }
+}

Under what circumstances would these be taken? Same question for MmWthUser.

This makes Mm compatible with the pointer type called ARef<_>. This pointer type is used to represent ownership of a refcount. So whenever a variable of type ARef<_> goes out of scope, the refcount is decremented, and whenever an ARef<_> is cloned, the refcount is incremented.

The way this works is that ARef<_> is implemented to use the AlwaysRefCounted trait to understand how to manipulate the count. Only types that implement the trait with an impl block like above can be used with ARef<_>.

Quoted 20 lines
Quoted 6 lines
rust/kernel/mm.rs new file +6 -0
+
+/// A wrapper for the kernel's `struct mm_struct`.
+///
+/// This type is like [`Mm`], but with non-zero `mm_users`. It can only be used when `mm_users` can
+/// be proven to be non-zero at compile-time, usually because the relevant code holds an `mmget`
+/// refcount. It can be used to access the associated address space.

rust/kernel/mm.rs line 66

Quoted 10 lines
rust/kernel/mm.rs new file +10 -0
+///
+/// The `ARef<MmWithUser>` smart pointer holds an `mmget` refcount. Its destructor may sleep.
+///
+/// # Invariants
+///
+/// Values of this type are always refcounted using `mmget`. The value of `mm_users` is non-zero.
+#[repr(transparent)]
+pub struct MmWithUser {
+    mm: Mm,
+}

Why does Mm have this as a Opaque<bindings::mm_struct> and this sort of nests it?

Quoted 2 lines

Does this somehow amount to the same thing, or would you probably never actually reference this mm field?

It amounts to the same thing as Opaque<bindings::mm_struct>.

Quoted 12 lines
Quoted 12 lines
rust/kernel/mm.rs new file +12 -0
+// SAFETY: It is safe to call `mmput` on another thread than where `mmget` was called.
+unsafe impl Send for MmWithUser {}
+// SAFETY: All methods on `MmWithUser` can be called in parallel from several threads.
+unsafe impl Sync for MmWithUser {}
+
+// SAFETY: By the type invariants, this type is always refcounted.
+unsafe impl AlwaysRefCounted for MmWithUser {
+    #[inline]
+    fn inc_ref(&self) {
+        // SAFETY: The pointer is valid since self is a reference.
+        unsafe { bindings::mmget(self.as_raw()) };
+    }
Quoted 8 lines

rust/kernel/mm.rs line 85

Quoted 6 lines
rust/kernel/mm.rs new file +6 -0
+
+    #[inline]
+    unsafe fn dec_ref(obj: NonNull<Self>) {
+        // SAFETY: The caller is giving up their refcount.
+        unsafe { bindings::mmput(obj.cast().as_ptr()) };
+    }

Hm, why is it we mmget(self.as_raw()) but mmput(obj.cast().as_ptr())?

There's one assumption about references that Opaque doesn't turn off:
The memory behind the reference must not get deallocated while the reference exists. We can't use a reference in dec_ref because the memory might get deallocated during the call to dec_ref.

Quoted 2 lines

Also I guess relatedly, why does one refer to &self and the other as a NonNull<Self>?

Writing &self means that the "self parameter" has type &Self, which in this case is the same as &MmWithUser.

The type NonNull<Self> is the same as NonNull<MmWithUser>. The NonNull type is a raw pointer that can't be null. Other than the non-null requirement, nothing is assumed about the raw pointer.

Quoted 4 lines

I'm guessing as a non-rust person a 'reference' is like a C++ reference in the sense that (well it is _assumed_ in C++ anyway) it acts like a pointer for the type which should never not be there, but we need .as_raw() to get the raw C pointer?

Yeah, Rust references come with an assumption that the object is not deallocated while the reference exists.

The .as_raw() call converts from &MmWithUser to *mut bindings::mm_struct. So note that it not only converts from reference to raw pointer, but it also changes the target type from MmWithUser to bindings::mm_struct.

Quoted 3 lines

And I guess in the dec_ref() case we need the .cast().as_ptr() because obj 'boxes' around self (I guess equivalent to 'this' in C++ kinda) guaranteeing that it can provide non-null pointer to the current object?

Well, the thing that is equivalent to "this" would be "self".

Quoted 4 lines
Quoted 4 lines
rust/kernel/mm.rs new file +4 -0
+// Make all `Mm` methods available on `MmWithUser`.
+impl Deref for MmWithUser {
+    type Target = Mm;
+
Quoted 8 lines

rust/kernel/mm.rs line 96

Quoted 5 lines
rust/kernel/mm.rs new file +5 -0
+    #[inline]
+    fn deref(&self) -> &Mm {
+        &self.mm
+    }
+}

I rubber ducked myself a bit on this, so I guess this makes it possible to dereference the object, and it

It lets you transparently obtain an &Mm from an &MmWithUser, making all Mm methods available on MmWithUser.

Quoted 34 lines

rust/kernel/mm.rs line 107

Quoted 10 lines
rust/kernel/mm.rs new file +10 -0
+// These methods are safe to call even if `mm_users` is zero.
+impl Mm {
+    /// Call `mmgrab` on `current.mm`.
+    #[inline]
+    pub fn mmgrab_current() -> Option<ARef<Mm>> {
+        // SAFETY: It's safe to get the `mm` field from current.
+        let mm = unsafe {
+            let current = bindings::get_current();
+            (*current).mm
+        };

I don't see an equivalent means of obtaining mm from current for MmWithUser, is that intentional, would there be another means of obtaining an mm? (perhaps via vma->vm_mm I guess?)

An aside -->

If we're grabbing from current, and this is non-NULL (i.e. not a kernel thread), this is kinda MmWithUser to _start out_ with, but I guess if you're grabbing the current one you might not expect it.

I guess one thing I want to point out (maybe here is wrong place) is that the usual way of interacting with current->mm is that we do _not_ increment mm->mm_count, mm->mm_users or any refernce count, as while we are in the kernel portion of the task, we are guaranteed the mm and the backing virtual address space will stick around.

With reference to MmWithUser, in fact, if you look up users of mmget()/mmput() it is pretty rare to do that.

So ideally we'd avoid doing this if we could (though having the semantics of grabbing a reference if we were to copy the object somehow again or hold its state or something would be nice).

Quoted 5 lines

I guess this might actually be tricky in rust, because we'd probably need to somehow express the current task's lifetime and tie this to that and... yeah.

<-- aside

Ah, yeah, I guess this API is incomplete. We could have an API that lets you obtain an &MmWithUser instead. Then, if the user wants to increment the refcount, they can manually convert that into an ARef<Mm> or ARef<MmWithUser>.

It's true that it's slightly tricky to express in Rust, but it's possible. We already have a way to get a &Task pointing at current.

Quoted 4 lines
Quoted 4 lines
rust/kernel/mm.rs new file +4 -0
+
+        if mm.is_null() {
+            return None;
+        }
Quoted 8 lines

rust/kernel/mm.rs line 116

Quoted 5 lines
rust/kernel/mm.rs new file +5 -0
+
+        // SAFETY: The value of `current->mm` is guaranteed to be null or a valid `mm_struct`. We
+        // just checked that it's not null. Furthermore, the returned `&Mm` is valid only for the
+        // duration of this function, and `current->mm` will stay valid for that long.
+        let mm = unsafe { Mm::from_raw(mm) };

Hm does mm now reference something with a different type, as in before it was a 'raw' pointer or such, and now it's a reference to an Mm right?

Yes ... this is using shadowing to change the type of the variable. It's actually rather common in Rust.

The former mm variable had type *mut bindings::mm_struct. The latter mm variable has type &Mm.

Quoted 3 lines

Also I guess the 'duration of this function' is because we put this in the 'Aref' smart pointer which kinda takes over the lifetime of the reference by wrapping it right?

Yeah, basically, the lifetime gets inferred from how we use it.

Quoted 11 lines

I mean I'm not a rust person so actually I have no business _commenting_ on this :P as this may very well be idiomatic rust, but I'm just curious about this.

It's nitty but I feel like maybe we're somewhat overloading 'mm's here a bit though? As we have our wrapped Mm type and then an internal raw mm type. On the other hand, it's hard to now have horribly awkward and confusing naming here I guess, and perhaps this is fine.

Not a big deal though!

Quoted 8 lines

rust/kernel/mm.rs line 119

Quoted 3 lines
rust/kernel/mm.rs new file +3 -0
+
+        // This increments the refcount using `mmgrab`.
+        Some(ARef::from(mm))

So I get that Some() means this is like a discriminated union or such, where we can return None (as above) or Some, which contains the value is of type ARef<Mm>. And I guess this moves the 'lifetime' of mm which was previously with the function into that of the ARef<>?

Yes, Some() is normally a discriminated union, but in this particular case since ARef uses a NonNull pointer for its only field, the compiler is smart enough to represent None as a null pointer instead of using a discriminated union with a separate tag.

As for the "lifetime" of the mm, that's not really the lifetime of the mm_struct. Rather, it's the duration for which the &Mm reference is assumed to be valid for. That lifetime ends right after the ARef::from call, because that's our last use of the &Mm.

Quoted 1 line

Does the ARef<> 'just know' to use the AlwaysRefCounted methods?

Yep! See e.g. the destructor of ARef:

impl<T: AlwaysRefCounted> Drop for ARef<T> {
    fn drop(&mut self) {
        unsafe { T::dec_ref(self.ptr) };
    }
}

Due to the T: AlwaysRefCounted, the type T must be a type that implements the AlwaysRefCounted trait, and the compiler is able to resolve T::dec_ref based on that.

Quoted 9 lines

rust/kernel/mm.rs line 126

Quoted 7 lines
rust/kernel/mm.rs new file +7 -0
+    }
+
+    /// Returns a raw pointer to the inner `mm_struct`.
+    #[inline]
+    pub fn as_raw(&self) -> *mut bindings::mm_struct {
+        self.mm.get()
+    }

I guess this .get() method is on the Opaque<> object and returns a raw ptr?

Yes, it just creates a raw pointer.

Quoted 11 lines

rust/kernel/mm.rs line 135

Quoted 8 lines
rust/kernel/mm.rs new file +8 -0
+    /// Obtain a reference from a raw pointer.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that `ptr` points at an `mm_struct`, and that it is not deallocated
+    /// during the lifetime 'a.
+    #[inline]
+    pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a Mm {

I'm guessing this funny 'a syntax, based on the comment, refers to the lifetime of the object?

It's a lifetime, but not necessarily the lifetime of the object. Rather, it's the maximum duration in which the reference is assumed to be valid. It must not be longer than the lifetime of the mm_struct of course, but it's usually going to be much shorter than the lifetime of the mm_struct.

Quoted 9 lines

rust/kernel/mm.rs line 137

Quoted 2 lines
rust/kernel/mm.rs new file +2 -0
+        // SAFETY: Caller promises that the pointer is valid for 'a. Layouts are compatible due to
+        // repr(transparent).

God I love these SAFETY comments (I mean actually, sorry I realise it's almost impossible to convey 'not sarcastically, actually' in text form :). Is that something that gets parsed somewhere, or a convention or?

I like that there is a discipline of expressing under what circumstances we are permitted to reference things.

They don't get parsed anywhere, except that not using a SAFETY comment at all is a compilation warning.

Quoted 14 lines

rust/kernel/mm.rs line 143

Quoted 6 lines
rust/kernel/mm.rs new file +6 -0
+        unsafe { &*ptr.cast() }
+    }
+
+    /// Calls `mmget_not_zero` and returns a handle if it succeeds.
+    #[inline]
+    pub fn mmget_not_zero(&self) -> Option<ARef<MmWithUser>> {

I actually kinda love that this takes an mm and guarantees that you get an MmWithUser out of it which is implied by the fact this succeeds.

However as to the point above, I'm concerned that this might be seen as 'the way' to access an mm, i.e. mm.mmgrab_current().mmget_not_zero() or something.

Quoted 7 lines

Whereas, the usual way of referencing current->mm is to not increment any reference counts at all (assuming what you are doing resides in the same lifetime as the task).

Obviously if you step outside of that lifetime, then you _do_ have to pin the mm (nearly always you want to grab rather than get though in that circumstance).

I can add a way to obtain an &MmWithUser from current without incrementing the refcount.

Quoted 9 lines

rust/kernel/mm.rs line 149

Quoted 6 lines
rust/kernel/mm.rs new file +6 -0
+        // SAFETY: The pointer is valid since self is a reference.
+        let success = unsafe { bindings::mmget_not_zero(self.as_raw()) };
+
+        if success {
+            // SAFETY: We just created an `mmget` refcount.
+            Some(unsafe { ARef::from_raw(NonNull::new_unchecked(self.as_raw().cast())) })

When you do this, does it cause the reference count to increment, or does it assume it's already at 1?

This uses from_raw which by convention never increments the refcount. Semantically we're taking ownership of the increment performed by bindings::mmget_not_zero.

Quoted 15 lines
Quoted 15 lines
rust/kernel/mm.rs new file +15 -0
+        } else {
+            None
+        }
+    }
+}
+
+// These methods require `mm_users` to be non-zero.
+impl MmWithUser {
+    /// Obtain a reference from a raw pointer.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that `ptr` points at an `mm_struct`, and that `mm_users` remains
+    /// non-zero for the duration of the lifetime 'a.
+    #[inline]
Quoted 8 lines

rust/kernel/mm.rs line 169

Quoted 5 lines
rust/kernel/mm.rs new file +5 -0
+    pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser {
+        // SAFETY: Caller promises that the pointer is valid for 'a. The layout is compatible due
+        // to repr(transparent).
+        unsafe { &*ptr.cast() }
+    }

I guess this is another means by which you can get the mm. I'd say an equivalent for getting from current is highly relevant.

This lets you write MmWithUser::from_raw in unsafe code.

Quoted 6 lines
Quoted 6 lines
rust/kernel/mm.rs new file +6 -0
+
+    /// Lock the mmap read lock.
+    #[inline]
+    pub fn mmap_read_lock(&self) -> MmapReadGuard<'_> {
+        // SAFETY: The pointer is valid since self is a reference.
+        unsafe { bindings::mmap_read_lock(self.as_raw()) };
Quoted 8 lines

rust/kernel/mm.rs line 180

Quoted 5 lines
rust/kernel/mm.rs new file +5 -0
+
+        // INVARIANT: We just acquired the read lock.
+        MmapReadGuard {
+            mm: self,
+            _nts: NotThreadSafe,

I'm sure this is a rusty thing, but curious as to why this is like that? What is '_nts', etc.?

_nts is the name of a field. The NotThreadSafe type has size zero, so it doesn't exist in the compiled code. It exists only to mark that the MmapReadGuard cannot be transferred across thread boundaries.

Quoted 34 lines
Quoted 34 lines
rust/kernel/mm.rs new file +34 -0
+        }
+    }
+
+    /// Try to lock the mmap read lock.
+    #[inline]
+    pub fn mmap_read_trylock(&self) -> Option<MmapReadGuard<'_>> {
+        // SAFETY: The pointer is valid since self is a reference.
+        let success = unsafe { bindings::mmap_read_trylock(self.as_raw()) };
+
+        if success {
+            // INVARIANT: We just acquired the read lock.
+            Some(MmapReadGuard {
+                mm: self,
+                _nts: NotThreadSafe,
+            })
+        } else {
+            None
+        }
+    }
+}
+
+/// A guard for the mmap read lock.
+///
+/// # Invariants
+///
+/// This `MmapReadGuard` guard owns the mmap read lock.
+pub struct MmapReadGuard<'a> {
+    mm: &'a MmWithUser,
+    // `mmap_read_lock` and `mmap_read_unlock` must be called on the same thread
+    _nts: NotThreadSafe,
+}
+
+impl Drop for MmapReadGuard<'_> {
+    #[inline]
Quoted 8 lines

rust/kernel/mm.rs line 219

Quoted 5 lines
rust/kernel/mm.rs new file +5 -0
+    fn drop(&mut self) {
+        // SAFETY: We hold the read lock by the type invariants.
+        unsafe { bindings::mmap_read_unlock(self.mm.as_raw()) };
+    }
+}

Ah that's nice, an actual guard for it :) I'm guessing the fact this implements the guard implies that you _must_ hold the lock first right?

Yeah so this code runs when a variable of type MmapReadGuard goes out of scope. We don't provide any way to obtain an MmapReadGuard without locking the mmap read guard.

Quoted 8 lines
Quoted 4 lines

--
2.47.0.371.ga323438b13-goog

Sorry for the numerous questions, I'm afraid there'll be a lot of this for rust stuff for the time being. Perhaps advent of code will help improve things on the rust front for me ;)

Thanks for all the excellent questions!

Alice

#4 lore raw

Re: [PATCH v8 1/7] mm: rust: add abstraction for struct mm_struct

I'm generally fine with this patch (other than rust specifics which I leave to the rust experts), however I'm a little concerned about us taking reference counts when we don't need to so this is something I'd like to see addressed for v9 or, at least to be confident we're not doing this in the binder code unnecessarily.

Thanks!

Quoted 9 lines · Alice Ryhl

On Wed, Nov 20, 2024 at 7:13 PM Lorenzo Stoakes

Quoted 6 lines

rust/helpers/mm.c line 39

Quoted 4 lines
rust/helpers/mm.c new file +4 -0
+void rust_helper_mmap_read_unlock(struct mm_struct *mm)
+{
+     mmap_read_unlock(mm);
+}

I guess at this point we're only interested in reading?

Yeah. The write lock would be very similar.

Ack

Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
rust/kernel/lib.rs +0 -0
index 66f5cde7f322..cc1963510cdf 100644

...

Quoted 22 lines
Quoted 10 lines

rust/kernel/lib.rs

Quoted 5 lines
rust/kernel/lib.rs +5 -0
+/// [`mmget_not_zero`]: Mm::mmget_not_zero
+#[repr(transparent)]
+pub struct Mm {
+    mm: Opaque<bindings::mm_struct>,
+}

Does this tie this type to the C struct mm_struct type?

Does 'Opaque' mean it is a pointer to a type which is 'opaque' in the sense that rust can't see into its internals?

This declaration defines a Rust type called Mm which has the same size, alignment, and contents as struct mm_struct. The purpose of Opaque is to tell Rust that it can't assume anything about the contents at all; we do that to leave it up to C.

For example, normally if you have an immutable reference &i32, then Rust is going to assume that the contents behind the reference are in fact immutable. Opaque turns that off, meaning that an &Opaque<i32> is allowed to reference an integer as it gets modified. It makes all access to the contents unsafe, though.

Quoted 3 lines

Note that Opaque is *not* a pointer type. We're going to be dealing with types like &Mm or ARef<Mm> where &_ and ARef<_> are two different kinds of pointers.

OK so when you reference Mm.mm that is in effect referencing the struct mm_struct object rather than a pointer to a struct mm_struct? and

Quoted 29 lines
Quoted 14 lines
Quoted 14 lines
rust/kernel/lib.rs +13 -0
+// SAFETY: It is safe to call `mmdrop` on another thread than where `mmgrab` was called.
+unsafe impl Send for Mm {}
+// SAFETY: All methods on `Mm` can be called in parallel from several threads.
+unsafe impl Sync for Mm {}
+
+// SAFETY: By the type invariants, this type is always refcounted.
+unsafe impl AlwaysRefCounted for Mm {
+    #[inline]
+    fn inc_ref(&self) {
+        // SAFETY: The pointer is valid since self is a reference.
+        unsafe { bindings::mmgrab(self.as_raw()) };
+    }
+
Quoted 8 lines

rust/kernel/lib.rs

Quoted 6 lines
rust/kernel/lib.rs +6 -0
+    #[inline]
+    unsafe fn dec_ref(obj: NonNull<Self>) {
+        // SAFETY: The caller is giving up their refcount.
+        unsafe { bindings::mmdrop(obj.cast().as_ptr()) };
+    }
+}

Under what circumstances would these be taken? Same question for MmWthUser.

This makes Mm compatible with the pointer type called ARef<_>. This pointer type is used to represent ownership of a refcount. So whenever a variable of type ARef<_> goes out of scope, the refcount is decremented, and whenever an ARef<_> is cloned, the refcount is incremented.

Quoted 4 lines

The way this works is that ARef<_> is implemented to use the AlwaysRefCounted trait to understand how to manipulate the count. Only types that implement the trait with an impl block like above can be used with ARef<_>.

OK so when you first instantiate an ARef<_> you don't increment the reference count, only if it is cloned from there on in?

Quoted 21 lines
Quoted 21 lines
Quoted 7 lines
rust/kernel/lib.rs +6 -0
+
+/// A wrapper for the kernel's `struct mm_struct`.
+///
+/// This type is like [`Mm`], but with non-zero `mm_users`. It can only be used when `mm_users` can
+/// be proven to be non-zero at compile-time, usually because the relevant code holds an `mmget`
+/// refcount. It can be used to access the associated address space.

rust/kernel/lib.rs

Quoted 10 lines
rust/kernel/lib.rs +10 -0
+///
+/// The `ARef<MmWithUser>` smart pointer holds an `mmget` refcount. Its destructor may sleep.
+///
+/// # Invariants
+///
+/// Values of this type are always refcounted using `mmget`. The value of `mm_users` is non-zero.
+#[repr(transparent)]
+pub struct MmWithUser {
+    mm: Mm,
+}

Why does Mm have this as a Opaque<bindings::mm_struct> and this sort of nests it?

Quoted 4 lines
Quoted 2 lines

Does this somehow amount to the same thing, or would you probably never actually reference this mm field?

It amounts to the same thing as Opaque<bindings::mm_struct>.

Ack.

Quoted 22 lines
Quoted 13 lines
Quoted 13 lines
rust/kernel/lib.rs +12 -0
+// SAFETY: It is safe to call `mmput` on another thread than where `mmget` was called.
+unsafe impl Send for MmWithUser {}
+// SAFETY: All methods on `MmWithUser` can be called in parallel from several threads.
+unsafe impl Sync for MmWithUser {}
+
+// SAFETY: By the type invariants, this type is always refcounted.
+unsafe impl AlwaysRefCounted for MmWithUser {
+    #[inline]
+    fn inc_ref(&self) {
+        // SAFETY: The pointer is valid since self is a reference.
+        unsafe { bindings::mmget(self.as_raw()) };
+    }
Quoted 8 lines

rust/kernel/lib.rs

Quoted 6 lines
rust/kernel/lib.rs +6 -0
+
+    #[inline]
+    unsafe fn dec_ref(obj: NonNull<Self>) {
+        // SAFETY: The caller is giving up their refcount.
+        unsafe { bindings::mmput(obj.cast().as_ptr()) };
+    }

Hm, why is it we mmget(self.as_raw()) but mmput(obj.cast().as_ptr())?

Quoted 4 lines

There's one assumption about references that Opaque doesn't turn off:
The memory behind the reference must not get deallocated while the reference exists. We can't use a reference in dec_ref because the memory might get deallocated during the call to dec_ref.

OK I see.

Quoted 10 lines
Quoted 3 lines

Also I guess relatedly, why does one refer to &self and the other as a NonNull<Self>?

Writing &self means that the "self parameter" has type &Self, which in this case is the same as &MmWithUser.

The type NonNull<Self> is the same as NonNull<MmWithUser>. The NonNull type is a raw pointer that can't be null. Other than the non-null requirement, nothing is assumed about the raw pointer.

Ack

Quoted 8 lines
Quoted 5 lines

I'm guessing as a non-rust person a 'reference' is like a C++ reference in the sense that (well it is _assumed_ in C++ anyway) it acts like a pointer for the type which should never not be there, but we need .as_raw() to get the raw C pointer?

Yeah, Rust references come with an assumption that the object is not deallocated while the reference exists.

Makes sense.

Quoted 5 lines

The .as_raw() call converts from &MmWithUser to *mut bindings::mm_struct. So note that it not only converts from reference to raw pointer, but it also changes the target type from MmWithUser to bindings::mm_struct.

Ah I see.

Quoted 6 lines
Quoted 4 lines

And I guess in the dec_ref() case we need the .cast().as_ptr() because obj 'boxes' around self (I guess equivalent to 'this' in C++ kinda) guaranteeing that it can provide non-null pointer to the current object?

Well, the thing that is equivalent to "this" would be "self".

Yeah, but in this case we actually need the 'only assume we have a non-null pointer' value obj, which we cast to a pointer. OK cull.

Quoted 14 lines
Quoted 13 lines

rust/kernel/lib.rs

Quoted 10 lines
rust/kernel/lib.rs +9 -0
+// Make all `Mm` methods available on `MmWithUser`.
+impl Deref for MmWithUser {
+    type Target = Mm;
+
+    #[inline]
+    fn deref(&self) -> &Mm {
+        &self.mm
+    }
+}

I rubber ducked myself a bit on this, so I guess this makes it possible to dereference the object, and it

Quoted 2 lines

It lets you transparently obtain an &Mm from an &MmWithUser, making all Mm methods available on MmWithUser.

Hm did I not finish my sentence haha. Yeah I think I kind of rubber ducked myself further and saw that this was the case.

Quoted 41 lines
Quoted 35 lines

rust/kernel/lib.rs

Quoted 11 lines
rust/kernel/lib.rs +10 -0
+// These methods are safe to call even if `mm_users` is zero.
+impl Mm {
+    /// Call `mmgrab` on `current.mm`.
+    #[inline]
+    pub fn mmgrab_current() -> Option<ARef<Mm>> {
+        // SAFETY: It's safe to get the `mm` field from current.
+        let mm = unsafe {
+            let current = bindings::get_current();
+            (*current).mm
+        };

I don't see an equivalent means of obtaining mm from current for MmWithUser, is that intentional, would there be another means of obtaining an mm? (perhaps via vma->vm_mm I guess?)

An aside -->

If we're grabbing from current, and this is non-NULL (i.e. not a kernel thread), this is kinda MmWithUser to _start out_ with, but I guess if you're grabbing the current one you might not expect it.

I guess one thing I want to point out (maybe here is wrong place) is that the usual way of interacting with current->mm is that we do _not_ increment mm->mm_count, mm->mm_users or any refernce count, as while we are in the kernel portion of the task, we are guaranteed the mm and the backing virtual address space will stick around.

With reference to MmWithUser, in fact, if you look up users of mmget()/mmput() it is pretty rare to do that.

So ideally we'd avoid doing this if we could (though having the semantics of grabbing a reference if we were to copy the object somehow again or hold its state or something would be nice).

Quoted 5 lines

I guess this might actually be tricky in rust, because we'd probably need to somehow express the current task's lifetime and tie this to that and... yeah.

<-- aside

Quoted 7 lines

Ah, yeah, I guess this API is incomplete. We could have an API that lets you obtain an &MmWithUser instead. Then, if the user wants to increment the refcount, they can manually convert that into an ARef<Mm> or ARef<MmWithUser>.

It's true that it's slightly tricky to express in Rust, but it's possible. We already have a way to get a &Task pointing at current.

Yeah, but I think we should do this incrementally as I want this initial series to merge first, after which we can tweak things.

Quoted 15 lines
Quoted 14 lines

rust/kernel/lib.rs

Quoted 11 lines
rust/kernel/lib.rs +9 -0
+
+        if mm.is_null() {
+            return None;
+        }
+
+        // SAFETY: The value of `current->mm` is guaranteed to be null or a valid `mm_struct`. We
+        // just checked that it's not null. Furthermore, the returned `&Mm` is valid only for the
+        // duration of this function, and `current->mm` will stay valid for that long.
+        let mm = unsafe { Mm::from_raw(mm) };

Hm does mm now reference something with a different type, as in before it was a 'raw' pointer or such, and now it's a reference to an Mm right?

Quoted 5 lines

Yes ... this is using shadowing to change the type of the variable. It's actually rather common in Rust.

The former mm variable had type *mut bindings::mm_struct. The latter mm variable has type &Mm.

Ack yeah I wondered if this might be an idiomatic rust thing.

Quoted 6 lines
Quoted 4 lines

Also I guess the 'duration of this function' is because we put this in the 'Aref' smart pointer which kinda takes over the lifetime of the reference by wrapping it right?

Yeah, basically, the lifetime gets inferred from how we use it.

Interesting, I do like this 'compiler consciously aware of lifetimes' thing.

Quoted 21 lines
Quoted 12 lines

I mean I'm not a rust person so actually I have no business _commenting_ on this :P as this may very well be idiomatic rust, but I'm just curious about this.

It's nitty but I feel like maybe we're somewhat overloading 'mm's here a bit though? As we have our wrapped Mm type and then an internal raw mm type. On the other hand, it's hard to now have horribly awkward and confusing naming here I guess, and perhaps this is fine.

Not a big deal though!

Quoted 8 lines

rust/kernel/lib.rs

Quoted 3 lines
rust/kernel/lib.rs +3 -0
+
+        // This increments the refcount using `mmgrab`.
+        Some(ARef::from(mm))

So I get that Some() means this is like a discriminated union or such, where we can return None (as above) or Some, which contains the value is of type ARef<Mm>. And I guess this moves the 'lifetime' of mm which was previously with the function into that of the ARef<>?

Quoted 4 lines

Yes, Some() is normally a discriminated union, but in this particular case since ARef uses a NonNull pointer for its only field, the compiler is smart enough to represent None as a null pointer instead of using a discriminated union with a separate tag.

Ohhhh nice!

Quoted 5 lines

As for the "lifetime" of the mm, that's not really the lifetime of the mm_struct. Rather, it's the duration for which the &Mm reference is assumed to be valid for. That lifetime ends right after the ARef::from call, because that's our last use of the &Mm.

Ack.

Quoted 11 lines
Quoted 2 lines

Does the ARef<> 'just know' to use the AlwaysRefCounted methods?

Yep! See e.g. the destructor of ARef:

impl<T: AlwaysRefCounted> Drop for ARef<T> {
    fn drop(&mut self) {
        unsafe { T::dec_ref(self.ptr) };
    }
}
Quoted 3 lines

Due to the T: AlwaysRefCounted, the type T must be a type that implements the AlwaysRefCounted trait, and the compiler is able to resolve T::dec_ref based on that.

Ah so this is mandatory for using an ARef<> in general then?

Quoted 9 lines
Quoted 9 lines
Quoted 8 lines
rust/kernel/lib.rs +7 -0
+    }
+
+    /// Returns a raw pointer to the inner `mm_struct`.
+    #[inline]
+    pub fn as_raw(&self) -> *mut bindings::mm_struct {
+        self.mm.get()
+    }
Quoted 3 lines
Quoted 1 line

I guess this .get() method is on the Opaque<> object and returns a raw ptr?

Yes, it just creates a raw pointer.

Ack

Quoted 10 lines
Quoted 10 lines
Quoted 9 lines
rust/kernel/lib.rs +8 -0
+    /// Obtain a reference from a raw pointer.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that `ptr` points at an `mm_struct`, and that it is not deallocated
+    /// during the lifetime 'a.
+    #[inline]
+    pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a Mm {
Quoted 8 lines
Quoted 2 lines

I'm guessing this funny 'a syntax, based on the comment, refers to the lifetime of the object?

It's a lifetime, but not necessarily the lifetime of the object. Rather, it's the maximum duration in which the reference is assumed to be valid. It must not be longer than the lifetime of the mm_struct of course, but it's usually going to be much shorter than the lifetime of the mm_struct.

Ack, I like how explicit this is...

Quoted 8 lines
Quoted 8 lines

rust/kernel/lib.rs

Quoted 3 lines
rust/kernel/lib.rs +2 -0
+        // SAFETY: Caller promises that the pointer is valid for 'a. Layouts are compatible due to
+        // repr(transparent).

God I love these SAFETY comments (I mean actually, sorry I realise it's almost impossible to convey 'not sarcastically, actually' in text form :). Is that something that gets parsed somewhere, or a convention or?

Quoted 5 lines
Quoted 2 lines

I like that there is a discipline of expressing under what circumstances we are permitted to reference things.

They don't get parsed anywhere, except that not using a SAFETY comment at all is a compilation warning.

Ah, nice!

Quoted 19 lines
Quoted 19 lines

rust/kernel/lib.rs

Quoted 7 lines
rust/kernel/lib.rs +6 -0
+        unsafe { &*ptr.cast() }
+    }
+
+    /// Calls `mmget_not_zero` and returns a handle if it succeeds.
+    #[inline]
+    pub fn mmget_not_zero(&self) -> Option<ARef<MmWithUser>> {

I actually kinda love that this takes an mm and guarantees that you get an MmWithUser out of it which is implied by the fact this succeeds.

However as to the point above, I'm concerned that this might be seen as 'the way' to access an mm, i.e. mm.mmgrab_current().mmget_not_zero() or something.

Whereas, the usual way of referencing current->mm is to not increment any reference counts at all (assuming what you are doing resides in the same lifetime as the task).

Quoted 6 lines
Quoted 3 lines

Obviously if you step outside of that lifetime, then you _do_ have to pin the mm (nearly always you want to grab rather than get though in that circumstance).

I can add a way to obtain an &MmWithUser from current without incrementing the refcount.

Yeah, I feel like we definitely need this.

However we'd need to _not_ drop the refcount when it goes out of scope too in this case.

I'm not sure how you'd express that, however.

Quoted 8 lines
Quoted 8 lines
Quoted 7 lines
rust/kernel/lib.rs +6 -0
+        // SAFETY: The pointer is valid since self is a reference.
+        let success = unsafe { bindings::mmget_not_zero(self.as_raw()) };
+
+        if success {
+            // SAFETY: We just created an `mmget` refcount.
+            Some(unsafe { ARef::from_raw(NonNull::new_unchecked(self.as_raw().cast())) })
Quoted 6 lines
Quoted 2 lines

When you do this, does it cause the reference count to increment, or does it assume it's already at 1?

This uses from_raw which by convention never increments the refcount. Semantically we're taking ownership of the increment performed by bindings::mmget_not_zero.

Cool, good!

Though as above, we definitely need a way to get this without fiddling with reference count.

Quoted 25 lines
Quoted 16 lines
Quoted 16 lines
rust/kernel/lib.rs +15 -0
+        } else {
+            None
+        }
+    }
+}
+
+// These methods require `mm_users` to be non-zero.
+impl MmWithUser {
+    /// Obtain a reference from a raw pointer.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that `ptr` points at an `mm_struct`, and that `mm_users` remains
+    /// non-zero for the duration of the lifetime 'a.
+    #[inline]
Quoted 8 lines

rust/kernel/lib.rs

Quoted 5 lines
rust/kernel/lib.rs +5 -0
+    pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser {
+        // SAFETY: Caller promises that the pointer is valid for 'a. The layout is compatible due
+        // to repr(transparent).
+        unsafe { &*ptr.cast() }
+    }

I guess this is another means by which you can get the mm. I'd say an equivalent for getting from current is highly relevant.

Quoted 1 line

This lets you write MmWithUser::from_raw in unsafe code.

Ack.

Quoted 16 lines
Quoted 15 lines

rust/kernel/lib.rs

Quoted 12 lines
rust/kernel/lib.rs +11 -0
+
+    /// Lock the mmap read lock.
+    #[inline]
+    pub fn mmap_read_lock(&self) -> MmapReadGuard<'_> {
+        // SAFETY: The pointer is valid since self is a reference.
+        unsafe { bindings::mmap_read_lock(self.as_raw()) };
+
+        // INVARIANT: We just acquired the read lock.
+        MmapReadGuard {
+            mm: self,
+            _nts: NotThreadSafe,

I'm sure this is a rusty thing, but curious as to why this is like that? What is '_nts', etc.?

Quoted 3 lines

_nts is the name of a field. The NotThreadSafe type has size zero, so it doesn't exist in the compiled code. It exists only to mark that the MmapReadGuard cannot be transferred across thread boundaries.

Ah right I see, wanting compiler-specific behaviour from the type but not to actually modify the compiled object in reality.

Quoted 44 lines
Quoted 35 lines
Quoted 35 lines
rust/kernel/lib.rs +34 -0
+        }
+    }
+
+    /// Try to lock the mmap read lock.
+    #[inline]
+    pub fn mmap_read_trylock(&self) -> Option<MmapReadGuard<'_>> {
+        // SAFETY: The pointer is valid since self is a reference.
+        let success = unsafe { bindings::mmap_read_trylock(self.as_raw()) };
+
+        if success {
+            // INVARIANT: We just acquired the read lock.
+            Some(MmapReadGuard {
+                mm: self,
+                _nts: NotThreadSafe,
+            })
+        } else {
+            None
+        }
+    }
+}
+
+/// A guard for the mmap read lock.
+///
+/// # Invariants
+///
+/// This `MmapReadGuard` guard owns the mmap read lock.
+pub struct MmapReadGuard<'a> {
+    mm: &'a MmWithUser,
+    // `mmap_read_lock` and `mmap_read_unlock` must be called on the same thread
+    _nts: NotThreadSafe,
+}
+
+impl Drop for MmapReadGuard<'_> {
+    #[inline]
Quoted 8 lines

rust/kernel/lib.rs

Quoted 5 lines
rust/kernel/lib.rs +5 -0
+    fn drop(&mut self) {
+        // SAFETY: We hold the read lock by the type invariants.
+        unsafe { bindings::mmap_read_unlock(self.mm.as_raw()) };
+    }
+}

Ah that's nice, an actual guard for it :) I'm guessing the fact this implements the guard implies that you _must_ hold the lock first right?

Quoted 3 lines

Yeah so this code runs when a variable of type MmapReadGuard goes out of scope. We don't provide any way to obtain an MmapReadGuard without locking the mmap read guard.

Delightful!

Quoted 11 lines
Quoted 9 lines
Quoted 5 lines

--
2.47.0.371.ga323438b13-goog

Sorry for the numerous questions, I'm afraid there'll be a lot of this for rust stuff for the time being. Perhaps advent of code will help improve things on the rust front for me ;)

Thanks for all the excellent questions!

Thanks for taking the time to answer them!

Quoted 2 lines

Alice

author maintainer
#5 lore raw

Re: [PATCH v8 1/7] mm: rust: add abstraction for struct mm_struct

Quoted 8 lines · Lorenzo Stoakes

I'm generally fine with this patch (other than rust specifics which I leave to the rust experts), however I'm a little concerned about us taking reference counts when we don't need to so this is something I'd like to see addressed for v9 or, at least to be confident we're not doing this in the binder code unnecessarily.

Thanks!

The refcount increment is *not* unnecessary in Binder. For the C equivalent, see the implementation of binder_alloc_init. It's used because Binder will access the mm of the recipient from the sender's scope, so it must hold on to an mm_struct reference.

Quoted 22 lines
Quoted 22 lines
Quoted 10 lines

rust/kernel/mm.rs line 30

Quoted 5 lines
rust/kernel/mm.rs new file +5 -0
+/// [`mmget_not_zero`]: Mm::mmget_not_zero
+#[repr(transparent)]
+pub struct Mm {
+    mm: Opaque<bindings::mm_struct>,
+}

Does this tie this type to the C struct mm_struct type?

Does 'Opaque' mean it is a pointer to a type which is 'opaque' in the sense that rust can't see into its internals?

This declaration defines a Rust type called Mm which has the same size, alignment, and contents as struct mm_struct. The purpose of Opaque is to tell Rust that it can't assume anything about the contents at all; we do that to leave it up to C.

For example, normally if you have an immutable reference &i32, then Rust is going to assume that the contents behind the reference are in fact immutable. Opaque turns that off, meaning that an &Opaque<i32> is allowed to reference an integer as it gets modified. It makes all access to the contents unsafe, though.

Quoted 6 lines
Quoted 3 lines

Note that Opaque is *not* a pointer type. We're going to be dealing with types like &Mm or ARef<Mm> where &_ and ARef<_> are two different kinds of pointers.

OK so when you reference Mm.mm that is in effect referencing the struct mm_struct object rather than a pointer to a struct mm_struct? and

Yes.

Quoted 23 lines
Quoted 23 lines
Quoted 8 lines
Quoted 8 lines
rust/kernel/mm.rs new file +8 -0
+// SAFETY: By the type invariants, this type is always refcounted.
+unsafe impl AlwaysRefCounted for Mm {
+    #[inline]
+    fn inc_ref(&self) {
+        // SAFETY: The pointer is valid since self is a reference.
+        unsafe { bindings::mmgrab(self.as_raw()) };
+    }
+
Quoted 8 lines

rust/kernel/mm.rs line 50

Quoted 6 lines
rust/kernel/mm.rs new file +6 -0
+    #[inline]
+    unsafe fn dec_ref(obj: NonNull<Self>) {
+        // SAFETY: The caller is giving up their refcount.
+        unsafe { bindings::mmdrop(obj.cast().as_ptr()) };
+    }
+}

Under what circumstances would these be taken? Same question for MmWthUser.

This makes Mm compatible with the pointer type called ARef<_>. This pointer type is used to represent ownership of a refcount. So whenever a variable of type ARef<_> goes out of scope, the refcount is decremented, and whenever an ARef<_> is cloned, the refcount is incremented.

Quoted 7 lines
Quoted 4 lines

The way this works is that ARef<_> is implemented to use the AlwaysRefCounted trait to understand how to manipulate the count. Only types that implement the trait with an impl block like above can be used with ARef<_>.

OK so when you first instantiate an ARef<_> you don't increment the reference count, only if it is cloned from there on in?

Well it depends on which ARef constructor you are using. But the uses of ARef::from_raw do not increment the count.

Quoted 45 lines
Quoted 45 lines
Quoted 34 lines

rust/kernel/mm.rs line 107

Quoted 10 lines
rust/kernel/mm.rs new file +10 -0
+// These methods are safe to call even if `mm_users` is zero.
+impl Mm {
+    /// Call `mmgrab` on `current.mm`.
+    #[inline]
+    pub fn mmgrab_current() -> Option<ARef<Mm>> {
+        // SAFETY: It's safe to get the `mm` field from current.
+        let mm = unsafe {
+            let current = bindings::get_current();
+            (*current).mm
+        };

I don't see an equivalent means of obtaining mm from current for MmWithUser, is that intentional, would there be another means of obtaining an mm? (perhaps via vma->vm_mm I guess?)

An aside -->

If we're grabbing from current, and this is non-NULL (i.e. not a kernel thread), this is kinda MmWithUser to _start out_ with, but I guess if you're grabbing the current one you might not expect it.

I guess one thing I want to point out (maybe here is wrong place) is that the usual way of interacting with current->mm is that we do _not_ increment mm->mm_count, mm->mm_users or any refernce count, as while we are in the kernel portion of the task, we are guaranteed the mm and the backing virtual address space will stick around.

With reference to MmWithUser, in fact, if you look up users of mmget()/mmput() it is pretty rare to do that.

So ideally we'd avoid doing this if we could (though having the semantics of grabbing a reference if we were to copy the object somehow again or hold its state or something would be nice).

Quoted 5 lines

I guess this might actually be tricky in rust, because we'd probably need to somehow express the current task's lifetime and tie this to that and... yeah.

<-- aside

Ah, yeah, I guess this API is incomplete. We could have an API that lets you obtain an &MmWithUser instead. Then, if the user wants to increment the refcount, they can manually convert that into an ARef<Mm> or ARef<MmWithUser>.

Quoted 5 lines
Quoted 2 lines

It's true that it's slightly tricky to express in Rust, but it's possible. We already have a way to get a &Task pointing at current.

Yeah, but I think we should do this incrementally as I want this initial series to merge first, after which we can tweak things.

Rest assured that the API can be written to not automatically increment the refcount when accessing current. That's just binder's case.

Quoted 25 lines
Quoted 18 lines
Quoted 18 lines

rust/kernel/mm.rs line 143

Quoted 6 lines
rust/kernel/mm.rs new file +6 -0
+        unsafe { &*ptr.cast() }
+    }
+
+    /// Calls `mmget_not_zero` and returns a handle if it succeeds.
+    #[inline]
+    pub fn mmget_not_zero(&self) -> Option<ARef<MmWithUser>> {

I actually kinda love that this takes an mm and guarantees that you get an MmWithUser out of it which is implied by the fact this succeeds.

However as to the point above, I'm concerned that this might be seen as 'the way' to access an mm, i.e. mm.mmgrab_current().mmget_not_zero() or something.

Whereas, the usual way of referencing current->mm is to not increment any reference counts at all (assuming what you are doing resides in the same lifetime as the task).

Quoted 6 lines
Quoted 3 lines

Obviously if you step outside of that lifetime, then you _do_ have to pin the mm (nearly always you want to grab rather than get though in that circumstance).

I can add a way to obtain an &MmWithUser from current without incrementing the refcount.

Quoted 6 lines

Yeah, I feel like we definitely need this.

However we'd need to _not_ drop the refcount when it goes out of scope too in this case.

I'm not sure how you'd express that, however.

The way you express that is by giving the user a &Mm or &MmWithUser instead of giving the user an ARef<Mm> or ARef<MmWithUser>. Using a normal reference implies that you don't have ownership over the refcount, and the reference has no destructor when it goes out of scope. The only slightly tricky piece is tying the lifetime of that reference to the scope of the current task, but this is a problem with a known solution.

For more on this, see the discussion on the various versions of Christian's PidNamespace series:
https://lore.kernel.org/rust-for-linux/[email protected]/

Alice

#6 lore raw

Re: [PATCH v8 1/7] mm: rust: add abstraction for struct mm_struct

In reply to Lorenzo Stoakes
Quoted 2 lines · Lorenzo Stoakes

I will obviously inevitably ask a TON of questions as a result of not being a rust person so, bear with me...

I'm just a lurker on the rust-for-linux mailing list but... thanks *so much* Lorenzo and Alice for this thread. It's the best introduction to Rust idioms for kernel programmers I've ever seen.

Paolo

#7 lore raw

Re: [PATCH v8 1/7] mm: rust: add abstraction for struct mm_struct

Quoted 10 lines · Paolo Bonzini
Quoted 2 lines · Lorenzo Stoakes

I will obviously inevitably ask a TON of questions as a result of not being a rust person so, bear with me...

I'm just a lurker on the rust-for-linux mailing list but... thanks *so much* Lorenzo and Alice for this thread. It's the best introduction to Rust idioms for kernel programmers I've ever seen.

Paolo

Thanks :) I am merely asking questions from mm side, so all credit goes to Alice for her patient and detailed explanations! :)

author maintainer
#8 lore raw

PATCH v8 2/7 mm: rust: add vm_area_struct methods that require read access

In reply to Alice Ryhl

This adds a type called VmAreaRef which is used when referencing a vma that you have read access to. Here, read access means that you hold either the mmap read lock or the vma read lock (or stronger).

Additionally, a vma_lookup method is added to the mmap read guard, which enables you to obtain a &VmAreaRef in safe Rust code.

---
 rust/helpers/mm.c      |   6 ++
 rust/kernel/mm.rs      |  21 ++++++
 rust/kernel/mm/virt.rs | 171 +++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 198 insertions(+)
rust/helpers/mm.c +6 -0
index 7201747a5d31..7b72eb065a3e 100644
@@ -37,3 +37,9 @@ void rust_helper_mmap_read_unlock(struct mm_struct *mm)
 {
 	mmap_read_unlock(mm);
 }
+
+struct vm_area_struct *rust_helper_vma_lookup(struct mm_struct *mm,
+					      unsigned long addr)
+{
+	return vma_lookup(mm, addr);
+}
rust/kernel/mm.rs +21 -0
index 84cba581edaa..ace8e7d57afe 100644
@@ -12,6 +12,8 @@
 };
 use core::{ops::Deref, ptr::NonNull};
 
+pub mod virt;
+
 /// A wrapper for the kernel's `struct mm_struct`.
 ///
 /// Since `mm_users` may be zero, the associated address space may not exist anymore. You can use
@@ -210,6 +212,25 @@ pub struct MmapReadGuard<'a> {
     _nts: NotThreadSafe,
 }
 
+impl<'a> MmapReadGuard<'a> {
+    /// Look up a vma at the given address.
+    #[inline]
+    pub fn vma_lookup(&self, vma_addr: usize) -> Option<&virt::VmAreaRef> {
+        // SAFETY: We hold a reference to the mm, so the pointer must be valid. Any value is okay
+        // for `vma_addr`.
+        let vma = unsafe { bindings::vma_lookup(self.mm.as_raw(), vma_addr as _) };
+
+        if vma.is_null() {
+            None
+        } else {
+            // SAFETY: We just checked that a vma was found, so the pointer is valid. Furthermore,
+            // the returned area will borrow from this read lock guard, so it can only be used
+            // while the mmap read lock is still held.
+            unsafe { Some(virt::VmAreaRef::from_raw(vma)) }
+        }
+    }
+}
+
 impl Drop for MmapReadGuard<'_> {
     #[inline]
     fn drop(&mut self) {
rust/kernel/mm/virt.rs new file +171 -0

171 lines not on this page · raw message

Signature · 1 line
2.47.0.371.ga323438b13-goog
#9 lore raw

Re: [PATCH v8 2/7] mm: rust: add vm_area_struct methods that require read access

Quoted 3 lines · Alice Ryhl

This adds a type called VmAreaRef which is used when referencing a vma that you have read access to. Here, read access means that you hold either the mmap read lock or the vma read lock (or stronger).

This is pure nit and not important but...

I know we screwed up naming in mm, with the god awful vm_area_struct (we abbreviate, for 2 letters, get bored, stop abbreviating, but throw in a struct for a laugh) or 'VMA', but I wonder if this would be better as VmaRef? Then again that's kinda terrible too.

Sorry about that. I mean this isn't hugely important + ultimately _our fault_.

VirtualMemoryAreaRef is worse... VirtMemAreaRef? OK. Maybe VMAreaRef is the least bad...

Quoted 16 lines

Additionally, a vma_lookup method is added to the mmap read guard, which enables you to obtain a &VmAreaRef in safe Rust code.

---
 rust/helpers/mm.c      |   6 ++
 rust/kernel/mm.rs      |  21 ++++++
 rust/kernel/mm/virt.rs | 171 +++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 198 insertions(+)
rust/helpers/mm.c +0 -0
index 7201747a5d31..7b72eb065a3e 100644

rust/helpers/mm.c void rust_helper_mmap_read_unlock(struct mm_struct *mm) · line 45

Quoted 9 lines
rust/helpers/mm.c +6 -0
@@ -37,3 +37,9 @@ void rust_helper_mmap_read_unlock(struct mm_struct *mm)
 {
 	mmap_read_unlock(mm);
 }
+
+struct vm_area_struct *rust_helper_vma_lookup(struct mm_struct *mm,
+					      unsigned long addr)
+{
+	return vma_lookup(mm, addr);
+}

I wonder whether we want to abstract some of the VMA iterator stuff, because it's inefficient to look up VMAs by doing this each time if you are looking at, for instance, adjacent VMAs.

But perhaps reasonable to defer doing that to later work?

Quoted 14 lines
rust/kernel/mm.rs +2 -0
index 84cba581edaa..ace8e7d57afe 100644
@@ -12,6 +12,8 @@
 };
 use core::{ops::Deref, ptr::NonNull};
 
+pub mod virt;
+
 /// A wrapper for the kernel's `struct mm_struct`.
 ///
 /// Since `mm_users` may be zero, the associated address space may not exist anymore. You can use

rust/kernel/mm.rs pub struct MmapReadGuard<'a> { · line 218

Quoted 7 lines
rust/kernel/mm.rs +4 -0
@@ -210,6 +212,25 @@ pub struct MmapReadGuard<'a> {
     _nts: NotThreadSafe,
 }
 
+impl<'a> MmapReadGuard<'a> {
+    /// Look up a vma at the given address.
+    #[inline]
+    pub fn vma_lookup(&self, vma_addr: usize) -> Option<&virt::VmAreaRef> {

Kind of lovely to have functions under the read guard and then knowing that hey - we must hold the read lock to be able to do this.

Imagine, a programming language with actual types... :P

rust/kernel/mm.rs pub struct MmapReadGuard<'a> { · line 221

Quoted 3 lines
rust/kernel/mm.rs +3 -0
+        // SAFETY: We hold a reference to the mm, so the pointer must be valid. Any value is okay
+        // for `vma_addr`.
+        let vma = unsafe { bindings::vma_lookup(self.mm.as_raw(), vma_addr as _) };

Why do we say 'as _' here?

rust/kernel/mm.rs pub struct MmapReadGuard<'a> { · line 228

Quoted 7 lines
rust/kernel/mm.rs +7 -0
+
+        if vma.is_null() {
+            None
+        } else {
+            // SAFETY: We just checked that a vma was found, so the pointer is valid. Furthermore,
+            // the returned area will borrow from this read lock guard, so it can only be used
+            // while the mmap read lock is still held.

Lovely!

Quoted 14 lines
rust/kernel/mm.rs +5 -0
+            unsafe { Some(virt::VmAreaRef::from_raw(vma)) }
+        }
+    }
+}
+
 impl Drop for MmapReadGuard<'_> {
     #[inline]
     fn drop(&mut self) {
rust/kernel/mm/virt.rs new file +0 -0
new file mode 100644
index 000000000000..1e755dca46dd

rust/kernel/mm/virt.rs line 5

Quoted 5 lines
rust/kernel/mm/virt.rs new file +5 -0
@@ -0,0 +1,171 @@
+// SPDX-License-Identifier: GPL-2.0
+
+// Copyright (C) 2024 Google LLC.
+
+//! Virtual memory.

Trivial rust q again but does this result in a heading in generated docs or something?

rust/kernel/mm/virt.rs line 15

Quoted 10 lines
rust/kernel/mm/virt.rs new file +10 -0
+
+use crate::{bindings, types::Opaque};
+
+/// A wrapper for the kernel's `struct vm_area_struct` with read access.
+///
+/// It represents an area of virtual memory.
+///
+/// # Invariants
+///
+/// The caller must hold the mmap read lock or the vma read lock.

Might be worth mentioning here that you have yet to abstract the vma lock?

rust/kernel/mm/virt.rs line 22

Quoted 7 lines
rust/kernel/mm/virt.rs new file +7 -0
+#[repr(transparent)]
+pub struct VmAreaRef {
+    vma: Opaque<bindings::vm_area_struct>,
+}
+
+// Methods you can call when holding the mmap or vma read lock (or strong). They must be usable no
+// matter what the vma flags are.

typo: 'or strong' -> 'or stronger'.

Nitty, but perhaps say 'Methods must be usable' rather than 'they' to be totally clear.

rust/kernel/mm/virt.rs line 29

Quoted 7 lines
rust/kernel/mm/virt.rs new file +7 -0
+impl VmAreaRef {
+    /// Access a virtual memory area given a raw pointer.
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that `vma` is valid for the duration of 'a, and that the mmap read lock
+    /// (or stronger) is held for at least the duration of 'a.

Well, VMA locks make this more complicated, in that we can just hold a VMA lock. But again, perhaps worth doing this incrementally and just talk about mmap locks to start with.

However since we reference VMA locks elsewhere, we should reference them here (and probably worth mentioning that they are not yet abstracted).

Quoted 10 lines
rust/kernel/mm/virt.rs new file +10 -0
+    #[inline]
+    pub unsafe fn from_raw<'a>(vma: *const bindings::vm_area_struct) -> &'a Self {
+        // SAFETY: The caller ensures that the invariants are satisfied for the duration of 'a.
+        unsafe { &*vma.cast() }
+    }
+
+    /// Returns a raw pointer to this area.
+    #[inline]
+    pub fn as_ptr(&self) -> *mut bindings::vm_area_struct {
+        self.vma.get()

rust/kernel/mm/virt.rs line 49

Quoted 10 lines
rust/kernel/mm/virt.rs new file +10 -0
+    }
+
+    /// Returns the flags associated with the virtual memory area.
+    ///
+    /// The possible flags are a combination of the constants in [`flags`].
+    #[inline]
+    pub fn flags(&self) -> vm_flags_t {
+        // SAFETY: By the type invariants, the caller holds at least the mmap read lock, so this
+        // access is not a data race.
+        unsafe { (*self.as_ptr()).__bindgen_anon_2.vm_flags as _ }

Hm what's up with this __bindgen_anon_N stuff?

rust/kernel/mm/virt.rs line 54

Quoted 5 lines
rust/kernel/mm/virt.rs new file +5 -0
+    }
+
+    /// Returns the start address of the virtual memory area.
+    #[inline]
+    pub fn start(&self) -> usize {

Is usize guranteed to be equivalent to unsigned long?

rust/kernel/mm/virt.rs line 60

Quoted 6 lines
rust/kernel/mm/virt.rs new file +6 -0
+        // SAFETY: By the type invariants, the caller holds at least the mmap read lock, so this
+        // access is not a data race.
+        unsafe { (*self.as_ptr()).__bindgen_anon_1.__bindgen_anon_1.vm_start as _ }
+    }
+
+    /// Returns the end address of the virtual memory area.

Worth mentioning that it's an _exclusive_ end.

rust/kernel/mm/virt.rs line 68

Quoted 8 lines
rust/kernel/mm/virt.rs new file +8 -0
+    #[inline]
+    pub fn end(&self) -> usize {
+        // SAFETY: By the type invariants, the caller holds at least the mmap read lock, so this
+        // access is not a data race.
+        unsafe { (*self.as_ptr()).__bindgen_anon_1.__bindgen_anon_1.vm_end as _ }
+    }
+
+    /// Unmap pages in the given page range.

This needs some more description, as 'unmapping' pages is unfortunately an overloaded term in the kernel and this very much might confuse people as opposed to e.g. munmap()'ing a range.

I'd say something like 'clear page table mappings for the range at the leaf level, leaving all other page tables intact, freeing any memory referenced by the VMA in this range (anonymous memory is completely freed, file-backed memory has its reference count on page cache folio's dropped, any dirty data will still be written back to disk as usual)'.

rust/kernel/mm/virt.rs line 75

Quoted 7 lines
rust/kernel/mm/virt.rs new file +7 -0
+    #[inline]
+    pub fn zap_page_range_single(&self, address: usize, size: usize) {
+        // SAFETY: By the type invariants, the caller has read access to this VMA, which is
+        // sufficient for this method call. This method has no requirements on the vma flags. Any
+        // value of `address` and `size` is allowed.
+        unsafe {
+            bindings::zap_page_range_single(

Hm weirdly I see this in rust/bindings/bindings_generated.rs but not in rust/helpers/mm.c is this intended?

Is this meant to be generated _from_ somewhere? Is something missing for that?

rust/kernel/mm/virt.rs line 87

Quoted 12 lines
rust/kernel/mm/virt.rs new file +12 -0
+                self.as_ptr(),
+                address as _,
+                size as _,
+                core::ptr::null_mut(),
+            )
+        };
+    }
+}
+
+/// The integer type used for vma flags.
+#[doc(inline)]
+pub use bindings::vm_flags_t;

Where do you declare this type?

rust/kernel/mm/virt.rs line 89

Quoted 2 lines
rust/kernel/mm/virt.rs new file +2 -0
+
+/// All possible flags for [`VmAreaRef`].

Well you've not specified all as they're some speciailist ones and ones that depend on config flags, so maybe worth just saying 'core' flags?

rust/kernel/mm/virt.rs line 90

Quoted 1 line
rust/kernel/mm/virt.rs new file +1 -0
+pub mod flags {

Pure rust noobie question (again...) but what is a 'mod'?

rust/kernel/mm/virt.rs line 95

Quoted 5 lines
rust/kernel/mm/virt.rs new file +5 -0
+    use super::vm_flags_t;
+    use crate::bindings;
+
+    /// No flags are set.
+    pub const NONE: vm_flags_t = bindings::VM_NONE as _;

This is strictly not a flag, as is the 0 value (and is used 'cleverly' in kernel code when we have flags that are defined under some circumstances but not others, where we can then assign these values to VM_NONE if not available, ensuring all |= ... operations are no-ops and all & ... expressions evaluate to false) but I guess it doesn't matter all too much right?

Quoted 40 lines
rust/kernel/mm/virt.rs new file +40 -0
+
+    /// Mapping allows reads.
+    pub const READ: vm_flags_t = bindings::VM_READ as _;
+
+    /// Mapping allows writes.
+    pub const WRITE: vm_flags_t = bindings::VM_WRITE as _;
+
+    /// Mapping allows execution.
+    pub const EXEC: vm_flags_t = bindings::VM_EXEC as _;
+
+    /// Mapping is shared.
+    pub const SHARED: vm_flags_t = bindings::VM_SHARED as _;
+
+    /// Mapping may be updated to allow reads.
+    pub const MAYREAD: vm_flags_t = bindings::VM_MAYREAD as _;
+
+    /// Mapping may be updated to allow writes.
+    pub const MAYWRITE: vm_flags_t = bindings::VM_MAYWRITE as _;
+
+    /// Mapping may be updated to allow execution.
+    pub const MAYEXEC: vm_flags_t = bindings::VM_MAYEXEC as _;
+
+    /// Mapping may be updated to be shared.
+    pub const MAYSHARE: vm_flags_t = bindings::VM_MAYSHARE as _;
+
+    /// Page-ranges managed without `struct page`, just pure PFN.
+    pub const PFNMAP: vm_flags_t = bindings::VM_PFNMAP as _;
+
+    /// Memory mapped I/O or similar.
+    pub const IO: vm_flags_t = bindings::VM_IO as _;
+
+    /// Do not copy this vma on fork.
+    pub const DONTCOPY: vm_flags_t = bindings::VM_DONTCOPY as _;
+
+    /// Cannot expand with mremap().
+    pub const DONTEXPAND: vm_flags_t = bindings::VM_DONTEXPAND as _;
+
+    /// Lock the pages covered when they are faulted in.
+    pub const LOCKONFAULT: vm_flags_t = bindings::VM_LOCKONFAULT as _;
+

rust/kernel/mm/virt.rs line 145

Quoted 10 lines
rust/kernel/mm/virt.rs new file +10 -0
+    /// Is a VM accounted object.
+    pub const ACCOUNT: vm_flags_t = bindings::VM_ACCOUNT as _;
+
+    /// should the VM suppress accounting.
+    pub const NORESERVE: vm_flags_t = bindings::VM_NORESERVE as _;
+
+    /// Huge TLB Page VM.
+    pub const HUGETLB: vm_flags_t = bindings::VM_HUGETLB as _;
+
+    /// Synchronous page faults.

Might be worth mentioning that this is DAX-specific only.

rust/kernel/mm/virt.rs line 151

Quoted 6 lines
rust/kernel/mm/virt.rs new file +6 -0
+    pub const SYNC: vm_flags_t = bindings::VM_SYNC as _;
+
+    /// Architecture-specific flag.
+    pub const ARCH_1: vm_flags_t = bindings::VM_ARCH_1 as _;
+
+    /// Wipe VMA contents in child..

Typo '..' - also probably worth saying 'wipe VMA contents in child on fork'.

Quoted 11 lines
rust/kernel/mm/virt.rs new file +10 -0
+    pub const WIPEONFORK: vm_flags_t = bindings::VM_WIPEONFORK as _;
+
+    /// Do not include in the core dump.
+    pub const DONTDUMP: vm_flags_t = bindings::VM_DONTDUMP as _;
+
+    /// Not soft dirty clean area.
+    pub const SOFTDIRTY: vm_flags_t = bindings::VM_SOFTDIRTY as _;
+
+    /// Can contain `struct page` and pure PFN pages.
+    pub const MIXEDMAP: vm_flags_t = bindings::VM_MIXEDMAP as _;

rust/kernel/mm/virt.rs line 171

Quoted 10 lines
rust/kernel/mm/virt.rs new file +10 -0
+
+    /// MADV_HUGEPAGE marked this vma.
+    pub const HUGEPAGE: vm_flags_t = bindings::VM_HUGEPAGE as _;
+
+    /// MADV_NOHUGEPAGE marked this vma.
+    pub const NOHUGEPAGE: vm_flags_t = bindings::VM_NOHUGEPAGE as _;
+
+    /// KSM may merge identical pages.
+    pub const MERGEABLE: vm_flags_t = bindings::VM_MERGEABLE as _;
+}

I'd say these comments are a bit sparse and need more detail, but they are literally comments from include/linux/mm.h and therefore, again, our fault so this is fine :)

Quoted 3 lines

--
2.47.0.371.ga323438b13-goog

author maintainer
#10 lore raw

Re: [PATCH v8 2/7] mm: rust: add vm_area_struct methods that require read access

Quoted 13 lines · Lorenzo Stoakes
Quoted 3 lines · Alice Ryhl

This adds a type called VmAreaRef which is used when referencing a vma that you have read access to. Here, read access means that you hold either the mmap read lock or the vma read lock (or stronger).

This is pure nit and not important but...

I know we screwed up naming in mm, with the god awful vm_area_struct (we abbreviate, for 2 letters, get bored, stop abbreviating, but throw in a struct for a laugh) or 'VMA', but I wonder if this would be better as VmaRef? Then again that's kinda terrible too.

Quoted 5 lines

Sorry about that. I mean this isn't hugely important + ultimately _our fault_.

VirtualMemoryAreaRef is worse... VirtMemAreaRef? OK. Maybe VMAreaRef is the least bad...

Happy to use whichever name you prefer. :)

Quoted 29 lines
Quoted 15 lines

Additionally, a vma_lookup method is added to the mmap read guard, which enables you to obtain a &VmAreaRef in safe Rust code.

---
 rust/helpers/mm.c      |   6 ++
 rust/kernel/mm.rs      |  21 ++++++
 rust/kernel/mm/virt.rs | 171 +++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 198 insertions(+)
rust/helpers/mm.c +0 -0
index 7201747a5d31..7b72eb065a3e 100644

rust/helpers/mm.c void rust_helper_mmap_read_unlock(struct mm_struct *mm) · line 45

Quoted 9 lines
rust/helpers/mm.c +6 -0
@@ -37,3 +37,9 @@ void rust_helper_mmap_read_unlock(struct mm_struct *mm)
 {
      mmap_read_unlock(mm);
 }
+
+struct vm_area_struct *rust_helper_vma_lookup(struct mm_struct *mm,
+                                           unsigned long addr)
+{
+     return vma_lookup(mm, addr);
+}

I wonder whether we want to abstract some of the VMA iterator stuff, because it's inefficient to look up VMAs by doing this each time if you are looking at, for instance, adjacent VMAs.

Quoted 1 line

But perhaps reasonable to defer doing that to later work?

Yeah, that should probably be deferred. Binder only has one vma per mm, so iteration is not useful.

Quoted 25 lines
Quoted 14 lines
rust/kernel/mm.rs +2 -0
index 84cba581edaa..ace8e7d57afe 100644
@@ -12,6 +12,8 @@
 };
 use core::{ops::Deref, ptr::NonNull};
 
+pub mod virt;
+
 /// A wrapper for the kernel's `struct mm_struct`.
 ///
 /// Since `mm_users` may be zero, the associated address space may not exist anymore. You can use

rust/kernel/mm.rs pub struct MmapReadGuard<'a> { · line 218

Quoted 7 lines
rust/kernel/mm.rs +4 -0
@@ -210,6 +212,25 @@ pub struct MmapReadGuard<'a> {
     _nts: NotThreadSafe,
 }
 
+impl<'a> MmapReadGuard<'a> {
+    /// Look up a vma at the given address.
+    #[inline]
+    pub fn vma_lookup(&self, vma_addr: usize) -> Option<&virt::VmAreaRef> {

Kind of lovely to have functions under the read guard and then knowing that hey - we must hold the read lock to be able to do this.

Quoted 1 line

Imagine, a programming language with actual types... :P

:)

Quoted 5 lines

rust/kernel/mm.rs pub struct MmapReadGuard<'a> { · line 221

Quoted 3 lines
rust/kernel/mm.rs +3 -0
+        // SAFETY: We hold a reference to the mm, so the pointer must be valid. Any value is okay
+        // for `vma_addr`.
+        let vma = unsafe { bindings::vma_lookup(self.mm.as_raw(), vma_addr as _) };

Why do we say 'as _' here?

This is an integer cast where the target type of the cast is inferred by the compiler. It will go away once this lands:
https://lore.kernel.org/rust-for-linux/[email protected]/

Quoted 24 lines

rust/kernel/mm.rs pub struct MmapReadGuard<'a> { · line 228

Quoted 7 lines
rust/kernel/mm.rs +7 -0
+
+        if vma.is_null() {
+            None
+        } else {
+            // SAFETY: We just checked that a vma was found, so the pointer is valid. Furthermore,
+            // the returned area will borrow from this read lock guard, so it can only be used
+            // while the mmap read lock is still held.

Lovely!

Quoted 14 lines
rust/kernel/mm.rs +5 -0
+            unsafe { Some(virt::VmAreaRef::from_raw(vma)) }
+        }
+    }
+}
+
 impl Drop for MmapReadGuard<'_> {
     #[inline]
     fn drop(&mut self) {
rust/kernel/mm/virt.rs new file +0 -0
new file mode 100644
index 000000000000..1e755dca46dd
@@ -0,0 +1,171 @@
Quoted 8 lines

rust/kernel/mm/virt.rs line 5

Quoted 5 lines
rust/kernel/mm/virt.rs new file +5 -0
+// SPDX-License-Identifier: GPL-2.0
+
+// Copyright (C) 2024 Google LLC.
+
+//! Virtual memory.

Trivial rust q again but does this result in a heading in generated docs or something?

Yes, this becomes module documentation. Check out:
https://rust.docs.kernel.org/kernel/
or try out make LLVM=1 rustdoc

Quoted 11 lines

rust/kernel/mm/virt.rs line 15

Quoted 9 lines
rust/kernel/mm/virt.rs new file +9 -0
+use crate::{bindings, types::Opaque};
+
+/// A wrapper for the kernel's `struct vm_area_struct` with read access.
+///
+/// It represents an area of virtual memory.
+///
+/// # Invariants
+///
+/// The caller must hold the mmap read lock or the vma read lock.

Might be worth mentioning here that you have yet to abstract the vma lock?

I do that in the next patch.

Quoted 10 lines

rust/kernel/mm/virt.rs line 22

Quoted 7 lines
rust/kernel/mm/virt.rs new file +7 -0
+#[repr(transparent)]
+pub struct VmAreaRef {
+    vma: Opaque<bindings::vm_area_struct>,
+}
+
+// Methods you can call when holding the mmap or vma read lock (or strong). They must be usable no
+// matter what the vma flags are.

typo: 'or strong' -> 'or stronger'.

Quoted 2 lines

Nitty, but perhaps say 'Methods must be usable' rather than 'they' to be totally clear.

Will reword.

Quoted 8 lines

rust/kernel/mm/virt.rs line 29

Quoted 7 lines
rust/kernel/mm/virt.rs new file +7 -0
+impl VmAreaRef {
+    /// Access a virtual memory area given a raw pointer.
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that `vma` is valid for the duration of 'a, and that the mmap read lock
+    /// (or stronger) is held for at least the duration of 'a.
Quoted 6 lines

Well, VMA locks make this more complicated, in that we can just hold a VMA lock. But again, perhaps worth doing this incrementally and just talk about mmap locks to start with.

However since we reference VMA locks elsewhere, we should reference them here (and probably worth mentioning that they are not yet abstracted).

Oh I forgot to update this, it should say "mmap or vma read lock".

Quoted 14 lines
Quoted 14 lines
rust/kernel/mm/virt.rs new file +14 -0
+    #[inline]
+    pub unsafe fn from_raw<'a>(vma: *const bindings::vm_area_struct) -> &'a Self {
+        // SAFETY: The caller ensures that the invariants are satisfied for the duration of 'a.
+        unsafe { &*vma.cast() }
+    }
+
+    /// Returns a raw pointer to this area.
+    #[inline]
+    pub fn as_ptr(&self) -> *mut bindings::vm_area_struct {
+        self.vma.get()
+    }
+
+    /// Returns the flags associated with the virtual memory area.
+    ///
Quoted 8 lines

rust/kernel/mm/virt.rs line 49

Quoted 6 lines
rust/kernel/mm/virt.rs new file +6 -0
+    /// The possible flags are a combination of the constants in [`flags`].
+    #[inline]
+    pub fn flags(&self) -> vm_flags_t {
+        // SAFETY: By the type invariants, the caller holds at least the mmap read lock, so this
+        // access is not a data race.
+        unsafe { (*self.as_ptr()).__bindgen_anon_2.vm_flags as _ }

Hm what's up with this __bindgen_anon_N stuff?

Whenever you have a struct { ... } or union { ... } in the middle of a struct, bindgen generates additional types for them because Rust doesn't have a direct equivalent.

Quoted 7 lines

rust/kernel/mm/virt.rs line 54

Quoted 5 lines
rust/kernel/mm/virt.rs new file +5 -0
+    }
+
+    /// Returns the start address of the virtual memory area.
+    #[inline]
+    pub fn start(&self) -> usize {

Is usize guranteed to be equivalent to unsigned long?

They are guaranteed to have the same size, yes.

But again, right now unsigned long is being translated to whichever one of u32 or u64 has the same size as usize, instead of just being translated to usize. Thus the annoying casts. We can get rid of them as soon as
https://lore.kernel.org/rust-for-linux/[email protected]/
lands.

Quoted 8 lines

rust/kernel/mm/virt.rs line 60

Quoted 6 lines
rust/kernel/mm/virt.rs new file +6 -0
+        // SAFETY: By the type invariants, the caller holds at least the mmap read lock, so this
+        // access is not a data race.
+        unsafe { (*self.as_ptr()).__bindgen_anon_1.__bindgen_anon_1.vm_start as _ }
+    }
+
+    /// Returns the end address of the virtual memory area.

Worth mentioning that it's an _exclusive_ end.

Sure, I'll add that.

Quoted 13 lines

rust/kernel/mm/virt.rs line 68

Quoted 8 lines
rust/kernel/mm/virt.rs new file +8 -0
+    #[inline]
+    pub fn end(&self) -> usize {
+        // SAFETY: By the type invariants, the caller holds at least the mmap read lock, so this
+        // access is not a data race.
+        unsafe { (*self.as_ptr()).__bindgen_anon_1.__bindgen_anon_1.vm_end as _ }
+    }
+
+    /// Unmap pages in the given page range.

This needs some more description, as 'unmapping' pages is unfortunately an overloaded term in the kernel and this very much might confuse people as opposed to e.g. munmap()'ing a range.

Quoted 5 lines

I'd say something like 'clear page table mappings for the range at the leaf level, leaving all other page tables intact, freeing any memory referenced by the VMA in this range (anonymous memory is completely freed, file-backed memory has its reference count on page cache folio's dropped, any dirty data will still be written back to disk as usual)'.

Sure, will add that to the docs.

Quoted 8 lines

rust/kernel/mm/virt.rs line 75

Quoted 7 lines
rust/kernel/mm/virt.rs new file +7 -0
+    #[inline]
+    pub fn zap_page_range_single(&self, address: usize, size: usize) {
+        // SAFETY: By the type invariants, the caller has read access to this VMA, which is
+        // sufficient for this method call. This method has no requirements on the vma flags. Any
+        // value of `address` and `size` is allowed.
+        unsafe {
+            bindings::zap_page_range_single(
Quoted 5 lines

Hm weirdly I see this in rust/bindings/bindings_generated.rs but not in rust/helpers/mm.c is this intended?

Is this meant to be generated _from_ somewhere? Is something missing for that?

The bindings_generated.rs file is generated at built-time from C headers. The zap_page_range_single is a real function, not a fake static inline header-only function, so bindgen is able to generate it without anything in rust/helpers.

Quoted 6 lines
Quoted 6 lines
rust/kernel/mm/virt.rs new file +6 -0
+                self.as_ptr(),
+                address as _,
+                size as _,
+                core::ptr::null_mut(),
+            )
+        };
Quoted 8 lines

rust/kernel/mm/virt.rs line 87

Quoted 6 lines
rust/kernel/mm/virt.rs new file +6 -0
+    }
+}
+
+/// The integer type used for vma flags.
+#[doc(inline)]
+pub use bindings::vm_flags_t;

Where do you declare this type?

It's declared in include/linux/mm_types.h

Quoted 5 lines

rust/kernel/mm/virt.rs line 88

Quoted 2 lines
rust/kernel/mm/virt.rs new file +2 -0
+
+/// All possible flags for [`VmAreaRef`].

Well you've not specified all as they're some speciailist ones and ones that depend on config flags, so maybe worth just saying 'core' flags?

Sure.

Quoted 3 lines

rust/kernel/mm/virt.rs line 90

Quoted 1 line
rust/kernel/mm/virt.rs new file +1 -0
+pub mod flags {

Pure rust noobie question (again...) but what is a 'mod'?

It's a module.

Quoted 6 lines

rust/kernel/mm/virt.rs line 95

Quoted 5 lines
rust/kernel/mm/virt.rs new file +5 -0
+    use super::vm_flags_t;
+    use crate::bindings;
+
+    /// No flags are set.
+    pub const NONE: vm_flags_t = bindings::VM_NONE as _;
Quoted 6 lines

This is strictly not a flag, as is the 0 value (and is used 'cleverly' in kernel code when we have flags that are defined under some circumstances but not others, where we can then assign these values to VM_NONE if not available, ensuring all |= ... operations are no-ops and all & ... expressions evaluate to false) but I guess it doesn't matter all too much right?

Ultimately it's just a bunch of integer constants. We can include or exclude whichever ones we prefer.

Quoted 43 lines
Quoted 43 lines
rust/kernel/mm/virt.rs new file +43 -0
+    /// Mapping allows reads.
+    pub const READ: vm_flags_t = bindings::VM_READ as _;
+
+    /// Mapping allows writes.
+    pub const WRITE: vm_flags_t = bindings::VM_WRITE as _;
+
+    /// Mapping allows execution.
+    pub const EXEC: vm_flags_t = bindings::VM_EXEC as _;
+
+    /// Mapping is shared.
+    pub const SHARED: vm_flags_t = bindings::VM_SHARED as _;
+
+    /// Mapping may be updated to allow reads.
+    pub const MAYREAD: vm_flags_t = bindings::VM_MAYREAD as _;
+
+    /// Mapping may be updated to allow writes.
+    pub const MAYWRITE: vm_flags_t = bindings::VM_MAYWRITE as _;
+
+    /// Mapping may be updated to allow execution.
+    pub const MAYEXEC: vm_flags_t = bindings::VM_MAYEXEC as _;
+
+    /// Mapping may be updated to be shared.
+    pub const MAYSHARE: vm_flags_t = bindings::VM_MAYSHARE as _;
+
+    /// Page-ranges managed without `struct page`, just pure PFN.
+    pub const PFNMAP: vm_flags_t = bindings::VM_PFNMAP as _;
+
+    /// Memory mapped I/O or similar.
+    pub const IO: vm_flags_t = bindings::VM_IO as _;
+
+    /// Do not copy this vma on fork.
+    pub const DONTCOPY: vm_flags_t = bindings::VM_DONTCOPY as _;
+
+    /// Cannot expand with mremap().
+    pub const DONTEXPAND: vm_flags_t = bindings::VM_DONTEXPAND as _;
+
+    /// Lock the pages covered when they are faulted in.
+    pub const LOCKONFAULT: vm_flags_t = bindings::VM_LOCKONFAULT as _;
+
+    /// Is a VM accounted object.
+    pub const ACCOUNT: vm_flags_t = bindings::VM_ACCOUNT as _;
+
+    /// should the VM suppress accounting.
Quoted 8 lines

rust/kernel/mm/virt.rs line 145

Quoted 6 lines
rust/kernel/mm/virt.rs new file +6 -0
+    pub const NORESERVE: vm_flags_t = bindings::VM_NORESERVE as _;
+
+    /// Huge TLB Page VM.
+    pub const HUGETLB: vm_flags_t = bindings::VM_HUGETLB as _;
+
+    /// Synchronous page faults.

Might be worth mentioning that this is DAX-specific only.

Will add.

Quoted 9 lines

rust/kernel/mm/virt.rs line 151

Quoted 6 lines
rust/kernel/mm/virt.rs new file +6 -0
+    pub const SYNC: vm_flags_t = bindings::VM_SYNC as _;
+
+    /// Architecture-specific flag.
+    pub const ARCH_1: vm_flags_t = bindings::VM_ARCH_1 as _;
+
+    /// Wipe VMA contents in child..

Typo '..' - also probably worth saying 'wipe VMA contents in child on fork'.

Will add.

Quoted 17 lines
Quoted 17 lines
rust/kernel/mm/virt.rs new file +17 -0
+    pub const WIPEONFORK: vm_flags_t = bindings::VM_WIPEONFORK as _;
+
+    /// Do not include in the core dump.
+    pub const DONTDUMP: vm_flags_t = bindings::VM_DONTDUMP as _;
+
+    /// Not soft dirty clean area.
+    pub const SOFTDIRTY: vm_flags_t = bindings::VM_SOFTDIRTY as _;
+
+    /// Can contain `struct page` and pure PFN pages.
+    pub const MIXEDMAP: vm_flags_t = bindings::VM_MIXEDMAP as _;
+
+    /// MADV_HUGEPAGE marked this vma.
+    pub const HUGEPAGE: vm_flags_t = bindings::VM_HUGEPAGE as _;
+
+    /// MADV_NOHUGEPAGE marked this vma.
+    pub const NOHUGEPAGE: vm_flags_t = bindings::VM_NOHUGEPAGE as _;
+
Quoted 8 lines

rust/kernel/mm/virt.rs line 171

Quoted 4 lines
rust/kernel/mm/virt.rs new file +3 -0
+    /// KSM may merge identical pages.
+    pub const MERGEABLE: vm_flags_t = bindings::VM_MERGEABLE as _;
+}

I'd say these comments are a bit sparse and need more detail, but they are literally comments from include/linux/mm.h and therefore, again, our fault so this is fine :)

Happy to add more if you tell me what you'd like to see. ;)

Alice

#11 lore raw

Re: [PATCH v8 2/7] mm: rust: add vm_area_struct methods that require read access

Quoted 15 lines · Alice Ryhl
Quoted 13 lines · Lorenzo Stoakes
Quoted 3 lines · Alice Ryhl

This adds a type called VmAreaRef which is used when referencing a vma that you have read access to. Here, read access means that you hold either the mmap read lock or the vma read lock (or stronger).

This is pure nit and not important but...

I know we screwed up naming in mm, with the god awful vm_area_struct (we abbreviate, for 2 letters, get bored, stop abbreviating, but throw in a struct for a laugh) or 'VMA', but I wonder if this would be better as VmaRef? Then again that's kinda terrible too.

Quoted 7 lines
Quoted 5 lines

Sorry about that. I mean this isn't hugely important + ultimately _our fault_.

VirtualMemoryAreaRef is worse... VirtMemAreaRef? OK. Maybe VMAreaRef is the least bad...

Happy to use whichever name you prefer. :)

Let's leave it as-is, this is kinda our fault* in mm :)

* pun intended

Quoted 5 lines
Quoted 5 lines
Quoted 5 lines

Additionally, a vma_lookup method is added to the mmap read guard, which enables you to obtain a &VmAreaRef in safe Rust code.

Other than trivial doc/comment tweaks this looks fine to me from mm perspective so:

Quoted 25 lines
Quoted 25 lines
Quoted 11 lines
---
 rust/helpers/mm.c      |   6 ++
 rust/kernel/mm.rs      |  21 ++++++
 rust/kernel/mm/virt.rs | 171 +++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 198 insertions(+)
rust/helpers/mm.c +0 -0
index 7201747a5d31..7b72eb065a3e 100644

rust/helpers/mm.c void rust_helper_mmap_read_unlock(struct mm_struct *mm) · line 45

Quoted 9 lines
rust/helpers/mm.c +6 -0
@@ -37,3 +37,9 @@ void rust_helper_mmap_read_unlock(struct mm_struct *mm)
 {
      mmap_read_unlock(mm);
 }
+
+struct vm_area_struct *rust_helper_vma_lookup(struct mm_struct *mm,
+                                           unsigned long addr)
+{
+     return vma_lookup(mm, addr);
+}

I wonder whether we want to abstract some of the VMA iterator stuff, because it's inefficient to look up VMAs by doing this each time if you are looking at, for instance, adjacent VMAs.

Quoted 4 lines
Quoted 1 line

But perhaps reasonable to defer doing that to later work?

Yeah, that should probably be deferred. Binder only has one vma per mm, so iteration is not useful.

Sure, no problem!

Quoted 34 lines
Quoted 26 lines
Quoted 15 lines
rust/kernel/mm.rs +2 -0
index 84cba581edaa..ace8e7d57afe 100644
@@ -12,6 +12,8 @@
 };
 use core::{ops::Deref, ptr::NonNull};
 
+pub mod virt;
+
 /// A wrapper for the kernel's `struct mm_struct`.
 ///
 /// Since `mm_users` may be zero, the associated address space may not exist anymore. You can use

rust/kernel/mm.rs pub struct MmapReadGuard<'a> { · line 218

Quoted 7 lines
rust/kernel/mm.rs +4 -0
@@ -210,6 +212,25 @@ pub struct MmapReadGuard<'a> {
     _nts: NotThreadSafe,
 }
 
+impl<'a> MmapReadGuard<'a> {
+    /// Look up a vma at the given address.
+    #[inline]
+    pub fn vma_lookup(&self, vma_addr: usize) -> Option<&virt::VmAreaRef> {

Kind of lovely to have functions under the read guard and then knowing that hey - we must hold the read lock to be able to do this.

Quoted 1 line

Imagine, a programming language with actual types... :P

:)

Quoted 4 lines
Quoted 3 lines
rust/kernel/mm.rs +3 -0
+        // SAFETY: We hold a reference to the mm, so the pointer must be valid. Any value is okay
+        // for `vma_addr`.
+        let vma = unsafe { bindings::vma_lookup(self.mm.as_raw(), vma_addr as _) };
Quoted 5 lines
Quoted 1 line

Why do we say 'as _' here?

This is an integer cast where the target type of the cast is inferred by the compiler. It will go away once this lands:
https://lore.kernel.org/rust-for-linux/[email protected]/

OK cool.

Quoted 34 lines
Quoted 25 lines

rust/kernel/mm.rs pub struct MmapReadGuard<'a> { · line 228

Quoted 8 lines
rust/kernel/mm.rs +7 -0
+
+        if vma.is_null() {
+            None
+        } else {
+            // SAFETY: We just checked that a vma was found, so the pointer is valid. Furthermore,
+            // the returned area will borrow from this read lock guard, so it can only be used
+            // while the mmap read lock is still held.

Lovely!

Quoted 14 lines
rust/kernel/mm.rs +5 -0
+            unsafe { Some(virt::VmAreaRef::from_raw(vma)) }
+        }
+    }
+}
+
 impl Drop for MmapReadGuard<'_> {
     #[inline]
     fn drop(&mut self) {
rust/kernel/mm/virt.rs new file +0 -0
new file mode 100644
index 000000000000..1e755dca46dd
@@ -0,0 +1,171 @@
Quoted 8 lines

rust/kernel/mm/virt.rs line 5

Quoted 5 lines
rust/kernel/mm/virt.rs new file +5 -0
+// SPDX-License-Identifier: GPL-2.0
+
+// Copyright (C) 2024 Google LLC.
+
+//! Virtual memory.

Trivial rust q again but does this result in a heading in generated docs or something?

Quoted 3 lines

Yes, this becomes module documentation. Check out:
https://rust.docs.kernel.org/kernel/
or try out make LLVM=1 rustdoc

Cool thanks, thought this might be the case!

Quoted 13 lines
Quoted 12 lines

rust/kernel/mm/virt.rs line 15

Quoted 10 lines
rust/kernel/mm/virt.rs new file +9 -0
+use crate::{bindings, types::Opaque};
+
+/// A wrapper for the kernel's `struct vm_area_struct` with read access.
+///
+/// It represents an area of virtual memory.
+///
+/// # Invariants
+///
+/// The caller must hold the mmap read lock or the vma read lock.

Might be worth mentioning here that you have yet to abstract the vma lock?

Quoted 1 line

I do that in the next patch.

Yeah saw, one of those 'comment in patch X, addressed in patch X+1' scenarios :)

Quoted 11 lines
Quoted 11 lines

rust/kernel/mm/virt.rs line 22

Quoted 8 lines
rust/kernel/mm/virt.rs new file +7 -0
+#[repr(transparent)]
+pub struct VmAreaRef {
+    vma: Opaque<bindings::vm_area_struct>,
+}
+
+// Methods you can call when holding the mmap or vma read lock (or strong). They must be usable no
+// matter what the vma flags are.

typo: 'or strong' -> 'or stronger'.

Quoted 4 lines
Quoted 2 lines

Nitty, but perhaps say 'Methods must be usable' rather than 'they' to be totally clear.

Will reword.

Thanks!

Quoted 9 lines
Quoted 9 lines
Quoted 8 lines
rust/kernel/mm/virt.rs new file +7 -0
+impl VmAreaRef {
+    /// Access a virtual memory area given a raw pointer.
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that `vma` is valid for the duration of 'a, and that the mmap read lock
+    /// (or stronger) is held for at least the duration of 'a.
Quoted 8 lines
Quoted 6 lines

Well, VMA locks make this more complicated, in that we can just hold a VMA lock. But again, perhaps worth doing this incrementally and just talk about mmap locks to start with.

However since we reference VMA locks elsewhere, we should reference them here (and probably worth mentioning that they are not yet abstracted).

Oh I forgot to update this, it should say "mmap or vma read lock".

Cool, one to tweak on respin also then.

Quoted 24 lines
Quoted 15 lines
Quoted 15 lines
rust/kernel/mm/virt.rs new file +14 -0
+    #[inline]
+    pub unsafe fn from_raw<'a>(vma: *const bindings::vm_area_struct) -> &'a Self {
+        // SAFETY: The caller ensures that the invariants are satisfied for the duration of 'a.
+        unsafe { &*vma.cast() }
+    }
+
+    /// Returns a raw pointer to this area.
+    #[inline]
+    pub fn as_ptr(&self) -> *mut bindings::vm_area_struct {
+        self.vma.get()
+    }
+
+    /// Returns the flags associated with the virtual memory area.
+    ///
Quoted 8 lines

rust/kernel/mm/virt.rs line 49

Quoted 6 lines
rust/kernel/mm/virt.rs new file +6 -0
+    /// The possible flags are a combination of the constants in [`flags`].
+    #[inline]
+    pub fn flags(&self) -> vm_flags_t {
+        // SAFETY: By the type invariants, the caller holds at least the mmap read lock, so this
+        // access is not a data race.
+        unsafe { (*self.as_ptr()).__bindgen_anon_2.vm_flags as _ }

Hm what's up with this __bindgen_anon_N stuff?

Quoted 3 lines

Whenever you have a struct { ... } or union { ... } in the middle of a struct, bindgen generates additional types for them because Rust doesn't have a direct equivalent.

OK I see.

Quoted 9 lines
Quoted 8 lines

rust/kernel/mm/virt.rs line 54

Quoted 6 lines
rust/kernel/mm/virt.rs new file +5 -0
+    }
+
+    /// Returns the start address of the virtual memory area.
+    #[inline]
+    pub fn start(&self) -> usize {

Is usize guranteed to be equivalent to unsigned long?

Quoted 8 lines

They are guaranteed to have the same size, yes.

But again, right now unsigned long is being translated to whichever one of u32 or u64 has the same size as usize, instead of just being translated to usize. Thus the annoying casts. We can get rid of them as soon as
https://lore.kernel.org/rust-for-linux/[email protected]/
lands.

Ack cool.

Quoted 11 lines
Quoted 9 lines

rust/kernel/mm/virt.rs line 60

Quoted 7 lines
rust/kernel/mm/virt.rs new file +6 -0
+        // SAFETY: By the type invariants, the caller holds at least the mmap read lock, so this
+        // access is not a data race.
+        unsafe { (*self.as_ptr()).__bindgen_anon_1.__bindgen_anon_1.vm_start as _ }
+    }
+
+    /// Returns the end address of the virtual memory area.

Worth mentioning that it's an _exclusive_ end.

Sure, I'll add that.

Thanks

Quoted 14 lines
Quoted 14 lines

rust/kernel/mm/virt.rs line 68

Quoted 9 lines
rust/kernel/mm/virt.rs new file +8 -0
+    #[inline]
+    pub fn end(&self) -> usize {
+        // SAFETY: By the type invariants, the caller holds at least the mmap read lock, so this
+        // access is not a data race.
+        unsafe { (*self.as_ptr()).__bindgen_anon_1.__bindgen_anon_1.vm_end as _ }
+    }
+
+    /// Unmap pages in the given page range.

This needs some more description, as 'unmapping' pages is unfortunately an overloaded term in the kernel and this very much might confuse people as opposed to e.g. munmap()'ing a range.

Quoted 7 lines
Quoted 5 lines

I'd say something like 'clear page table mappings for the range at the leaf level, leaving all other page tables intact, freeing any memory referenced by the VMA in this range (anonymous memory is completely freed, file-backed memory has its reference count on page cache folio's dropped, any dirty data will still be written back to disk as usual)'.

Sure, will add that to the docs.

Thanks, I assume you mean this comment, which will form part of the docs? As here we should at least replace the 'unmap' with 'zap' to avoid confusion vs. munmap().

Quoted 35 lines
Quoted 9 lines

rust/kernel/mm/virt.rs line 75

Quoted 8 lines
rust/kernel/mm/virt.rs new file +7 -0
+    #[inline]
+    pub fn zap_page_range_single(&self, address: usize, size: usize) {
+        // SAFETY: By the type invariants, the caller has read access to this VMA, which is
+        // sufficient for this method call. This method has no requirements on the vma flags. Any
+        // value of `address` and `size` is allowed.
+        unsafe {
+            bindings::zap_page_range_single(
Quoted 5 lines

Hm weirdly I see this in rust/bindings/bindings_generated.rs but not in rust/helpers/mm.c is this intended?

Is this meant to be generated _from_ somewhere? Is something missing for that?

The bindings_generated.rs file is generated at built-time from C headers. The zap_page_range_single is a real function, not a fake static inline header-only function, so bindgen is able to generate it without anything in rust/helpers.

Quoted 6 lines
Quoted 6 lines
rust/kernel/mm/virt.rs new file +6 -0
+                self.as_ptr(),
+                address as _,
+                size as _,
+                core::ptr::null_mut(),
+            )
+        };
Quoted 8 lines

rust/kernel/mm/virt.rs line 87

Quoted 6 lines
rust/kernel/mm/virt.rs new file +6 -0
+    }
+}
+
+/// The integer type used for vma flags.
+#[doc(inline)]
+pub use bindings::vm_flags_t;

Where do you declare this type?

Quoted 1 line

It's declared in include/linux/mm_types.h

I meant from a rust perspective, but I guess bindgen handles this?

Quoted 8 lines
Quoted 6 lines

rust/kernel/mm/virt.rs line 88

Quoted 3 lines
rust/kernel/mm/virt.rs new file +2 -0
+
+/// All possible flags for [`VmAreaRef`].

Well you've not specified all as they're some speciailist ones and ones that depend on config flags, so maybe worth just saying 'core' flags?

Sure.

Thanks.

Quoted 6 lines
Quoted 4 lines

rust/kernel/mm/virt.rs line 90

Quoted 2 lines
rust/kernel/mm/virt.rs new file +1 -0
+pub mod flags {

Pure rust noobie question (again...) but what is a 'mod'?

It's a module.

Ack.

Quoted 14 lines
Quoted 7 lines

rust/kernel/mm/virt.rs line 95

Quoted 6 lines
rust/kernel/mm/virt.rs new file +5 -0
+    use super::vm_flags_t;
+    use crate::bindings;
+
+    /// No flags are set.
+    pub const NONE: vm_flags_t = bindings::VM_NONE as _;
Quoted 6 lines

This is strictly not a flag, as is the 0 value (and is used 'cleverly' in kernel code when we have flags that are defined under some circumstances but not others, where we can then assign these values to VM_NONE if not available, ensuring all |= ... operations are no-ops and all & ... expressions evaluate to false) but I guess it doesn't matter all too much right?

Quoted 2 lines

Ultimately it's just a bunch of integer constants. We can include or exclude whichever ones we prefer.

Yeah not a big deal.

Quoted 53 lines
Quoted 44 lines
Quoted 44 lines
rust/kernel/mm/virt.rs new file +43 -0
+    /// Mapping allows reads.
+    pub const READ: vm_flags_t = bindings::VM_READ as _;
+
+    /// Mapping allows writes.
+    pub const WRITE: vm_flags_t = bindings::VM_WRITE as _;
+
+    /// Mapping allows execution.
+    pub const EXEC: vm_flags_t = bindings::VM_EXEC as _;
+
+    /// Mapping is shared.
+    pub const SHARED: vm_flags_t = bindings::VM_SHARED as _;
+
+    /// Mapping may be updated to allow reads.
+    pub const MAYREAD: vm_flags_t = bindings::VM_MAYREAD as _;
+
+    /// Mapping may be updated to allow writes.
+    pub const MAYWRITE: vm_flags_t = bindings::VM_MAYWRITE as _;
+
+    /// Mapping may be updated to allow execution.
+    pub const MAYEXEC: vm_flags_t = bindings::VM_MAYEXEC as _;
+
+    /// Mapping may be updated to be shared.
+    pub const MAYSHARE: vm_flags_t = bindings::VM_MAYSHARE as _;
+
+    /// Page-ranges managed without `struct page`, just pure PFN.
+    pub const PFNMAP: vm_flags_t = bindings::VM_PFNMAP as _;
+
+    /// Memory mapped I/O or similar.
+    pub const IO: vm_flags_t = bindings::VM_IO as _;
+
+    /// Do not copy this vma on fork.
+    pub const DONTCOPY: vm_flags_t = bindings::VM_DONTCOPY as _;
+
+    /// Cannot expand with mremap().
+    pub const DONTEXPAND: vm_flags_t = bindings::VM_DONTEXPAND as _;
+
+    /// Lock the pages covered when they are faulted in.
+    pub const LOCKONFAULT: vm_flags_t = bindings::VM_LOCKONFAULT as _;
+
+    /// Is a VM accounted object.
+    pub const ACCOUNT: vm_flags_t = bindings::VM_ACCOUNT as _;
+
+    /// should the VM suppress accounting.
Quoted 8 lines

rust/kernel/mm/virt.rs line 145

Quoted 6 lines
rust/kernel/mm/virt.rs new file +6 -0
+    pub const NORESERVE: vm_flags_t = bindings::VM_NORESERVE as _;
+
+    /// Huge TLB Page VM.
+    pub const HUGETLB: vm_flags_t = bindings::VM_HUGETLB as _;
+
+    /// Synchronous page faults.

Might be worth mentioning that this is DAX-specific only.

Quoted 1 line

Will add.

Ack.

Quoted 11 lines
Quoted 10 lines

rust/kernel/mm/virt.rs line 151

Quoted 7 lines
rust/kernel/mm/virt.rs new file +6 -0
+    pub const SYNC: vm_flags_t = bindings::VM_SYNC as _;
+
+    /// Architecture-specific flag.
+    pub const ARCH_1: vm_flags_t = bindings::VM_ARCH_1 as _;
+
+    /// Wipe VMA contents in child..

Typo '..' - also probably worth saying 'wipe VMA contents in child on fork'.

Quoted 1 line

Will add.

Ack, thanks.

Quoted 27 lines
Quoted 18 lines
Quoted 18 lines
rust/kernel/mm/virt.rs new file +17 -0
+    pub const WIPEONFORK: vm_flags_t = bindings::VM_WIPEONFORK as _;
+
+    /// Do not include in the core dump.
+    pub const DONTDUMP: vm_flags_t = bindings::VM_DONTDUMP as _;
+
+    /// Not soft dirty clean area.
+    pub const SOFTDIRTY: vm_flags_t = bindings::VM_SOFTDIRTY as _;
+
+    /// Can contain `struct page` and pure PFN pages.
+    pub const MIXEDMAP: vm_flags_t = bindings::VM_MIXEDMAP as _;
+
+    /// MADV_HUGEPAGE marked this vma.
+    pub const HUGEPAGE: vm_flags_t = bindings::VM_HUGEPAGE as _;
+
+    /// MADV_NOHUGEPAGE marked this vma.
+    pub const NOHUGEPAGE: vm_flags_t = bindings::VM_NOHUGEPAGE as _;
+
Quoted 8 lines

rust/kernel/mm/virt.rs line 171

Quoted 4 lines
rust/kernel/mm/virt.rs new file +3 -0
+    /// KSM may merge identical pages.
+    pub const MERGEABLE: vm_flags_t = bindings::VM_MERGEABLE as _;
+}

I'd say these comments are a bit sparse and need more detail, but they are literally comments from include/linux/mm.h and therefore, again, our fault so this is fine :)

Quoted 1 line

Happy to add more if you tell me what you'd like to see. ;)

Sure, this is fine for now.

Quoted 2 lines

Alice

author maintainer
#12 lore raw

Re: [PATCH v8 2/7] mm: rust: add vm_area_struct methods that require read access

Quoted 25 lines · Lorenzo Stoakes
Quoted 23 lines · Alice Ryhl
Quoted 20 lines · Lorenzo Stoakes

rust/kernel/mm/virt.rs line 68

Quoted 8 lines · Alice Ryhl
rust/kernel/mm/virt.rs new file +8 -0
+    #[inline]
+    pub fn end(&self) -> usize {
+        // SAFETY: By the type invariants, the caller holds at least the mmap read lock, so this
+        // access is not a data race.
+        unsafe { (*self.as_ptr()).__bindgen_anon_1.__bindgen_anon_1.vm_end as _ }
+    }
+
+    /// Unmap pages in the given page range.

This needs some more description, as 'unmapping' pages is unfortunately an overloaded term in the kernel and this very much might confuse people as opposed to e.g. munmap()'ing a range.

I'd say something like 'clear page table mappings for the range at the leaf level, leaving all other page tables intact, freeing any memory referenced by the VMA in this range (anonymous memory is completely freed, file-backed memory has its reference count on page cache folio's dropped, any dirty data will still be written back to disk as usual)'.

Quoted 5 lines
Quoted 1 line

Sure, will add that to the docs.

Thanks, I assume you mean this comment, which will form part of the docs? As here we should at least replace the 'unmap' with 'zap' to avoid confusion vs. munmap().

Yes. Comments with three slashes are rendered in the html documentation.

Quoted 34 lines
Quoted 34 lines
Quoted 8 lines

rust/kernel/mm/virt.rs line 75

Quoted 7 lines
rust/kernel/mm/virt.rs new file +7 -0
+    #[inline]
+    pub fn zap_page_range_single(&self, address: usize, size: usize) {
+        // SAFETY: By the type invariants, the caller has read access to this VMA, which is
+        // sufficient for this method call. This method has no requirements on the vma flags. Any
+        // value of `address` and `size` is allowed.
+        unsafe {
+            bindings::zap_page_range_single(
Quoted 5 lines

Hm weirdly I see this in rust/bindings/bindings_generated.rs but not in rust/helpers/mm.c is this intended?

Is this meant to be generated _from_ somewhere? Is something missing for that?

The bindings_generated.rs file is generated at built-time from C headers. The zap_page_range_single is a real function, not a fake static inline header-only function, so bindgen is able to generate it without anything in rust/helpers.

Quoted 14 lines

rust/kernel/mm/virt.rs line 87

Quoted 12 lines
rust/kernel/mm/virt.rs new file +12 -0
+                self.as_ptr(),
+                address as _,
+                size as _,
+                core::ptr::null_mut(),
+            )
+        };
+    }
+}
+
+/// The integer type used for vma flags.
+#[doc(inline)]
+pub use bindings::vm_flags_t;

Where do you declare this type?

Quoted 3 lines
Quoted 1 line

It's declared in include/linux/mm_types.h

I meant from a rust perspective, but I guess bindgen handles this?

Yes, anything in bindings:: is output from bindgen based on C headers.

Alice

author maintainer
#13 lore raw

PATCH v8 3/7 mm: rust: add vm_insert_page

In reply to Alice Ryhl

The vm_insert_page method is only usable on vmas with the VM_MIXEDMAP flag, so we introduce a new type to keep track of such vmas.

The approach used in this patch assumes that we will not need to encode many flag combinations in the type. I don't think we need to encode more than VM_MIXEDMAP and VM_PFNMAP as things are now. However, if that becomes necessary, using generic parameters in a single type would scale better as the number of flags increases.

---
 rust/kernel/mm/virt.rs | 68 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 67 insertions(+), 1 deletion(-)
rust/kernel/mm/virt.rs +67 -1
index 1e755dca46dd..de7f2338810a 100644
@@ -4,7 +4,14 @@
 
 //! Virtual memory.
 
-use crate::{bindings, types::Opaque};
+use crate::{
+    bindings,
+    error::{to_result, Result},
+    page::Page,
+    types::Opaque,
+};
+
+use core::ops::Deref;
 
 /// A wrapper for the kernel's `struct vm_area_struct` with read access.
 ///
@@ -80,6 +87,65 @@ pub fn zap_page_range_single(&self, address: usize, size: usize) {
             )
         };
     }
+
+    /// Check whether the `VM_MIXEDMAP` flag is set.
+    #[inline]
+    pub fn check_mixedmap(&self) -> Option<&VmAreaMixedMap> {
+        if self.flags() & flags::MIXEDMAP != 0 {
+            // SAFETY: We just checked that `VM_MIXEDMAP` is set. All other requirements are
+            // satisfied by the type invariants of `VmAreaRef`.
+            Some(unsafe { VmAreaMixedMap::from_raw(self.as_ptr()) })
+        } else {
+            None
+        }
+    }
+}
+
+/// A wrapper for the kernel's `struct vm_area_struct` with read access and `VM_MIXEDMAP` set.
+///
+/// It represents an area of virtual memory.
+///
+/// # Invariants
+///
+/// The caller must hold the mmap read lock or the vma read lock. The `VM_MIXEDMAP` flag must be
+/// set.
+#[repr(transparent)]
+pub struct VmAreaMixedMap {
+    vma: VmAreaRef,
+}
+
+// Make all `VmAreaRef` methods available on `VmAreaMixedMap`.
+impl Deref for VmAreaMixedMap {
+    type Target = VmAreaRef;
+
+    #[inline]
+    fn deref(&self) -> &VmAreaRef {
+        &self.vma
+    }
+}
+
+impl VmAreaMixedMap {
+    /// Access a virtual memory area given a raw pointer.
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that `vma` is valid for the duration of 'a, and that the mmap read lock
+    /// (or stronger) is held for at least the duration of 'a. The `VM_MIXEDMAP` flag must be set.
+    #[inline]
+    pub unsafe fn from_raw<'a>(vma: *const bindings::vm_area_struct) -> &'a Self {
+        // SAFETY: The caller ensures that the invariants are satisfied for the duration of 'a.
+        unsafe { &*vma.cast() }
+    }
+
+    /// Maps a single page at the given address within the virtual memory area.
+    ///
+    /// This operation does not take ownership of the page.
+    #[inline]
+    pub fn vm_insert_page(&self, address: usize, page: &Page) -> Result {
+        // SAFETY: The caller has read access and has verified that `VM_MIXEDMAP` is set. The page
+        // is order 0. The address is checked on the C side so it can take any value.
+        to_result(unsafe { bindings::vm_insert_page(self.as_ptr(), address as _, page.as_ptr()) })
+    }
 }
 
 /// The integer type used for vma flags.
Signature · 1 line
2.47.0.371.ga323438b13-goog
#14 lore raw

Re: [PATCH v8 3/7] mm: rust: add vm_insert_page

Quoted 2 lines · Alice Ryhl

The vm_insert_page method is only usable on vmas with the VM_MIXEDMAP flag, so we introduce a new type to keep track of such vmas.

Worth mentioning that it can be used for VMAs without this flag set, but if so we must hold a _write_ lock to be able to do so, so it can update the flag itself, however we intend only to use it with VMAs which already have this flag set.

Quoted 33 lines

The approach used in this patch assumes that we will not need to encode many flag combinations in the type. I don't think we need to encode more than VM_MIXEDMAP and VM_PFNMAP as things are now. However, if that becomes necessary, using generic parameters in a single type would scale better as the number of flags increases.

---
 rust/kernel/mm/virt.rs | 68 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 67 insertions(+), 1 deletion(-)
rust/kernel/mm/virt.rs +8 -1
index 1e755dca46dd..de7f2338810a 100644
@@ -4,7 +4,14 @@
 
 //! Virtual memory.
 
-use crate::{bindings, types::Opaque};
+use crate::{
+    bindings,
+    error::{to_result, Result},
+    page::Page,
+    types::Opaque,
+};
+
+use core::ops::Deref;
 
 /// A wrapper for the kernel's `struct vm_area_struct` with read access.
 ///

rust/kernel/mm/virt.rs pub fn zap_page_range_single(&self, address: usize, size: usize) { · line 93

Quoted 7 lines
rust/kernel/mm/virt.rs +4 -0
@@ -80,6 +87,65 @@ pub fn zap_page_range_single(&self, address: usize, size: usize) {
             )
         };
     }
+
+    /// Check whether the `VM_MIXEDMAP` flag is set.
+    #[inline]
+    pub fn check_mixedmap(&self) -> Option<&VmAreaMixedMap> {

Nitty + a little bikesheddy (this may be my mistake as I am unfamiliar with rust idioms also) but shouldn't this be 'as_mixedmap_vma()' or something?

Quoted 22 lines
rust/kernel/mm/virt.rs +22 -0
+        if self.flags() & flags::MIXEDMAP != 0 {
+            // SAFETY: We just checked that `VM_MIXEDMAP` is set. All other requirements are
+            // satisfied by the type invariants of `VmAreaRef`.
+            Some(unsafe { VmAreaMixedMap::from_raw(self.as_ptr()) })
+        } else {
+            None
+        }
+    }
+}
+
+/// A wrapper for the kernel's `struct vm_area_struct` with read access and `VM_MIXEDMAP` set.
+///
+/// It represents an area of virtual memory.
+///
+/// # Invariants
+///
+/// The caller must hold the mmap read lock or the vma read lock. The `VM_MIXEDMAP` flag must be
+/// set.
+#[repr(transparent)]
+pub struct VmAreaMixedMap {
+    vma: VmAreaRef,
+}

rust/kernel/mm/virt.rs pub fn zap_page_range_single(&self, address: usize, size: usize) { · line 125

Quoted 10 lines
rust/kernel/mm/virt.rs +10 -0
+
+// Make all `VmAreaRef` methods available on `VmAreaMixedMap`.
+impl Deref for VmAreaMixedMap {
+    type Target = VmAreaRef;
+
+    #[inline]
+    fn deref(&self) -> &VmAreaRef {
+        &self.vma
+    }
+}

Ah OK, thinking back to the 'impl Deref' from the other patch, I guess this allows you to deref VmAreaMixedMap as a VmAreaRef, does it all sort of automagically merge methods for you as if they were mix-ins then?

Quoted 9 lines
rust/kernel/mm/virt.rs +9 -0
+
+impl VmAreaMixedMap {
+    /// Access a virtual memory area given a raw pointer.
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that `vma` is valid for the duration of 'a, and that the mmap read lock
+    /// (or stronger) is held for at least the duration of 'a. The `VM_MIXEDMAP` flag must be set.
+    #[inline]

rust/kernel/mm/virt.rs pub fn zap_page_range_single(&self, address: usize, size: usize) { · line 144

Quoted 10 lines
rust/kernel/mm/virt.rs +10 -0
+    pub unsafe fn from_raw<'a>(vma: *const bindings::vm_area_struct) -> &'a Self {
+        // SAFETY: The caller ensures that the invariants are satisfied for the duration of 'a.
+        unsafe { &*vma.cast() }
+    }
+
+    /// Maps a single page at the given address within the virtual memory area.
+    ///
+    /// This operation does not take ownership of the page.
+    #[inline]
+    pub fn vm_insert_page(&self, address: usize, page: &Page) -> Result {

I'm guessing this 'Result' type encodes 0 vs. -Exxx error codes?

rust/kernel/mm/virt.rs pub fn zap_page_range_single(&self, address: usize, size: usize) { · line 149

Quoted 5 lines
rust/kernel/mm/virt.rs +4 -0
+        // SAFETY: The caller has read access and has verified that `VM_MIXEDMAP` is set. The page
+        // is order 0. The address is checked on the C side so it can take any value.
+        to_result(unsafe { bindings::vm_insert_page(self.as_ptr(), address as _, page.as_ptr()) })
+    }
 }

It's really nice to abstract this as a seprate type and then to know its methods only apply in known circumstances... I guess in future we can use clever generic types when it comes to combinations of characteristics that would otherwise result in a combinatorial explosion?

Quoted 6 lines
rust/kernel/mm/virt.rs +0 -1
 /// The integer type used for vma flags.
 
--

2.47.0.371.ga323438b13-goog

author maintainer
#15 lore raw

Re: [PATCH v8 3/7] mm: rust: add vm_insert_page

Quoted 9 lines · Lorenzo Stoakes
Quoted 2 lines · Alice Ryhl

The vm_insert_page method is only usable on vmas with the VM_MIXEDMAP flag, so we introduce a new type to keep track of such vmas.

Worth mentioning that it can be used for VMAs without this flag set, but if so we must hold a _write_ lock to be able to do so, so it can update the flag itself, however we intend only to use it with VMAs which already have this flag set.

I got the impression from Jann that the automatically-set-VM_MIXEDMAP thing should only be used during mmap, and that VM_MIXEDMAP should not get set after initialization even with a write lock?
https://lore.kernel.org/all/CAG48ez3gXicVYXiPsQDmYuPSsKMbES2KRQDk+0ANWSS0zDkqSw@mail.gmail.com/

Quoted 29 lines
Quoted 29 lines

The approach used in this patch assumes that we will not need to encode many flag combinations in the type. I don't think we need to encode more than VM_MIXEDMAP and VM_PFNMAP as things are now. However, if that becomes necessary, using generic parameters in a single type would scale better as the number of flags increases.

---
 rust/kernel/mm/virt.rs | 68 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 67 insertions(+), 1 deletion(-)
rust/kernel/mm/virt.rs +8 -1
index 1e755dca46dd..de7f2338810a 100644
@@ -4,7 +4,14 @@
 
 //! Virtual memory.
 
-use crate::{bindings, types::Opaque};
+use crate::{
+    bindings,
+    error::{to_result, Result},
+    page::Page,
+    types::Opaque,
+};
+
+use core::ops::Deref;
 
Quoted 13 lines

rust/kernel/mm/virt.rs pub fn zap_page_range_single(&self, address: usize, size: usize) { · line 93

Quoted 10 lines
rust/kernel/mm/virt.rs +4 -0
 /// A wrapper for the kernel's `struct vm_area_struct` with read access.
 ///
@@ -80,6 +87,65 @@ pub fn zap_page_range_single(&self, address: usize, size: usize) {
             )
         };
     }
+
+    /// Check whether the `VM_MIXEDMAP` flag is set.
+    #[inline]
+    pub fn check_mixedmap(&self) -> Option<&VmAreaMixedMap> {

Nitty + a little bikesheddy (this may be my mistake as I am unfamiliar with rust idioms also) but shouldn't this be 'as_mixedmap_vma()' or something?

You're probably right that this name is more consistent with Rust naming conventions. :)

Quoted 28 lines
Quoted 28 lines
rust/kernel/mm/virt.rs +28 -0
+        if self.flags() & flags::MIXEDMAP != 0 {
+            // SAFETY: We just checked that `VM_MIXEDMAP` is set. All other requirements are
+            // satisfied by the type invariants of `VmAreaRef`.
+            Some(unsafe { VmAreaMixedMap::from_raw(self.as_ptr()) })
+        } else {
+            None
+        }
+    }
+}
+
+/// A wrapper for the kernel's `struct vm_area_struct` with read access and `VM_MIXEDMAP` set.
+///
+/// It represents an area of virtual memory.
+///
+/// # Invariants
+///
+/// The caller must hold the mmap read lock or the vma read lock. The `VM_MIXEDMAP` flag must be
+/// set.
+#[repr(transparent)]
+pub struct VmAreaMixedMap {
+    vma: VmAreaRef,
+}
+
+// Make all `VmAreaRef` methods available on `VmAreaMixedMap`.
+impl Deref for VmAreaMixedMap {
+    type Target = VmAreaRef;
+
+    #[inline]
Quoted 8 lines

rust/kernel/mm/virt.rs pub fn zap_page_range_single(&self, address: usize, size: usize) { · line 125

Quoted 4 lines
rust/kernel/mm/virt.rs +4 -0
+    fn deref(&self) -> &VmAreaRef {
+        &self.vma
+    }
+}

Ah OK, thinking back to the 'impl Deref' from the other patch, I guess this allows you to deref VmAreaMixedMap as a VmAreaRef, does it all sort of automagically merge methods for you as if they were mix-ins then?

Yeah, I use it to "merge" the method sets to avoid duplication.

The main limitation is that you can only deref to one other type, so you can't have "diamond inheritance".

Quoted 12 lines
Quoted 12 lines
rust/kernel/mm/virt.rs +12 -0
+impl VmAreaMixedMap {
+    /// Access a virtual memory area given a raw pointer.
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that `vma` is valid for the duration of 'a, and that the mmap read lock
+    /// (or stronger) is held for at least the duration of 'a. The `VM_MIXEDMAP` flag must be set.
+    #[inline]
+    pub unsafe fn from_raw<'a>(vma: *const bindings::vm_area_struct) -> &'a Self {
+        // SAFETY: The caller ensures that the invariants are satisfied for the duration of 'a.
+        unsafe { &*vma.cast() }
+    }
Quoted 8 lines

rust/kernel/mm/virt.rs pub fn zap_page_range_single(&self, address: usize, size: usize) { · line 144

Quoted 6 lines
rust/kernel/mm/virt.rs +6 -0
+
+    /// Maps a single page at the given address within the virtual memory area.
+    ///
+    /// This operation does not take ownership of the page.
+    #[inline]
+    pub fn vm_insert_page(&self, address: usize, page: &Page) -> Result {

I'm guessing this 'Result' type encodes 0 vs. -Exxx error codes?

In this particular case, yes.

More generally, Result is a discriminated union containing either Ok(val) for success or Err(err) with some error type. But the default success type is the unit type () and the default error type is kernel::error::Error which corresponds to errno numbers.

In this case, the compiler is clever enough to not use a discriminated union and instead represents Ok(()) as 0 and Err(err) as just the negative errno. This works since kernel::error::Error uses NonZeroI32 as its only field (as of 6.13).

Quoted 10 lines

rust/kernel/mm/virt.rs pub fn zap_page_range_single(&self, address: usize, size: usize) { · line 149

Quoted 5 lines
rust/kernel/mm/virt.rs +4 -0
+        // SAFETY: The caller has read access and has verified that `VM_MIXEDMAP` is set. The page
+        // is order 0. The address is checked on the C side so it can take any value.
+        to_result(unsafe { bindings::vm_insert_page(self.as_ptr(), address as _, page.as_ptr()) })
+    }
 }

It's really nice to abstract this as a seprate type and then to know its methods only apply in known circumstances... I guess in future we can use clever generic types when it comes to combinations of characteristics that would otherwise result in a combinatorial explosion?

Yeah, so the alternate approach I mention in the commit message would be to have something like this:

struct VmAreaRef<const MIXEDMAP: bool, const PFNMAP: bool, const
MAYWRITE: bool> { ... }

listing all the flags we care about. This way, we get 2^3 different types by writing just one.

(There are a few different variations on how to do this, instead of bools, we may want to allow three options: true, false, unknown.)

Alice

#16 lore raw

Re: [PATCH v8 3/7] mm: rust: add vm_insert_page

Quoted 12 lines · Alice Ryhl
Quoted 9 lines · Lorenzo Stoakes
Quoted 2 lines · Alice Ryhl

The vm_insert_page method is only usable on vmas with the VM_MIXEDMAP flag, so we introduce a new type to keep track of such vmas.

Worth mentioning that it can be used for VMAs without this flag set, but if so we must hold a _write_ lock to be able to do so, so it can update the flag itself, however we intend only to use it with VMAs which already have this flag set.

Quoted 4 lines

I got the impression from Jann that the automatically-set-VM_MIXEDMAP thing should only be used during mmap, and that VM_MIXEDMAP should not get set after initialization even with a write lock?
https://lore.kernel.org/all/CAG48ez3gXicVYXiPsQDmYuPSsKMbES2KRQDk+0ANWSS0zDkqSw@mail.gmail.com/

Yeah he's right, but we do allow that to happen, perhaps we shouldn't. A separate patch idea ;)

In that case let's leave this bit out, as while we allow it, it seems inadvisible except on very early internal mm initialisation perhaps.

Quoted 8 lines
Quoted 8 lines
Quoted 8 lines

The approach used in this patch assumes that we will not need to encode many flag combinations in the type. I don't think we need to encode more than VM_MIXEDMAP and VM_PFNMAP as things are now. However, if that becomes necessary, using generic parameters in a single type would scale better as the number of flags increases.

Quoted 36 lines
Quoted 22 lines
Quoted 22 lines
---
 rust/kernel/mm/virt.rs | 68 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 67 insertions(+), 1 deletion(-)
rust/kernel/mm/virt.rs +8 -1
index 1e755dca46dd..de7f2338810a 100644
@@ -4,7 +4,14 @@
 
 //! Virtual memory.
 
-use crate::{bindings, types::Opaque};
+use crate::{
+    bindings,
+    error::{to_result, Result},
+    page::Page,
+    types::Opaque,
+};
+
+use core::ops::Deref;
 
Quoted 13 lines

rust/kernel/mm/virt.rs pub fn zap_page_range_single(&self, address: usize, size: usize) { · line 93

Quoted 10 lines
rust/kernel/mm/virt.rs +4 -0
 /// A wrapper for the kernel's `struct vm_area_struct` with read access.
 ///
@@ -80,6 +87,65 @@ pub fn zap_page_range_single(&self, address: usize, size: usize) {
             )
         };
     }
+
+    /// Check whether the `VM_MIXEDMAP` flag is set.
+    #[inline]
+    pub fn check_mixedmap(&self) -> Option<&VmAreaMixedMap> {

Nitty + a little bikesheddy (this may be my mistake as I am unfamiliar with rust idioms also) but shouldn't this be 'as_mixedmap_vma()' or something?

Quoted 2 lines

You're probably right that this name is more consistent with Rust naming conventions. :)

Yeah, I think it's reasonable in rust code to follow rust idioms and conventions.

Quoted 38 lines
Quoted 29 lines
Quoted 29 lines
rust/kernel/mm/virt.rs +28 -0
+        if self.flags() & flags::MIXEDMAP != 0 {
+            // SAFETY: We just checked that `VM_MIXEDMAP` is set. All other requirements are
+            // satisfied by the type invariants of `VmAreaRef`.
+            Some(unsafe { VmAreaMixedMap::from_raw(self.as_ptr()) })
+        } else {
+            None
+        }
+    }
+}
+
+/// A wrapper for the kernel's `struct vm_area_struct` with read access and `VM_MIXEDMAP` set.
+///
+/// It represents an area of virtual memory.
+///
+/// # Invariants
+///
+/// The caller must hold the mmap read lock or the vma read lock. The `VM_MIXEDMAP` flag must be
+/// set.
+#[repr(transparent)]
+pub struct VmAreaMixedMap {
+    vma: VmAreaRef,
+}
+
+// Make all `VmAreaRef` methods available on `VmAreaMixedMap`.
+impl Deref for VmAreaMixedMap {
+    type Target = VmAreaRef;
+
+    #[inline]
Quoted 8 lines

rust/kernel/mm/virt.rs pub fn zap_page_range_single(&self, address: usize, size: usize) { · line 125

Quoted 4 lines
rust/kernel/mm/virt.rs +4 -0
+    fn deref(&self) -> &VmAreaRef {
+        &self.vma
+    }
+}

Ah OK, thinking back to the 'impl Deref' from the other patch, I guess this allows you to deref VmAreaMixedMap as a VmAreaRef, does it all sort of automagically merge methods for you as if they were mix-ins then?

Quoted 4 lines

Yeah, I use it to "merge" the method sets to avoid duplication.

The main limitation is that you can only deref to one other type, so you can't have "diamond inheritance".

Aww, diamond inheritance is such fun though! ;)

Quoted 29 lines
Quoted 13 lines
Quoted 13 lines
rust/kernel/mm/virt.rs +12 -0
+impl VmAreaMixedMap {
+    /// Access a virtual memory area given a raw pointer.
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that `vma` is valid for the duration of 'a, and that the mmap read lock
+    /// (or stronger) is held for at least the duration of 'a. The `VM_MIXEDMAP` flag must be set.
+    #[inline]
+    pub unsafe fn from_raw<'a>(vma: *const bindings::vm_area_struct) -> &'a Self {
+        // SAFETY: The caller ensures that the invariants are satisfied for the duration of 'a.
+        unsafe { &*vma.cast() }
+    }
Quoted 8 lines

rust/kernel/mm/virt.rs pub fn zap_page_range_single(&self, address: usize, size: usize) { · line 144

Quoted 6 lines
rust/kernel/mm/virt.rs +6 -0
+
+    /// Maps a single page at the given address within the virtual memory area.
+    ///
+    /// This operation does not take ownership of the page.
+    #[inline]
+    pub fn vm_insert_page(&self, address: usize, page: &Page) -> Result {

I'm guessing this 'Result' type encodes 0 vs. -Exxx error codes?

In this particular case, yes.

More generally, Result is a discriminated union containing either Ok(val) for success or Err(err) with some error type. But the default success type is the unit type () and the default error type is kernel::error::Error which corresponds to errno numbers.

Quoted 4 lines

In this case, the compiler is clever enough to not use a discriminated union and instead represents Ok(()) as 0 and Err(err) as just the negative errno. This works since kernel::error::Error uses NonZeroI32 as its only field (as of 6.13).

Kinda selling me on rust again...

Quoted 15 lines
Quoted 11 lines

rust/kernel/mm/virt.rs pub fn zap_page_range_single(&self, address: usize, size: usize) { · line 149

Quoted 6 lines
rust/kernel/mm/virt.rs +4 -0
+        // SAFETY: The caller has read access and has verified that `VM_MIXEDMAP` is set. The page
+        // is order 0. The address is checked on the C side so it can take any value.
+        to_result(unsafe { bindings::vm_insert_page(self.as_ptr(), address as _, page.as_ptr()) })
+    }
 }

It's really nice to abstract this as a seprate type and then to know its methods only apply in known circumstances... I guess in future we can use clever generic types when it comes to combinations of characteristics that would otherwise result in a combinatorial explosion?

Yeah, so the alternate approach I mention in the commit message would be to have something like this:

Quoted 8 lines

struct VmAreaRef<const MIXEDMAP: bool, const PFNMAP: bool, const
MAYWRITE: bool> { ... }

listing all the flags we care about. This way, we get 2^3 different types by writing just one.

(There are a few different variations on how to do this, instead of bools, we may want to allow three options: true, false, unknown.)

Sure, it's something we can come to later I guess as we progress.

Quoted 2 lines

Alice

author maintainer
#17 lore raw

PATCH v8 4/7 mm: rust: add lock_vma_under_rcu

In reply to Alice Ryhl

All of Rust Binder's existing calls to vm_insert_page could be optimized to first attempt to use lock_vma_under_rcu. This patch provides an abstraction to enable that.

---
 rust/helpers/mm.c |  5 +++++
 rust/kernel/mm.rs | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)
rust/helpers/mm.c +5 -0
index 7b72eb065a3e..81b510c96fd2 100644
@@ -43,3 +43,8 @@ struct vm_area_struct *rust_helper_vma_lookup(struct mm_struct *mm,
 {
 	return vma_lookup(mm, addr);
 }
+
+void rust_helper_vma_end_read(struct vm_area_struct *vma)
+{
+	vma_end_read(vma);
+}
rust/kernel/mm.rs +56 -0

71 lines not on this page · raw message

Signature · 1 line
2.47.0.371.ga323438b13-goog
#18 lore raw

Re: [PATCH v8 4/7] mm: rust: add lock_vma_under_rcu

Quoted 3 lines · Alice Ryhl

All of Rust Binder's existing calls to vm_insert_page could be optimized to first attempt to use lock_vma_under_rcu. This patch provides an abstraction to enable that.

I think there should be a blurb about what the VMA locks are, how they avoid contention on the mmap read lock etc. before talking about a use case (though it's useful to mention the motivating reason!)

Quoted 33 lines
---
 rust/helpers/mm.c |  5 +++++
 rust/kernel/mm.rs | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)
rust/helpers/mm.c +5 -0
index 7b72eb065a3e..81b510c96fd2 100644
@@ -43,3 +43,8 @@ struct vm_area_struct *rust_helper_vma_lookup(struct mm_struct *mm,
 {
 	return vma_lookup(mm, addr);
 }
+
+void rust_helper_vma_end_read(struct vm_area_struct *vma)
+{
+	vma_end_read(vma);
+}
rust/kernel/mm.rs +1 -0
index ace8e7d57afe..a15acb546f68 100644
@@ -13,6 +13,7 @@
 use core::{ops::Deref, ptr::NonNull};
 
 pub mod virt;
+use virt::VmAreaRef;
 
 /// A wrapper for the kernel's `struct mm_struct`.
 ///

rust/kernel/mm.rs pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser { · line 174

Quoted 4 lines
rust/kernel/mm.rs +1 -0
@@ -170,6 +171,32 @@ pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser {
         unsafe { &*ptr.cast() }
     }
 
+    /// Try to lock the vma read lock under rcu.

This reads oddly, I'd say 'try to acquire the VMA read lock'. It's not really necessary to mention RCU here I'd say, as while lock_vma_under_rcu() acquires the RCU lock in order to try to get the VMA read lock, it releases it afterwards and you hold the VMA read luck until you are done with it and don't need to hold an RCU lock.

A reader might otherwise be confused and think an RCU read lock is required to be held throughout too which isn't the case (this is maybe a critique of the name of the function too, sorry Suren :P).

rust/kernel/mm.rs pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser { · line 177

Quoted 3 lines
rust/kernel/mm.rs +3 -0
+    ///
+    /// If this operation fails, the vma may still exist. In that case, you should take the mmap
+    /// read lock and try to use `vma_lookup` instead.

This also reads oddly, you're more likely (assuming you are not arbitrarily trying to acquire a lock on an address likely to be unmapped soon) to have failed due to lock contention.

So I'd say 'this is an optimistic try lock operation, so it may fail, in which case you should fall back to taking the mmap read lock'.

I'm not sure it's necessary to reference vma_lookup() either, especially as in future versions of this code we might want to use a VMA iterator instead.

rust/kernel/mm.rs pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser { · line 181

Quoted 4 lines
rust/kernel/mm.rs +4 -0
+    ///
+    /// When per-vma locks are disabled, this always returns `None`.
+    #[inline]
+    pub fn lock_vma_under_rcu(&self, vma_addr: usize) -> Option<VmaReadGuard<'_>> {

Ah I love having lock guards available... Something I miss from C++ :>)

rust/kernel/mm.rs pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser { · line 182

Quoted 1 line
rust/kernel/mm.rs +1 -0
+        #[cfg(CONFIG_PER_VMA_LOCK)]

Ah interesting, so we have an abstraction for kernel config operations!

Quoted 41 lines
rust/kernel/mm.rs +34 -0
+        {
+            // SAFETY: Calling `bindings::lock_vma_under_rcu` is always okay given an mm where
+            // `mm_users` is non-zero.
+            let vma = unsafe { bindings::lock_vma_under_rcu(self.as_raw(), vma_addr as _) };
+            if !vma.is_null() {
+                return Some(VmaReadGuard {
+                    // SAFETY: If `lock_vma_under_rcu` returns a non-null ptr, then it points at a
+                    // valid vma. The vma is stable for as long as the vma read lock is held.
+                    vma: unsafe { VmAreaRef::from_raw(vma) },
+                    _nts: NotThreadSafe,
+                });
+            }
+        }
+
+        None
+    }
+
     /// Lock the mmap read lock.
     #[inline]
     pub fn mmap_read_lock(&self) -> MmapReadGuard<'_> {
@@ -238,3 +265,32 @@ fn drop(&mut self) {
         unsafe { bindings::mmap_read_unlock(self.mm.as_raw()) };
     }
 }
+
+/// A guard for the vma read lock.
+///
+/// # Invariants
+///
+/// This `VmaReadGuard` guard owns the vma read lock.
+pub struct VmaReadGuard<'a> {
+    vma: &'a VmAreaRef,
+    // `vma_end_read` must be called on the same thread as where the lock was taken
+    _nts: NotThreadSafe,
+}
+
+// Make all `VmAreaRef` methods available on `VmaReadGuard`.
+impl Deref for VmaReadGuard<'_> {
+    type Target = VmAreaRef;
+
+    #[inline]

rust/kernel/mm.rs fn drop(&mut self) { · line 294

Quoted 10 lines
rust/kernel/mm.rs +10 -0
+    fn deref(&self) -> &VmAreaRef {
+        self.vma
+    }
+}
+
+impl Drop for VmaReadGuard<'_> {
+    #[inline]
+    fn drop(&mut self) {
+        // SAFETY: We hold the read lock by the type invariants.
+        unsafe { bindings::vma_end_read(self.vma.as_ptr()) };

Extremely nice to know it is _guaranteed_ this will eventually be called and that we can be sure that the VMA is valid by the fact we hold it already and etc.

Selling me on this rust thing here... ;)

Quoted 6 lines
rust/kernel/mm.rs +2 -1
+    }
+}
 
--

2.47.0.371.ga323438b13-goog

author maintainer
#19 lore raw

Re: [PATCH v8 4/7] mm: rust: add lock_vma_under_rcu

Quoted 65 lines · Lorenzo Stoakes
Quoted 3 lines · Alice Ryhl

All of Rust Binder's existing calls to vm_insert_page could be optimized to first attempt to use lock_vma_under_rcu. This patch provides an abstraction to enable that.

I think there should be a blurb about what the VMA locks are, how they avoid contention on the mmap read lock etc. before talking about a use case (though it's useful to mention the motivating reason!)

Quoted 33 lines
---
 rust/helpers/mm.c |  5 +++++
 rust/kernel/mm.rs | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)
rust/helpers/mm.c +5 -0
index 7b72eb065a3e..81b510c96fd2 100644
@@ -43,3 +43,8 @@ struct vm_area_struct *rust_helper_vma_lookup(struct mm_struct *mm,
 {
      return vma_lookup(mm, addr);
 }
+
+void rust_helper_vma_end_read(struct vm_area_struct *vma)
+{
+     vma_end_read(vma);
+}
rust/kernel/mm.rs +1 -0
index ace8e7d57afe..a15acb546f68 100644
@@ -13,6 +13,7 @@
 use core::{ops::Deref, ptr::NonNull};
 
 pub mod virt;
+use virt::VmAreaRef;
 
 /// A wrapper for the kernel's `struct mm_struct`.
 ///

rust/kernel/mm.rs pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser { · line 174

Quoted 4 lines
rust/kernel/mm.rs +1 -0
@@ -170,6 +171,32 @@ pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser {
         unsafe { &*ptr.cast() }
     }
 
+    /// Try to lock the vma read lock under rcu.

This reads oddly, I'd say 'try to acquire the VMA read lock'. It's not really necessary to mention RCU here I'd say, as while lock_vma_under_rcu() acquires the RCU lock in order to try to get the VMA read lock, it releases it afterwards and you hold the VMA read luck until you are done with it and don't need to hold an RCU lock.

A reader might otherwise be confused and think an RCU read lock is required to be held throughout too which isn't the case (this is maybe a critique of the name of the function too, sorry Suren :P).

rust/kernel/mm.rs pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser { · line 177

Quoted 2 lines
rust/kernel/mm.rs +2 -0
+    /// If this operation fails, the vma may still exist. In that case, you should take the mmap
+    /// read lock and try to use `vma_lookup` instead.

This also reads oddly, you're more likely (assuming you are not arbitrarily trying to acquire a lock on an address likely to be unmapped soon) to have failed due to lock contention.

Quoted 5 lines

So I'd say 'this is an optimistic try lock operation, so it may fail, in which case you should fall back to taking the mmap read lock'.

I'm not sure it's necessary to reference vma_lookup() either, especially as in future versions of this code we might want to use a VMA iterator instead.

Thanks for the doc suggestions, they sound great.

Quoted 6 lines

rust/kernel/mm.rs pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser { · line 181

Quoted 4 lines
rust/kernel/mm.rs +4 -0
+    ///
+    /// When per-vma locks are disabled, this always returns `None`.
+    #[inline]
+    pub fn lock_vma_under_rcu(&self, vma_addr: usize) -> Option<VmaReadGuard<'_>> {

Ah I love having lock guards available... Something I miss from C++ :>)

I've heard that C is starting to get lock guards recently!

Quoted 3 lines

rust/kernel/mm.rs pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser { · line 182

Quoted 1 line
rust/kernel/mm.rs +1 -0
+        #[cfg(CONFIG_PER_VMA_LOCK)]

Ah interesting, so we have an abstraction for kernel config operations!

Yeah, it's basically an #ifdef, but the block must still parse even if the config is disabled.

Alice

#20 lore raw

Re: [PATCH v8 4/7] mm: rust: add lock_vma_under_rcu

Quoted 11 lines · Alice Ryhl
Quoted 9 lines · Lorenzo Stoakes
Quoted 3 lines · Alice Ryhl

All of Rust Binder's existing calls to vm_insert_page could be optimized to first attempt to use lock_vma_under_rcu. This patch provides an abstraction to enable that.

I think there should be a blurb about what the VMA locks are, how they avoid contention on the mmap read lock etc. before talking about a use case (though it's useful to mention the motivating reason!)

^ I think we should update the commit message to add this at the start then the binder stuff underneath.

Quoted 3 lines
Quoted 3 lines
Quoted 3 lines

Other than the doc stuff, this looks fine, so:

Quoted 53 lines
Quoted 53 lines
Quoted 31 lines
---
 rust/helpers/mm.c |  5 +++++
 rust/kernel/mm.rs | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)
rust/helpers/mm.c +5 -0
index 7b72eb065a3e..81b510c96fd2 100644
@@ -43,3 +43,8 @@ struct vm_area_struct *rust_helper_vma_lookup(struct mm_struct *mm,
 {
      return vma_lookup(mm, addr);
 }
+
+void rust_helper_vma_end_read(struct vm_area_struct *vma)
+{
+     vma_end_read(vma);
+}
rust/kernel/mm.rs +1 -0
index ace8e7d57afe..a15acb546f68 100644
@@ -13,6 +13,7 @@
 use core::{ops::Deref, ptr::NonNull};
 
 pub mod virt;
+use virt::VmAreaRef;
 
 /// A wrapper for the kernel's `struct mm_struct`.
 ///

rust/kernel/mm.rs pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser { · line 174

Quoted 4 lines
rust/kernel/mm.rs +1 -0
@@ -170,6 +171,32 @@ pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser {
         unsafe { &*ptr.cast() }
     }
 
+    /// Try to lock the vma read lock under rcu.

This reads oddly, I'd say 'try to acquire the VMA read lock'. It's not really necessary to mention RCU here I'd say, as while lock_vma_under_rcu() acquires the RCU lock in order to try to get the VMA read lock, it releases it afterwards and you hold the VMA read luck until you are done with it and don't need to hold an RCU lock.

A reader might otherwise be confused and think an RCU read lock is required to be held throughout too which isn't the case (this is maybe a critique of the name of the function too, sorry Suren :P).

rust/kernel/mm.rs pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser { · line 177

Quoted 2 lines
rust/kernel/mm.rs +2 -0
+    /// If this operation fails, the vma may still exist. In that case, you should take the mmap
+    /// read lock and try to use `vma_lookup` instead.

This also reads oddly, you're more likely (assuming you are not arbitrarily trying to acquire a lock on an address likely to be unmapped soon) to have failed due to lock contention.

Quoted 7 lines
Quoted 5 lines

So I'd say 'this is an optimistic try lock operation, so it may fail, in which case you should fall back to taking the mmap read lock'.

I'm not sure it's necessary to reference vma_lookup() either, especially as in future versions of this code we might want to use a VMA iterator instead.

Thanks for the doc suggestions, they sound great.

Thanks :)

Quoted 9 lines
Quoted 7 lines

rust/kernel/mm.rs pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser { · line 181

Quoted 5 lines
rust/kernel/mm.rs +4 -0
+    ///
+    /// When per-vma locks are disabled, this always returns `None`.
+    #[inline]
+    pub fn lock_vma_under_rcu(&self, vma_addr: usize) -> Option<VmaReadGuard<'_>> {

Ah I love having lock guards available... Something I miss from C++ :>)

I've heard that C is starting to get lock guards recently!

Yeah there are some (e.g. [0]) but the weak typing hinders things imo and the syntax is not fun.

This is wrt to the _kernel_ C rather than C in general though in case you were referring to the newer standard or such!

[0]: https://elixir.bootlin.com/linux/v6.12/source/include/linux/cleanup.h#L307

Quoted 8 lines
Quoted 4 lines

rust/kernel/mm.rs pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser { · line 182

Quoted 2 lines
rust/kernel/mm.rs +1 -0
+        #[cfg(CONFIG_PER_VMA_LOCK)]

Ah interesting, so we have an abstraction for kernel config operations!

Yeah, it's basically an #ifdef, but the block must still parse even if the config is disabled.

Right, kinda sane to actually make sure it parses too... :)

Quoted 1 line

Alice

author maintainer
#21 lore raw

PATCH v8 5/7 mm: rust: add mmput_async support

In reply to Alice Ryhl

Adds an MmWithUserAsync type that uses mmput_async when dropped but is otherwise identical to MmWithUser. This has to be done using a separate type because the thing we are changing is the destructor.

Rust Binder needs this to avoid a certain deadlock. See commit 9a9ab0d96362 ("binder: fix race between mmput() and do_exit()") for details. It's also needed in the shrinker to avoid cleaning up the mm in the shrinker's context.

---
 rust/kernel/mm.rs | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
rust/kernel/mm.rs +49 -0
index a15acb546f68..f800b6c244cd 100644
@@ -98,6 +98,48 @@ fn deref(&self) -> &Mm {
     }
 }
 
+/// A wrapper for the kernel's `struct mm_struct`.
+///
+/// This type is identical to `MmWithUser` except that it uses `mmput_async` when dropping a
+/// refcount. This means that the destructor of `ARef<MmWithUserAsync>` is safe to call in atomic
+/// context.
+///
+/// # Invariants
+///
+/// Values of this type are always refcounted using `mmget`. The value of `mm_users` is non-zero.
+#[repr(transparent)]
+pub struct MmWithUserAsync {
+    mm: MmWithUser,
+}
+
+// SAFETY: It is safe to call `mmput_async` on another thread than where `mmget` was called.
+unsafe impl Send for MmWithUserAsync {}
+// SAFETY: All methods on `MmWithUserAsync` can be called in parallel from several threads.
+unsafe impl Sync for MmWithUserAsync {}
+
+// SAFETY: By the type invariants, this type is always refcounted.
+unsafe impl AlwaysRefCounted for MmWithUserAsync {
+    fn inc_ref(&self) {
+        // SAFETY: The pointer is valid since self is a reference.
+        unsafe { bindings::mmget(self.as_raw()) };
+    }
+
+    unsafe fn dec_ref(obj: NonNull<Self>) {
+        // SAFETY: The caller is giving up their refcount.
+        unsafe { bindings::mmput_async(obj.cast().as_ptr()) };
+    }
+}
+
+// Make all `MmWithUser` methods available on `MmWithUserAsync`.
+impl Deref for MmWithUserAsync {
+    type Target = MmWithUser;
+
+    #[inline]
+    fn deref(&self) -> &MmWithUser {
+        &self.mm
+    }
+}
+
 // These methods are safe to call even if `mm_users` is zero.
 impl Mm {
     /// Call `mmgrab` on `current.mm`.
@@ -171,6 +213,13 @@ pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser {
         unsafe { &*ptr.cast() }
     }
 
+    /// Use `mmput_async` when dropping this refcount.
+    #[inline]
+    pub fn use_mmput_async(me: ARef<MmWithUser>) -> ARef<MmWithUserAsync> {
+        // SAFETY: The layouts and invariants are compatible.
+        unsafe { ARef::from_raw(ARef::into_raw(me).cast()) }
+    }
+
     /// Try to lock the vma read lock under rcu.
     ///
     /// If this operation fails, the vma may still exist. In that case, you should take the mmap
Signature · 1 line
2.47.0.371.ga323438b13-goog
#22 lore raw

Re: [PATCH v8 5/7] mm: rust: add mmput_async support

Quoted 8 lines · Alice Ryhl

Adds an MmWithUserAsync type that uses mmput_async when dropped but is otherwise identical to MmWithUser. This has to be done using a separate type because the thing we are changing is the destructor.

Rust Binder needs this to avoid a certain deadlock. See commit 9a9ab0d96362 ("binder: fix race between mmput() and do_exit()") for details. It's also needed in the shrinker to avoid cleaning up the mm in the shrinker's context.

Oh Lord, I didn't even know this existed... I see it was (re-)added in commit a1b2289cef92 ("android: binder: drop lru lock in isolate callback") back in 2017 so quite a history of being necessary for binder.

I see mmdrop_async(), I guess that's not needed for anything binder-ish? A quick look in the code suggests this is invoked in free_signal_struct() and is there due to some softirq stuff on x86... so yeah I guess not :)

Quoted 60 lines
---
 rust/kernel/mm.rs | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
rust/kernel/mm.rs +42 -0
index a15acb546f68..f800b6c244cd 100644
@@ -98,6 +98,48 @@ fn deref(&self) -> &Mm {
     }
 }
 
+/// A wrapper for the kernel's `struct mm_struct`.
+///
+/// This type is identical to `MmWithUser` except that it uses `mmput_async` when dropping a
+/// refcount. This means that the destructor of `ARef<MmWithUserAsync>` is safe to call in atomic
+/// context.
+///
+/// # Invariants
+///
+/// Values of this type are always refcounted using `mmget`. The value of `mm_users` is non-zero.
+#[repr(transparent)]
+pub struct MmWithUserAsync {
+    mm: MmWithUser,
+}
+
+// SAFETY: It is safe to call `mmput_async` on another thread than where `mmget` was called.
+unsafe impl Send for MmWithUserAsync {}
+// SAFETY: All methods on `MmWithUserAsync` can be called in parallel from several threads.
+unsafe impl Sync for MmWithUserAsync {}
+
+// SAFETY: By the type invariants, this type is always refcounted.
+unsafe impl AlwaysRefCounted for MmWithUserAsync {
+    fn inc_ref(&self) {
+        // SAFETY: The pointer is valid since self is a reference.
+        unsafe { bindings::mmget(self.as_raw()) };
+    }
+
+    unsafe fn dec_ref(obj: NonNull<Self>) {
+        // SAFETY: The caller is giving up their refcount.
+        unsafe { bindings::mmput_async(obj.cast().as_ptr()) };
+    }
+}
+
+// Make all `MmWithUser` methods available on `MmWithUserAsync`.
+impl Deref for MmWithUserAsync {
+    type Target = MmWithUser;
+
+    #[inline]
+    fn deref(&self) -> &MmWithUser {
+        &self.mm
+    }
+}
+
 // These methods are safe to call even if `mm_users` is zero.
 impl Mm {
     /// Call `mmgrab` on `current.mm`.

rust/kernel/mm.rs pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser { · line 218

Quoted 6 lines
rust/kernel/mm.rs +3 -0
@@ -171,6 +213,13 @@ pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser {
         unsafe { &*ptr.cast() }
     }
 
+    /// Use `mmput_async` when dropping this refcount.
+    #[inline]
+    pub fn use_mmput_async(me: ARef<MmWithUser>) -> ARef<MmWithUserAsync> {

Again, nitty, but I wonder if this should be as_xxx()?

But I guess this makes sense too.

Quoted 11 lines
rust/kernel/mm.rs +4 -1
+        // SAFETY: The layouts and invariants are compatible.
+        unsafe { ARef::from_raw(ARef::into_raw(me).cast()) }
+    }
+
     /// Try to lock the vma read lock under rcu.
     ///
     /// If this operation fails, the vma may still exist. In that case, you should take the mmap
 
--

2.47.0.371.ga323438b13-goog

author maintainer
#23 lore raw

Re: [PATCH v8 5/7] mm: rust: add mmput_async support

Quoted 11 lines · Lorenzo Stoakes
Quoted 8 lines · Alice Ryhl

Adds an MmWithUserAsync type that uses mmput_async when dropped but is otherwise identical to MmWithUser. This has to be done using a separate type because the thing we are changing is the destructor.

Rust Binder needs this to avoid a certain deadlock. See commit 9a9ab0d96362 ("binder: fix race between mmput() and do_exit()") for details. It's also needed in the shrinker to avoid cleaning up the mm in the shrinker's context.

Quoted 7 lines

Oh Lord, I didn't even know this existed... I see it was (re-)added in commit a1b2289cef92 ("android: binder: drop lru lock in isolate callback") back in 2017 so quite a history of being necessary for binder.

I see mmdrop_async(), I guess that's not needed for anything binder-ish? A quick look in the code suggests this is invoked in free_signal_struct() and is there due to some softirq stuff on x86... so yeah I guess not :)

I didn't know it was so binder-specific. I assumed it would be a relatively common use-case.

Quoted 7 lines
Quoted 7 lines

// These methods are safe to call even if mm_users is zero.

 impl Mm {
     /// Call `mmgrab` on `current.mm`.
rust/kernel/mm.rs +0 -0
@@ -171,6 +213,13 @@ pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser {
         unsafe { &*ptr.cast() }
     }
 
Quoted 7 lines

rust/kernel/mm.rs pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser { · line 218

Quoted 3 lines
rust/kernel/mm.rs +3 -0
+    /// Use `mmput_async` when dropping this refcount.
+    #[inline]
+    pub fn use_mmput_async(me: ARef<MmWithUser>) -> ARef<MmWithUserAsync> {

Again, nitty, but I wonder if this should be as_xxx()?

But I guess this makes sense too.

In this case, the as_ prefix is incorrect because this is an owned -> owned conversion. See the API guidelines:
https://rust-lang.github.io/api-guidelines/naming.html#ad-hoc-conversions-follow-as_-to_-into_-conventions-c-conv

If we wish to use a prefix, the correct prefix is into_.

Alice

#24 lore raw

Re: [PATCH v8 5/7] mm: rust: add mmput_async support

Quoted 17 lines · Alice Ryhl
Quoted 15 lines · Lorenzo Stoakes
Quoted 8 lines · Alice Ryhl

Adds an MmWithUserAsync type that uses mmput_async when dropped but is otherwise identical to MmWithUser. This has to be done using a separate type because the thing we are changing is the destructor.

Rust Binder needs this to avoid a certain deadlock. See commit 9a9ab0d96362 ("binder: fix race between mmput() and do_exit()") for details. It's also needed in the shrinker to avoid cleaning up the mm in the shrinker's context.

Oh Lord, I didn't even know this existed... I see it was (re-)added in commit a1b2289cef92 ("android: binder: drop lru lock in isolate callback") back in 2017 so quite a history of being necessary for binder.

Quoted 6 lines
Quoted 3 lines

I see mmdrop_async(), I guess that's not needed for anything binder-ish? A quick look in the code suggests this is invoked in free_signal_struct() and is there due to some softirq stuff on x86... so yeah I guess not :)

I didn't know it was so binder-specific. I assumed it would be a relatively common use-case.

Yeah, seems not so much :>)

Quoted 14 lines
Quoted 14 lines

rust/kernel/mm.rs pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser { · line 218

Quoted 11 lines

// These methods are safe to call even if mm_users is zero.

 impl Mm {
     /// Call `mmgrab` on `current.mm`.
rust/kernel/mm.rs +3 -0
@@ -171,6 +213,13 @@ pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser {
         unsafe { &*ptr.cast() }
     }
 
+    /// Use `mmput_async` when dropping this refcount.
+    #[inline]
+    pub fn use_mmput_async(me: ARef<MmWithUser>) -> ARef<MmWithUserAsync> {

Again, nitty, but I wonder if this should be as_xxx()?

Quoted 7 lines
Quoted 1 line

But I guess this makes sense too.

In this case, the as_ prefix is incorrect because this is an owned -> owned conversion. See the API guidelines:
https://rust-lang.github.io/api-guidelines/naming.html#ad-hoc-conversions-follow-as_-to_-into_-conventions-c-conv

If we wish to use a prefix, the correct prefix is into_.

Ack.

Quoted 2 lines

Alice

#25 lore raw

Re: [PATCH v8 5/7] mm: rust: add mmput_async support

In reply to Lorenzo Stoakes
Quoted 10 lines · Lorenzo Stoakes
Quoted 8 lines · Alice Ryhl

Adds an MmWithUserAsync type that uses mmput_async when dropped but is otherwise identical to MmWithUser. This has to be done using a separate type because the thing we are changing is the destructor.

Rust Binder needs this to avoid a certain deadlock. See commit 9a9ab0d96362 ("binder: fix race between mmput() and do_exit()") for details. It's also needed in the shrinker to avoid cleaning up the mm in the shrinker's context.

Quoted 10 lines

Oh Lord, I didn't even know this existed... I see it was (re-)added in commit a1b2289cef92 ("android: binder: drop lru lock in isolate callback") back in 2017 so quite a history of being necessary for binder.

I see mmdrop_async(), I guess that's not needed for anything binder-ish? A quick look in the code suggests this is invoked in free_signal_struct() and is there due to some softirq stuff on x86... so yeah I guess not :)

Quoted 2 lines

Other than queries, looks good to me from mm side so:

Quoted 80 lines
Quoted 58 lines
---
 rust/kernel/mm.rs | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
rust/kernel/mm.rs +42 -0
index a15acb546f68..f800b6c244cd 100644
@@ -98,6 +98,48 @@ fn deref(&self) -> &Mm {
     }
 }
 
+/// A wrapper for the kernel's `struct mm_struct`.
+///
+/// This type is identical to `MmWithUser` except that it uses `mmput_async` when dropping a
+/// refcount. This means that the destructor of `ARef<MmWithUserAsync>` is safe to call in atomic
+/// context.
+///
+/// # Invariants
+///
+/// Values of this type are always refcounted using `mmget`. The value of `mm_users` is non-zero.
+#[repr(transparent)]
+pub struct MmWithUserAsync {
+    mm: MmWithUser,
+}
+
+// SAFETY: It is safe to call `mmput_async` on another thread than where `mmget` was called.
+unsafe impl Send for MmWithUserAsync {}
+// SAFETY: All methods on `MmWithUserAsync` can be called in parallel from several threads.
+unsafe impl Sync for MmWithUserAsync {}
+
+// SAFETY: By the type invariants, this type is always refcounted.
+unsafe impl AlwaysRefCounted for MmWithUserAsync {
+    fn inc_ref(&self) {
+        // SAFETY: The pointer is valid since self is a reference.
+        unsafe { bindings::mmget(self.as_raw()) };
+    }
+
+    unsafe fn dec_ref(obj: NonNull<Self>) {
+        // SAFETY: The caller is giving up their refcount.
+        unsafe { bindings::mmput_async(obj.cast().as_ptr()) };
+    }
+}
+
+// Make all `MmWithUser` methods available on `MmWithUserAsync`.
+impl Deref for MmWithUserAsync {
+    type Target = MmWithUser;
+
+    #[inline]
+    fn deref(&self) -> &MmWithUser {
+        &self.mm
+    }
+}
+
 // These methods are safe to call even if `mm_users` is zero.
 impl Mm {
     /// Call `mmgrab` on `current.mm`.

rust/kernel/mm.rs pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser { · line 218

Quoted 6 lines
rust/kernel/mm.rs +3 -0
@@ -171,6 +213,13 @@ pub unsafe fn from_raw<'a>(ptr: *const bindings::mm_struct) -> &'a MmWithUser {
         unsafe { &*ptr.cast() }
     }
 
+    /// Use `mmput_async` when dropping this refcount.
+    #[inline]
+    pub fn use_mmput_async(me: ARef<MmWithUser>) -> ARef<MmWithUserAsync> {

Again, nitty, but I wonder if this should be as_xxx()?

But I guess this makes sense too.

Quoted 11 lines
rust/kernel/mm.rs +4 -1
+        // SAFETY: The layouts and invariants are compatible.
+        unsafe { ARef::from_raw(ARef::into_raw(me).cast()) }
+    }
+
     /// Try to lock the vma read lock under rcu.
     ///
     /// If this operation fails, the vma may still exist. In that case, you should take the mmap
 
--

2.47.0.371.ga323438b13-goog

author maintainer
#26 lore raw

PATCH v8 6/7 mm: rust: add VmAreaNew

In reply to Alice Ryhl

When setting up a new vma in an mmap call, you have a bunch of extra permissions that you normally don't have. This introduces a new VmAreaNew type that is used for this case.

To avoid setting invalid flag values, the methods for clearing VM_MAYWRITE and similar involve a check of VM_WRITE, and return an error if VM_WRITE is set. Trying to use try_clear_maywrite without checking the return value results in a compilation error because the Result type is marked #[must_use].

For now, there's only a method for VM_MIXEDMAP and not VM_PFNMAP. When we add a VM_PFNMAP method, we will need some way to prevent you from setting both VM_MIXEDMAP and VM_PFNMAP on the same vma.

---
 rust/kernel/mm/virt.rs | 169 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 168 insertions(+), 1 deletion(-)
rust/kernel/mm/virt.rs +168 -1
index de7f2338810a..22aff8e77854 100644
@@ -6,7 +6,7 @@
 
 use crate::{
     bindings,
-    error::{to_result, Result},
+    error::{code::EINVAL, to_result, Result},
     page::Page,
     types::Opaque,
 };
@@ -148,6 +148,173 @@ pub fn vm_insert_page(&self, address: usize, page: &Page) -> Result {
     }
 }
 
+/// A builder for setting up a vma in an `mmap` call.
+///
+/// # Invariants
+///
+/// For the duration of 'a, the referenced vma must be undergoing initialization.
+pub struct VmAreaNew {
+    vma: VmAreaRef,
+}
+
+// Make all `VmAreaRef` methods available on `VmAreaNew`.
+impl Deref for VmAreaNew {
+    type Target = VmAreaRef;
+
+    #[inline]
+    fn deref(&self) -> &VmAreaRef {
+        &self.vma
+    }
+}
+
+impl VmAreaNew {
+    /// Access a virtual memory area given a raw pointer.
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that `vma` is undergoing initial vma setup for the duration of 'a.
+    #[inline]
+    pub unsafe fn from_raw<'a>(vma: *const bindings::vm_area_struct) -> &'a Self {
+        // SAFETY: The caller ensures that the invariants are satisfied for the duration of 'a.
+        unsafe { &*vma.cast() }
+    }
+
+    /// Internal method for updating the vma flags.
+    ///
+    /// # Safety
+    ///
+    /// This must not be used to set the flags to an invalid value.
+    #[inline]
+    unsafe fn update_flags(&self, set: vm_flags_t, unset: vm_flags_t) {
+        let mut flags = self.flags();
+        flags |= set;
+        flags &= !unset;
+
+        // SAFETY: This is not a data race: the vma is undergoing initial setup, so it's not yet
+        // shared. Additionally, `VmAreaNew` is `!Sync`, so it cannot be used to write in parallel.
+        // The caller promises that this does not set the flags to an invalid value.
+        unsafe { (*self.as_ptr()).__bindgen_anon_2.vm_flags = flags };
+    }
+
+    /// Set the `VM_MIXEDMAP` flag on this vma.
+    ///
+    /// This enables the vma to contain both `struct page` and pure PFN pages. Returns a reference
+    /// that can be used to call `vm_insert_page` on the vma.
+    #[inline]
+    pub fn set_mixedmap(&self) -> &VmAreaMixedMap {
+        // SAFETY: We don't yet provide a way to set VM_PFNMAP, so this cannot put the flags in an
+        // invalid state.
+        unsafe { self.update_flags(flags::MIXEDMAP, 0) };
+
+        // SAFETY: We just set `VM_MIXEDMAP` on the vma.
+        unsafe { VmAreaMixedMap::from_raw(self.vma.as_ptr()) }
+    }
+
+    /// Set the `VM_IO` flag on this vma.
+    ///
+    /// This marks the vma as being a memory-mapped I/O region.
+    #[inline]
+    pub fn set_io(&self) {
+        // SAFETY: Setting the VM_IO flag is always okay.
+        unsafe { self.update_flags(flags::IO, 0) };
+    }
+
+    /// Set the `VM_DONTEXPAND` flag on this vma.
+    ///
+    /// This prevents the vma from being expanded with `mremap()`.
+    #[inline]
+    pub fn set_dontexpand(&self) {
+        // SAFETY: Setting the VM_DONTEXPAND flag is always okay.
+        unsafe { self.update_flags(flags::DONTEXPAND, 0) };
+    }
+
+    /// Set the `VM_DONTCOPY` flag on this vma.
+    ///
+    /// This prevents the vma from being copied on fork. This option is only permanent if `VM_IO`
+    /// is set.
+    #[inline]
+    pub fn set_dontcopy(&self) {
+        // SAFETY: Setting the VM_DONTCOPY flag is always okay.
+        unsafe { self.update_flags(flags::DONTCOPY, 0) };
+    }
+
+    /// Set the `VM_DONTDUMP` flag on this vma.
+    ///
+    /// This prevents the vma from being included in core dumps. This option is only permanent if
+    /// `VM_IO` is set.
+    #[inline]
+    pub fn set_dontdump(&self) {
+        // SAFETY: Setting the VM_DONTDUMP flag is always okay.
+        unsafe { self.update_flags(flags::DONTDUMP, 0) };
+    }
+
+    /// Returns whether `VM_READ` is set.
+    ///
+    /// This flag indicates whether userspace is mapping this vma as readable.
+    #[inline]
+    pub fn get_read(&self) -> bool {
+        (self.flags() & flags::READ) != 0
+    }
+
+    /// Try to clear the `VM_MAYREAD` flag, failing if `VM_READ` is set.
+    ///
+    /// This flag indicates whether userspace is allowed to make this vma readable with
+    /// `mprotect()`.
+    #[inline]
+    pub fn try_clear_mayread(&self) -> Result {
+        if self.get_read() {
+            return Err(EINVAL);
+        }
+        // SAFETY: Clearing `VM_MAYREAD` is okay when `VM_READ` is not set.
+        unsafe { self.update_flags(0, flags::MAYREAD) };
+        Ok(())
+    }
+
+    /// Returns whether `VM_WRITE` is set.
+    ///
+    /// This flag indicates whether userspace is mapping this vma as writable.
+    #[inline]
+    pub fn get_write(&self) -> bool {
+        (self.flags() & flags::WRITE) != 0
+    }
+
+    /// Try to clear the `VM_MAYWRITE` flag, failing if `VM_WRITE` is set.
+    ///
+    /// This flag indicates whether userspace is allowed to make this vma writable with
+    /// `mprotect()`.
+    #[inline]
+    pub fn try_clear_maywrite(&self) -> Result {
+        if self.get_write() {
+            return Err(EINVAL);
+        }
+        // SAFETY: Clearing `VM_MAYWRITE` is okay when `VM_WRITE` is not set.
+        unsafe { self.update_flags(0, flags::MAYWRITE) };
+        Ok(())
+    }
+
+    /// Returns whether `VM_EXEC` is set.
+    ///
+    /// This flag indicates whether userspace is mapping this vma as executable.
+    #[inline]
+    pub fn get_exec(&self) -> bool {
+        (self.flags() & flags::EXEC) != 0
+    }
+
+    /// Try to clear the `VM_MAYEXEC` flag, failing if `VM_EXEC` is set.
+    ///
+    /// This flag indicates whether userspace is allowed to make this vma executable with
+    /// `mprotect()`.
+    #[inline]
+    pub fn try_clear_mayexec(&self) -> Result {
+        if self.get_exec() {
+            return Err(EINVAL);
+        }
+        // SAFETY: Clearing `VM_MAYEXEC` is okay when `VM_EXEC` is not set.
+        unsafe { self.update_flags(0, flags::MAYEXEC) };
+        Ok(())
+    }
+}
+
 /// The integer type used for vma flags.
 #[doc(inline)]
 pub use bindings::vm_flags_t;
Signature · 1 line
2.47.0.371.ga323438b13-goog
#27 lore raw

Re: [PATCH v8 6/7] mm: rust: add VmAreaNew

Quoted 3 lines · Alice Ryhl

When setting up a new vma in an mmap call, you have a bunch of extra permissions that you normally don't have. This introduces a new VmAreaNew type that is used for this case.

Hm I'm confused by what you mean here. What permissions do you mean?

Is this to abstract a VMA as passed by f_op->mmap()? I think it would be better to explicitly say this if so.

Quoted 6 lines

To avoid setting invalid flag values, the methods for clearing VM_MAYWRITE and similar involve a check of VM_WRITE, and return an error if VM_WRITE is set. Trying to use try_clear_maywrite without checking the return value results in a compilation error because the Result type is marked #[must_use].

This is nice.

Though note that, it is explicitly not permitted to permit writability for a VMA that previously had it disallowed, and we explicitly WARN_ON() this now. Concretely that means a VMA where !(vma->vm_flags & VM_MAYWRITE), you must not vma->vm_flags |= VM_MAYWRITE.

Quoted 4 lines

For now, there's only a method for VM_MIXEDMAP and not VM_PFNMAP. When we add a VM_PFNMAP method, we will need some way to prevent you from setting both VM_MIXEDMAP and VM_PFNMAP on the same vma.

Yes this would be unwise.

An aside here - really you should _only_ change flags in this hook (perhaps of course also initialising vma->vm_private_data state), trying to change anything _core_ here would be deeply dangerous.

We are far too permissive with this right now, and it's something we want to try ideally to limit in the future.

Quoted 20 lines
---
 rust/kernel/mm/virt.rs | 169 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 168 insertions(+), 1 deletion(-)
rust/kernel/mm/virt.rs +1 -1
index de7f2338810a..22aff8e77854 100644
@@ -6,7 +6,7 @@
 
 use crate::{
     bindings,
-    error::{to_result, Result},
+    error::{code::EINVAL, to_result, Result},
     page::Page,
     types::Opaque,
 };

rust/kernel/mm/virt.rs pub fn vm_insert_page(&self, address: usize, page: &Page) -> Result { · line 151

Quoted 4 lines
rust/kernel/mm/virt.rs +1 -0
@@ -148,6 +148,173 @@ pub fn vm_insert_page(&self, address: usize, page: &Page) -> Result {
     }
 }
 
+/// A builder for setting up a vma in an `mmap` call.

Would be better to explicitly reference the struct file_operations->mmap() hook and to say that we should only be updating flags and vm_private_data here (though perhaps not worth mentioning _that_ if not explicitly exposed by your interface).

I'm guessing fields are, unless a setter/builder is established, immutable?

Quoted 35 lines
rust/kernel/mm/virt.rs +35 -0
+///
+/// # Invariants
+///
+/// For the duration of 'a, the referenced vma must be undergoing initialization.
+pub struct VmAreaNew {
+    vma: VmAreaRef,
+}
+
+// Make all `VmAreaRef` methods available on `VmAreaNew`.
+impl Deref for VmAreaNew {
+    type Target = VmAreaRef;
+
+    #[inline]
+    fn deref(&self) -> &VmAreaRef {
+        &self.vma
+    }
+}
+
+impl VmAreaNew {
+    /// Access a virtual memory area given a raw pointer.
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that `vma` is undergoing initial vma setup for the duration of 'a.
+    #[inline]
+    pub unsafe fn from_raw<'a>(vma: *const bindings::vm_area_struct) -> &'a Self {
+        // SAFETY: The caller ensures that the invariants are satisfied for the duration of 'a.
+        unsafe { &*vma.cast() }
+    }
+
+    /// Internal method for updating the vma flags.
+    ///
+    /// # Safety
+    ///
+    /// This must not be used to set the flags to an invalid value.

rust/kernel/mm/virt.rs pub fn vm_insert_page(&self, address: usize, page: &Page) -> Result { · line 196

Quoted 10 lines
rust/kernel/mm/virt.rs +10 -0
+    #[inline]
+    unsafe fn update_flags(&self, set: vm_flags_t, unset: vm_flags_t) {
+        let mut flags = self.flags();
+        flags |= set;
+        flags &= !unset;
+
+        // SAFETY: This is not a data race: the vma is undergoing initial setup, so it's not yet
+        // shared. Additionally, `VmAreaNew` is `!Sync`, so it cannot be used to write in parallel.
+        // The caller promises that this does not set the flags to an invalid value.
+        unsafe { (*self.as_ptr()).__bindgen_anon_2.vm_flags = flags };

Hm not sure if this is correct. We explicitly maintain a union in struct vm_area_struct as:

	union {
		const vm_flags_t vm_flags;
		vm_flags_t __private __vm_flags;
	};

Where vma->vm_flags is const, and then use helpers like vm_flags_init() to set them, which also do things like assert locks (though not in the init case, of course).

So erally we should at least be updating __vm_flags here, though I'm not sure how bindgen treats it?

Quoted 61 lines
rust/kernel/mm/virt.rs +61 -0
+    }
+
+    /// Set the `VM_MIXEDMAP` flag on this vma.
+    ///
+    /// This enables the vma to contain both `struct page` and pure PFN pages. Returns a reference
+    /// that can be used to call `vm_insert_page` on the vma.
+    #[inline]
+    pub fn set_mixedmap(&self) -> &VmAreaMixedMap {
+        // SAFETY: We don't yet provide a way to set VM_PFNMAP, so this cannot put the flags in an
+        // invalid state.
+        unsafe { self.update_flags(flags::MIXEDMAP, 0) };
+
+        // SAFETY: We just set `VM_MIXEDMAP` on the vma.
+        unsafe { VmAreaMixedMap::from_raw(self.vma.as_ptr()) }
+    }
+
+    /// Set the `VM_IO` flag on this vma.
+    ///
+    /// This marks the vma as being a memory-mapped I/O region.
+    #[inline]
+    pub fn set_io(&self) {
+        // SAFETY: Setting the VM_IO flag is always okay.
+        unsafe { self.update_flags(flags::IO, 0) };
+    }
+
+    /// Set the `VM_DONTEXPAND` flag on this vma.
+    ///
+    /// This prevents the vma from being expanded with `mremap()`.
+    #[inline]
+    pub fn set_dontexpand(&self) {
+        // SAFETY: Setting the VM_DONTEXPAND flag is always okay.
+        unsafe { self.update_flags(flags::DONTEXPAND, 0) };
+    }
+
+    /// Set the `VM_DONTCOPY` flag on this vma.
+    ///
+    /// This prevents the vma from being copied on fork. This option is only permanent if `VM_IO`
+    /// is set.
+    #[inline]
+    pub fn set_dontcopy(&self) {
+        // SAFETY: Setting the VM_DONTCOPY flag is always okay.
+        unsafe { self.update_flags(flags::DONTCOPY, 0) };
+    }
+
+    /// Set the `VM_DONTDUMP` flag on this vma.
+    ///
+    /// This prevents the vma from being included in core dumps. This option is only permanent if
+    /// `VM_IO` is set.
+    #[inline]
+    pub fn set_dontdump(&self) {
+        // SAFETY: Setting the VM_DONTDUMP flag is always okay.
+        unsafe { self.update_flags(flags::DONTDUMP, 0) };
+    }
+
+    /// Returns whether `VM_READ` is set.
+    ///
+    /// This flag indicates whether userspace is mapping this vma as readable.
+    #[inline]
+    pub fn get_read(&self) -> bool {
+        (self.flags() & flags::READ) != 0
+    }

rust/kernel/mm/virt.rs pub fn vm_insert_page(&self, address: usize, page: &Page) -> Result { · line 267

Quoted 10 lines
rust/kernel/mm/virt.rs +10 -0
+
+    /// Try to clear the `VM_MAYREAD` flag, failing if `VM_READ` is set.
+    ///
+    /// This flag indicates whether userspace is allowed to make this vma readable with
+    /// `mprotect()`.
+    #[inline]
+    pub fn try_clear_mayread(&self) -> Result {
+        if self.get_read() {
+            return Err(EINVAL);
+        }

This is quite nice! Strong(er) typing for the win, again :>)

Quoted 57 lines
rust/kernel/mm/virt.rs +50 -1
+        // SAFETY: Clearing `VM_MAYREAD` is okay when `VM_READ` is not set.
+        unsafe { self.update_flags(0, flags::MAYREAD) };
+        Ok(())
+    }
+
+    /// Returns whether `VM_WRITE` is set.
+    ///
+    /// This flag indicates whether userspace is mapping this vma as writable.
+    #[inline]
+    pub fn get_write(&self) -> bool {
+        (self.flags() & flags::WRITE) != 0
+    }
+
+    /// Try to clear the `VM_MAYWRITE` flag, failing if `VM_WRITE` is set.
+    ///
+    /// This flag indicates whether userspace is allowed to make this vma writable with
+    /// `mprotect()`.
+    #[inline]
+    pub fn try_clear_maywrite(&self) -> Result {
+        if self.get_write() {
+            return Err(EINVAL);
+        }
+        // SAFETY: Clearing `VM_MAYWRITE` is okay when `VM_WRITE` is not set.
+        unsafe { self.update_flags(0, flags::MAYWRITE) };
+        Ok(())
+    }
+
+    /// Returns whether `VM_EXEC` is set.
+    ///
+    /// This flag indicates whether userspace is mapping this vma as executable.
+    #[inline]
+    pub fn get_exec(&self) -> bool {
+        (self.flags() & flags::EXEC) != 0
+    }
+
+    /// Try to clear the `VM_MAYEXEC` flag, failing if `VM_EXEC` is set.
+    ///
+    /// This flag indicates whether userspace is allowed to make this vma executable with
+    /// `mprotect()`.
+    #[inline]
+    pub fn try_clear_mayexec(&self) -> Result {
+        if self.get_exec() {
+            return Err(EINVAL);
+        }
+        // SAFETY: Clearing `VM_MAYEXEC` is okay when `VM_EXEC` is not set.
+        unsafe { self.update_flags(0, flags::MAYEXEC) };
+        Ok(())
+    }
+}
+
 /// The integer type used for vma flags.
 #[doc(inline)]
 pub use bindings::vm_flags_t;
 
--

2.47.0.371.ga323438b13-goog

author maintainer
#28 lore raw

Re: [PATCH v8 6/7] mm: rust: add VmAreaNew

Quoted 7 lines · Lorenzo Stoakes
Quoted 3 lines · Alice Ryhl

When setting up a new vma in an mmap call, you have a bunch of extra permissions that you normally don't have. This introduces a new VmAreaNew type that is used for this case.

Hm I'm confused by what you mean here. What permissions do you mean?

I just mean that there are additional things you can do, e.g. you can set VM_MIXEDMAP.

Quoted 2 lines

Is this to abstract a VMA as passed by f_op->mmap()? I think it would be better to explicitly say this if so.

Yeah, the VmAreaNew type is specifically for f_op->mmap(). I'll be more explicit about that.

Quoted 6 lines
Quoted 5 lines

To avoid setting invalid flag values, the methods for clearing VM_MAYWRITE and similar involve a check of VM_WRITE, and return an error if VM_WRITE is set. Trying to use try_clear_maywrite without checking the return value results in a compilation error because the Result type is marked #[must_use].

Quoted 6 lines

This is nice.

Though note that, it is explicitly not permitted to permit writability for a VMA that previously had it disallowed, and we explicitly WARN_ON() this now. Concretely that means a VMA where !(vma->vm_flags & VM_MAYWRITE), you must not vma->vm_flags |= VM_MAYWRITE.

Got it. The API here doesn't allow that, but good to know we can't add it in the future.

Quoted 4 lines
Quoted 3 lines

For now, there's only a method for VM_MIXEDMAP and not VM_PFNMAP. When we add a VM_PFNMAP method, we will need some way to prevent you from setting both VM_MIXEDMAP and VM_PFNMAP on the same vma.

Quoted 8 lines

Yes this would be unwise.

An aside here - really you should _only_ change flags in this hook (perhaps of course also initialising vma->vm_private_data state), trying to change anything _core_ here would be deeply dangerous.

We are far too permissive with this right now, and it's something we want to try ideally to limit in the future.

The previous version just had a function called "set_flags" that could be used to set any flags you want. Given Jann's feedback, I had restricted it to only allow certain flag changes.

Quoted 22 lines
Quoted 22 lines
---
 rust/kernel/mm/virt.rs | 169 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 168 insertions(+), 1 deletion(-)
rust/kernel/mm/virt.rs +1 -1
index de7f2338810a..22aff8e77854 100644
@@ -6,7 +6,7 @@
 
 use crate::{
     bindings,
-    error::{to_result, Result},
+    error::{code::EINVAL, to_result, Result},
     page::Page,
     types::Opaque,
 };
@@ -148,6 +148,173 @@ pub fn vm_insert_page(&self, address: usize, page: &Page) -> Result {
     }
 }
 
Quoted 6 lines

rust/kernel/mm/virt.rs pub fn vm_insert_page(&self, address: usize, page: &Page) -> Result { · line 151

Quoted 1 line
rust/kernel/mm/virt.rs +1 -0
+/// A builder for setting up a vma in an `mmap` call.

Would be better to explicitly reference the struct file_operations->mmap() hook and to say that we should only be updating flags and vm_private_data here (though perhaps not worth mentioning _that_ if not explicitly exposed by your interface).

I guess also vm_ops?

Quoted 1 line

I'm guessing fields are, unless a setter/builder is established, immutable?

If you have a mutable reference, you can always modify fields. When you don't want that, fields are made private.

Quoted 23 lines
Quoted 5 lines
rust/kernel/mm/virt.rs +5 -0
+    /// Internal method for updating the vma flags.
+    ///
+    /// # Safety
+    ///
+    /// This must not be used to set the flags to an invalid value.

rust/kernel/mm/virt.rs pub fn vm_insert_page(&self, address: usize, page: &Page) -> Result { · line 196

Quoted 10 lines
rust/kernel/mm/virt.rs +10 -0
+    #[inline]
+    unsafe fn update_flags(&self, set: vm_flags_t, unset: vm_flags_t) {
+        let mut flags = self.flags();
+        flags |= set;
+        flags &= !unset;
+
+        // SAFETY: This is not a data race: the vma is undergoing initial setup, so it's not yet
+        // shared. Additionally, `VmAreaNew` is `!Sync`, so it cannot be used to write in parallel.
+        // The caller promises that this does not set the flags to an invalid value.
+        unsafe { (*self.as_ptr()).__bindgen_anon_2.vm_flags = flags };

Hm not sure if this is correct. We explicitly maintain a union in struct vm_area_struct as:

        union {
                const vm_flags_t vm_flags;
                vm_flags_t __private __vm_flags;
        };
Quoted 6 lines

Where vma->vm_flags is const, and then use helpers like vm_flags_init() to set them, which also do things like assert locks (though not in the init case, of course).

So erally we should at least be updating __vm_flags here, though I'm not sure how bindgen treats it?

I don't think using vm_flags vs __vm_flags changes anything on the Rust side. The modifications are happening unsafely through a raw pointer to something inside Opaque, so Rust isn't going to care about stuff like your const annotation; it's unsafe either way.

I'll update this to use __vm_flags instead.

Quoted 11 lines

rust/kernel/mm/virt.rs pub fn vm_insert_page(&self, address: usize, page: &Page) -> Result { · line 267

Quoted 9 lines
rust/kernel/mm/virt.rs +9 -0
+    /// Try to clear the `VM_MAYREAD` flag, failing if `VM_READ` is set.
+    ///
+    /// This flag indicates whether userspace is allowed to make this vma readable with
+    /// `mprotect()`.
+    #[inline]
+    pub fn try_clear_mayread(&self) -> Result {
+        if self.get_read() {
+            return Err(EINVAL);
+        }

This is quite nice! Strong(er) typing for the win, again :>)

:)

Alice

#29 lore raw

Re: [PATCH v8 6/7] mm: rust: add VmAreaNew

Quoted 10 lines · Alice Ryhl
Quoted 7 lines · Lorenzo Stoakes
Quoted 3 lines · Alice Ryhl

When setting up a new vma in an mmap call, you have a bunch of extra permissions that you normally don't have. This introduces a new VmAreaNew type that is used for this case.

Hm I'm confused by what you mean here. What permissions do you mean?

Quoted 8 lines

I just mean that there are additional things you can do, e.g. you can set VM_MIXEDMAP.

Quoted 2 lines

Is this to abstract a VMA as passed by f_op->mmap()? I think it would be better to explicitly say this if so.

Yeah, the VmAreaNew type is specifically for f_op->mmap(). I'll be more explicit about that.

Yeah this is really critical on this one for me.

Quoted 27 lines
Quoted 7 lines
Quoted 6 lines

To avoid setting invalid flag values, the methods for clearing VM_MAYWRITE and similar involve a check of VM_WRITE, and return an error if VM_WRITE is set. Trying to use try_clear_maywrite without checking the return value results in a compilation error because the Result type is marked #[must_use].

Quoted 6 lines

This is nice.

Though note that, it is explicitly not permitted to permit writability for a VMA that previously had it disallowed, and we explicitly WARN_ON() this now. Concretely that means a VMA where !(vma->vm_flags & VM_MAYWRITE), you must not vma->vm_flags |= VM_MAYWRITE.

Got it. The API here doesn't allow that, but good to know we can't add it in the future.

Quoted 10 lines
Quoted 3 lines

For now, there's only a method for VM_MIXEDMAP and not VM_PFNMAP. When we add a VM_PFNMAP method, we will need some way to prevent you from setting both VM_MIXEDMAP and VM_PFNMAP on the same vma.

Yes this would be unwise.

An aside here - really you should _only_ change flags in this hook (perhaps of course also initialising vma->vm_private_data state), trying to change anything _core_ here would be deeply dangerous.

Quoted 6 lines
Quoted 2 lines

We are far too permissive with this right now, and it's something we want to try ideally to limit in the future.

The previous version just had a function called "set_flags" that could be used to set any flags you want. Given Jann's feedback, I had restricted it to only allow certain flag changes.

Yes this is a good idea.

Quoted 2 lines
Quoted 2 lines
Quoted 2 lines

This stuff is sensitive (again, we really need to do something about this in the VMA code, TBD) so will want to see the v9 respin before ack.

Quoted 65 lines
Quoted 21 lines
Quoted 21 lines
---
 rust/kernel/mm/virt.rs | 169 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 168 insertions(+), 1 deletion(-)
rust/kernel/mm/virt.rs +1 -1
index de7f2338810a..22aff8e77854 100644
@@ -6,7 +6,7 @@
 
 use crate::{
     bindings,
-    error::{to_result, Result},
+    error::{code::EINVAL, to_result, Result},
     page::Page,
     types::Opaque,
 };
@@ -148,6 +148,173 @@ pub fn vm_insert_page(&self, address: usize, page: &Page) -> Result {
     }
 }
 
Quoted 6 lines

rust/kernel/mm/virt.rs pub fn vm_insert_page(&self, address: usize, page: &Page) -> Result { · line 151

Quoted 1 line
rust/kernel/mm/virt.rs +1 -0
+/// A builder for setting up a vma in an `mmap` call.

Would be better to explicitly reference the struct file_operations->mmap() hook and to say that we should only be updating flags and vm_private_data here (though perhaps not worth mentioning _that_ if not explicitly exposed by your interface).

I guess also vm_ops?

Quoted 1 line

I'm guessing fields are, unless a setter/builder is established, immutable?

If you have a mutable reference, you can always modify fields. When you don't want that, fields are made private.

Quoted 23 lines
Quoted 5 lines
rust/kernel/mm/virt.rs +5 -0
+    /// Internal method for updating the vma flags.
+    ///
+    /// # Safety
+    ///
+    /// This must not be used to set the flags to an invalid value.

rust/kernel/mm/virt.rs pub fn vm_insert_page(&self, address: usize, page: &Page) -> Result { · line 196

Quoted 10 lines
rust/kernel/mm/virt.rs +10 -0
+    #[inline]
+    unsafe fn update_flags(&self, set: vm_flags_t, unset: vm_flags_t) {
+        let mut flags = self.flags();
+        flags |= set;
+        flags &= !unset;
+
+        // SAFETY: This is not a data race: the vma is undergoing initial setup, so it's not yet
+        // shared. Additionally, `VmAreaNew` is `!Sync`, so it cannot be used to write in parallel.
+        // The caller promises that this does not set the flags to an invalid value.
+        unsafe { (*self.as_ptr()).__bindgen_anon_2.vm_flags = flags };

Hm not sure if this is correct. We explicitly maintain a union in struct vm_area_struct as:

        union {
                const vm_flags_t vm_flags;
                vm_flags_t __private __vm_flags;
        };
Quoted 6 lines

Where vma->vm_flags is const, and then use helpers like vm_flags_init() to set them, which also do things like assert locks (though not in the init case, of course).

So erally we should at least be updating __vm_flags here, though I'm not sure how bindgen treats it?

Quoted 6 lines

I don't think using vm_flags vs __vm_flags changes anything on the Rust side. The modifications are happening unsafely through a raw pointer to something inside Opaque, so Rust isn't going to care about stuff like your const annotation; it's unsafe either way.

I'll update this to use __vm_flags instead.

Yeah, I mean _in practice_ byte-for-byte it will make no difference but it'd be nice just for the purposes of maintaining a similar abstraction.

It might be worth wrapping in something that explicitly references that this is on init only but I guess _the whole type_ does this.

Quoted 16 lines
Quoted 11 lines

rust/kernel/mm/virt.rs pub fn vm_insert_page(&self, address: usize, page: &Page) -> Result { · line 267

Quoted 10 lines
rust/kernel/mm/virt.rs +9 -0
+    /// Try to clear the `VM_MAYREAD` flag, failing if `VM_READ` is set.
+    ///
+    /// This flag indicates whether userspace is allowed to make this vma readable with
+    /// `mprotect()`.
+    #[inline]
+    pub fn try_clear_mayread(&self) -> Result {
+        if self.get_read() {
+            return Err(EINVAL);
+        }
Quoted 1 line

This is quite nice! Strong(er) typing for the win, again :>)

:)

Alice

author maintainer
#30 lore raw

PATCH v8 7/7 rust: miscdevice: add mmap support

In reply to Alice Ryhl

Using the vma support introduced by the previous commit, introduce mmap support for miscdevices. The mmap call is given a vma that is undergoing initial setup, so the VmAreaNew type is used.

---
 rust/kernel/miscdevice.rs | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)
rust/kernel/miscdevice.rs +28 -0
index 7e2a79b3ae26..4e4b9476e092 100644
@@ -11,6 +11,7 @@
 use crate::{
     bindings,
     error::{to_result, Error, Result, VTABLE_DEFAULT_ERROR},
+    mm::virt::VmAreaNew,
     prelude::*,
     str::CStr,
     types::{ForeignOwnable, Opaque},
@@ -110,6 +111,11 @@ fn release(device: Self::Ptr) {
         drop(device);
     }
 
+    /// Handle for mmap.
+    fn mmap(_device: <Self::Ptr as ForeignOwnable>::Borrowed<'_>, _vma: &VmAreaNew) -> Result {
+        kernel::build_error(VTABLE_DEFAULT_ERROR)
+    }
+
     /// Handler for ioctls.
     ///
     /// The `cmd` argument is usually manipulated using the utilties in [`kernel::ioctl`].
@@ -156,6 +162,7 @@ impl<T: MiscDevice> VtableHelper<T> {
         const VTABLE: bindings::file_operations = bindings::file_operations {
             open: Some(fops_open::<T>),
             release: Some(fops_release::<T>),
+            mmap: maybe_fn(T::HAS_MMAP, fops_mmap::<T>),
             unlocked_ioctl: maybe_fn(T::HAS_IOCTL, fops_ioctl::<T>),
             #[cfg(CONFIG_COMPAT)]
             compat_ioctl: if T::HAS_COMPAT_IOCTL {
@@ -216,6 +223,27 @@ impl<T: MiscDevice> VtableHelper<T> {
     0
 }
 
+/// # Safety
+///
+/// `file` must be a valid file that is associated with a `MiscDeviceRegistration<T>`.
+/// `vma` must be a vma that is currently being mmap'ed with this file.
+unsafe extern "C" fn fops_mmap<T: MiscDevice>(
+    file: *mut bindings::file,
+    vma: *mut bindings::vm_area_struct,
+) -> c_int {
+    // SAFETY: The mmap call of a file can access the private data.
+    let private = unsafe { (*file).private_data };
+    // SAFETY: Mmap calls can borrow the private data of the file.
+    let device = unsafe { <T::Ptr as ForeignOwnable>::borrow(private) };
+    // SAFETY: The caller provides a vma that is undergoing initial VMA setup.
+    let area = unsafe { VmAreaNew::from_raw(vma) };
+
+    match T::mmap(device, area) {
+        Ok(()) => 0,
+        Err(err) => err.to_errno() as c_int,
+    }
+}
+
 /// # Safety
 ///
 /// `file` must be a valid file that is associated with a `MiscDeviceRegistration<T>`.
Signature · 1 line
2.47.0.371.ga323438b13-goog
#31 lore raw

Re: [PATCH v8 7/7] rust: miscdevice: add mmap support

Quoted 3 lines · Alice Ryhl

Using the vma support introduced by the previous commit, introduce mmap support for miscdevices. The mmap call is given a vma that is undergoing initial setup, so the VmAreaNew type is used.

Again, I'd be explicit about the VMA being passed to a struct file_operations->mmap() hook on mmap. Otherwise this seems super vague to me!

Quoted 19 lines
---
 rust/kernel/miscdevice.rs | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)
rust/kernel/miscdevice.rs +1 -0
index 7e2a79b3ae26..4e4b9476e092 100644
@@ -11,6 +11,7 @@
 use crate::{
     bindings,
     error::{to_result, Error, Result, VTABLE_DEFAULT_ERROR},
+    mm::virt::VmAreaNew,
     prelude::*,
     str::CStr,
     types::{ForeignOwnable, Opaque},

rust/kernel/miscdevice.rs fn release(device: Self::Ptr) { · line 115

Quoted 5 lines
rust/kernel/miscdevice.rs +2 -0
@@ -110,6 +111,11 @@ fn release(device: Self::Ptr) {
         drop(device);
     }
 
+    /// Handle for mmap.
+    fn mmap(_device: <Self::Ptr as ForeignOwnable>::Borrowed<'_>, _vma: &VmAreaNew) -> Result {

You will have to help me with this :) ForeignOwnable, Borrowed<'_>, _vma I'm a bit lost here!

rust/kernel/miscdevice.rs fn release(device: Self::Ptr) { · line 116

Quoted 1 line
rust/kernel/miscdevice.rs +1 -0
+        kernel::build_error(VTABLE_DEFAULT_ERROR)

What is this? Is this not yet implemented or something, and this is a placeholder or something?

Quoted 46 lines
rust/kernel/miscdevice.rs +2 -0
+    }
 
+
     /// Handler for ioctls.
     ///
     /// The `cmd` argument is usually manipulated using the utilties in [`kernel::ioctl`].
rust/kernel/miscdevice.rs +22 -1
@@ -156,6 +162,7 @@ impl<T: MiscDevice> VtableHelper<T> {
         const VTABLE: bindings::file_operations = bindings::file_operations {
             open: Some(fops_open::<T>),
             release: Some(fops_release::<T>),
+            mmap: maybe_fn(T::HAS_MMAP, fops_mmap::<T>),
             unlocked_ioctl: maybe_fn(T::HAS_IOCTL, fops_ioctl::<T>),
             #[cfg(CONFIG_COMPAT)]
             compat_ioctl: if T::HAS_COMPAT_IOCTL {
@@ -216,6 +223,27 @@ impl<T: MiscDevice> VtableHelper<T> {
     0
 }
 
+/// # Safety
+///
+/// `file` must be a valid file that is associated with a `MiscDeviceRegistration<T>`.
+/// `vma` must be a vma that is currently being mmap'ed with this file.
+unsafe extern "C" fn fops_mmap<T: MiscDevice>(
+    file: *mut bindings::file,
+    vma: *mut bindings::vm_area_struct,
+) -> c_int {
+    // SAFETY: The mmap call of a file can access the private data.
+    let private = unsafe { (*file).private_data };
+    // SAFETY: Mmap calls can borrow the private data of the file.
+    let device = unsafe { <T::Ptr as ForeignOwnable>::borrow(private) };
+    // SAFETY: The caller provides a vma that is undergoing initial VMA setup.
+    let area = unsafe { VmAreaNew::from_raw(vma) };
+
+    match T::mmap(device, area) {
+        Ok(()) => 0,
+        Err(err) => err.to_errno() as c_int,
+    }
+}
+
 /// # Safety
 ///
 /// `file` must be a valid file that is associated with a `MiscDeviceRegistration<T>`.
 
--

2.47.0.371.ga323438b13-goog

author maintainer
#32 lore raw

Re: [PATCH v8 7/7] rust: miscdevice: add mmap support

Quoted 9 lines · Lorenzo Stoakes
Quoted 3 lines · Alice Ryhl

Using the vma support introduced by the previous commit, introduce mmap support for miscdevices. The mmap call is given a vma that is undergoing initial setup, so the VmAreaNew type is used.

Again, I'd be explicit about the VMA being passed to a struct file_operations->mmap() hook on mmap. Otherwise this seems super vague to me!

I wasn't sure if vmas could be constructed in any context other than mmap. Will reword.

Quoted 21 lines
Quoted 21 lines
---
 rust/kernel/miscdevice.rs | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)
rust/kernel/miscdevice.rs +1 -0
index 7e2a79b3ae26..4e4b9476e092 100644
@@ -11,6 +11,7 @@
 use crate::{
     bindings,
     error::{to_result, Error, Result, VTABLE_DEFAULT_ERROR},
+    mm::virt::VmAreaNew,
     prelude::*,
     str::CStr,
     types::{ForeignOwnable, Opaque},
@@ -110,6 +111,11 @@ fn release(device: Self::Ptr) {
         drop(device);
     }
 
Quoted 5 lines

rust/kernel/miscdevice.rs fn release(device: Self::Ptr) { · line 115

Quoted 2 lines
rust/kernel/miscdevice.rs +2 -0
+    /// Handle for mmap.
+    fn mmap(_device: <Self::Ptr as ForeignOwnable>::Borrowed<'_>, _vma: &VmAreaNew) -> Result {

You will have to help me with this :) ForeignOwnable, Borrowed<'_>, _vma I'm a bit lost here!

When you implement the Miscdevice for your own type, you write a block like this one:

impl Miscdevice for MyType {
    type Ptr = Arc<MyType>;
    ...
}

Here Arc is a pointer type (very similar to ARef) that represents ownership over a refcount to a refcounted value.

In this case:
* Self refers to MyType.
* Self::Ptr refers to Arc<MyType>
* <Self::Ptr as ForeignOwnable>::Borrowed<'_> refers to ArcBorrow<MyType>

The last step is resolved to ArcBorrow<MyType> because of this impl block in rust/kernel/sync/arc.rs:

impl<T: 'static> ForeignOwnable for Arc<T> {
    type Borrowed<'a> = ArcBorrow<'a, T>;
    ...
}

Note that Self::Ptr is short-hand for <Self as Miscdevice>::Ptr.

Quoted 4 lines

rust/kernel/miscdevice.rs fn release(device: Self::Ptr) { · line 116

Quoted 1 line
rust/kernel/miscdevice.rs +1 -0
+        kernel::build_error(VTABLE_DEFAULT_ERROR)

What is this? Is this not yet implemented or something, and this is a placeholder or something?

It's a build-time assertion that this function is dead-code eliminated.

There are two cases:
* Either the driver does not override mmap. In this case, we store a null pointer in the fops table.
* Or the driver overrides mmap with their own implementation. In this case, we store a function pointer to whichever implementation they provided.
In neither case is the above function present anywhere in the final executable.

Alice

#33 lore raw

Re: [PATCH v8 7/7] rust: miscdevice: add mmap support

Quoted 8 lines · Alice Ryhl
Quoted 6 lines · Lorenzo Stoakes
Quoted 3 lines · Alice Ryhl

Using the vma support introduced by the previous commit, introduce mmap support for miscdevices. The mmap call is given a vma that is undergoing initial setup, so the VmAreaNew type is used.

Quoted 6 lines
Quoted 3 lines

Again, I'd be explicit about the VMA being passed to a struct file_operations->mmap() hook on mmap. Otherwise this seems super vague to me!

I wasn't sure if vmas could be constructed in any context other than mmap. Will reword.

Thanks.

Quoted 2 lines
Quoted 2 lines
Quoted 2 lines

_Definitely_ need the commit msg update above, but other than this from mm side looks reasonable, so:

Quoted 45 lines
Quoted 20 lines
Quoted 20 lines
---
 rust/kernel/miscdevice.rs | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)
rust/kernel/miscdevice.rs +1 -0
index 7e2a79b3ae26..4e4b9476e092 100644
@@ -11,6 +11,7 @@
 use crate::{
     bindings,
     error::{to_result, Error, Result, VTABLE_DEFAULT_ERROR},
+    mm::virt::VmAreaNew,
     prelude::*,
     str::CStr,
     types::{ForeignOwnable, Opaque},
@@ -110,6 +111,11 @@ fn release(device: Self::Ptr) {
         drop(device);
     }
 
Quoted 5 lines

rust/kernel/miscdevice.rs fn release(device: Self::Ptr) { · line 115

Quoted 2 lines
rust/kernel/miscdevice.rs +2 -0
+    /// Handle for mmap.
+    fn mmap(_device: <Self::Ptr as ForeignOwnable>::Borrowed<'_>, _vma: &VmAreaNew) -> Result {

You will have to help me with this :) ForeignOwnable, Borrowed<'_>, _vma I'm a bit lost here!

When you implement the Miscdevice for your own type, you write a block like this one:

impl Miscdevice for MyType {
    type Ptr = Arc<MyType>;
    ...
}

Here Arc is a pointer type (very similar to ARef) that represents ownership over a refcount to a refcounted value.

In this case:
* Self refers to MyType.
* Self::Ptr refers to Arc<MyType>
* <Self::Ptr as ForeignOwnable>::Borrowed<'_> refers to ArcBorrow<MyType>

The last step is resolved to ArcBorrow<MyType> because of this impl block in rust/kernel/sync/arc.rs:

Quoted 6 lines
impl<T: 'static> ForeignOwnable for Arc<T> {
    type Borrowed<'a> = ArcBorrow<'a, T>;
    ...
}

Note that Self::Ptr is short-hand for <Self as Miscdevice>::Ptr.

Thanks!

Quoted 8 lines
Quoted 5 lines

rust/kernel/miscdevice.rs fn release(device: Self::Ptr) { · line 116

Quoted 2 lines
rust/kernel/miscdevice.rs +1 -0
+        kernel::build_error(VTABLE_DEFAULT_ERROR)

What is this? Is this not yet implemented or something, and this is a placeholder or something?

It's a build-time assertion that this function is dead-code eliminated.

Quoted 7 lines

There are two cases:
* Either the driver does not override mmap. In this case, we store a null pointer in the fops table.
* Or the driver overrides mmap with their own implementation. In this case, we store a function pointer to whichever implementation they provided.
In neither case is the above function present anywhere in the final executable.

Ah nice, zero-cost stuff.

Quoted 2 lines

Alice