Skip to content

Commit 863bd2e

Browse files
committed
rust: Rename libmodule to libmacros
Renaming to libmacros allows us to potentially have more procedural macros in the future without introducing additional crates. Having all our proc macros in a single crate allows potential code sharing between macros, and it simplifies the build process compared to multiple crates. Multiple crate does allow parallel compilation, but given the limited number of proc macros at this stage, the compilation time difference is negligible. Even when we have a big `macros` crate we can still use multiple codegen units while keep them in a single crate. Signed-off-by: Gary Guo <[email protected]>
1 parent 7fde08b commit 863bd2e

File tree

6 files changed

+151
-136
lines changed

6 files changed

+151
-136
lines changed

rust/Makefile

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
obj-$(CONFIG_RUST) += core.o compiler_builtins.o helpers.o
44
extra-$(CONFIG_RUST) += exports_core_generated.h
55

6-
extra-$(CONFIG_RUST) += libmodule.so
6+
extra-$(CONFIG_RUST) += libmacros.so
77

88
extra-$(CONFIG_RUST) += bindings_generated.rs
99
obj-$(CONFIG_RUST) += alloc.o kernel.o
@@ -35,21 +35,21 @@ quiet_cmd_rustdoc = RUSTDOC $<
3535
--output $(objtree)/rust/doc --crate-name $(subst rustdoc-,,$@) \
3636
-Fmissing-docs @$(objtree)/include/generated/rustc_cfg $<
3737

38-
rustdoc: rustdoc-module rustdoc-compiler_builtins rustdoc-kernel
38+
rustdoc: rustdoc-macros rustdoc-compiler_builtins rustdoc-kernel
3939

40-
rustdoc-module: private rustdoc_target_flags = --crate-type proc-macro \
40+
rustdoc-macros: private rustdoc_target_flags = --crate-type proc-macro \
4141
--extern proc_macro
42-
rustdoc-module: $(srctree)/rust/module.rs FORCE
42+
rustdoc-macros: $(srctree)/rust/macros/lib.rs FORCE
4343
$(call if_changed,rustdoc_host)
4444

4545
rustdoc-compiler_builtins: $(srctree)/rust/compiler_builtins.rs FORCE
4646
$(call if_changed,rustdoc)
4747

4848
rustdoc-kernel: private rustdoc_target_flags = --extern alloc \
4949
--extern build_error \
50-
--extern module=$(objtree)/rust/libmodule.so
51-
rustdoc-kernel: $(srctree)/rust/kernel/lib.rs rustdoc-module \
52-
$(objtree)/rust/libmodule.so $(objtree)/rust/bindings_generated.rs FORCE
50+
--extern macros=$(objtree)/rust/libmacros.so
51+
rustdoc-kernel: $(srctree)/rust/kernel/lib.rs rustdoc-macros \
52+
$(objtree)/rust/libmacros.so $(objtree)/rust/bindings_generated.rs FORCE
5353
$(call if_changed,rustdoc)
5454

5555
ifdef CONFIG_CC_IS_CLANG
@@ -126,9 +126,9 @@ quiet_cmd_rustc_procmacro = $(RUSTC_OR_CLIPPY_QUIET) P $@
126126
sed -i '/^\#/d' $(depfile)
127127

128128
# Procedural macros can only be used with the `rustc` that compiled it.
129-
# Therefore, to get `libmodule.so` automatically recompiled when the compiler
129+
# Therefore, to get `libmacros.so` automatically recompiled when the compiler
130130
# version changes, we add `core.o` as a dependency (even if it is not needed).
131-
$(objtree)/rust/libmodule.so: $(srctree)/rust/module.rs \
131+
$(objtree)/rust/libmacros.so: $(srctree)/rust/macros/lib.rs \
132132
$(objtree)/rust/core.o FORCE
133133
$(call if_changed_dep,rustc_procmacro)
134134

@@ -169,11 +169,11 @@ $(objtree)/rust/build_error.o: $(srctree)/rust/build_error.rs \
169169
$(objtree)/rust/compiler_builtins.o FORCE
170170
$(call if_changed_dep,rustc_library)
171171

172-
# ICE on `--extern module`: https://github.com/rust-lang/rust/issues/56935
172+
# ICE on `--extern macros`: https://github.com/rust-lang/rust/issues/56935
173173
$(objtree)/rust/kernel.o: private rustc_target_flags = --extern alloc \
174174
--extern build_error \
175-
--extern module=$(objtree)/rust/libmodule.so
175+
--extern macros=$(objtree)/rust/libmacros.so
176176
$(objtree)/rust/kernel.o: $(srctree)/rust/kernel/lib.rs $(objtree)/rust/alloc.o \
177177
$(objtree)/rust/build_error.o \
178-
$(objtree)/rust/libmodule.so $(objtree)/rust/bindings_generated.rs FORCE
178+
$(objtree)/rust/libmacros.so $(objtree)/rust/bindings_generated.rs FORCE
179179
$(call if_changed_dep,rustc_library)

