rust: add C FFI types to the prelude
Subsystems (2)
Miguel Ojeda
maintainerPATCH 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
@@ -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
@@ -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
Alice Ryhl
reviewerQuoted 8 lines · Miguel Ojeda
Rust kernel code is supposed to use the custom mapping of C FFI types, i.e. those from the
fficrate, rather than the ones coming fromcore.Thus, to minimize mistakes and to simplify the code everywhere, just provide them in the
kernelprelude 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-typesto prevent the use of thecoreones, 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@@ -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
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
fficrate, rather than the ones coming fromcore.Thus, to minimize mistakes and to simplify the code everywhere, just provide them in the
kernelprelude 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-typesto prevent the use of thecoreones, 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@@ -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 typesDocumentation/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_intand 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 fromcore::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,
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_intand 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 fromcore::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
Alice Ryhl
reviewerQuoted 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_intand 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 fromcore::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
thekernelprelude, 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
Quoted 3 lines · Alice Ryhl
Hmm. Maybe, but I think having it at the end is okay. Could we catch
core::ffiwith checkpath instead of clippy? Just search forcore::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
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::ffiwith checkpath instead of clippy? Just search forcore::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
Quoted 8 lines · Miguel Ojeda
Rust kernel code is supposed to use the custom mapping of C FFI types, i.e. those from the
fficrate, rather than the ones coming fromcore.Thus, to minimize mistakes and to simplify the code everywhere, just provide them in the
kernelprelude 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-typesto prevent the use of thecoreones, but that one sees through aliases.
[ Reworded content of the documentation to focus on how to use the
aliases first. - Miguel ]
Cheers,
Miguel