Rust kernel code is supposed to use the custom mapping of C FFI types,
i.e. those from the `ffi` crate, rather than the ones coming from `core`.

Thus, to minimize mistakes and to simplify the code everywhere, just
provide them in the `kernel` prelude and ask in the Coding Guidelines
to use them directly, i.e. as a single segment path.

After this lands, we can start cleaning up the existing users.

Ideally, we would use something like Clippy's `disallowed-types` to
prevent the use of the `core` ones, but that one sees through aliases.

Link: https://lore.kernel.org/rust-for-linux/CANiq72kc4gzfieD-FjuWfELRDXXD2vLgPv4wqk3nt4pjdPQ=qg@mail.gmail.com/
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
---
 Documentation/rust/coding-guidelines.rst | 17 +++++++++++++++++
 rust/kernel/prelude.rs                   |  5 +++++
 2 files changed, 22 insertions(+)

diff --git a/Documentation/rust/coding-guidelines.rst b/Documentation/rust/coding-guidelines.rst
index 27f2a7bb5a4a..d0bf0b3a058a 100644
--- a/Documentation/rust/coding-guidelines.rst
+++ b/Documentation/rust/coding-guidelines.rst
@@ -191,6 +191,23 @@ or:
 	/// [`struct mutex`]: srctree/include/linux/mutex.h
 
 
+C FFI types
+-----------
+
+Rust kernel code does not use the C FFI types (such as ``c_char``) from
+``core::ffi::*``. Instead, a custom mapping that matches properly the C types
+used in the kernel is provided in the prelude, i.e. ``kernel::prelude::*``.
+
+These types (aliases) should generally be referred directly by their identifier,
+i.e. as a single segment path. For instance:
+
+.. code-block:: rust
+
+	fn f(p: *const c_char) -> c_int {
+	    // ...
+	}
+
+
 Naming
 ------
 
diff --git a/rust/kernel/prelude.rs b/rust/kernel/prelude.rs
index baa774a351ce..f869b02f1f25 100644
--- a/rust/kernel/prelude.rs
+++ b/rust/kernel/prelude.rs
@@ -14,6 +14,11 @@
 #[doc(no_inline)]
 pub use core::pin::Pin;
 
+pub use ::ffi::{
+    c_char, c_int, c_long, c_longlong, c_schar, c_short, c_uchar, c_uint, c_ulong, c_ulonglong,
+    c_ushort, c_void,
+};
+
 pub use crate::alloc::{flags::*, Box, KBox, KVBox, KVVec, KVec, VBox, VVec, Vec};
 
 #[doc(no_inline)]

base-commit: 0af2f6be1b4281385b618cb86ad946eded089ac8
-- 
2.49.0

On Sun, Apr 13, 2025 at 2:57 AM Miguel Ojeda <ojeda@kernel.org> wrote:
>
> Rust kernel code is supposed to use the custom mapping of C FFI types,
> i.e. those from the `ffi` crate, rather than the ones coming from `core`.
>
> Thus, to minimize mistakes and to simplify the code everywhere, just
> provide them in the `kernel` prelude and ask in the Coding Guidelines
> to use them directly, i.e. as a single segment path.
>
> After this lands, we can start cleaning up the existing users.
>
> Ideally, we would use something like Clippy's `disallowed-types` to
> prevent the use of the `core` ones, but that one sees through aliases.
>
> Link: https://lore.kernel.org/rust-for-linux/CANiq72kc4gzfieD-FjuWfELRDXXD2vLgPv4wqk3nt4pjdPQ=qg@mail.gmail.com/
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>

    [ Reworded content of the documentation to focus on how to use the
      aliases first. - Miguel ]

Cheers,
Miguel

On Sun, Apr 13, 2025 at 2:57 AM Miguel Ojeda <ojeda@kernel.org> wrote:
>
> Rust kernel code is supposed to use the custom mapping of C FFI types,
> i.e. those from the `ffi` crate, rather than the ones coming from `core`.
>
> Thus, to minimize mistakes and to simplify the code everywhere, just
> provide them in the `kernel` prelude and ask in the Coding Guidelines
> to use them directly, i.e. as a single segment path.
>
> After this lands, we can start cleaning up the existing users.
>
> Ideally, we would use something like Clippy's `disallowed-types` to
> prevent the use of the `core` ones, but that one sees through aliases.
>
> Link: https://lore.kernel.org/rust-for-linux/CANiq72kc4gzfieD-FjuWfELRDXXD2vLgPv4wqk3nt4pjdPQ=qg@mail.gmail.com/
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>

Yes please!

