rust: add CBoundedStr

`CBoundedStr<N>` is a `CStr` with length known to be less than `N`.
It can be used in cases where a known length limit exists.

Signed-off-by: Gary Guo <[email protected]>

Author: nbdd0121

rust/kernel/lib.rs

@@ -70,7 +70,7 @@ pub mod user_ptr;
 pub use macros;
 
 pub use crate::error::{Error, KernelResult};
-pub use crate::types::{CStr, Mode};
+pub use crate::types::{CBoundedStr, CStr, Mode};
 
 /// Page size defined in terms of the `PAGE_SHIFT` macro from C.
 ///

rust/kernel/types.rs

@@ -4,6 +4,9 @@
 //!
 //! C header: [`include/linux/types.h`](../../../../include/linux/types.h)
 
+use build_assert::build_assert;
+use core::ops::Deref;
+
 use crate::bindings;
 use crate::c_types;
 
@@ -123,6 +126,112 @@ impl CStr {
     }
 }
 
+/// A `NUL`-terminated string that is guaranteed to be shorter than a given
+/// length. This type is useful because C-side usually impose maximum length
+/// on types.
+///
+/// The size parameter `N` represent the maximum number of bytes including NUL.
+/// This implies that even though `CBoundedStr<0>` is a well-formed type it cannot
+/// be safely created.
+#[repr(transparent)]
+pub struct CBoundedStr<const N: usize>(CStr);
+
+impl<const N: usize> CBoundedStr<N> {
+    /// Creates a [`CBoundedStr`] form a [`CStr`].
+    ///
+    /// The provided `CStr` must be shorten than `N`.
+    #[inline]
+    pub fn from_c_str(c_str: &CStr) -> Result<&Self, CStrConvertError> {
+        if c_str.0.len() > N {
+            return Err(CStrConvertError::BoundExceeded);
+        }
+
+        // SAFETY: We just checked that all properties hold.
+        Ok(unsafe { Self::from_c_str_unchecked(c_str) })
+    }
+
+    /// Creates a [`CBoundedStr`] form a [`CStr`] without performing any sanity
+    /// checks.
+    ///
+    /// # Safety
+    ///
+    /// The provided CStr must be shorten than `N`.
+    #[inline]
+    pub const unsafe fn from_c_str_unchecked(c_str: &CStr) -> &Self {
+        &*(c_str as *const CStr as *const Self)
+    }
+
+    /// Creates a [`CBoundedStr`] form a `[u8]`.
+    ///
+    /// The provided slice must be nul-terminated, does not contain any
+    /// interior nul bytes and be shorten than `N`.
+    #[inline]
+    pub fn from_bytes_with_nul(bytes: &[u8]) -> Result<&Self, CStrConvertError> {
+        Self::from_c_str(CStr::from_bytes_with_nul(bytes)?)
+    }
+
+    /// Creates a [`CBoundedStr`] form a `[u8]` without performing any sanity
+    /// checks.
+    ///
+    /// # Safety
+    ///
+    /// The provided slice must be nul-terminated, does not contain any
+    /// interior nul bytes and be shorten than `N`.
+    #[inline]
+    pub const unsafe fn from_bytes_with_nul_unchecked(bytes: &[u8]) -> &Self {
+        Self::from_c_str_unchecked(CStr::from_bytes_with_nul_unchecked(bytes))
+    }
+
+    /// Creates a [`CBoundedStr`] form a `[u8; N]` without performing any sanity
+    /// checks.
+    ///
+    /// # Safety
+    ///
+    /// The provided slice must be nul-terminated.
+    #[inline]
+    pub const unsafe fn from_exact_bytes_with_nul_unchecked(bytes: &[u8; N]) -> &Self {
+        Self::from_bytes_with_nul_unchecked(bytes)
+    }
+
+    /// Relaxes the bound from `N` to `M`.
+    ///
+    /// `M` must be no less than the bound `N`.
+    #[inline]
+    pub const fn relax_bound<const M: usize>(&self) -> &CBoundedStr<M> {
+        build_assert!(N <= M, "relaxed bound should be no less than current bound");
+        unsafe { CBoundedStr::<M>::from_c_str_unchecked(&self.0) }
+    }
+
+    /// Converts the string to a c_char array with the current bound, fills the
+    /// remaining bytes with zero.
+    #[inline]
+    pub const fn to_char_array(&self) -> [c_types::c_char; N] {
+        let mut ret: [c_types::c_char; N] = [0; N];
+        let mut i = 0;
+        while i < self.0 .0.len() {
+            ret[i] = self.0 .0[i] as _;
+            i += 1;
+        }
+        ret
+    }
+
+    /// Expands the string a c_char array, fills remaining bytes with zero.
+    ///
+    /// `M` must be no less than the bound `N`.
+    #[inline]
+    pub const fn expand_to_char_array<const M: usize>(&self) -> [c_types::c_char; M] {
+        self.relax_bound().to_char_array()
+    }
+}
+
+impl<const N: usize> Deref for CBoundedStr<N> {
+    type Target = CStr;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
 /// Creates a new `CStr` from a string literal.
 ///
 /// The string literal should not contain any `NUL` bytes.
@@ -142,3 +251,53 @@ macro_rules! c_str {
         C
     }};
 }
+
+/// Creates a new `CBoundedStr` from a string literal.
+///
+/// The string literal should not contain any `NUL` bytes, and its length with NUL should not
+/// exceed the bound supplied.
+///
+/// # Examples
+///
+/// ```rust,no_run
+/// // If no bound is specified, the tighest bound will be inferred:
+/// const MY_CSTR: &'static CBoundedStr<17> = c_bounded_str!("My awesome CStr!");
+/// ```
+///
+/// ```rust,compile_fail
+/// // This would not compile as the type is `CBoundedStr<17>`.
+/// const MY_CSTR: &'static CBoundedStr<100> = c_bounded_str!("My awesome CStr!");
+/// ```
+///
+/// ```rust,no_run
+/// // You can relax the bound using the `relax_bound` method.
+/// const MY_CSTR: &'static CBoundedStr<100> = c_bounded_str!("My awesome CStr!").relax_bound();
+/// ```
+///
+/// ```rust,no_run
+/// // Or alternatively specify a bound when invoking macro.
+/// const MY_CSTR: &'static CBoundedStr<100> = c_bounded_str!(100, "My awesome CStr!");
+/// ```
+///
+/// ```rust,compile_fail
+/// // shouldn't compile as the string is longer than the specified bound.
+/// const MY_CSTR: &'static CBoundedStr<10> = c_bounded_str!(100, "My awesome CStr!");
+/// ```
+#[macro_export]
+macro_rules! c_bounded_str {
+    ($str:literal) => {{
+        let s = $crate::macros::append_nul!($str);
+        unsafe { $crate::CBoundedStr::from_exact_bytes_with_nul_unchecked(s) }
+    }};
+    ($bound:expr, $str:literal) => {{
+        const C: &'static $crate::CBoundedStr<$bound> = {
+            let s = $crate::macros::append_nul!($str);
+            if s.len() > $bound {
+                // NOPANIC: This is a const panic.
+                panic!("bound exceeded");
+            }
+            unsafe { $crate::CBoundedStr::<$bound>::from_bytes_with_nul_unchecked(s) }
+        };
+        C
+    }};
+}