[PATCH v2] Rust: kernel patch submission

[AI talking about AI <aitalkingai@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 575 bytes --]

Hi all,

This is a two-patch series for the Rust-for-Linux tree:

  1) rust: mark CStr::to_str #[must_use] and update docs
     - Adds an "# Errors" section explaining UTF-8 failure modes
     - Prevents silent ignores by marking to_str() as #[must_use]
     - Documents safety preconditions on as_str_unchecked()

  2) rust: clarify safety comments in workqueue.rs
     - Replaces generic SAFETY: TODO with detailed invariants
       for RawWorkItem::__enqueue and WorkItemPointer::run

Please let me know if you’d like any tweaks.

Thanks,
—Slopisgood

[-- Attachment #1.2: Type: text/html, Size: 698 bytes --]

[-- Attachment #2: 0002-rust-clarify-safety-comments-in-workqueue.rs.patch --]
[-- Type: text/x-patch, Size: 2902 bytes --]

From d66384514f12bf7607fbb45185bc66699e6cbf48 Mon Sep 17 00:00:00 2001
From: slopisgood <aitalkingai@gmail.com>
Date: Thu, 7 Aug 2025 07:54:00 -0700
Subject: [PATCH 2/2] rust: clarify safety comments in workqueue.rs

Replace placeholder `SAFETY: TODO` comments in rust/kernel/workqueue.rs with detailed explanations of safety invariants for RawWorkItem and WorkItemPointer, following rust kernel guidelines.

Signed-off-by: slopisgood <aitalkingai@gmail.com>
---
 rust/kernel/workqueue.rs | 29 +++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs
index b9343d5..4a34651 100644
--- a/rust/kernel/workqueue.rs
+++ b/rust/kernel/workqueue.rs
@@ -881,7 +881,19 @@ where
 {
 }
 
-// SAFETY: TODO.
+    // SAFETY:
+    //
+    // The [`run`](WorkItemPointer::run) function pointer stored in the `work_struct` always
+    // originates from a prior call to [`__enqueue`](RawWorkItem::__enqueue) on a
+    // `Pin<KBox<T>>`.  A `Pin<KBox<T>>` owns its heap allocation and, by virtue of being
+    // pinned, guarantees that its contents will not be moved.  When the C side of the
+    // workqueue invokes the function pointer, it passes back the same `work_struct`
+    // pointer that was produced by `__enqueue`.  This implementation computes the
+    // original `KBox` from that pointer via `work_container_of` and converts it back
+    // into a pinned box, which is safe because ownership is transferred back from the
+    // kernel.  Therefore, the pointer passed to `run` is always valid for the
+    // duration of the call, and dereferencing it is sound.
+
 unsafe impl<T, const ID: u64> WorkItemPointer<ID> for Pin<KBox<T>>
 where
     T: WorkItem<ID, Pointer = Self>,
@@ -901,7 +913,20 @@ where
     }
 }
 
-// SAFETY: TODO.
+    // SAFETY:
+    //
+    // The implementation of [`RawWorkItem::__enqueue`] for `Pin<KBox<T>>` allocates a
+    // new `Work<T, ID>` and obtains a raw pointer to its embedded `work_struct` via
+    // [`raw_get_work`](Work::raw_get).  It then passes that pointer to the provided
+    // closure.  The `Pin<KBox<T>>` is freshly allocated and by type invariants cannot
+    // already be enqueued, so the closure must return `true`.  If it were to return
+    // `false`, the implementation invokes `unreachable_unchecked()`, which is never
+    // reached in valid usage.  When the closure returns `true` the C workqueue
+    // subsystem takes ownership of the `work_struct` and will eventually call back
+    // into [`WorkItemPointer::run`], at which point the box is recovered and
+    // dropped.  Throughout this process the raw pointer passed to the closure
+    // remains valid for the duration specified in [`RawWorkItem`]'s safety contract.
+
 unsafe impl<T, const ID: u64> RawWorkItem<ID> for Pin<KBox<T>>
 where
     T: WorkItem<ID, Pointer = Self>,