>  Documentation/rust/coding-guidelines.rst | 17 +++++++++++++++++
>  rust/kernel/prelude.rs                   |  5 +++++
>  2 files changed, 22 insertions(+)
>
> diff --git a/Documentation/rust/coding-guidelines.rst b/Documentation/rust/coding-guidelines.rst
> index 27f2a7bb5a4a..d0bf0b3a058a 100644
> --- a/Documentation/rust/coding-guidelines.rst
> +++ b/Documentation/rust/coding-guidelines.rst
> @@ -191,6 +191,23 @@ or:
>         /// [`struct mutex`]: srctree/include/linux/mutex.h
>
>
> +C FFI types
> +-----------
> +
> +Rust kernel code does not use the C FFI types (such as ``c_char``) from
> +``core::ffi::*``. Instead, a custom mapping that matches properly the C types
> +used in the kernel is provided in the prelude, i.e. ``kernel::prelude::*``.
> +
> +These types (aliases) should generally be referred directly by their identifier,
> +i.e. as a single segment path. For instance:
> +
> +.. code-block:: rust
> +
> +       fn f(p: *const c_char) -> c_int {
> +           // ...
> +       }

I wonder if it would make more sense to rephrase this section to first
say that rfl has type aliases for the C integer types called c_int and
so on, then mention that they are available in the prelude, and then
at the end of the section have a note that we don't use the type
aliases from core::ffi. I think focusing on how to use C integer
types, rather than technical details about how they are defined, is
more relevant for a reader who is just looking for coding guidelines.

Alice

On Mon, Apr 14, 2025 at 10:47 AM Alice Ryhl <aliceryhl@google.com> wrote:
>
> I wonder if it would make more sense to rephrase this section to first
> say that rfl has type aliases for the C integer types called c_int and
> so on, then mention that they are available in the prelude, and then
> at the end of the section have a note that we don't use the type
> aliases from core::ffi. I think focusing on how to use C integer
> types, rather than technical details about how they are defined, is
> more relevant for a reader who is just looking for coding guidelines.

Hmm... I see what you mean. In other places in the document, we start
comparing with userspace Rust in order to establish a bit of context.
But, more importantly, in this particular guideline I think it is
quite important to say "do not use the usual ones", because they are
actually different types, i.e. it is not just a style thing.

I have thought a couple times about perhaps changing the overall style
of the document to have a 1-liner short summary on each guideline --
some books do something like that consistently. And perhaps an
example, before a longer description. So something like the following,
which is closer to what you are suggesting:

    To refer to C types, use the FFI types (aliases) available from
the `kernel` prelude, e.g. ``c_int``.

    For instance:

        ...

    Refer to them with a single segment path: e.g. ``c_char`` instead
of ``ffi::c_char`` or ``kernel::ffi::c_char``.

    Do not use the `core::ffi::*` types -- they are different and some
do not map to the correct C type.

But even with this style, I think it is important putting the last
sentence in the "1-liner summary". Otherwise, someone may skip the
guideline thinking "oh, OK, it is just a style thing about using just
small paths, I will fix it later", without realizing they are actually
different sets of types unless they read the entire section, no?

Thanks!

Cheers,
Miguel

On Mon, Apr 14, 2025 at 03:22:44PM +0200, Miguel Ojeda wrote:
> On Mon, Apr 14, 2025 at 10:47 AM Alice Ryhl <aliceryhl@google.com> wrote:
> >
> > I wonder if it would make more sense to rephrase this section to first
> > say that rfl has type aliases for the C integer types called c_int and
> > so on, then mention that they are available in the prelude, and then
> > at the end of the section have a note that we don't use the type
> > aliases from core::ffi. I think focusing on how to use C integer
> > types, rather than technical details about how they are defined, is
> > more relevant for a reader who is just looking for coding guidelines.
> 
> Hmm... I see what you mean. In other places in the document, we start
> comparing with userspace Rust in order to establish a bit of context.
> But, more importantly, in this particular guideline I think it is
> quite important to say "do not use the usual ones", because they are
> actually different types, i.e. it is not just a style thing.
> 
> I have thought a couple times about perhaps changing the overall style
> of the document to have a 1-liner short summary on each guideline --
> some books do something like that consistently. And perhaps an
> example, before a longer description. So something like the following,
> which is closer to what you are suggesting:
> 
>     To refer to C types, use the FFI types (aliases) available from
> the `kernel` prelude, e.g. ``c_int``.
> 
>     For instance:
> 
>         ...
> 
>     Refer to them with a single segment path: e.g. ``c_char`` instead
> of ``ffi::c_char`` or ``kernel::ffi::c_char``.
> 
>     Do not use the `core::ffi::*` types -- they are different and some
> do not map to the correct C type.
> 
> But even with this style, I think it is important putting the last
> sentence in the "1-liner summary". Otherwise, someone may skip the
> guideline thinking "oh, OK, it is just a style thing about using just
> small paths, I will fix it later", without realizing they are actually
> different sets of types unless they read the entire section, no?

