Skip to content

Commit 03ecf73

Browse files
nbdd0121nbdd0121
committed
rust: Rename libmodule to libmacros
Renaming to libmacros allows us to potentially have more procedural macros in the future without introducing additional crates. Signed-off-by: Gary Guo <[email protected]>
1 parent 7fde08b commit 03ecf73

File tree

6 files changed

+145
-131
lines changed

6 files changed

+145
-131
lines changed

‎rust/Makefile

+12-12
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

+2-2
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

+1-1
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

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

‎rust/module.rs ‎rust/macros/module.rs

-112
Original file line numberDiff line numberDiff line change
@@ -1,9 +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-
73
#![deny(clippy::complexity)]
84
#![deny(clippy::correctness)]
95
#![deny(clippy::perf)]
@@ -399,86 +395,6 @@ impl ModuleInfo {
399395
}
400396
}
401397

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]
482398
pub fn module(ts: TokenStream) -> TokenStream {
483399
let mut it = ts.into_iter();
484400

@@ -775,34 +691,6 @@ pub fn module(ts: TokenStream) -> TokenStream {
775691
).parse().expect("Error parsing formatted string into token stream.")
776692
}
777693

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]
806694
pub fn module_misc_device(ts: TokenStream) -> TokenStream {
807695
let mut it = ts.into_iter();
808696

‎scripts/generate_rust_analyzer.py

+4-4
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)