Skip to contentSkip to conversation

rust: kernel: document safety for rust_fmt_argument

PATCH In review Shivendra Sharma 2 participants 2 messages Jan 28 – Feb 10 Rust

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 rust: kernel: document safety for rust_fmt_argument

Currently, rust_fmt_argument uses a TODO for its safety rationale and suppresses the missing_safety_doc clippy warning.

Following feedback from a previous attempt [1], replace the suppression with a formal "# Safety" section and update the internal "// SAFETY" comments to reference these requirements. Additionally, add a comment to the C header file pointing to the Rust documentation for safety preconditions.

[1] https://lore.kernel.org/rust-for-linux/CANiq72=b=Z+6dk4XWK6QWcKDJx7SYXL0obAFFfWp8xpE1CFkkw@mail.gmail.com/

---
 include/linux/sprintf.h |  7 ++++++-
 rust/kernel/print.rs    | 14 +++++++++++---
 2 files changed, 17 insertions(+), 4 deletions(-)
include/linux/sprintf.h +6 -1
index f06f7b785091..f915829cbba5 100644
@@ -25,7 +25,12 @@ __scanf(2, 0) int vsscanf(const char *, const char *, va_list);
 extern bool no_hash_pointers;
 void hash_pointers_finalize(bool slub_debug);
 
-/* Used for Rust formatting ('%pA') */
+/**
+ * Used for Rust formatting ('%pA').
+ *
+ * Safety preconditions are documented in the Rust implementation
+ * (rust/kernel/print.rs).
+ */
 char *rust_fmt_argument(char *buf, char *end, const void *ptr);
 
 #endif	/* _LINUX_KERNEL_SPRINTF_H */
rust/kernel/print.rs +11 -3
index 2d743d78d220..30da8b974398 100644
@@ -14,7 +14,12 @@
 };
 
 // Called from `vsprintf` with format specifier `%pA`.
-#[expect(clippy::missing_safety_doc)]
+///
+/// # Safety
+///
+/// - `buf` must be valid for writes until `end`.
+/// - `ptr` must point to a valid `fmt::Arguments` instance.
+/// - The `fmt::Arguments` must remain valid for the duration of the call.
 #[export]
 unsafe extern "C" fn rust_fmt_argument(
     buf: *mut c_char,
@@ -22,9 +27,12 @@
     ptr: *const c_void,
 ) -> *mut c_char {
     use fmt::Write;
-    // SAFETY: The C contract guarantees that `buf` is valid if it's less than `end`.
+    // SAFETY: The safety requirements of this function (see above)
+    // guarantee that `buf` and `end` define a valid range.
     let mut w = unsafe { RawFormatter::from_ptrs(buf.cast(), end.cast()) };
-    // SAFETY: TODO.
+
+    // SAFETY: The safety requirements of this function guarantee that `ptr`
+    // points to a valid `fmt::Arguments`.
     let _ = w.write_fmt(unsafe { *ptr.cast::<fmt::Arguments<'_>>() });
     w.pos().cast()
 }
Signature · 1 line
2.52.0
#1 lore raw
Quoted 10 lines · Shivendra Sharma

Currently, rust_fmt_argument uses a TODO for its safety rationale and suppresses the missing_safety_doc clippy warning.

Following feedback from a previous attempt [1], replace the suppression with a formal "# Safety" section and update the internal "// SAFETY" comments to reference these requirements. Additionally, add a comment to the C header file pointing to the Rust documentation for safety preconditions.

Quoted 3 lines

[1] https://lore.kernel.org/rust-for-linux/CANiq72=b=Z+6dk4XWK6QWcKDJx7SYXL0obAFFfWp8xpE1CFkkw@mail.gmail.com/

Related:

https://lore.kernel.org/rust-for-linux/[email protected]/

Cc'ing Muchamad.

Could you (i.e. both) please coordinate the patches, perhaps merging them into a single series? You may want to use Co-developed-by and/or have a different author per patch etc.

Thanks!

Cheers,
Miguel