From 474be445555ba8f2e776b4b6458c310bc215f76b Mon Sep 17 00:00:00 2001 From: Miguel Ojeda Date: Thu, 10 Nov 2022 17:41:13 +0100 Subject: rust: prelude: split re-exports into groups Split the prelude re-exports into groups: first the ones coming from the `core` crate, then `alloc`, then our own crates and finally the ones from modules from `kernel` itself (i.e. `super`). We are doing this manually for the moment, but ideally, long-term, this could be automated via `rustfmt` with options such as `group_imports` and `imports_granularity` (both currently unstable). Reviewed-by: Boqun Feng Reviewed-by: Wei Liu Signed-off-by: Miguel Ojeda --- rust/kernel/prelude.rs | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) (limited to 'rust') diff --git a/rust/kernel/prelude.rs b/rust/kernel/prelude.rs index 495e22250726..f8219285d8c0 100644 --- a/rust/kernel/prelude.rs +++ b/rust/kernel/prelude.rs @@ -11,10 +11,14 @@ //! use kernel::prelude::*; //! ``` -pub use super::{ - error::{Error, Result}, - pr_emerg, pr_info, ThisModule, -}; -pub use alloc::{boxed::Box, vec::Vec}; pub use core::pin::Pin; + +pub use alloc::{boxed::Box, vec::Vec}; + pub use macros::module; + +pub use super::{pr_emerg, pr_info}; + +pub use super::error::{Error, Result}; + +pub use super::ThisModule; -- cgit v1.2.3 From 4c7f949906ae2ceb31d71fb235975f1bfa1adb21 Mon Sep 17 00:00:00 2001 From: Miguel Ojeda Date: Thu, 10 Nov 2022 17:41:14 +0100 Subject: rust: print: add more `pr_*!` levels Currently, only `pr_info!` (for the minimal sample) and `pr_emerg!` (for the panic handler) are there. Add the other levels as new macros, i.e. `pr_alert!`, `pr_crit!`, `pr_err!`, `pr_warn!`, `pr_notice!` and `pr_debug!`. Co-developed-by: Adam Bratschi-Kaye Signed-off-by: Adam Bratschi-Kaye Co-developed-by: Wedson Almeida Filho Signed-off-by: Wedson Almeida Filho Co-developed-by: Gary Guo Signed-off-by: Gary Guo Reviewed-by: Boqun Feng Reviewed-by: Wei Liu Reviewed-by: Sergio Gonzalez Collado Signed-off-by: Miguel Ojeda --- rust/kernel/prelude.rs | 2 +- rust/kernel/print.rs | 154 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 155 insertions(+), 1 deletion(-) (limited to 'rust') diff --git a/rust/kernel/prelude.rs b/rust/kernel/prelude.rs index f8219285d8c0..6a1c6b38327f 100644 --- a/rust/kernel/prelude.rs +++ b/rust/kernel/prelude.rs @@ -17,7 +17,7 @@ pub use alloc::{boxed::Box, vec::Vec}; pub use macros::module; -pub use super::{pr_emerg, pr_info}; +pub use super::{pr_alert, pr_crit, pr_debug, pr_emerg, pr_err, pr_info, pr_notice, pr_warn}; pub use super::error::{Error, Result}; diff --git a/rust/kernel/print.rs b/rust/kernel/print.rs index 55db5a1ba752..694f51c6da5c 100644 --- a/rust/kernel/print.rs +++ b/rust/kernel/print.rs @@ -74,7 +74,13 @@ pub mod format_strings { // Furthermore, `static` instead of `const` is used to share the strings // for all the kernel. pub static EMERG: [u8; LENGTH] = generate(false, bindings::KERN_EMERG); + pub static ALERT: [u8; LENGTH] = generate(false, bindings::KERN_ALERT); + pub static CRIT: [u8; LENGTH] = generate(false, bindings::KERN_CRIT); + pub static ERR: [u8; LENGTH] = generate(false, bindings::KERN_ERR); + pub static WARNING: [u8; LENGTH] = generate(false, bindings::KERN_WARNING); + pub static NOTICE: [u8; LENGTH] = generate(false, bindings::KERN_NOTICE); pub static INFO: [u8; LENGTH] = generate(false, bindings::KERN_INFO); + pub static DEBUG: [u8; LENGTH] = generate(false, bindings::KERN_DEBUG); } /// Prints a message via the kernel's [`_printk`]. @@ -172,6 +178,126 @@ macro_rules! pr_emerg ( ) ); +/// Prints an alert-level message (level 1). +/// +/// Use this level if action must be taken immediately. +/// +/// Equivalent to the kernel's [`pr_alert`] macro. +/// +/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and +/// `alloc::format!` for information about the formatting syntax. +/// +/// [`pr_alert`]: https://www.kernel.org/doc/html/latest/core-api/printk-basics.html#c.pr_alert +/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html +/// +/// # Examples +/// +/// ``` +/// pr_alert!("hello {}\n", "there"); +/// ``` +#[macro_export] +macro_rules! pr_alert ( + ($($arg:tt)*) => ( + $crate::print_macro!($crate::print::format_strings::ALERT, $($arg)*) + ) +); + +/// Prints a critical-level message (level 2). +/// +/// Use this level for critical conditions. +/// +/// Equivalent to the kernel's [`pr_crit`] macro. +/// +/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and +/// `alloc::format!` for information about the formatting syntax. +/// +/// [`pr_crit`]: https://www.kernel.org/doc/html/latest/core-api/printk-basics.html#c.pr_crit +/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html +/// +/// # Examples +/// +/// ``` +/// pr_crit!("hello {}\n", "there"); +/// ``` +#[macro_export] +macro_rules! pr_crit ( + ($($arg:tt)*) => ( + $crate::print_macro!($crate::print::format_strings::CRIT, $($arg)*) + ) +); + +/// Prints an error-level message (level 3). +/// +/// Use this level for error conditions. +/// +/// Equivalent to the kernel's [`pr_err`] macro. +/// +/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and +/// `alloc::format!` for information about the formatting syntax. +/// +/// [`pr_err`]: https://www.kernel.org/doc/html/latest/core-api/printk-basics.html#c.pr_err +/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html +/// +/// # Examples +/// +/// ``` +/// pr_err!("hello {}\n", "there"); +/// ``` +#[macro_export] +macro_rules! pr_err ( + ($($arg:tt)*) => ( + $crate::print_macro!($crate::print::format_strings::ERR, $($arg)*) + ) +); + +/// Prints a warning-level message (level 4). +/// +/// Use this level for warning conditions. +/// +/// Equivalent to the kernel's [`pr_warn`] macro. +/// +/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and +/// `alloc::format!` for information about the formatting syntax. +/// +/// [`pr_warn`]: https://www.kernel.org/doc/html/latest/core-api/printk-basics.html#c.pr_warn +/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html +/// +/// # Examples +/// +/// ``` +/// pr_warn!("hello {}\n", "there"); +/// ``` +#[macro_export] +macro_rules! pr_warn ( + ($($arg:tt)*) => ( + $crate::print_macro!($crate::print::format_strings::WARNING, $($arg)*) + ) +); + +/// Prints a notice-level message (level 5). +/// +/// Use this level for normal but significant conditions. +/// +/// Equivalent to the kernel's [`pr_notice`] macro. +/// +/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and +/// `alloc::format!` for information about the formatting syntax. +/// +/// [`pr_notice`]: https://www.kernel.org/doc/html/latest/core-api/printk-basics.html#c.pr_notice +/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html +/// +/// # Examples +/// +/// ``` +/// pr_notice!("hello {}\n", "there"); +/// ``` +#[macro_export] +macro_rules! pr_notice ( + ($($arg:tt)*) => ( + $crate::print_macro!($crate::print::format_strings::NOTICE, $($arg)*) + ) +); + /// Prints an info-level message (level 6). /// /// Use this level for informational messages. @@ -196,3 +322,31 @@ macro_rules! pr_info ( $crate::print_macro!($crate::print::format_strings::INFO, $($arg)*) ) ); + +/// Prints a debug-level message (level 7). +/// +/// Use this level for debug messages. +/// +/// Equivalent to the kernel's [`pr_debug`] macro, except that it doesn't support dynamic debug +/// yet. +/// +/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and +/// `alloc::format!` for information about the formatting syntax. +/// +/// [`pr_debug`]: https://www.kernel.org/doc/html/latest/core-api/printk-basics.html#c.pr_debug +/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html +/// +/// # Examples +/// +/// ``` +/// pr_debug!("hello {}\n", "there"); +/// ``` +#[macro_export] +#[doc(alias = "print")] +macro_rules! pr_debug ( + ($($arg:tt)*) => ( + if cfg!(debug_assertions) { + $crate::print_macro!($crate::print::format_strings::DEBUG, $($arg)*) + } + ) +); -- cgit v1.2.3 From fc6c7cac83f05f455be1f35160a618e9df103838 Mon Sep 17 00:00:00 2001 From: Miguel Ojeda Date: Thu, 10 Nov 2022 17:41:15 +0100 Subject: rust: print: add `pr_cont!` macro MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This level is a bit different from the rest since it does not pass the module name to the `_printk()` call. Thus add a new parameter to the general `print_macro!` to handle it differently. Co-developed-by: Adam Bratschi-Kaye Signed-off-by: Adam Bratschi-Kaye Co-developed-by: Wedson Almeida Filho Signed-off-by: Wedson Almeida Filho Co-developed-by: Gary Guo Signed-off-by: Gary Guo Reviewed-by: Wei Liu Reviewed-by: Sergio González Collado Signed-off-by: Miguel Ojeda --- rust/kernel/print.rs | 72 +++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 63 insertions(+), 9 deletions(-) (limited to 'rust') diff --git a/rust/kernel/print.rs b/rust/kernel/print.rs index 694f51c6da5c..29bf9c2e8aee 100644 --- a/rust/kernel/print.rs +++ b/rust/kernel/print.rs @@ -81,6 +81,7 @@ pub mod format_strings { pub static NOTICE: [u8; LENGTH] = generate(false, bindings::KERN_NOTICE); pub static INFO: [u8; LENGTH] = generate(false, bindings::KERN_INFO); pub static DEBUG: [u8; LENGTH] = generate(false, bindings::KERN_DEBUG); + pub static CONT: [u8; LENGTH] = generate(true, bindings::KERN_CONT); } /// Prints a message via the kernel's [`_printk`]. @@ -111,6 +112,26 @@ pub unsafe fn call_printk( } } +/// Prints a message via the kernel's [`_printk`] for the `CONT` level. +/// +/// Public but hidden since it should only be used from public macros. +/// +/// [`_printk`]: ../../../../include/linux/printk.h +#[doc(hidden)] +#[cfg_attr(not(CONFIG_PRINTK), allow(unused_variables))] +pub fn call_printk_cont(args: fmt::Arguments<'_>) { + // `_printk` does not seem to fail in any path. + // + // SAFETY: The format string is fixed. + #[cfg(CONFIG_PRINTK)] + unsafe { + bindings::_printk( + format_strings::CONT.as_ptr() as _, + &args as *const _ as *const c_void, + ); + } +} + /// Performs formatting and forwards the string to [`call_printk`]. /// /// Public but hidden since it should only be used from public macros. @@ -120,7 +141,7 @@ pub unsafe fn call_printk( #[allow(clippy::crate_in_macro_def)] macro_rules! print_macro ( // The non-continuation cases (most of them, e.g. `INFO`). - ($format_string:path, $($arg:tt)+) => ( + ($format_string:path, false, $($arg:tt)+) => ( // SAFETY: This hidden macro should only be called by the documented // printing macros which ensure the format string is one of the fixed // ones. All `__LOG_PREFIX`s are null-terminated as they are generated @@ -134,6 +155,13 @@ macro_rules! print_macro ( ); } ); + + // The `CONT` case. + ($format_string:path, true, $($arg:tt)+) => ( + $crate::print::call_printk_cont( + format_args!($($arg)+), + ); + ); ); /// Stub for doctests @@ -174,7 +202,7 @@ macro_rules! print_macro ( #[macro_export] macro_rules! pr_emerg ( ($($arg:tt)*) => ( - $crate::print_macro!($crate::print::format_strings::EMERG, $($arg)*) + $crate::print_macro!($crate::print::format_strings::EMERG, false, $($arg)*) ) ); @@ -198,7 +226,7 @@ macro_rules! pr_emerg ( #[macro_export] macro_rules! pr_alert ( ($($arg:tt)*) => ( - $crate::print_macro!($crate::print::format_strings::ALERT, $($arg)*) + $crate::print_macro!($crate::print::format_strings::ALERT, false, $($arg)*) ) ); @@ -222,7 +250,7 @@ macro_rules! pr_alert ( #[macro_export] macro_rules! pr_crit ( ($($arg:tt)*) => ( - $crate::print_macro!($crate::print::format_strings::CRIT, $($arg)*) + $crate::print_macro!($crate::print::format_strings::CRIT, false, $($arg)*) ) ); @@ -246,7 +274,7 @@ macro_rules! pr_crit ( #[macro_export] macro_rules! pr_err ( ($($arg:tt)*) => ( - $crate::print_macro!($crate::print::format_strings::ERR, $($arg)*) + $crate::print_macro!($crate::print::format_strings::ERR, false, $($arg)*) ) ); @@ -270,7 +298,7 @@ macro_rules! pr_err ( #[macro_export] macro_rules! pr_warn ( ($($arg:tt)*) => ( - $crate::print_macro!($crate::print::format_strings::WARNING, $($arg)*) + $crate::print_macro!($crate::print::format_strings::WARNING, false, $($arg)*) ) ); @@ -294,7 +322,7 @@ macro_rules! pr_warn ( #[macro_export] macro_rules! pr_notice ( ($($arg:tt)*) => ( - $crate::print_macro!($crate::print::format_strings::NOTICE, $($arg)*) + $crate::print_macro!($crate::print::format_strings::NOTICE, false, $($arg)*) ) ); @@ -319,7 +347,7 @@ macro_rules! pr_notice ( #[doc(alias = "print")] macro_rules! pr_info ( ($($arg:tt)*) => ( - $crate::print_macro!($crate::print::format_strings::INFO, $($arg)*) + $crate::print_macro!($crate::print::format_strings::INFO, false, $($arg)*) ) ); @@ -346,7 +374,33 @@ macro_rules! pr_info ( macro_rules! pr_debug ( ($($arg:tt)*) => ( if cfg!(debug_assertions) { - $crate::print_macro!($crate::print::format_strings::DEBUG, $($arg)*) + $crate::print_macro!($crate::print::format_strings::DEBUG, false, $($arg)*) } ) ); + +/// Continues a previous log message in the same line. +/// +/// Use only when continuing a previous `pr_*!` macro (e.g. [`pr_info!`]). +/// +/// Equivalent to the kernel's [`pr_cont`] macro. +/// +/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and +/// `alloc::format!` for information about the formatting syntax. +/// +/// [`pr_cont`]: https://www.kernel.org/doc/html/latest/core-api/printk-basics.html#c.pr_cont +/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html +/// +/// # Examples +/// +/// ``` +/// # use kernel::pr_cont; +/// pr_info!("hello"); +/// pr_cont!(" {}\n", "there"); +/// ``` +#[macro_export] +macro_rules! pr_cont ( + ($($arg:tt)*) => ( + $crate::print_macro!($crate::print::format_strings::CONT, true, $($arg)*) + ) +); -- cgit v1.2.3 From 60f18c225f5f6939e348c4b067711d10afd33151 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Roy=20Baron?= Date: Thu, 10 Nov 2022 17:41:17 +0100 Subject: rust: macros: add `concat_idents!` proc macro MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This macro provides similar functionality to the unstable feature `concat_idents` without having to rely on it. For instance: let x_1 = 42; let x_2 = concat_idents!(x, _1); assert!(x_1 == x_2); It has different behavior with respect to macro hygiene. Unlike the unstable `concat_idents!` macro, it allows, for example, referring to local variables by taking the span of the second macro as span for the output identifier. Signed-off-by: Björn Roy Baron Reviewed-by: Finn Behrens Reviewed-by: Gary Guo [Reworded, adapted for upstream and applied latest changes] Signed-off-by: Miguel Ojeda --- rust/macros/concat_idents.rs | 23 +++++++++++++++++++++++ rust/macros/lib.rs | 44 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+) create mode 100644 rust/macros/concat_idents.rs (limited to 'rust') diff --git a/rust/macros/concat_idents.rs b/rust/macros/concat_idents.rs new file mode 100644 index 000000000000..7e4b450f3a50 --- /dev/null +++ b/rust/macros/concat_idents.rs @@ -0,0 +1,23 @@ +// SPDX-License-Identifier: GPL-2.0 + +use proc_macro::{token_stream, Ident, TokenStream, TokenTree}; + +use crate::helpers::expect_punct; + +fn expect_ident(it: &mut token_stream::IntoIter) -> Ident { + if let Some(TokenTree::Ident(ident)) = it.next() { + ident + } else { + panic!("Expected Ident") + } +} + +pub(crate) fn concat_idents(ts: TokenStream) -> TokenStream { + let mut it = ts.into_iter(); + let a = expect_ident(&mut it); + assert_eq!(expect_punct(&mut it), ','); + let b = expect_ident(&mut it); + assert!(it.next().is_none(), "only two idents can be concatenated"); + let res = Ident::new(&format!("{a}{b}"), b.span()); + TokenStream::from_iter([TokenTree::Ident(res)]) +} diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs index 91764bfb1f89..15555e7ff487 100644 --- a/rust/macros/lib.rs +++ b/rust/macros/lib.rs @@ -2,6 +2,7 @@ //! Crate for all kernel procedural macros. +mod concat_idents; mod helpers; mod module; @@ -70,3 +71,46 @@ use proc_macro::TokenStream; pub fn module(ts: TokenStream) -> TokenStream { module::module(ts) } + +/// Concatenate two identifiers. +/// +/// This is useful in macros that need to declare or reference items with names +/// starting with a fixed prefix and ending in a user specified name. The resulting +/// identifier has the span of the second argument. +/// +/// # Examples +/// +/// ```ignore +/// use kernel::macro::concat_idents; +/// +/// macro_rules! pub_no_prefix { +/// ($prefix:ident, $($newname:ident),+) => { +/// $(pub(crate) const $newname: u32 = kernel::macros::concat_idents!($prefix, $newname);)+ +/// }; +/// } +/// +/// pub_no_prefix!( +/// binder_driver_return_protocol_, +/// BR_OK, +/// BR_ERROR, +/// BR_TRANSACTION, +/// BR_REPLY, +/// BR_DEAD_REPLY, +/// BR_TRANSACTION_COMPLETE, +/// BR_INCREFS, +/// BR_ACQUIRE, +/// BR_RELEASE, +/// BR_DECREFS, +/// BR_NOOP, +/// BR_SPAWN_LOOPER, +/// BR_DEAD_BINDER, +/// BR_CLEAR_DEATH_NOTIFICATION_DONE, +/// BR_FAILED_REPLY +/// ); +/// +/// assert_eq!(BR_OK, binder_driver_return_protocol_BR_OK); +/// ``` +#[proc_macro] +pub fn concat_idents(ts: TokenStream) -> TokenStream { + concat_idents::concat_idents(ts) +} -- cgit v1.2.3 From b44becc5ee808e02bbda0f90ee0584f206693a33 Mon Sep 17 00:00:00 2001 From: Gary Guo Date: Thu, 10 Nov 2022 17:41:18 +0100 Subject: rust: macros: add `#[vtable]` proc macro MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This procedural macro attribute provides a simple way to declare a trait with a set of operations that later users can partially implement, providing compile-time `HAS_*` boolean associated constants that indicate whether a particular operation was overridden. This is useful as the Rust counterpart to structs like `file_operations` where some pointers may be `NULL`, indicating an operation is not provided. For instance: #[vtable] trait Operations { fn read(...) -> Result { Err(EINVAL) } fn write(...) -> Result { Err(EINVAL) } } #[vtable] impl Operations for S { fn read(...) -> Result { ... } } assert_eq!(::HAS_READ, true); assert_eq!(::HAS_WRITE, false); Signed-off-by: Gary Guo Reviewed-by: Sergio González Collado [Reworded, adapted for upstream and applied latest changes] Signed-off-by: Miguel Ojeda --- rust/kernel/prelude.rs | 2 +- rust/macros/lib.rs | 52 +++++++++++++++++++++++++++ rust/macros/vtable.rs | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 148 insertions(+), 1 deletion(-) create mode 100644 rust/macros/vtable.rs (limited to 'rust') diff --git a/rust/kernel/prelude.rs b/rust/kernel/prelude.rs index 6a1c6b38327f..7c4c35bf3c66 100644 --- a/rust/kernel/prelude.rs +++ b/rust/kernel/prelude.rs @@ -15,7 +15,7 @@ pub use core::pin::Pin; pub use alloc::{boxed::Box, vec::Vec}; -pub use macros::module; +pub use macros::{module, vtable}; pub use super::{pr_alert, pr_crit, pr_debug, pr_emerg, pr_err, pr_info, pr_notice, pr_warn}; diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs index 15555e7ff487..e40caaf0a656 100644 --- a/rust/macros/lib.rs +++ b/rust/macros/lib.rs @@ -5,6 +5,7 @@ mod concat_idents; mod helpers; mod module; +mod vtable; use proc_macro::TokenStream; @@ -72,6 +73,57 @@ pub fn module(ts: TokenStream) -> TokenStream { module::module(ts) } +/// Declares or implements a vtable trait. +/// +/// Linux's use of pure vtables is very close to Rust traits, but they differ +/// in how unimplemented functions are represented. In Rust, traits can provide +/// default implementation for all non-required methods (and the default +/// implementation could just return `Error::EINVAL`); Linux typically use C +/// `NULL` pointers to represent these functions. +/// +/// This attribute is intended to close the gap. Traits can be declared and +/// implemented with the `#[vtable]` attribute, and a `HAS_*` associated constant +/// will be generated for each method in the trait, indicating if the implementor +/// has overridden a method. +/// +/// This attribute is not needed if all methods are required. +/// +/// # Examples +/// +/// ```ignore +/// use kernel::prelude::*; +/// +/// // Declares a `#[vtable]` trait +/// #[vtable] +/// pub trait Operations: Send + Sync + Sized { +/// fn foo(&self) -> Result<()> { +/// Err(EINVAL) +/// } +/// +/// fn bar(&self) -> Result<()> { +/// Err(EINVAL) +/// } +/// } +/// +/// struct Foo; +/// +/// // Implements the `#[vtable]` trait +/// #[vtable] +/// impl Operations for Foo { +/// fn foo(&self) -> Result<()> { +/// # Err(EINVAL) +/// // ... +/// } +/// } +/// +/// assert_eq!(::HAS_FOO, true); +/// assert_eq!(::HAS_BAR, false); +/// ``` +#[proc_macro_attribute] +pub fn vtable(attr: TokenStream, ts: TokenStream) -> TokenStream { + vtable::vtable(attr, ts) +} + /// Concatenate two identifiers. /// /// This is useful in macros that need to declare or reference items with names diff --git a/rust/macros/vtable.rs b/rust/macros/vtable.rs new file mode 100644 index 000000000000..34d5e7fb5768 --- /dev/null +++ b/rust/macros/vtable.rs @@ -0,0 +1,95 @@ +// SPDX-License-Identifier: GPL-2.0 + +use proc_macro::{Delimiter, Group, TokenStream, TokenTree}; +use std::collections::HashSet; +use std::fmt::Write; + +pub(crate) fn vtable(_attr: TokenStream, ts: TokenStream) -> TokenStream { + let mut tokens: Vec<_> = ts.into_iter().collect(); + + // Scan for the `trait` or `impl` keyword. + let is_trait = tokens + .iter() + .find_map(|token| match token { + TokenTree::Ident(ident) => match ident.to_string().as_str() { + "trait" => Some(true), + "impl" => Some(false), + _ => None, + }, + _ => None, + }) + .expect("#[vtable] attribute should only be applied to trait or impl block"); + + // Retrieve the main body. The main body should be the last token tree. + let body = match tokens.pop() { + Some(TokenTree::Group(group)) if group.delimiter() == Delimiter::Brace => group, + _ => panic!("cannot locate main body of trait or impl block"), + }; + + let mut body_it = body.stream().into_iter(); + let mut functions = Vec::new(); + let mut consts = HashSet::new(); + while let Some(token) = body_it.next() { + match token { + TokenTree::Ident(ident) if ident.to_string() == "fn" => { + let fn_name = match body_it.next() { + Some(TokenTree::Ident(ident)) => ident.to_string(), + // Possibly we've encountered a fn pointer type instead. + _ => continue, + }; + functions.push(fn_name); + } + TokenTree::Ident(ident) if ident.to_string() == "const" => { + let const_name = match body_it.next() { + Some(TokenTree::Ident(ident)) => ident.to_string(), + // Possibly we've encountered an inline const block instead. + _ => continue, + }; + consts.insert(const_name); + } + _ => (), + } + } + + let mut const_items; + if is_trait { + const_items = " + /// A marker to prevent implementors from forgetting to use [`#[vtable]`](vtable) + /// attribute when implementing this trait. + const USE_VTABLE_ATTR: (); + " + .to_owned(); + + for f in functions { + let gen_const_name = format!("HAS_{}", f.to_uppercase()); + // Skip if it's declared already -- this allows user override. + if consts.contains(&gen_const_name) { + continue; + } + // We don't know on the implementation-site whether a method is required or provided + // so we have to generate a const for all methods. + write!( + const_items, + "/// Indicates if the `{f}` method is overridden by the implementor. + const {gen_const_name}: bool = false;", + ) + .unwrap(); + } + } else { + const_items = "const USE_VTABLE_ATTR: () = ();".to_owned(); + + for f in functions { + let gen_const_name = format!("HAS_{}", f.to_uppercase()); + if consts.contains(&gen_const_name) { + continue; + } + write!(const_items, "const {gen_const_name}: bool = true;").unwrap(); + } + } + + let new_body = vec![const_items.parse().unwrap(), body.stream()] + .into_iter() + .collect(); + tokens.push(TokenTree::Group(Group::new(Delimiter::Brace, new_body))); + tokens.into_iter().collect() +} -- cgit v1.2.3 From b13c9880f909ca5e406d9b3d061359fd8fb0c514 Mon Sep 17 00:00:00 2001 From: Gary Guo Date: Thu, 10 Nov 2022 17:41:19 +0100 Subject: rust: macros: take string literals in `module!` Instead of taking binary string literals, take string ones instead, making it easier for users to define a module, i.e. instead of calling `module!` like: module! { ... name: b"rust_minimal", ... } now it is called as: module! { ... name: "rust_minimal", ... } Module names, aliases and license strings are restricted to ASCII only. However, the author and the description allows UTF-8. For simplicity (avoid parsing), escape sequences and raw string literals are not yet handled. Link: https://github.com/Rust-for-Linux/linux/issues/252 Link: https://lore.kernel.org/lkml/YukvvPOOu8uZl7+n@yadro.com/ Signed-off-by: Gary Guo [Reworded, adapted for upstream and applied latest changes] Signed-off-by: Miguel Ojeda --- rust/macros/helpers.rs | 24 ++++++++++++++++++------ rust/macros/lib.rs | 12 ++++++------ rust/macros/module.rs | 10 +++++----- 3 files changed, 29 insertions(+), 17 deletions(-) (limited to 'rust') diff --git a/rust/macros/helpers.rs b/rust/macros/helpers.rs index cdc7dc6135d2..cf7ad950dc1e 100644 --- a/rust/macros/helpers.rs +++ b/rust/macros/helpers.rs @@ -18,10 +18,16 @@ pub(crate) fn try_literal(it: &mut token_stream::IntoIter) -> Option { } } -pub(crate) fn try_byte_string(it: &mut token_stream::IntoIter) -> Option { - try_literal(it).and_then(|byte_string| { - if byte_string.starts_with("b\"") && byte_string.ends_with('\"') { - Some(byte_string[2..byte_string.len() - 1].to_string()) +pub(crate) fn try_string(it: &mut token_stream::IntoIter) -> Option { + try_literal(it).and_then(|string| { + if string.starts_with('\"') && string.ends_with('\"') { + let content = &string[1..string.len() - 1]; + if content.contains('\\') { + panic!("Escape sequences in string literals not yet handled"); + } + Some(content.to_string()) + } else if string.starts_with("r\"") { + panic!("Raw string literals are not yet handled"); } else { None } @@ -40,8 +46,14 @@ pub(crate) fn expect_punct(it: &mut token_stream::IntoIter) -> char { } } -pub(crate) fn expect_byte_string(it: &mut token_stream::IntoIter) -> String { - try_byte_string(it).expect("Expected byte string") +pub(crate) fn expect_string(it: &mut token_stream::IntoIter) -> String { + try_string(it).expect("Expected string") +} + +pub(crate) fn expect_string_ascii(it: &mut token_stream::IntoIter) -> String { + let string = try_string(it).expect("Expected string"); + assert!(string.is_ascii(), "Expected ASCII string"); + string } pub(crate) fn expect_end(it: &mut token_stream::IntoIter) { diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs index e40caaf0a656..c1d385e345b9 100644 --- a/rust/macros/lib.rs +++ b/rust/macros/lib.rs @@ -25,20 +25,20 @@ use proc_macro::TokenStream; /// /// module!{ /// type: MyModule, -/// name: b"my_kernel_module", -/// author: b"Rust for Linux Contributors", -/// description: b"My very own kernel module!", -/// license: b"GPL", +/// name: "my_kernel_module", +/// author: "Rust for Linux Contributors", +/// description: "My very own kernel module!", +/// license: "GPL", /// params: { /// my_i32: i32 { /// default: 42, /// permissions: 0o000, -/// description: b"Example of i32", +/// description: "Example of i32", /// }, /// writeable_i32: i32 { /// default: 42, /// permissions: 0o644, -/// description: b"Example of i32", +/// description: "Example of i32", /// }, /// }, /// } diff --git a/rust/macros/module.rs b/rust/macros/module.rs index 186a5b8be23c..a7e363c2b044 100644 --- a/rust/macros/module.rs +++ b/rust/macros/module.rs @@ -108,11 +108,11 @@ impl ModuleInfo { match key.as_str() { "type" => info.type_ = expect_ident(it), - "name" => info.name = expect_byte_string(it), - "author" => info.author = Some(expect_byte_string(it)), - "description" => info.description = Some(expect_byte_string(it)), - "license" => info.license = expect_byte_string(it), - "alias" => info.alias = Some(expect_byte_string(it)), + "name" => info.name = expect_string_ascii(it), + "author" => info.author = Some(expect_string(it)), + "description" => info.description = Some(expect_string(it)), + "license" => info.license = expect_string_ascii(it), + "alias" => info.alias = Some(expect_string_ascii(it)), _ => panic!( "Unknown key \"{}\". Valid keys are: {:?}.", key, EXPECTED_KEYS -- cgit v1.2.3 From 4b0c68bd0d8b0e23ab1763d4a6632720dd3f1a83 Mon Sep 17 00:00:00 2001 From: Finn Behrens Date: Thu, 10 Nov 2022 17:41:20 +0100 Subject: rust: error: declare errors using macro Add a macro to declare errors, which simplifies the work needed to add each one, avoids repetition of the code and makes it easier to change the way they are declared. Signed-off-by: Finn Behrens Reviewed-by: Gary Guo [Reworded, adapted for upstream and applied latest changes] Signed-off-by: Miguel Ojeda --- rust/kernel/error.rs | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) (limited to 'rust') diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs index 466b2a8fe569..b843f3445483 100644 --- a/rust/kernel/error.rs +++ b/rust/kernel/error.rs @@ -8,8 +8,16 @@ use alloc::collections::TryReserveError; /// Contains the C-compatible error codes. pub mod code { - /// Out of memory. - pub const ENOMEM: super::Error = super::Error(-(crate::bindings::ENOMEM as i32)); + macro_rules! declare_err { + ($err:tt $(,)? $($doc:expr),+) => { + $( + #[doc = $doc] + )* + pub const $err: super::Error = super::Error(-(crate::bindings::$err as i32)); + }; + } + + declare_err!(ENOMEM, "Out of memory."); } /// Generic integer kernel error. -- cgit v1.2.3 From 266def2a0f5bbe44b11902bd4c93b9c5d8b8d708 Mon Sep 17 00:00:00 2001 From: Viktor Garske Date: Thu, 10 Nov 2022 17:41:21 +0100 Subject: rust: error: add codes from `errno-base.h` Only a few codes were added so far. With the `declare_err!` macro in place, add the remaining ones (which is most of them) from `include/uapi/asm-generic/errno-base.h`. Co-developed-by: Wedson Almeida Filho Signed-off-by: Wedson Almeida Filho Signed-off-by: Viktor Garske Reviewed-by: Gary Guo [Reworded, adapted for upstream and applied latest changes] Signed-off-by: Miguel Ojeda --- rust/kernel/error.rs | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) (limited to 'rust') diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs index b843f3445483..861746f2422d 100644 --- a/rust/kernel/error.rs +++ b/rust/kernel/error.rs @@ -17,7 +17,40 @@ pub mod code { }; } + declare_err!(EPERM, "Operation not permitted."); + declare_err!(ENOENT, "No such file or directory."); + declare_err!(ESRCH, "No such process."); + declare_err!(EINTR, "Interrupted system call."); + declare_err!(EIO, "I/O error."); + declare_err!(ENXIO, "No such device or address."); + declare_err!(E2BIG, "Argument list too long."); + declare_err!(ENOEXEC, "Exec format error."); + declare_err!(EBADF, "Bad file number."); + declare_err!(ECHILD, "Exec format error."); + declare_err!(EAGAIN, "Try again."); declare_err!(ENOMEM, "Out of memory."); + declare_err!(EACCES, "Permission denied."); + declare_err!(EFAULT, "Bad address."); + declare_err!(ENOTBLK, "Block device required."); + declare_err!(EBUSY, "Device or resource busy."); + declare_err!(EEXIST, "File exists."); + declare_err!(EXDEV, "Cross-device link."); + declare_err!(ENODEV, "No such device."); + declare_err!(ENOTDIR, "Not a directory."); + declare_err!(EISDIR, "Is a directory."); + declare_err!(EINVAL, "Invalid argument."); + declare_err!(ENFILE, "File table overflow."); + declare_err!(EMFILE, "Too many open files."); + declare_err!(ENOTTY, "Not a typewriter."); + declare_err!(ETXTBSY, "Text file busy."); + declare_err!(EFBIG, "File too large."); + declare_err!(ENOSPC, "No space left on device."); + declare_err!(ESPIPE, "Illegal seek."); + declare_err!(EROFS, "Read-only file system."); + declare_err!(EMLINK, "Too many links."); + declare_err!(EPIPE, "Broken pipe."); + declare_err!(EDOM, "Math argument out of domain of func."); + declare_err!(ERANGE, "Math result not representable."); } /// Generic integer kernel error. -- cgit v1.2.3 From 76e2c2d9a22a402e816607ae575b1a194cc45a31 Mon Sep 17 00:00:00 2001 From: Wedson Almeida Filho Date: Thu, 10 Nov 2022 17:41:22 +0100 Subject: rust: error: add `From` implementations for `Error` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a set of `From` implementations for the `Error` kernel type. These implementations allow to easily convert from standard Rust error types to the usual kernel errors based on one of the `E*` integer codes. On top of that, the question mark Rust operator (`?`) implicitly performs a conversion on the error value using the `From` trait when propagating. Thus it is extra convenient to use. For instance, a kernel function that needs to convert a `i64` into a `i32` and to bubble up the error as a kernel error may write: fn f(x: i64) -> Result<...> { ... let y = i32::try_from(x)?; ... } which will transform the `TryFromIntError` into an `Err(EINVAL)`. Co-developed-by: Adam Bratschi-Kaye Signed-off-by: Adam Bratschi-Kaye Co-developed-by: Nándor István Krácser Signed-off-by: Nándor István Krácser Signed-off-by: Wedson Almeida Filho Reviewed-by: Finn Behrens [Reworded, adapted for upstream and applied latest changes] Signed-off-by: Miguel Ojeda --- rust/kernel/error.rs | 45 ++++++++++++++++++++++++++++++++++++++++++++- rust/kernel/lib.rs | 1 + 2 files changed, 45 insertions(+), 1 deletion(-) (limited to 'rust') diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs index 861746f2422d..5b9751d7ff1d 100644 --- a/rust/kernel/error.rs +++ b/rust/kernel/error.rs @@ -4,7 +4,14 @@ //! //! C header: [`include/uapi/asm-generic/errno-base.h`](../../../include/uapi/asm-generic/errno-base.h) -use alloc::collections::TryReserveError; +use alloc::{ + alloc::{AllocError, LayoutError}, + collections::TryReserveError, +}; + +use core::convert::From; +use core::num::TryFromIntError; +use core::str::Utf8Error; /// Contains the C-compatible error codes. pub mod code { @@ -71,12 +78,48 @@ impl Error { } } +impl From for Error { + fn from(_: AllocError) -> Error { + code::ENOMEM + } +} + +impl From for Error { + fn from(_: TryFromIntError) -> Error { + code::EINVAL + } +} + +impl From for Error { + fn from(_: Utf8Error) -> Error { + code::EINVAL + } +} + impl From for Error { fn from(_: TryReserveError) -> Error { code::ENOMEM } } +impl From for Error { + fn from(_: LayoutError) -> Error { + code::ENOMEM + } +} + +impl From for Error { + fn from(_: core::fmt::Error) -> Error { + code::EINVAL + } +} + +impl From for Error { + fn from(e: core::convert::Infallible) -> Error { + match e {} + } +} + /// A [`Result`] with an [`Error`] error type. /// /// To be used as the return type for functions that may fail. diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs index abd46261d385..ffc6626a6d29 100644 --- a/rust/kernel/lib.rs +++ b/rust/kernel/lib.rs @@ -12,6 +12,7 @@ //! do so first instead of bypassing this crate. #![no_std] +#![feature(allocator_api)] #![feature(core_ffi_c)] // Ensure conditional compilation based on the kernel configuration works; -- cgit v1.2.3 From 25d176a4fad5841de1f85d2a4d69ce87416abc26 Mon Sep 17 00:00:00 2001 From: Wedson Almeida Filho Date: Thu, 10 Nov 2022 17:41:23 +0100 Subject: rust: prelude: add `error::code::*` constant items It is convenient to have all the `Error` constant items (such as `EINVAL`) available as-is everywhere (i.e. for code using the kernel prelude such as kernel modules). Therefore, add all of them to the prelude. For instance, this allows to write `Err(EINVAL)` to create a kernel `Result`: fn f() -> Result<...> { ... Err(EINVAL) } Signed-off-by: Wedson Almeida Filho Reviewed-by: Gary Guo [Reworded, adapted for upstream and applied latest changes] Signed-off-by: Miguel Ojeda --- rust/kernel/prelude.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'rust') diff --git a/rust/kernel/prelude.rs b/rust/kernel/prelude.rs index 7c4c35bf3c66..1e08b08e9420 100644 --- a/rust/kernel/prelude.rs +++ b/rust/kernel/prelude.rs @@ -19,6 +19,6 @@ pub use macros::{module, vtable}; pub use super::{pr_alert, pr_crit, pr_debug, pr_emerg, pr_err, pr_info, pr_notice, pr_warn}; -pub use super::error::{Error, Result}; +pub use super::error::{code::*, Error, Result}; pub use super::ThisModule; -- cgit v1.2.3 From 51d3a25ab3a4f1dd701b17f7340e36de8600e41e Mon Sep 17 00:00:00 2001 From: Miguel Ojeda Date: Thu, 10 Nov 2022 17:41:24 +0100 Subject: rust: alloc: add `RawVec::try_with_capacity_in()` constructor Add the `RawVec::try_with_capacity_in()` constructor as the fallible version of `RawVec::with_capacity_in()`. The implementation follows the original. The infallible constructor is implemented in terms of the private `RawVec::allocate_in()` constructor, thus also add the private `RawVec::try_allocate_in()` constructor following the other. It will be used to implement `Vec::try_with_capacity{,_in}()` in the next patch. Reviewed-by: Gary Guo Signed-off-by: Miguel Ojeda --- rust/alloc/raw_vec.rs | 34 +++++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) (limited to 'rust') diff --git a/rust/alloc/raw_vec.rs b/rust/alloc/raw_vec.rs index daf5f2da7168..c342f3843972 100644 --- a/rust/alloc/raw_vec.rs +++ b/rust/alloc/raw_vec.rs @@ -20,11 +20,11 @@ use crate::collections::TryReserveErrorKind::*; #[cfg(test)] mod tests; -#[cfg(not(no_global_oom_handling))] enum AllocInit { /// The contents of the new memory are uninitialized. Uninitialized, /// The new memory is guaranteed to be zeroed. + #[allow(dead_code)] Zeroed, } @@ -133,6 +133,14 @@ impl RawVec { Self::allocate_in(capacity, AllocInit::Uninitialized, alloc) } + /// Like `try_with_capacity`, but parameterized over the choice of + /// allocator for the returned `RawVec`. + #[allow(dead_code)] + #[inline] + pub fn try_with_capacity_in(capacity: usize, alloc: A) -> Result { + Self::try_allocate_in(capacity, AllocInit::Uninitialized, alloc) + } + /// Like `with_capacity_zeroed`, but parameterized over the choice /// of allocator for the returned `RawVec`. #[cfg(not(no_global_oom_handling))] @@ -203,6 +211,30 @@ impl RawVec { } } + fn try_allocate_in(capacity: usize, init: AllocInit, alloc: A) -> Result { + // Don't allocate here because `Drop` will not deallocate when `capacity` is 0. + if mem::size_of::() == 0 || capacity == 0 { + return Ok(Self::new_in(alloc)); + } + + let layout = Layout::array::(capacity).map_err(|_| CapacityOverflow)?; + alloc_guard(layout.size())?; + let result = match init { + AllocInit::Uninitialized => alloc.allocate(layout), + AllocInit::Zeroed => alloc.allocate_zeroed(layout), + }; + let ptr = result.map_err(|_| AllocError { layout, non_exhaustive: () })?; + + // Allocators currently return a `NonNull<[u8]>` whose length + // matches the size requested. If that ever changes, the capacity + // here should change to `ptr.len() / mem::size_of::()`. + Ok(Self { + ptr: unsafe { Unique::new_unchecked(ptr.cast().as_ptr()) }, + cap: capacity, + alloc, + }) + } + /// Reconstitutes a `RawVec` from a pointer, capacity, and allocator. /// /// # Safety -- cgit v1.2.3 From feadd062871704b1de2111d06008ee24a8f03d02 Mon Sep 17 00:00:00 2001 From: Miguel Ojeda Date: Thu, 10 Nov 2022 17:41:25 +0100 Subject: rust: alloc: add `Vec::try_with_capacity{,_in}()` constructors Add `Vec::try_with_capacity()` and `Vec::try_with_capacity_in()` as the fallible versions of `Vec::with_capacity()` and `Vec::with_capacity_in()`, respectively. The implementations follow the originals and use the previously added `RawVec::try_with_capacity_in()`. In turn, `Vec::try_with_capacity()` will be used to implement the `CString` type (which wraps a `Vec`) in a later patch. Reviewed-by: Gary Guo Signed-off-by: Miguel Ojeda --- rust/alloc/raw_vec.rs | 1 - rust/alloc/vec/mod.rs | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+), 1 deletion(-) (limited to 'rust') diff --git a/rust/alloc/raw_vec.rs b/rust/alloc/raw_vec.rs index c342f3843972..eb77db5def55 100644 --- a/rust/alloc/raw_vec.rs +++ b/rust/alloc/raw_vec.rs @@ -135,7 +135,6 @@ impl RawVec { /// Like `try_with_capacity`, but parameterized over the choice of /// allocator for the returned `RawVec`. - #[allow(dead_code)] #[inline] pub fn try_with_capacity_in(capacity: usize, alloc: A) -> Result { Self::try_allocate_in(capacity, AllocInit::Uninitialized, alloc) diff --git a/rust/alloc/vec/mod.rs b/rust/alloc/vec/mod.rs index 540787804cc2..8ac6c1e3b2a8 100644 --- a/rust/alloc/vec/mod.rs +++ b/rust/alloc/vec/mod.rs @@ -472,6 +472,48 @@ impl Vec { Self::with_capacity_in(capacity, Global) } + /// Tries to construct a new, empty `Vec` with the specified capacity. + /// + /// The vector will be able to hold exactly `capacity` elements without + /// reallocating. If `capacity` is 0, the vector will not allocate. + /// + /// It is important to note that although the returned vector has the + /// *capacity* specified, the vector will have a zero *length*. For an + /// explanation of the difference between length and capacity, see + /// *[Capacity and reallocation]*. + /// + /// [Capacity and reallocation]: #capacity-and-reallocation + /// + /// # Examples + /// + /// ``` + /// let mut vec = Vec::try_with_capacity(10).unwrap(); + /// + /// // The vector contains no items, even though it has capacity for more + /// assert_eq!(vec.len(), 0); + /// assert_eq!(vec.capacity(), 10); + /// + /// // These are all done without reallocating... + /// for i in 0..10 { + /// vec.push(i); + /// } + /// assert_eq!(vec.len(), 10); + /// assert_eq!(vec.capacity(), 10); + /// + /// // ...but this may make the vector reallocate + /// vec.push(11); + /// assert_eq!(vec.len(), 11); + /// assert!(vec.capacity() >= 11); + /// + /// let mut result = Vec::try_with_capacity(usize::MAX); + /// assert!(result.is_err()); + /// ``` + #[inline] + #[stable(feature = "kernel", since = "1.0.0")] + pub fn try_with_capacity(capacity: usize) -> Result { + Self::try_with_capacity_in(capacity, Global) + } + /// Creates a `Vec` directly from the raw components of another vector. /// /// # Safety @@ -617,6 +659,53 @@ impl Vec { Vec { buf: RawVec::with_capacity_in(capacity, alloc), len: 0 } } + /// Tries to construct a new, empty `Vec` with the specified capacity + /// with the provided allocator. + /// + /// The vector will be able to hold exactly `capacity` elements without + /// reallocating. If `capacity` is 0, the vector will not allocate. + /// + /// It is important to note that although the returned vector has the + /// *capacity* specified, the vector will have a zero *length*. For an + /// explanation of the difference between length and capacity, see + /// *[Capacity and reallocation]*. + /// + /// [Capacity and reallocation]: #capacity-and-reallocation + /// + /// # Examples + /// + /// ``` + /// #![feature(allocator_api)] + /// + /// use std::alloc::System; + /// + /// let mut vec = Vec::try_with_capacity_in(10, System).unwrap(); + /// + /// // The vector contains no items, even though it has capacity for more + /// assert_eq!(vec.len(), 0); + /// assert_eq!(vec.capacity(), 10); + /// + /// // These are all done without reallocating... + /// for i in 0..10 { + /// vec.push(i); + /// } + /// assert_eq!(vec.len(), 10); + /// assert_eq!(vec.capacity(), 10); + /// + /// // ...but this may make the vector reallocate + /// vec.push(11); + /// assert_eq!(vec.len(), 11); + /// assert!(vec.capacity() >= 11); + /// + /// let mut result = Vec::try_with_capacity_in(usize::MAX, System); + /// assert!(result.is_err()); + /// ``` + #[inline] + #[stable(feature = "kernel", since = "1.0.0")] + pub fn try_with_capacity_in(capacity: usize, alloc: A) -> Result { + Ok(Vec { buf: RawVec::try_with_capacity_in(capacity, alloc)?, len: 0 }) + } + /// Creates a `Vec` directly from the raw components of another vector. /// /// # Safety -- cgit v1.2.3 From 7c5977464681c2ec603efcac32a9432bcd355f12 Mon Sep 17 00:00:00 2001 From: Gary Guo Date: Thu, 10 Nov 2022 17:41:26 +0100 Subject: rust: str: add `BStr` type Add the `BStr` type, which is a byte string without UTF-8 validity guarantee. It is simply an alias to `[u8]`, but has a more evident semantical meaning. Signed-off-by: Gary Guo [Reworded, adapted for upstream and applied latest changes] Signed-off-by: Miguel Ojeda --- rust/kernel/str.rs | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'rust') diff --git a/rust/kernel/str.rs b/rust/kernel/str.rs index e45ff220ae50..3aa1a0cb9bf8 100644 --- a/rust/kernel/str.rs +++ b/rust/kernel/str.rs @@ -4,6 +4,11 @@ use core::fmt; +/// Byte string without UTF-8 validity guarantee. +/// +/// `BStr` is simply an alias to `[u8]`, but has a more evident semantical meaning. +pub type BStr = [u8]; + /// Allows formatting of [`fmt::Arguments`] into a raw buffer. /// /// It does not fail if callers write past the end of the buffer so that they can calculate the -- cgit v1.2.3 From 650ec51561fd201bcf47ce9b1d9b6fedd4bb60a6 Mon Sep 17 00:00:00 2001 From: Gary Guo Date: Thu, 10 Nov 2022 17:41:27 +0100 Subject: rust: str: add `b_str!` macro Add the `b_str!` macro, which creates a new `BStr` from a string literal. It is usable in const contexts, for instance: const X: &BStr = b_str!("Example"); Signed-off-by: Gary Guo [Reworded, adapted for upstream and applied latest changes] Signed-off-by: Miguel Ojeda --- rust/kernel/str.rs | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) (limited to 'rust') diff --git a/rust/kernel/str.rs b/rust/kernel/str.rs index 3aa1a0cb9bf8..95eb757c619d 100644 --- a/rust/kernel/str.rs +++ b/rust/kernel/str.rs @@ -9,6 +9,27 @@ use core::fmt; /// `BStr` is simply an alias to `[u8]`, but has a more evident semantical meaning. pub type BStr = [u8]; +/// Creates a new [`BStr`] from a string literal. +/// +/// `b_str!` converts the supplied string literal to byte string, so non-ASCII +/// characters can be included. +/// +/// # Examples +/// +/// ``` +/// # use kernel::b_str; +/// # use kernel::str::BStr; +/// const MY_BSTR: &BStr = b_str!("My awesome BStr!"); +/// ``` +#[macro_export] +macro_rules! b_str { + ($str:literal) => {{ + const S: &'static str = $str; + const C: &'static $crate::str::BStr = S.as_bytes(); + C + }}; +} + /// Allows formatting of [`fmt::Arguments`] into a raw buffer. /// /// It does not fail if callers write past the end of the buffer so that they can calculate the -- cgit v1.2.3 From d126d2380131dfbc880f5b5f0e3015e9bef6fa1c Mon Sep 17 00:00:00 2001 From: Gary Guo Date: Thu, 10 Nov 2022 17:41:28 +0100 Subject: rust: str: add `CStr` type Add the `CStr` type, which is a borrowed string that is guaranteed to have exactly one `NUL` byte, which is at the end. It is used for interoperability with kernel APIs that take C strings. Add it to the prelude too. Co-developed-by: Alex Gaynor Signed-off-by: Alex Gaynor Co-developed-by: Milan Landaverde Signed-off-by: Milan Landaverde Signed-off-by: Gary Guo [Reworded, adapted for upstream and applied latest changes] Signed-off-by: Miguel Ojeda --- rust/kernel/prelude.rs | 2 +- rust/kernel/str.rs | 169 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 170 insertions(+), 1 deletion(-) (limited to 'rust') diff --git a/rust/kernel/prelude.rs b/rust/kernel/prelude.rs index 1e08b08e9420..89c2c9f4e7a7 100644 --- a/rust/kernel/prelude.rs +++ b/rust/kernel/prelude.rs @@ -21,4 +21,4 @@ pub use super::{pr_alert, pr_crit, pr_debug, pr_emerg, pr_err, pr_info, pr_notic pub use super::error::{code::*, Error, Result}; -pub use super::ThisModule; +pub use super::{str::CStr, ThisModule}; diff --git a/rust/kernel/str.rs b/rust/kernel/str.rs index 95eb757c619d..d66565f92f71 100644 --- a/rust/kernel/str.rs +++ b/rust/kernel/str.rs @@ -4,6 +4,11 @@ use core::fmt; +use crate::{ + bindings, + error::{code::*, Error}, +}; + /// Byte string without UTF-8 validity guarantee. /// /// `BStr` is simply an alias to `[u8]`, but has a more evident semantical meaning. @@ -30,6 +35,170 @@ macro_rules! b_str { }}; } +/// Possible errors when using conversion functions in [`CStr`]. +#[derive(Debug, Clone, Copy)] +pub enum CStrConvertError { + /// Supplied bytes contain an interior `NUL`. + InteriorNul, + + /// Supplied bytes are not terminated by `NUL`. + NotNulTerminated, +} + +impl From for Error { + #[inline] + fn from(_: CStrConvertError) -> Error { + EINVAL + } +} + +/// A string that is guaranteed to have exactly one `NUL` byte, which is at the +/// end. +/// +/// Used for interoperability with kernel APIs that take C strings. +#[repr(transparent)] +pub struct CStr([u8]); + +impl CStr { + /// Returns the length of this string excluding `NUL`. + #[inline] + pub const fn len(&self) -> usize { + self.len_with_nul() - 1 + } + + /// Returns the length of this string with `NUL`. + #[inline] + pub const fn len_with_nul(&self) -> usize { + // SAFETY: This is one of the invariant of `CStr`. + // We add a `unreachable_unchecked` here to hint the optimizer that + // the value returned from this function is non-zero. + if self.0.is_empty() { + unsafe { core::hint::unreachable_unchecked() }; + } + self.0.len() + } + + /// Returns `true` if the string only includes `NUL`. + #[inline] + pub const fn is_empty(&self) -> bool { + self.len() == 0 + } + + /// Wraps a raw C string pointer. + /// + /// # Safety + /// + /// `ptr` must be a valid pointer to a `NUL`-terminated C string, and it must + /// last at least `'a`. When `CStr` is alive, the memory pointed by `ptr` + /// must not be mutated. + #[inline] + pub unsafe fn from_char_ptr<'a>(ptr: *const core::ffi::c_char) -> &'a Self { + // SAFETY: The safety precondition guarantees `ptr` is a valid pointer + // to a `NUL`-terminated C string. + let len = unsafe { bindings::strlen(ptr) } + 1; + // SAFETY: Lifetime guaranteed by the safety precondition. + let bytes = unsafe { core::slice::from_raw_parts(ptr as _, len as _) }; + // SAFETY: As `len` is returned by `strlen`, `bytes` does not contain interior `NUL`. + // As we have added 1 to `len`, the last byte is known to be `NUL`. + unsafe { Self::from_bytes_with_nul_unchecked(bytes) } + } + + /// Creates a [`CStr`] from a `[u8]`. + /// + /// The provided slice must be `NUL`-terminated, does not contain any + /// interior `NUL` bytes. + pub const fn from_bytes_with_nul(bytes: &[u8]) -> Result<&Self, CStrConvertError> { + if bytes.is_empty() { + return Err(CStrConvertError::NotNulTerminated); + } + if bytes[bytes.len() - 1] != 0 { + return Err(CStrConvertError::NotNulTerminated); + } + let mut i = 0; + // `i + 1 < bytes.len()` allows LLVM to optimize away bounds checking, + // while it couldn't optimize away bounds checks for `i < bytes.len() - 1`. + while i + 1 < bytes.len() { + if bytes[i] == 0 { + return Err(CStrConvertError::InteriorNul); + } + i += 1; + } + // SAFETY: We just checked that all properties hold. + Ok(unsafe { Self::from_bytes_with_nul_unchecked(bytes) }) + } + + /// Creates a [`CStr`] from a `[u8]` without performing any additional + /// checks. + /// + /// # Safety + /// + /// `bytes` *must* end with a `NUL` byte, and should only have a single + /// `NUL` byte (or the string will be truncated). + #[inline] + pub const unsafe fn from_bytes_with_nul_unchecked(bytes: &[u8]) -> &CStr { + // SAFETY: Properties of `bytes` guaranteed by the safety precondition. + unsafe { core::mem::transmute(bytes) } + } + + /// Returns a C pointer to the string. + #[inline] + pub const fn as_char_ptr(&self) -> *const core::ffi::c_char { + self.0.as_ptr() as _ + } + + /// Convert the string to a byte slice without the trailing 0 byte. + #[inline] + pub fn as_bytes(&self) -> &[u8] { + &self.0[..self.len()] + } + + /// Convert the string to a byte slice containing the trailing 0 byte. + #[inline] + pub const fn as_bytes_with_nul(&self) -> &[u8] { + &self.0 + } + + /// Yields a [`&str`] slice if the [`CStr`] contains valid UTF-8. + /// + /// If the contents of the [`CStr`] are valid UTF-8 data, this + /// function will return the corresponding [`&str`] slice. Otherwise, + /// it will return an error with details of where UTF-8 validation failed. + /// + /// # Examples + /// + /// ``` + /// # use kernel::str::CStr; + /// let cstr = CStr::from_bytes_with_nul(b"foo\0").unwrap(); + /// assert_eq!(cstr.to_str(), Ok("foo")); + /// ``` + #[inline] + pub fn to_str(&self) -> Result<&str, core::str::Utf8Error> { + core::str::from_utf8(self.as_bytes()) + } + + /// Unsafely convert this [`CStr`] into a [`&str`], without checking for + /// valid UTF-8. + /// + /// # Safety + /// + /// The contents must be valid UTF-8. + /// + /// # Examples + /// + /// ``` + /// # use kernel::c_str; + /// # use kernel::str::CStr; + /// // SAFETY: String literals are guaranteed to be valid UTF-8 + /// // by the Rust compiler. + /// let bar = c_str!("ツ"); + /// assert_eq!(unsafe { bar.as_str_unchecked() }, "ツ"); + /// ``` + #[inline] + pub unsafe fn as_str_unchecked(&self) -> &str { + unsafe { core::str::from_utf8_unchecked(self.as_bytes()) } + } +} + /// Allows formatting of [`fmt::Arguments`] into a raw buffer. /// /// It does not fail if callers write past the end of the buffer so that they can calculate the -- cgit v1.2.3 From c07e67bd2daf99de923b6fd927ab8c18e0f57b05 Mon Sep 17 00:00:00 2001 From: Gary Guo Date: Thu, 10 Nov 2022 17:41:29 +0100 Subject: rust: str: implement several traits for `CStr` Implement `Debug`, `Display`, `Deref` (into `BStr`), `AsRef` and a set of `Index<...>` traits. This makes it `CStr` more convenient to use (and closer to `str`). Co-developed-by: Alex Gaynor Signed-off-by: Alex Gaynor Co-developed-by: Morgan Bartlett Signed-off-by: Morgan Bartlett Signed-off-by: Gary Guo [Reworded, adapted for upstream and applied latest changes] Signed-off-by: Miguel Ojeda --- rust/kernel/str.rs | 124 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 123 insertions(+), 1 deletion(-) (limited to 'rust') diff --git a/rust/kernel/str.rs b/rust/kernel/str.rs index d66565f92f71..11d297c1a61c 100644 --- a/rust/kernel/str.rs +++ b/rust/kernel/str.rs @@ -2,7 +2,8 @@ //! String representations. -use core::fmt; +use core::fmt::{self, Write}; +use core::ops::{self, Deref, Index}; use crate::{ bindings, @@ -199,6 +200,127 @@ impl CStr { } } +impl fmt::Display for CStr { + /// Formats printable ASCII characters, escaping the rest. + /// + /// ``` + /// # use kernel::c_str; + /// # use kernel::str::CStr; + /// # use kernel::str::CString; + /// let penguin = c_str!("🐧"); + /// let s = CString::try_from_fmt(fmt!("{}", penguin)).unwrap(); + /// assert_eq!(s.as_bytes_with_nul(), "\\xf0\\x9f\\x90\\xa7\0".as_bytes()); + /// + /// let ascii = c_str!("so \"cool\""); + /// let s = CString::try_from_fmt(fmt!("{}", ascii)).unwrap(); + /// assert_eq!(s.as_bytes_with_nul(), "so \"cool\"\0".as_bytes()); + /// ``` + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + for &c in self.as_bytes() { + if (0x20..0x7f).contains(&c) { + // Printable character. + f.write_char(c as char)?; + } else { + write!(f, "\\x{:02x}", c)?; + } + } + Ok(()) + } +} + +impl fmt::Debug for CStr { + /// Formats printable ASCII characters with a double quote on either end, escaping the rest. + /// + /// ``` + /// # use kernel::c_str; + /// # use kernel::str::CStr; + /// # use kernel::str::CString; + /// let penguin = c_str!("🐧"); + /// let s = CString::try_from_fmt(fmt!("{:?}", penguin)).unwrap(); + /// assert_eq!(s.as_bytes_with_nul(), "\"\\xf0\\x9f\\x90\\xa7\"\0".as_bytes()); + /// + /// // Embedded double quotes are escaped. + /// let ascii = c_str!("so \"cool\""); + /// let s = CString::try_from_fmt(fmt!("{:?}", ascii)).unwrap(); + /// assert_eq!(s.as_bytes_with_nul(), "\"so \\\"cool\\\"\"\0".as_bytes()); + /// ``` + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str("\"")?; + for &c in self.as_bytes() { + match c { + // Printable characters. + b'\"' => f.write_str("\\\"")?, + 0x20..=0x7e => f.write_char(c as char)?, + _ => write!(f, "\\x{:02x}", c)?, + } + } + f.write_str("\"") + } +} + +impl AsRef for CStr { + #[inline] + fn as_ref(&self) -> &BStr { + self.as_bytes() + } +} + +impl Deref for CStr { + type Target = BStr; + + #[inline] + fn deref(&self) -> &Self::Target { + self.as_bytes() + } +} + +impl Index> for CStr { + type Output = CStr; + + #[inline] + fn index(&self, index: ops::RangeFrom) -> &Self::Output { + // Delegate bounds checking to slice. + // Assign to _ to mute clippy's unnecessary operation warning. + let _ = &self.as_bytes()[index.start..]; + // SAFETY: We just checked the bounds. + unsafe { Self::from_bytes_with_nul_unchecked(&self.0[index.start..]) } + } +} + +impl Index for CStr { + type Output = CStr; + + #[inline] + fn index(&self, _index: ops::RangeFull) -> &Self::Output { + self + } +} + +mod private { + use core::ops; + + // Marker trait for index types that can be forward to `BStr`. + pub trait CStrIndex {} + + impl CStrIndex for usize {} + impl CStrIndex for ops::Range {} + impl CStrIndex for ops::RangeInclusive {} + impl CStrIndex for ops::RangeToInclusive {} +} + +impl Index for CStr +where + Idx: private::CStrIndex, + BStr: Index, +{ + type Output = >::Output; + + #[inline] + fn index(&self, index: Idx) -> &Self::Output { + &self.as_bytes()[index] + } +} + /// Allows formatting of [`fmt::Arguments`] into a raw buffer. /// /// It does not fail if callers write past the end of the buffer so that they can calculate the -- cgit v1.2.3 From 985f1f09bf5bf8cbcb43e58a2320de2a5054be4c Mon Sep 17 00:00:00 2001 From: Milan Landaverde Date: Thu, 10 Nov 2022 17:41:30 +0100 Subject: rust: str: add `CStr` unit tests Add unit tests for `CStr::from_bytes_with_nul()` and `CStr::from_bytes_with_nul_unchecked()`. These serve as an example of the first unit tests for Rust code (i.e. different from documentation tests). Signed-off-by: Milan Landaverde [Reworded, adapted for upstream and applied lates