Hmm. Maybe, but I think having it at the end is okay. Could we catch
core::ffi with checkpath instead of clippy? Just search for core::ffi?

Alice

On Mon, Apr 14, 2025 at 4:13 PM Alice Ryhl <aliceryhl@google.com> wrote:
>
> Hmm. Maybe, but I think having it at the end is okay. Could we catch
> core::ffi with checkpath instead of clippy? Just search for core::ffi?

Sure, we can add it as a good first issue (Clippy would still be ideal
-- it allows to check all the current code).

I came up with this, which puts the right way first:

    Rust kernel code refers to C types, such as ``int``, using type
    aliases such as ``c_int``, which are readily available from
    the ``kernel`` prelude. Please do not use the aliases from
    ``core::ffi`` -- they may not map to the correct types.

If neither of you are against that, I will put that in a few days,
including Danilo's tag.

Thanks!

Cheers,
Miguel

On Thu, May 22, 2025 at 1:05 PM Miguel Ojeda
<miguel.ojeda.sandonis@gmail.com> wrote:
>
> On Mon, Apr 14, 2025 at 4:13 PM Alice Ryhl <aliceryhl@google.com> wrote:
> >
> > Hmm. Maybe, but I think having it at the end is okay. Could we catch
> > core::ffi with checkpath instead of clippy? Just search for core::ffi?
>
> Sure, we can add it as a good first issue (Clippy would still be ideal
> -- it allows to check all the current code).
>
> I came up with this, which puts the right way first:
>
>     Rust kernel code refers to C types, such as ``int``, using type
>     aliases such as ``c_int``, which are readily available from
>     the ``kernel`` prelude. Please do not use the aliases from
>     ``core::ffi`` -- they may not map to the correct types.
>
> If neither of you are against that, I will put that in a few days,
> including Danilo's tag.

LGTM
Reviewed-by: Alice Ryhl <aliceryhl@google.com>

On Mon, Apr 14, 2025 at 10:46:46AM +0200, Alice Ryhl wrote:
> On Sun, Apr 13, 2025 at 2:57 AM Miguel Ojeda <ojeda@kernel.org> wrote:
> >
> > Rust kernel code is supposed to use the custom mapping of C FFI types,
> > i.e. those from the `ffi` crate, rather than the ones coming from `core`.
> >
> > Thus, to minimize mistakes and to simplify the code everywhere, just
> > provide them in the `kernel` prelude and ask in the Coding Guidelines
> > to use them directly, i.e. as a single segment path.
> >
> > After this lands, we can start cleaning up the existing users.
> >
> > Ideally, we would use something like Clippy's `disallowed-types` to
> > prevent the use of the `core` ones, but that one sees through aliases.
> >
> > Link: https://lore.kernel.org/rust-for-linux/CANiq72kc4gzfieD-FjuWfELRDXXD2vLgPv4wqk3nt4pjdPQ=qg@mail.gmail.com/
> > Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
> 
> Yes please!
> 
> >  Documentation/rust/coding-guidelines.rst | 17 +++++++++++++++++
> >  rust/kernel/prelude.rs                   |  5 +++++
> >  2 files changed, 22 insertions(+)
> >
> > diff --git a/Documentation/rust/coding-guidelines.rst b/Documentation/rust/coding-guidelines.rst
> > index 27f2a7bb5a4a..d0bf0b3a058a 100644
> > --- a/Documentation/rust/coding-guidelines.rst
> > +++ b/Documentation/rust/coding-guidelines.rst
> > @@ -191,6 +191,23 @@ or:
> >         /// [`struct mutex`]: srctree/include/linux/mutex.h
> >
> >
> > +C FFI types
> > +-----------
> > +
> > +Rust kernel code does not use the C FFI types (such as ``c_char``) from
> > +``core::ffi::*``. Instead, a custom mapping that matches properly the C types
> > +used in the kernel is provided in the prelude, i.e. ``kernel::prelude::*``.
> > +
> > +These types (aliases) should generally be referred directly by their identifier,
> > +i.e. as a single segment path. For instance:
> > +
> > +.. code-block:: rust
> > +
> > +       fn f(p: *const c_char) -> c_int {
> > +           // ...
> > +       }
> 
> I wonder if it would make more sense to rephrase this section to first
> say that rfl has type aliases for the C integer types called c_int and
> so on, then mention that they are available in the prelude, and then
> at the end of the section have a note that we don't use the type
> aliases from core::ffi. I think focusing on how to use C integer
> types, rather than technical details about how they are defined, is
> more relevant for a reader who is just looking for coding guidelines.

I think that's a good suggestion. With that,

	Reviewed-by: Danilo Krummrich <dakr@kernel.org>