rust: kernel: document safety for rust_fmt_argument
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.
--- include/linux/sprintf.h | 7 ++++++- rust/kernel/print.rs | 14 +++++++++++--- 2 files changed, 17 insertions(+), 4 deletions(-)
include/linux/sprintf.h +6 -1
@@ -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
@@ -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
Quoted 10 lines · Shivendra Sharma
Currently,
rust_fmt_argumentuses a TODO for its safety rationale and suppresses themissing_safety_docclippy 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
Signed-off-by Shivendra Sharma <[email protected]>
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