rust: add safety comment in rust_fmt_argument
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
@@ -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 { *(ptras *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
Quoted 8 lines · Konstantin Andrikopoulos
The function
rust_fmt_argumentdereferences a pointer, and thus it needs an unsafe block. The safety comment for that block was missing.Signed-off-by Konstantin Andrikopoulos <[email protected]>Suggested-by Miguel Ojeda <[email protected]>
Quoted 10 lines · Konstantin Andrikopoulos
The function
rust_fmt_argumentdereferences 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
%pAformat 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
Quoted 6 lines · Rasmus Villemoes
Nit: The file implementing this is
vsprintf.c, but the actual workhorse isvsnprintf()(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 throughsprintf()orvsprintf(). 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?
Quoted 9 lines · Konstantin Andrikopoulos
Quoted 6 lines · Rasmus Villemoes
Nit: The file implementing this is
vsprintf.c, but the actual workhorse isvsnprintf()(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 throughsprintf()orvsprintf(). 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_argumentis directly called from the pointer function invsprintf.cBut pointer is not only called from vsnprintf. It is also called in
vbin_printfandbstr_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
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.cas 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