-- 
2.39.5


[-- Attachment #3: 0001-rust-mark-CStr-to_str-must_use-and-update-docs.patch --]
[-- Type: text/x-patch, Size: 3210 bytes --]

From 21a3d2a2dcff13f445915602c06a17af07835ee7 Mon Sep 17 00:00:00 2001
From: slopisgood <aitalkingai@gmail.com>
Date: Thu, 7 Aug 2025 07:53:56 -0700
Subject: [PATCH 1/2] rust: mark CStr::to_str #[must_use] and update docs

Add explanation about handling UTF-8 errors and mark CStr::to_str as #[must_use] to prevent silent error ignoring. Also document safety requirements of as_str_unchecked.

Signed-off-by: slopisgood <aitalkingai@gmail.com>
---
 rust/kernel/str.rs | 29 +++++++++++++++++++++--------
 1 file changed, 21 insertions(+), 8 deletions(-)

diff --git a/rust/kernel/str.rs b/rust/kernel/str.rs
index 6c89255..290031b 100644
--- a/rust/kernel/str.rs
+++ b/rust/kernel/str.rs
@@ -37,12 +37,8 @@ impl BStr {
     /// # Examples
     ///
     /// ```
-    /// # use kernel::b_str;
-    /// assert_eq!(Some(b_str!("bar")), b_str!("foobar").strip_prefix(b_str!("foo")));
-    /// assert_eq!(None, b_str!("foobar").strip_prefix(b_str!("bar")));
-    /// assert_eq!(Some(b_str!("foobar")), b_str!("foobar").strip_prefix(b_str!("")));
-    /// assert_eq!(Some(b_str!("")), b_str!("foobar").strip_prefix(b_str!("foobar")));
-    /// ```
+
+///
     pub fn strip_prefix(&self, pattern: impl AsRef<Self>) -> Option<&BStr> {
         self.deref()
             .strip_prefix(pattern.as_ref().deref())
@@ -346,7 +342,7 @@ impl CStr {
     ///
     /// If the contents of the [`CStr`] are valid UTF-8 data, this
     /// function will return the corresponding [`&str`] slice. Otherwise,
-    /// it will return an error with details of where UTF-8 validation failed.
+    /// it will return an [`Err`] with details of where UTF-8 validation failed.
     ///
     /// # Examples
     ///
@@ -356,7 +352,21 @@ impl CStr {
     /// assert_eq!(cstr.to_str(), Ok("foo"));
     /// # Ok::<(), kernel::error::Error>(())
     /// ```
+
+    ///
+    /// # Errors
+    ///
+    /// This function returns an [`Err`] when the underlying bytes are not
+    /// valid UTF-8. The [`Err`] must be handled; it cannot be discarded,
+    /// as indicated by the `#[must_use]` annotation on this method.
+    ///
+    /// This method returns a [`Result`] because not all C strings contain
+    /// valid UTF-8. To avoid accidentally ignoring a failed conversion,
+    /// the return type is marked `#[must_use]`. Code that calls this
+    /// function should handle the error case explicitly (e.g. by logging or
+    /// propagating it), rather than silently discarding it.
     #[inline]
+    #[must_use]
     pub fn to_str(&self) -> Result<&str, core::str::Utf8Error> {
         core::str::from_utf8(self.as_bytes())
     }
@@ -380,7 +390,10 @@ impl CStr {
     /// ```
     #[inline]
     pub unsafe fn as_str_unchecked(&self) -> &str {
-        // SAFETY: TODO.
+        // SAFETY: The data behind `self` are bytes from a `CStr`, i.e. a NUL-terminated sequence
+        // of u8 values. `from_utf8_unchecked` requires that the byte slice be valid UTF-8; the
+        // caller of this method must therefore guarantee that the `CStr` contains valid UTF-8
+        // data before calling this function. See [`to_str`] for a checked version.
         unsafe { core::str::from_utf8_unchecked(self.as_bytes()) }
     }
 
-- 
2.39.5