rust: str: Use `core::CStr`, remove the custom `CStr` implementation
Subsystems (8)
PATCH v3 1/1 rust: str: Use `core::CStr`, remove the custom `CStr` implementation
CStr became a part of core library in Rust 1.75. This change replaces the custom CStr implementation with the one from core.
core::CStr behaves generally the same as the removed implementation, with the following differences:
- It does not implement Display (but implements Debug). Therefore, by switching to core::CStr, we lose the Display implementation.
- Lack of Display implementation impacted only rust/kernel/kunit.rs. In this change, we use Debug format there. The only difference between the removed Display output and Debug output are quotation marks present in the latter (foo vs "foo").
- It does not provide from_bytes_with_nul_unchecked_mut method.
- It was used only in DerefMut implementation for CString. This change removes that implementation.
- Otherwise, having such a method is not desirable. The rule in Rust std is that str is used only as an immutable reference (&str), while mutating strings is done with the owned String type. Similarly, we can introduce the rule that CStr should be used only as an immutable reference (&CStr), while mutating is done only with the owned CString type.
- It has as_ptr() method instead of as_char_ptr(), which also returns *const c_char.
---
v1 -> v2:
- Do not remove c_str macro. While it's preferred to use C-string literals, there are two cases where c_str is helpful:
- When working with macros, which already return a Rust string literal
(e.g. `stringify!`).
- When building macros, where we want to take a Rust string literal as an argument (for caller's convenience), but still use it as a C-string internally.
- Use Rust literals as arguments in macros (new_mutex, new_condvar, new_mutex). Use the c_str macro to convert these literals to C-string literals.
- Use c_str in kunit.rs for converting the output of stringify! to a CStr.
- Remove DerefMut implementation for CString.
v2 -> v3:
- Fix the commit message.
- Remove redundant braces in use, when only one item is imported.
rust/kernel/error.rs | 7 +- rust/kernel/kunit.rs | 12 +- rust/kernel/net/phy.rs | 2 +- rust/kernel/prelude.rs | 4 +- rust/kernel/str.rs | 486 ++---------------------------------- rust/kernel/sync/condvar.rs | 5 +- rust/kernel/sync/lock.rs | 6 +- rust/kernel/workqueue.rs | 2 +- scripts/rustdoc_test_gen.rs | 4 +- 9 files changed, 44 insertions(+), 484 deletions(-)
rust/kernel/error.rs +4 -3
@@ -4,10 +4,11 @@//! //! C header: [`include/uapi/asm-generic/errno-base.h`](srctree/include/uapi/asm-generic/errno-base.h) -use crate ::{alloc::AllocError , str::CStr }; +use crate ::alloc::AllocError ;use alloc::alloc::LayoutError ; +use core::ffi::CStr ;use core::fmt;use core::num::TryFromIntError ;use core::str::Utf8Error ;
@@ -142,7 +143,7 @@ pub fn name(&self) -> Option<&'static CStr> {None }else {// SAFETY: The string returned by `errname` is static and `NUL`-terminated. -Some (unsafe {CStr ::from_char_ptr (ptr) }) +Some (unsafe {CStr ::from_ptr (ptr) }) } }
@@ -164,7 +165,7 @@ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { None => f.debug_tuple("Error").field(&-self.0).finish(),// SAFETY: These strings are ASCII-only. Some(name) => f - .debug_tuple (unsafe { core::str::from_utf8_unchecked (name) }) + .debug_tuple (unsafe { core::str::from_utf8_unchecked (name.to_bytes ()) }) .finish(), } }
rust/kernel/kunit.rs +6 -6
@@ -56,9 +56,9 @@ macro_rules! kunit_assert {break 'out; } -static FILE : &'static $crate::str::CStr = $crate::c_str!($file); +static FILE : &'static core::ffi::CStr = $file;static LINE :i32 = core::line!()as i32 - $diff; -static CONDITION : &'static $crate::str::CStr = $crate::c_str!(stringify! ($condition)); +static CONDITION : &'static core::ffi::CStr = $crate::c_str!(stringify! ($condition));// SAFETY: FFI call without safety requirements. let kunit_test =unsafe { $crate::bindings::kunit_get_current_test () };
@@ -71,11 +71,11 @@ macro_rules! kunit_assert {// // This mimics KUnit's failed assertion format. $crate::kunit::err (format_args! ( -" # {}: ASSERTION FAILED at {FILE}:{LINE}\n" , +" # {:?}: ASSERTION FAILED at {FILE:?}:{LINE:?}\n" , $name )); $crate::kunit::err (format_args! ( -" Expected {CONDITION} to be true, but is false\n" +" Expected {CONDITION:?} to be true, but is false\n" )); $crate::kunit::err(format_args!( " Failure not reported to KUnit since this is a non-KUnit task\n"
@@ -98,12 +98,12 @@ unsafe impl Sync for Location {}unsafe impl Sync for UnaryAssert {}static LOCATION :Location =Location ($crate::bindings::kunit_loc { - file:FILE .as_char_ptr (), + file:FILE .as_ptr (), line:LINE , });static ASSERTION :UnaryAssert =UnaryAssert ($crate::bindings::kunit_unary_assert { assert: $crate::bindings::kunit_assert {}, - condition:CONDITION .as_char_ptr (), + condition:CONDITION .as_ptr (), expected_true:true , });
rust/kernel/net/phy.rs +1 -1
@@ -502,7 +502,7 @@ unsafe impl Sync for DriverVTable {}pub const fn create_phy_driver <T :Driver >() ->DriverVTable {// INVARIANT: All the fields of `struct phy_driver` are initialized properly. DriverVTable(Opaque::new(bindings::phy_driver { - name: T::NAME.as_char_ptr().cast_mut(), + name: T::NAME.as_ptr().cast_mut(), flags: T::FLAGS, phy_id: T::PHY_DEVICE_ID.id, phy_id_mask: T::PHY_DEVICE_ID.mask_as_int(),
rust/kernel/prelude.rs +2 -2
@@ -12,7 +12,7 @@//! ``` #[doc(no_inline)] -pub use core::pin::Pin ; +pub use core::{ffi::CStr , pin::Pin };pub use crate ::alloc::{box_ext::BoxExt , flags::*, vec_ext::VecExt };
@@ -35,7 +35,7 @@pub use super ::error::{code::*,Error ,Result }; -pub use super ::{str::CStr ,ThisModule }; +pub use super ::ThisModule ;pub use super ::init::{InPlaceInit ,Init ,PinInit };
rust/kernel/str.rs +23 -463
556 lines not on this page · raw message
rust/kernel/sync/condvar.rs +2 -3
@@ -9,12 +9,11 @@use crate ::{ init::PinInit , pin_init, - str::CStr , task::{MAX_SCHEDULE_TIMEOUT ,TASK_INTERRUPTIBLE ,TASK_NORMAL ,TASK_UNINTERRUPTIBLE }, time::Jiffies , types::Opaque , }; -use core::ffi::{c_int, c_long}; +use core::ffi::{c_int, c_long,CStr };use core::marker::PhantomPinned ;use core::ptr;use macros::pin_data;
@@ -108,7 +107,7 @@ pub fn new(name: &'static CStr, key: &'static LockClassKey) -> impl PinInit<Self// SAFETY: `slot` is valid while the closure is called and both `name` and `key` have // static lifetimes so they live indefinitely. wait_queue_head <-Opaque ::ffi_init (|slot|unsafe { - bindings::__init_waitqueue_head (slot, name.as_char_ptr (), key.as_ptr ()) + bindings::__init_waitqueue_head (slot, name.as_ptr (), key.as_ptr ()) }), }) }
rust/kernel/sync/lock.rs +3 -3
@@ -6,8 +6,8 @@//! spinlocks, raw spinlocks) to be provided with minimal effort. use super ::LockClassKey ; -use crate ::{init::PinInit , pin_init, str::CStr , types::Opaque , types::ScopeGuard }; -use core::{cell::UnsafeCell , marker::PhantomData , marker::PhantomPinned }; +use crate ::{init::PinInit , pin_init, types::Opaque , types::ScopeGuard }; +use core::{cell::UnsafeCell , ffi::CStr , marker::PhantomData , marker::PhantomPinned };use macros::pin_data;pub mod mutex;
@@ -113,7 +113,7 @@ pub fn new(t: T, name: &'static CStr, key: &'static LockClassKey) -> impl PinIni// SAFETY: `slot` is valid while the closure is called and both `name` and `key` have // static lifetimes so they live indefinitely. state <-Opaque ::ffi_init (|slot|unsafe { -B ::init (slot, name.as_char_ptr (), key.as_ptr ()) +B ::init (slot, name.as_ptr (), key.as_ptr ()) }), }) }
rust/kernel/workqueue.rs +1 -1
@@ -380,7 +380,7 @@ pub fn new(name: &'static CStr, key: &'static LockClassKey) -> impl PinInit<Self slot, Some(T::Pointer::run), false, - name.as_char_ptr(), + name.as_ptr(), key.as_ptr(), ) }
scripts/rustdoc_test_gen.rs +2 -2
@@ -172,7 +172,7 @@ pub extern "C" fn {kunit_name}(__kunit_test: *mut kernel::bindings::kunit) {{#[allow(unused)] macro_rules! assert {{ ($cond:expr $(,)?) => {{{{ - kernel::kunit_assert!("{kunit_name}", "{real_path}", __DOCTEST_ANCHOR - {line}, $cond); + kernel::kunit_assert!(c"{kunit_name}", c"{real_path}", __DOCTEST_ANCHOR - {line}, $cond); }}}} }}
@@ -180,7 +180,7 @@ macro_rules! assert {{#[allow(unused)] macro_rules! assert_eq {{ ($left:expr, $right:expr $(,)?) => {{{{ - kernel::kunit_assert_eq!("{kunit_name}", "{real_path}", __DOCTEST_ANCHOR - {line}, $left, $right); + kernel::kunit_assert_eq!(c"{kunit_name}", c"{real_path}", __DOCTEST_ANCHOR - {line}, $left, $right); }}}} }}
Signature · 1 line
2.45.2
Trevor Gross
reviewerQuoted 9 lines · Michal Rostecki
rust/kernel/kunit.rs +0
-0// SAFETY: FFI call without safety requirements. let kunit_test =unsafe { $crate::bindings::kunit_get_current_test () };@@ -71,11 +71,11 @@ macro_rules! kunit_assert {//
rust/kernel/kunit.rs macro_rules! kunit_assert { · line 79
Quoted 10 lines
rust/kernel/kunit.rs +2
-2// This mimics KUnit's failed assertion format. $crate::kunit::err (format_args! ( -" # {}: ASSERTION FAILED at {FILE}:{LINE}\n" , +" # {:?}: ASSERTION FAILED at {FILE:?}:{LINE:?}\n" , $name )); $crate::kunit::err (format_args! ( -" Expected {CONDITION} to be true, but is false\n" +" Expected {CONDITION:?} to be true, but is false\n" ));
These aren't exactly the same: the existing Display impl will print the string (hexifying invalid characters), but this will add " ... " around it.
In Rust's libraries, string Path and OsStr both have a .display() method that returns a wrapper type that does implement fmt::Display, which can then be printed (see [1]). We could do something similar here, via a CStrExt trait that goes in the prelude and provides .display(&self).
Rust itself could actually use something here too - if you're up for it, feel free to propose an implementation via ACP (that's just an issue template at [2]). It would probably be pretty similar to the recent OsStr one. Of course it will be a while before we can use it in the kernel, but it wouldn't hurt to get the ball rolling.
[1]: https://doc.rust-lang.org/std/path/struct.Path.html#method.display
[2]: https://github.com/rust-lang/libs-team/issues
rust/kernel/kunit.rs macro_rules! kunit_assert {
Quoted 13 lines
rust/kernel/kunit.rs +10
-1/// Creates a new [`CStr`] from a string literal. /// -/// The string literal should not contain any `NUL` bytes. +/// Usually, defining C-string literals directly should be preffered, but this +/// macro is helpful in situations when C-string literals are hard or +/// impossible to use, for example: +/// +/// - When working with macros, which already return a Rust string literal +/// (e.g. `stringify!`). +/// - When building macros, where we want to take a Rust string literal as an +/// argument (for caller's convenience), but still use it as a C-string +/// internally. +///
s/preffered/prefered
"when C-string literals are hard or impossible to use" doesn't sound quite right - I think it is more common that you're just hiding an implementation detail (string type) from the user of a macro. Maybe something like:
This isn't needed when C-string literals (c"hello" syntax) can be used directly, but can be used when a C-string version of a standard string literal is required (often when working with macros).
Quoted 10 lines
rust/kernel/kunit.rs +3
-2+/// The string should not contain any `NUL` bytes. /// /// # Examples /// /// ``` +/// # use core::ffi::CStr; /// # use kernel::c_str; -/// # use kernel::str::CStr; -/// const MY_CSTR: &CStr = c_str!("My awesome CStr!"); +/// const MY_CSTR: &CStr = c_str!(stringify!(5));
rust/kernel/kunit.rs
Quoted 10 lines
rust/kernel/kunit.rs +1
-1/// ``` #[macro_export] macro_rules! c_str { ($str:expr) => {{const S : &str =concat! ($str ,"\0" ); -const C : &$crate::str ::CStr =match $crate::str ::CStr ::from_bytes_with_nul (S .as_bytes ()) { +const C : &core::ffi::CStr =match core::ffi::CStr ::from_bytes_with_nul (S .as_bytes ()) {Ok (v) => v,Err (_) =>panic! ("string contains interior NUL" ), };
Thanks for this, will be a nice bit of code cleanup.
- Trevor
(also, v2 and v3 are appearing in different threads on lore (as they should), but they're in the same thread as v1 in my email client - any idea if there is a reason for this?)
Quoted 3 lines · Trevor Gross
(also, v2 and v3 are appearing in different threads on lore (as they should), but they're in the same thread as v1 in my email client - any idea if there is a reason for this?)
No idea, I've sent both patches with:
git send-email --cc-cmd='./scripts/get_maintainer.pl --norolestats' -v${VERSION} -1