[PATCH v2 2/4] rust: print: document safety of _printk FFI calls

Two calls in this file had their SAFETY comments left as "TODO.": the
cast back to `fmt::Arguments` in `rust_fmt_argument`, and the call to
`bindings::_printk` in `call_printk`.

`rust_fmt_argument` is only reachable through the `%pA` format
specifier. Every in-tree Rust caller that uses `%pA` -- `call_printk`,
`device::printk`, `kunit::printk`, and `seq_file::call_printf` -- invokes
it synchronously with a pointer derived from its own live
`fmt::Arguments`, as one call in a `switch` dispatch in
`lib/vsprintf.c`'s pointer formatter that returns its result immediately;
there is no deferred use or storage of the pointer on the C side. So the
`fmt::Arguments` value stays alive on the caller's stack for the whole
time `rust_fmt_argument` is running with `ptr` pointing at it.

The `_printk` call itself is also justified by this function's own
`# Safety` section: `format_string` is guaranteed to be one of the fixed
`format_strings` statics (traced through every `pr_*!` macro, each of
which hardcodes a specific one), so its `%s`/`%pA` specifiers always
match the two extra arguments supplied, and `module_name` is guaranteed
null-terminated by both of its possible origins (`kernel::__LOG_PREFIX`
and the one generated by the `module!` proc macro).

Suggested-by: Miguel Ojeda <[email protected]>
Link: https://github.com/Rust-for-Linux/linux/issues/351
Signed-off-by: Cian McGuire <[email protected]>
---
v2:
- The `rust_fmt_argument` comment named only `call_printk` as the caller
  supplying `ptr`; it now names all four in-tree `%pA` callers
  (`call_printk`, `device::printk`, `kunit::printk`,
  `seq_file::call_printf`), since the argument applies to any of them.

 rust/kernel/print.rs | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/rust/kernel/print.rs b/rust/kernel/print.rs
index 6fd84389a858..b2be5ab50f15 100644
--- a/rust/kernel/print.rs
+++ b/rust/kernel/print.rs
@@ -29,7 +29,10 @@
     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: This function is only reachable via the `%pA` format specifier; using `%pA` from
+    // Rust requires the caller to invoke it synchronously with a `ptr` derived from a live
+    // `&fmt::Arguments`, before that reference's scope can end. `ptr` is therefore valid and
+    // properly aligned for a `fmt::Arguments<'_>` for the duration of this call.
     let _ = w.write_fmt(unsafe { *ptr.cast::<fmt::Arguments<'_>>() });
     w.pos().cast()
 }
@@ -109,7 +112,11 @@ pub unsafe fn call_printk(
 ) {
     // `_printk` does not seem to fail in any path.
     #[cfg(CONFIG_PRINTK)]
-    // SAFETY: TODO.
+    // SAFETY: By this function's safety requirements, `format_string` is one of the fixed
+    // `format_strings` statics, so its `%s`/`%pA` specifiers match the two arguments
+    // supplied below, and `module_name` is null-terminated as `%s` requires. The third
+    // argument points at `args`, which remains valid for the duration of this call and is
+    // only read back synchronously, through `%pA`, by `rust_fmt_argument`.
     unsafe {
         bindings::_printk(
             format_string.as_ptr(),
-- 
2.55.0