Skip to contentSkip to conversation

rust: add C FFI types to the prelude

PATCH In review Miguel Ojeda 4 participants 8 messages Apr 13, 2025 – May 25, 2025

Subsystems (2)
lore
Share & tools
lore

Miguel Ojeda

author maintainer
#0 lore raw

PATCH 1/1 rust: add C FFI types to the prelude

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.

---
 Documentation/rust/coding-guidelines.rst | 17 +++++++++++++++++
 rust/kernel/prelude.rs                   |  5 +++++
 2 files changed, 22 insertions(+)
Documentation/rust/coding-guidelines.rst +17 -0
index 27f2a7bb5a4a..d0bf0b3a058a 100644
@@ -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
 ------
 
rust/kernel/prelude.rs +5 -0
index baa774a351ce..f869b02f1f25 100644
@@ -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

Signature · 1 line
2.49.0
reviewer
#1 lore raw
Quoted 8 lines · Miguel Ojeda

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.

Quoted 7 lines

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.

Yes please!

Quoted 17 lines
 Documentation/rust/coding-guidelines.rst | 17 +++++++++++++++++
 rust/kernel/prelude.rs                   |  5 +++++
 2 files changed, 22 insertions(+)
Documentation/rust/coding-guidelines.rst +5 -0
index 27f2a7bb5a4a..d0bf0b3a058a 100644
@@ -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

Documentation/rust/coding-guidelines.rst or: · line 208

Quoted 10 lines
Documentation/rust/coding-guidelines.rst +10 -0
+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

reviewer Reviewed-by
#2 lore raw
Quoted 47 lines · Alice Ryhl
Quoted 8 lines · Miguel Ojeda

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.

Quoted 7 lines

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.

Yes please!

Quoted 17 lines
 Documentation/rust/coding-guidelines.rst | 17 +++++++++++++++++
 rust/kernel/prelude.rs                   |  5 +++++
 2 files changed, 22 insertions(+)
Documentation/rust/coding-guidelines.rst +5 -0
index 27f2a7bb5a4a..d0bf0b3a058a 100644
@@ -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

Documentation/rust/coding-guidelines.rst or: · line 208

Quoted 10 lines
Documentation/rust/coding-guidelines.rst +10 -0
+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 {
+           // ...
+       }
Quoted 7 lines

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,

#3 lore raw
In reply to Alice Ryhl
Quoted 8 lines · Alice Ryhl

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

reviewer
#4 lore raw
Quoted 32 lines · Miguel Ojeda
Quoted 8 lines · Alice Ryhl

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``.

Quoted 8 lines

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

#5 lore raw
Quoted 3 lines · Alice Ryhl

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

reviewer Reviewed-by
#6 lore raw
Quoted 11 lines · Miguel Ojeda
Quoted 3 lines · Alice Ryhl

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:

Quoted 7 lines

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

#7 lore raw
In reply to Miguel Ojeda
Quoted 8 lines · Miguel Ojeda

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.

Quoted 7 lines

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.

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

Cheers,
Miguel