[PATCH v2 1/1] rust: seq_file: add puts, putc, write, and hex_dump methods

[Christian Benton <t1bur0n.kernel.org@protonmail.ch>]

The SeqFile abstraction currently only exposes seq_printf via the
seq_print! macro. This leaves several commonly used seq_file operations
unavailable to Rust kernel code.

Add the following methods to SeqFile:

- puts(): writes a C string using __seq_puts()
- putc(): writes a single byte using seq_putc()
- write(): writes raw bytes using seq_write()
- hex_dump(): dumps binary data as formatted hex using seq_hex_dump()

Also add HexDumpPrefix, a Rust enum wrapping the DUMP_PREFIX_NONE,
DUMP_PREFIX_ADDRESS, and DUMP_PREFIX_OFFSET constants, replacing the
raw integer interface with a type-safe alternative that makes invalid
prefix values unrepresentable.

The motivation for this patch is to support Rust character device drivers
that expose data as formatted output through the seq_file interface. The
amdtelem out-of-tree driver is a concrete example — it registers a misc
character device that exposes GPU telemetry data, where puts() and
hex_dump() provide cleaner alternatives to repeated seq_print! calls for
string labels and binary register dumps.

v2: Fix build issues reported by kernel test robot
  - Reformat use statement to satisfy rustfmt line length requirement
  - Rename as_c_int() to to_c_int() to satisfy clippy wrong_self_convention
  - Replace rowsize/groupsize as-casts with ffi::c_int::from() to satisfy
    clippy cast_lossless lint

Signed-off-by: Christian Benton <t1bur0n.kernel.org@protonmail.ch>
---
 rust/kernel/seq_file.rs | 87 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 86 insertions(+), 1 deletion(-)

diff --git a/rust/kernel/seq_file.rs b/rust/kernel/seq_file.rs
index 518265558d66..144bd6ef92d5 100644
--- a/rust/kernel/seq_file.rs
+++ b/rust/kernel/seq_file.rs
@@ -4,7 +4,9 @@
 //!
 //! C header: [`include/linux/seq_file.h`](srctree/include/linux/seq_file.h)
 
-use crate::{bindings, fmt, str::CStrExt as _, types::NotThreadSafe, types::Opaque};
+use crate::{
+    bindings, ffi, fmt, str::CStr, str::CStrExt as _, types::NotThreadSafe, types::Opaque,
+};
 
 /// A utility for generating the contents of a seq file.
 #[repr(transparent)]
@@ -13,6 +15,26 @@ pub struct SeqFile {
     _not_send: NotThreadSafe,
 }
 
+/// The prefix type for [`SeqFile::hex_dump`].
+pub enum HexDumpPrefix {
+    /// No prefix.
+    None,
+    /// Prefix with the memory address.
+    Address,
+    /// Prefix with the offset within the buffer.
+    Offset,
+}
+
+impl HexDumpPrefix {
+    fn to_c_int(self) -> ffi::c_int {
+        match self {
+            Self::None => bindings::DUMP_PREFIX_NONE as ffi::c_int,
+            Self::Address => bindings::DUMP_PREFIX_ADDRESS as ffi::c_int,
+            Self::Offset => bindings::DUMP_PREFIX_OFFSET as ffi::c_int,
+        }
+    }
+}
+
 impl SeqFile {
     /// Creates a new [`SeqFile`] from a raw pointer.
     ///
@@ -41,6 +63,69 @@ pub fn call_printf(&self, args: fmt::Arguments<'_>) {
             );
         }
     }
+
+    /// Prints a C string to the seq file.
+    pub fn puts(&self, s: &CStr) {
+        // SAFETY: `self.inner.get()` is valid because `&self` guarantees the
+        // `SeqFile` is alive and was properly initialized via `from_raw`.
+        // `s.as_char_ptr()` is valid because `CStr` is always a valid
+        // null-terminated C string.
+        unsafe { bindings::__seq_puts(self.inner.get(), s.as_char_ptr()) }
+    }
+
+    /// Prints a single char to the seq file.
+    pub fn putc(&self, c: u8) {
+        // SAFETY: `self.inner.get()` is valid because `&self`
+        // guarantees `SeqFile` is alive and was properly initialized via `from_raw`
+        unsafe { bindings::seq_putc(self.inner.get(), c as ffi::c_char) }
+    }
+
+    /// Writes raw bytes to the seq file.
+    pub fn write(&self, data: &[u8]) {
+        // SAFETY: `self.inner.get()` is valid because `&self` guarantees the
+        // `SeqFile` is alive and was properly initialized via `from_raw`.
+        // `data.as_ptr()` is valid and non-dangling because it comes from a
+        // `&[u8]`, which guarantees the memory is valid for `data.len()` bytes
+        // and will not be modified during the call due to the shared reference.
+        unsafe {
+            bindings::seq_write(
+                self.inner.get(),
+                data.as_ptr().cast::<ffi::c_void>(),
+                data.len(),
+            )
+        };
+    }
+
+    /// Prints a hex dump of `buf` to the seq file.
+    pub fn hex_dump(
+        &self,
+        prefix_str: &CStr,
+        prefix_type: HexDumpPrefix,
+        rowsize: u8,
+        groupsize: u8,
+        buf: &[u8],
+        ascii: bool,
+    ) {
+        // SAFETY: `self.inner.get()` is valid because `&self` guarantees the
+        // `SeqFile` is alive and was properly initialized via `from_raw`.
+        // `prefix_str.as_char_ptr()` is valid because `CStr` is always a valid
+        // null-terminated C string. `buf.as_ptr()` is valid and non-dangling
+        // because it comes from a `&[u8]`, which guarantees the memory is valid
+        // for `buf.len()` bytes and will not be modified during the call due to
+        // the shared reference.
+        unsafe {
+            bindings::seq_hex_dump(
+                self.inner.get(),
+                prefix_str.as_char_ptr(),
+                prefix_type.to_c_int(),
+                ffi::c_int::from(rowsize),
+                ffi::c_int::from(groupsize),
+                buf.as_ptr().cast::<ffi::c_void>(),
+                buf.len(),
+                ascii,
+            )
+        }
+    }
 }
 
 /// Write to a [`SeqFile`] with the ordinary Rust formatting syntax.
-- 
2.53.0