Skip to contentSkip to conversation

rust: add safety comment in rust_fmt_argument

PATCH In review Konstantin Andrikopoulos 4 participants 6 messages Nov 18, 2024 – Dec 1, 2024 Rust

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 rust: add safety comment in rust_fmt_argument

The function rust_fmt_argument dereferences a pointer, and thus it needs an unsafe block. The safety comment for that block was missing.

---
 rust/kernel/print.rs | 31 ++++++++++++++++++++++++++-----
 1 file changed, 26 insertions(+), 5 deletions(-)
rust/kernel/print.rs +26 -5
index a28077a7cb30..57a4fc48bbcd 100644
@@ -13,8 +13,27 @@
 
 use crate::str::RawFormatter;
 
-// Called from `vsprintf` with format specifier `%pA`.
-#[expect(clippy::missing_safety_doc)]
+/// Handles the `%pA` format specifier.
+///
+/// This function is called by [`vsprintf`] when it encounters a `%pA` format specifier in a
+/// format string. `ptr` points to the corresponding argument, `buf` points to a buffer to hold
+/// the formatted argument, and `end` points at the buffer's end.
+///
+/// `rust_fmt_argument` treats `ptr` as a pointer to a [`core::fmt::Arguments`], which it formats,
+/// and writes the result to `buf`.
+///
+/// It returns the address after the last byte it has written in `buf`.
+///
+/// # Safety
+///
+/// `buf` and `end` must follow the requirements of [`RawFormatter`]. `ptr` must be valid for
+/// reading a [`core::fmt::Arguments`].
+///
+/// `vsprintf` guarantees that `buf` and `end` will uphold their requirements. However, it will
+/// just forward the argument that corresponds to `%pA`. Callers that provide format strings must
+/// guarantee that arguments which correspond to `%pA` are valid pointers.
+///
+/// [`vsprintf`]: srctree/lib/vsprintf.c
 #[no_mangle]
 unsafe extern "C" fn rust_fmt_argument(
     buf: *mut c_char,
@@ -24,7 +43,8 @@
     use fmt::Write;
     // SAFETY: The C contract guarantees that `buf` is valid if it's less than `end`.
     let mut w = unsafe { RawFormatter::from_ptrs(buf.cast(), end.cast()) };
-    // SAFETY: TODO.
+    // SAFETY: The safety preconditions require that `ptr` is a valid pointer to a `fmt::Arguments`
+    // struct.
     let _ = w.write_fmt(unsafe { *(ptr as *const fmt::Arguments<'_>) });
     w.pos().cast()
 }
@@ -104,7 +124,8 @@ pub unsafe fn call_printk(
 ) {
     // `_printk` does not seem to fail in any path.
     #[cfg(CONFIG_PRINTK)]
-    // SAFETY: TODO.
+    // SAFETY: The format string and the module name are valid to pass to `_printk` as required
+    // by the preconditions. Additionally we pass a pointer to a valid `fmt::Arguments` struct.
     unsafe {
         bindings::_printk(
             format_string.as_ptr() as _,
@@ -124,7 +145,7 @@ pub unsafe fn call_printk(
 pub fn call_printk_cont(args: fmt::Arguments<'_>) {
     // `_printk` does not seem to fail in any path.
     //
-    // SAFETY: The format string is fixed.
+    // SAFETY: The format string is fixed and we pass a valid pointer to a `fmt::Arguments`.
     #[cfg(CONFIG_PRINTK)]
     unsafe {
         bindings::_printk(
Signature · 1 line
2.47.0
#2 lore raw
In reply to Konstantin Andrikopoulos
Quoted 10 lines · Konstantin Andrikopoulos

The function rust_fmt_argument dereferences a pointer, and thus it needs an unsafe block. The safety comment for that block was missing.

rust/kernel/print.rs +3 -2
-// Called from `vsprintf` with format specifier `%pA`.
-#[expect(clippy::missing_safety_doc)]
+/// Handles the `%pA` format specifier.
+///
+/// This function is called by [`vsprintf`] when it encounters a

%pA format specifier in a

Nit: The file implementing this is vsprintf.c, but the actual workhorse is vsnprintf() (note the n); all other *printf() variants are wrappers around that, and I'm pretty sure no code path called from Rust ends up passing through sprintf() or vsprintf(). Yes, I see that the original code said vsprintf, but please fix while here.

Quoted 14 lines
rust/kernel/print.rs +14 -0
+/// format string. `ptr` points to the corresponding argument, `buf` points to a buffer to hold
+/// the formatted argument, and `end` points at the buffer's end.
+///
+/// `rust_fmt_argument` treats `ptr` as a pointer to a [`core::fmt::Arguments`], which it formats,
+/// and writes the result to `buf`.
+///
+/// It returns the address after the last byte it has written in `buf`.
+///
+/// # Safety
+///
+/// `buf` and `end` must follow the requirements of [`RawFormatter`]. `ptr` must be valid for
+/// reading a [`core::fmt::Arguments`].
+///
+/// `vsprintf` guarantees that `buf` and `end` will uphold their
Quoted 1 line

requirements. However, it will

Same here.

rust/kernel/print.rs line 36

Quoted 4 lines
rust/kernel/print.rs +4 -0
+/// just forward the argument that corresponds to `%pA`. Callers that provide format strings must
+/// guarantee that arguments which correspond to `%pA` are valid pointers.
+///
+/// [`vsprintf`]: srctree/lib/vsprintf.c

Same here (the filename is correct).

Rasmus

#3 lore raw
Quoted 6 lines · Rasmus Villemoes

Nit: The file implementing this is vsprintf.c, but the actual workhorse is vsnprintf() (note the n); all other *printf() variants are wrappers around that, and I'm pretty sure no code path called from Rust ends up passing through sprintf() or vsprintf(). Yes, I see that the original code said vsprintf, but please fix while here.

Thanks for the comments! Going through the code again, I see that rust_fmt_argument is directly called from the pointer function in vsprintf.c

But pointer is not only called from vsnprintf. It is also called in vbin_printf and bstr_printf. Should this be reflected in rust_fmt_argument's documentation, or are these functions unreachable from rust code?

Perhaps the docs should just mention pointer()? Maybe the original comment used "vsprintf" to refer collectively to all these functions?

#4 lore raw
Quoted 9 lines · Konstantin Andrikopoulos
Quoted 6 lines · Rasmus Villemoes

Nit: The file implementing this is vsprintf.c, but the actual workhorse is vsnprintf() (note the n); all other *printf() variants are wrappers around that, and I'm pretty sure no code path called from Rust ends up passing through sprintf() or vsprintf(). Yes, I see that the original code said vsprintf, but please fix while here.

Quoted 6 lines

Thanks for the comments! Going through the code again, I see that rust_fmt_argument is directly called from the pointer function in vsprintf.c

But pointer is not only called from vsnprintf. It is also called in vbin_printf and bstr_printf. Should this be reflected in rust_fmt_argument's documentation, or are these functions unreachable from rust code?

As for the latter, I think they are used by the tracing code, so probably they are or will be reachable from rust (Alice?).

Quoted 2 lines

Perhaps the docs should just mention pointer()? Maybe the original comment used "vsprintf" to refer collectively to all these functions?

That's certainly possible, I didn't think about that possibility. If so, my comments should be ignored :)

The occurrence of vsprintf that triggered me was

vsprintf guarantees that buf and end will uphold their requirements.

because while this could perhaps be read as vsprintf-the-translation-unit, vsprintf-the-function blindly assumes that its caller has passed a large enough buffer and fakes a len argument of INT_MAX to vsnprintf().

So I dunno. If the intention is to refer to vsprintf.c as a whole, perhaps it would be better to actually include that .c extension when referring to it, to avoid the ambiguity.

Rasmus

#5 lore raw
Quoted 3 lines · Rasmus Villemoes

That's certainly possible, I didn't think about that possibility. If so, my comments should be ignored :)

That may have been the case -- this was commit 9e8bd679ecf2 ("Support Rust core::fmt::Argument in vsprintf") in our old out-of-tree branch, which added the docs to pointer().

Quoted 3 lines

So I dunno. If the intention is to refer to vsprintf.c as a whole, perhaps it would be better to actually include that .c extension when referring to it, to avoid the ambiguity.

Agreed, it would be better to clearly distinguish between one and the other.

In addition, I would suggest moving the "vsprintf guarantees that ..." out of the # Safety section since it is not a precondition, and probably reword it to clarify it is talking about particular callers.

In fact, wouldn't it make more sense to move that note to the // SAFETY comment(s)? Actually, what if we just add it to the C call? i.e.

        /* SAFETY: ... */
        return rust_fmt_argument(buf, end, ptr);

It would be our first SAFETY comment outside a Rust file, but I think it would be a good time to start doing that.

...now, I actually did a quick grep, and there already are a couple /* SAFETY: comments in drivers/rtc/rtc-tps6594.c by Esteban -- that was a nice surprise! :)

(Speaking of drivers/rtc/rtc-tps6594.c: I think to follow the usual convention those SAFETY comments should be on top the block (not below) and ideally split for each operation. Also, I think it is not up to date (?), e.g. it mentions TICK(S)_PER_HOUR but it uses NANO instead (the other side of the code does use TICKS_PER_HOUR))

Thanks!

Cheers,
Miguel