[PATCH v2] rust: add safety comment in rust_fmt_argument

[PATCH v2] rust: add safety comment in rust_fmt_argument

[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.

Link: https://github.com/Rust-for-Linux/linux/issues/351.

Signed-off-by: Konstantin Andrikopoulos <kernel@mandragore.io>
Suggested-by: Miguel Ojeda <ojeda@kernel.org>
---
 rust/kernel/print.rs | 31 ++++++++++++++++++++++++++-----
 1 file changed, 26 insertions(+), 5 deletions(-)

diff --git a/rust/kernel/print.rs b/rust/kernel/print.rs
index a28077a7cb30..57a4fc48bbcd 100644
--- a/rust/kernel/print.rs
+++ b/rust/kernel/print.rs
@@ -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(
-- 
2.47.0

Re: [PATCH v2] rust: add safety comment in rust_fmt_argument

[Alice Ryhl]

On Mon, Nov 18, 2024 at 4:14 AM Konstantin Andrikopoulos
<kernel@mandragore.io> wrote:
>
> The function rust_fmt_argument dereferences a pointer, and thus it
> needs an unsafe block. The safety comment for that block was missing.
>
> Link: https://github.com/Rust-for-Linux/linux/issues/351.
>
> Signed-off-by: Konstantin Andrikopoulos <kernel@mandragore.io>
> Suggested-by: Miguel Ojeda <ojeda@kernel.org>

Reviewed-by: Alice Ryhl <aliceryhl@google.com>

Re: [PATCH v2] rust: add safety comment in rust_fmt_argument

[Rasmus Villemoes]

On Mon, Nov 18 2024, Konstantin Andrikopoulos <kernel@mandragore.io> wrote:

> The function rust_fmt_argument dereferences a pointer, and thus it
> needs an unsafe block. The safety comment for that block was missing.
>
>  
> -// 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.

> +/// 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

Same here.

> +/// 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

Re: [PATCH v2] rust: add safety comment in rust_fmt_argument

[Konstantin Andrikopoulos]

On Thursday, November 21st, 2024 at 10:42 AM, Rasmus Villemoes <ravi@prevas.dk> wrote:

> 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?

Re: [PATCH v2] rust: add safety comment in rust_fmt_argument

[Rasmus Villemoes]

On Sat, Nov 23 2024, Konstantin Andrikopoulos <kernel@mandragore.io> wrote:

> On Thursday, November 21st, 2024 at 10:42 AM, Rasmus Villemoes <ravi@prevas.dk> wrote:
>
>> 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?

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

> 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

Re: [PATCH v2] rust: add safety comment in rust_fmt_argument

[Miguel Ojeda]

On Tue, Nov 26, 2024 at 10:07 AM Rasmus Villemoes <ravi@prevas.dk> wrote:
>
> 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()`.

> 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