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

[Cian McGuire]

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

Both are two ends of the same round trip. `call_printk` passes a raw
pointer to its `args: fmt::Arguments<'_>` parameter into `_printk`,
whose format string always contains a `%pA` specifier for it. The `%pA`
case in `lib/vsprintf.c`'s pointer formatter calls back into
`rust_fmt_argument` with that same pointer, synchronously, as one call
in a `switch` dispatch that returns its result immediately -- there is
no deferred use or storage of the pointer on the C side. So `args`
remains alive on `call_printk`'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 <ojeda@xxxxxxxxxx>
Link: https://github.com/Rust-for-Linux/linux/issues/351
Signed-off-by: Cian McGuire <cianmcguire167@xxxxxxxxx>
---
 rust/kernel/print.rs | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/rust/kernel/print.rs b/rust/kernel/print.rs
index 6fd84389a858..0e341262f83e 100644
--- a/rust/kernel/print.rs
+++ b/rust/kernel/print.rs
@@ -29,7 +29,11 @@
     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 handled in
+    // `lib/vsprintf.c`, which calls it synchronously with the `ptr` that `call_printk`
+    // 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 +113,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