rust/kernel/module_param.rs

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ pub trait ModuleParam: core::fmt::Display + core::marker::Sized {
5252
/// Get the current value of the parameter for use in the kernel module.
5353
///
5454
/// This function should not be used directly. Instead use the wrapper
55-
/// `read` which will be generated by [`module::module`].
55+
/// `read` which will be generated by [`macros::module`].
5656
fn value(&self) -> &Self::Value;
5757

5858
/// Set the module parameter from a string.
@@ -428,7 +428,7 @@ impl<T: Copy + core::fmt::Display + ModuleParam, const N: usize> ModuleParam
428428
/// A C-style string parameter.
429429
///
430430
/// The Rust version of the [`charp`] parameter. This type is meant to be
431-
/// used by the [`module::module`] macro, not handled directly. Instead use the
431+
/// used by the [`macros::module`] macro, not handled directly. Instead use the
432432
/// `read` method generated by that macro.
433433
///
434434
/// [`charp`]: ../../../include/linux/moduleparam.h

rust/kernel/prelude.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ pub use alloc::{borrow::ToOwned, string::String};
1515

1616
pub use super::build_assert;
1717

18-
pub use module::{module, module_misc_device};
18+
pub use macros::{module, module_misc_device};
1919

2020
pub use super::{pr_alert, pr_cont, pr_crit, pr_emerg, pr_err, pr_info, pr_notice, pr_warn};
2121

rust/macros/lib.rs

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
// SPDX-License-Identifier: GPL-2.0
2+
3+
//! Crate for all kernel procedural macros.
4+
5+
#![deny(clippy::complexity)]
6+
#![deny(clippy::correctness)]
7+
#![deny(clippy::perf)]
8+
#![deny(clippy::style)]
9+
10+
mod module;
11+
12+
use proc_macro::TokenStream;
13+
14+
/// Declares a kernel module.
15+
///
16+
/// The `type` argument should be a type which implements the [`KernelModule`]
17+
/// trait. Also accepts various forms of kernel metadata.
18+
///
19+
/// C header: [`include/linux/moduleparam.h`](../../../include/linux/moduleparam.h)
20+
///
21+
/// [`KernelModule`]: ../kernel/trait.KernelModule.html
22+
///
23+
/// # Examples
24+
///
25+
/// ```rust,no_run
26+
/// use kernel::prelude::*;
27+
///
28+
/// module!{
29+
/// type: MyKernelModule,
30+
/// name: b"my_kernel_module",
31+
/// author: b"Rust for Linux Contributors",
32+
/// description: b"My very own kernel module!",
33+
/// license: b"GPL v2",
34+
/// params: {
35+
/// my_i32: i32 {
36+
/// default: 42,
37+
/// permissions: 0o000,
38+
/// description: b"Example of i32",
39+
/// },
40+
/// writeable_i32: i32 {
41+
/// default: 42,
42+
/// permissions: 0o644,
43+
/// description: b"Example of i32",
44+
/// },
45+
/// },
46+
/// }
47+
///
48+
/// struct MyKernelModule;
49+
///
50+
/// impl KernelModule for MyKernelModule {
51+
/// fn init() -> Result<Self> {
52+
/// // If the parameter is writeable, then the kparam lock must be
53+
/// // taken to read the parameter:
54+
/// {
55+
/// let lock = THIS_MODULE.kernel_param_lock();
56+
/// pr_info!("i32 param is: {}\n", writeable_i32.read(&lock));
57+
/// }
58+
/// // If the parameter is read only, it can be read without locking
59+
/// // the kernel parameters:
60+
/// pr_info!("i32 param is: {}\n", my_i32.read());
61+
/// Ok(MyKernelModule)
62+
/// }
63+
/// }
64+
/// ```
65+
///
66+
/// # Supported argument types
67+
/// - `type`: type which implements the [`KernelModule`] trait (required).
68+
/// - `name`: byte array of the name of the kernel module (required).
69+
/// - `author`: byte array of the author of the kernel module.
70+
/// - `description`: byte array of the description of the kernel module.
71+
/// - `license`: byte array of the license of the kernel module (required).
72+
/// - `alias`: byte array of alias name of the kernel module.
73+
/// - `alias_rtnl_link`: byte array of the `rtnl_link_alias` of the kernel module (mutually exclusive with `alias`).
74+
/// - `params`: parameters for the kernel module, as described below.
75+
///
76+
/// # Supported parameter types
77+
///
78+
/// - `bool`: Corresponds to C `bool` param type.
79+
/// - `i8`: No equivalent C param type.
80+
/// - `u8`: Corresponds to C `char` param type.
81+
/// - `i16`: Corresponds to C `short` param type.
82+
/// - `u16`: Corresponds to C `ushort` param type.
83+
/// - `i32`: Corresponds to C `int` param type.
84+
/// - `u32`: Corresponds to C `uint` param type.
85+
/// - `i64`: No equivalent C param type.
86+
/// - `u64`: Corresponds to C `ullong` param type.
87+
/// - `isize`: No equivalent C param type.
88+
/// - `usize`: No equivalent C param type.
89+
/// - `str`: Corresponds to C `charp` param type. Reading returns a byte slice.
90+
/// - `ArrayParam<T,N>`: Corresponds to C parameters created using `module_param_array`. An array
91+
/// of `T`'s of length at **most** `N`.
92+
///
93+
/// `invbool` is unsupported: it was only ever used in a few modules.
94+
/// Consider using a `bool` and inverting the logic instead.
95+
#[proc_macro]
96+
pub fn module(ts: TokenStream) -> TokenStream {
97+
module::module(ts)
98+
}
99+
100+
/// Declares a kernel module that exposes a single misc device.
101+
///
102+
/// The `type` argument should be a type which implements the [`FileOpener`] trait. Also accepts
103+
/// various forms of kernel metadata.
104+
///
105+
/// C header: [`include/linux/moduleparam.h`](../../../include/linux/moduleparam.h)
106+
///
107+
/// [`FileOpener`]: ../kernel/file_operations/trait.FileOpener.html
108+
///
109+
/// # Examples
110+
///
111+
/// ```rust,no_run
112+
/// use kernel::prelude::*;
113+
///
114+
/// module_misc_device! {
115+
/// type: MyFile,
116+
/// name: b"my_miscdev_kernel_module",
117+
/// author: b"Rust for Linux Contributors",
118+
/// description: b"My very own misc device kernel module!",
119+
/// license: b"GPL v2",
120+
/// }
121+
///
122+
/// #[derive(Default)]
123+
/// struct MyFile;
124+
///
125+
/// impl kernel::file_operations::FileOperations for MyFile {
126+
/// kernel::declare_file_operations!();
127+
/// }
128+
/// ```
129+
#[proc_macro]
130+
pub fn module_misc_device(ts: TokenStream) -> TokenStream {
131+
module::module_misc_device(ts)
132+
}

rust/module.rs renamed to rust/macros/module.rs

Lines changed: 0 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,5 @@
11
// SPDX-License-Identifier: GPL-2.0
22

3-
//! Proc macro crate implementing the [`module!`] magic.
4-
//!
5-
//! C header: [`include/linux/moduleparam.h`](../../../include/linux/moduleparam.h)
6-
7-
#![deny(clippy::complexity)]
8-
#![deny(clippy::correctness)]
9-
#![deny(clippy::perf)]
10-
#![deny(clippy::style)]
11-
123
use proc_macro::{token_stream, Delimiter, Group, TokenStream, TokenTree};
134

145
fn try_ident(it: &mut token_stream::IntoIter) -> Option<String> {
@@ -399,86 +390,6 @@ impl ModuleInfo {
399390
}
400391
}
401392

402-
/// Declares a kernel module.
403-
///
404-
/// The `type` argument should be a type which implements the [`KernelModule`]
405-
/// trait. Also accepts various forms of kernel metadata.
406-
///
407-
/// [`KernelModule`]: ../kernel/trait.KernelModule.html
408-
///
409-
/// # Examples
410-
///
411-
/// ```rust,no_run
412-
/// use kernel::prelude::*;
413-
///
414-
/// module!{
415-
/// type: MyKernelModule,
416-
/// name: b"my_kernel_module",
417-
/// author: b"Rust for Linux Contributors",
418-
/// description: b"My very own kernel module!",
419-
/// license: b"GPL v2",
420-
/// params: {
421-
/// my_i32: i32 {
422-
/// default: 42,
423-
/// permissions: 0o000,
424-
/// description: b"Example of i32",
425-
/// },
426-
/// writeable_i32: i32 {
427-
/// default: 42,
428-
/// permissions: 0o644,
429-
/// description: b"Example of i32",
430-
/// },
431-
/// },
432-
/// }
433-
///
434-
/// struct MyKernelModule;
435-
///
436-
/// impl KernelModule for MyKernelModule {
437-
/// fn init() -> Result<Self> {
438-
/// // If the parameter is writeable, then the kparam lock must be
439-
/// // taken to read the parameter:
440-
/// {
441-
/// let lock = THIS_MODULE.kernel_param_lock();
442-
/// pr_info!("i32 param is: {}\n", writeable_i32.read(&lock));
443-
/// }
444-
/// // If the parameter is read only, it can be read without locking
445-
/// // the kernel parameters:
446-
/// pr_info!("i32 param is: {}\n", my_i32.read());
447-
/// Ok(MyKernelModule)
448-
/// }
449-
/// }
450-
/// ```
451-
///
452-
/// # Supported argument types
453-
/// - `type`: type which implements the [`KernelModule`] trait (required).
454-
/// - `name`: byte array of the name of the kernel module (required).
455-
/// - `author`: byte array of the author of the kernel module.
456-
/// - `description`: byte array of the description of the kernel module.
457-
/// - `license`: byte array of the license of the kernel module (required).
458-
/// - `alias`: byte array of alias name of the kernel module.
459-
/// - `alias_rtnl_link`: byte array of the `rtnl_link_alias` of the kernel module (mutually exclusive with `alias`).
460-
/// - `params`: parameters for the kernel module, as described below.
461-
///
462-
/// # Supported parameter types
463-
///
464-
/// - `bool`: Corresponds to C `bool` param type.
465-
/// - `i8`: No equivalent C param type.
466-
/// - `u8`: Corresponds to C `char` param type.
467-
/// - `i16`: Corresponds to C `short` param type.
468-
/// - `u16`: Corresponds to C `ushort` param type.
469-
/// - `i32`: Corresponds to C `int` param type.
470-
/// - `u32`: Corresponds to C `uint` param type.
471-
/// - `i64`: No equivalent C param type.
472-
/// - `u64`: Corresponds to C `ullong` param type.
473-
/// - `isize`: No equivalent C param type.
474-
/// - `usize`: No equivalent C param type.
475-
/// - `str`: Corresponds to C `charp` param type. Reading returns a byte slice.
476-
/// - `ArrayParam<T,N>`: Corresponds to C parameters created using `module_param_array`. An array
477-
/// of `T`'s of length at **most** `N`.
478-
///
479-
/// `invbool` is unsupported: it was only ever used in a few modules.
480-
/// Consider using a `bool` and inverting the logic instead.
481-
#[proc_macro]
482393
pub fn module(ts: TokenStream) -> TokenStream {
483394
let mut it = ts.into_iter();
484395

@@ -775,34 +686,6 @@ pub fn module(ts: TokenStream) -> TokenStream {
775686
).parse().expect("Error parsing formatted string into token stream.")
776687
}
777688

778-
/// Declares a kernel module that exposes a single misc device.
779-
///
780-
/// The `type` argument should be a type which implements the [`FileOpener`] trait. Also accepts
781-
/// various forms of kernel metadata.
782-
///
783-
/// [`FileOpener`]: ../kernel/file_operations/trait.FileOpener.html
784-
///
785-
/// # Examples
786-
///
787-
/// ```rust,no_run
788-
/// use kernel::prelude::*;
789-
///
790-
/// module_misc_device! {
791-
/// type: MyFile,
792-
/// name: b"my_miscdev_kernel_module",
793-
/// author: b"Rust for Linux Contributors",
794-
/// description: b"My very own misc device kernel module!",
795-
/// license: b"GPL v2",
796-
/// }
797-
///
798-
/// #[derive(Default)]
799-
/// struct MyFile;
800-
///
801-
/// impl kernel::file_operations::FileOperations for MyFile {
802-
/// kernel::declare_file_operations!();
803-
/// }
804-
/// ```
805-
#[proc_macro]
806689
pub fn module_misc_device(ts: TokenStream) -> TokenStream {
807690
let mut it = ts.into_iter();
808691

scripts/generate_rust_analyzer.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -63,13 +63,13 @@ def append_crate(display_name, root_module, is_workspace_member, deps, cfg):
6363
)
6464

6565
append_crate(
66-
"module",
67-
srctree / "rust" / "module.rs",
66+
"macros",
67+
srctree / "rust" / "macros" / "lib.rs",
6868
True,
6969
[],
7070
[],
7171
)
72-
crates[-1]["proc_macro_dylib_path"] = "rust/libmodule.so"
72+
crates[-1]["proc_macro_dylib_path"] = "rust/libmacros.so"
7373

7474
append_crate(
7575
"build_error",
@@ -83,7 +83,7 @@ def append_crate(display_name, root_module, is_workspace_member, deps, cfg):
8383
"kernel",
8484
srctree / "rust" / "kernel" / "lib.rs",
8585
True,
86-
["core", "alloc", "module", "build_error"],
86+
["core", "alloc", "macros", "build_error"],
8787
cfg,
8888
)
8989
crates[-1]["env"]["RUST_BINDINGS_FILE"] = str(bindings_file.resolve(True))

0 commit comments

Comments
 (0)