linux-toradex.git/rust/kernel/prelude.rs, branch v6.4-rc1

rust: introduce `current`

2023-04-21T22:20:00+00:00

This allows Rust code to get a reference to the current task without
having to increment the refcount, but still guaranteeing memory safety.

Cc: Ingo Molnar 
Cc: Peter Zijlstra 
Reviewed-by: Martin Rodriguez Reboredo 
Signed-off-by: Wedson Almeida Filho 
Link: https://lore.kernel.org/r/20230411054543.21278-10-wedsonaf@gmail.com
Signed-off-by: Miguel Ojeda

rust: prelude: add `pin-init` API items to prelude

2023-04-12T16:41:05+00:00

Add `pin-init` API macros and traits to the prelude.

Signed-off-by: Benno Lossin 
Reviewed-by: Gary Guo 
Reviewed-by: Alice Ryhl 
Reviewed-by: Andreas Hindborg 
Link: https://lore.kernel.org/r/20230408122429.1103522-13-y86-dev@protonmail.com
Signed-off-by: Miguel Ojeda

rust: prelude: prevent doc inline of external imports

2023-01-16T22:49:46+00:00

This shows exactly where the items are from, previously the items from
macros, alloc and core were shown as a declaration from the kernel crate,
this shows the correct path.

Link: https://github.com/rust-lang/rust/issues/106713
Signed-off-by: Finn Behrens 
Reviewed-by: Vincenzo Palazzo 
[Reworded to add Link, fixed two typos and comment style]
Signed-off-by: Miguel Ojeda

rust: build_assert: add `build_{error,assert}!` macros

2022-12-04T00:59:16+00:00

Add the `build_error!` and `build_assert!` macros which leverage
the previously introduced `build_error` crate. Do so in a new
module, called `build_assert`.

The former fails the build if the code path calling it can possibly
be executed. The latter asserts that a boolean expression is `true`
at compile time.

In particular, `build_assert!` can be used in some contexts where
`static_assert!` cannot:

    fn f1() {
        static_assert!(N > 1);` // Error.
        build_assert!(N > 1);   // Build-time check.
        assert!(N > 1);         // Run-time check.
    }

    #[inline]
    fn f2(n: usize) {
        static_assert!(n > 1);  // Error.
        build_assert!(n > 1);   // Build-time check.
        assert!(n > 1);         // Run-time check.
    }

Signed-off-by: Gary Guo 
Reviewed-by: Wei Liu 
[Reworded, adapted for upstream and applied latest changes]
Signed-off-by: Miguel Ojeda

rust: static_assert: add `static_assert!` macro

2022-12-04T00:59:16+00:00

Add the `static_assert!` macro, which is a compile-time assert, similar
to the C11 `_Static_assert` and C++11 `static_assert` declarations [1,2].
Do so in a new module, called `static_assert`.

For instance:

    static_assert!(42 > 24);
    static_assert!(core::mem::size_of::() == 1);

    const X: &[u8] = b"bar";
    static_assert!(X[1] == b'a');

    const fn f(x: i32) -> i32 {
        x + 2
    }
    static_assert!(f(40) == 42);

Link: https://en.cppreference.com/w/c/language/_Static_assert [1]
Link: https://en.cppreference.com/w/cpp/language/static_assert [2]
Co-developed-by: Alex Gaynor 
Signed-off-by: Alex Gaynor 
Signed-off-by: Miguel Ojeda

rust: std_vendor: add `dbg!` macro based on `std`'s one

2022-12-04T00:59:16+00:00

The Rust standard library has a really handy macro, `dbg!` [1,2].
It prints the source location (filename and line) along with the raw
source code that is invoked with and the `Debug` representation
of the given expression, e.g.:

    let a = 2;
    let b = dbg!(a * 2) + 1;
    //      ^-- prints: [src/main.rs:2] a * 2 = 4
    assert_eq!(b, 5);

Port the macro over to the `kernel` crate inside a new module
called `std_vendor`, using `pr_info!` instead of `eprintln!` and
make the rules about committing uses of `dbg!` into version control
more concrete (i.e. tailored for the kernel).

Since the source code for the macro is taken from the standard
library source (with only minor adjustments), the new file is
licensed under `Apache 2.0 OR MIT`, just like the original [3,4].

Link: https://doc.rust-lang.org/std/macro.dbg.html [1]
Link: https://github.com/rust-lang/rust/blob/master/library/std/src/macros.rs#L212 [2]
Link: https://github.com/rust-lang/rust/blob/master/library/std/Cargo.toml [3]
Link: https://github.com/rust-lang/rust/blob/master/COPYRIGHT [4]
Signed-off-by: Niklas Mohrin 
[Reworded, adapted for upstream and applied latest changes]
Signed-off-by: Miguel Ojeda

rust: str: add `CStr` type

2022-12-04T00:59:15+00:00

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: prelude: add `error::code::*` constant items

2022-12-04T00:59:15+00:00

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: macros: add `#[vtable]` proc macro

2022-12-04T00:59:15+00:00

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: print: add more `pr_*!` levels

2022-12-01T19:12:14+00:00

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