projects/linux·blob uaccess-cleanups · refs

204 lines · 6.3 KiB

1// SPDX-License-Identifier: GPL-2.0
2
3//! Support for module parameters.
4//!
5//! C header: [`include/linux/moduleparam.h`](srctree/include/linux/moduleparam.h)
6
7use crate::prelude::*;
8use crate::str::{kstrtobool_bytes, BStr};
9use bindings;
10use kernel::sync::SetOnce;
11
12/// Newtype to make `bindings::kernel_param` [`Sync`].
13#[repr(transparent)]
14#[doc(hidden)]
15pub struct KernelParam(bindings::kernel_param);
16
17impl KernelParam {
18 #[doc(hidden)]
19 pub const fn new(val: bindings::kernel_param) -> Self {
20 Self(val)
21 }
22}
23
24// SAFETY: C kernel handles serializing access to this type. We never access it
25// from Rust module.
26unsafe impl Sync for KernelParam {}
27
28/// Types that can be used for module parameters.
29// NOTE: This trait is `Copy` because drop could produce unsoundness during teardown.
30pub trait ModuleParam: Sized + Copy {
31 /// Parse a parameter argument into the parameter value.
32 fn try_from_param_arg(arg: &BStr) -> Result<Self>;
33}
34
35/// Set the module parameter from a string.
36///
37/// Used to set the parameter value at kernel initialization, when loading
38/// the module or when set through `sysfs`.
39///
40/// See `struct kernel_param_ops.set`.
41///
42/// # Safety
43///
44/// - If `val` is non-null then it must point to a valid null-terminated string that must be valid
45/// for reads for the duration of the call.
46/// - `param` must be a pointer to a `bindings::kernel_param` initialized by the rust module macro.
47/// The pointee must be valid for reads for the duration of the call.
48///
49/// # Note
50///
51/// - The safety requirements are satisfied by C API contract when this function is invoked by the
52/// module subsystem C code.
53/// - Currently, we only support read-only parameters that are not readable from `sysfs`. Thus, this
54/// function is only called at kernel initialization time, or at module load time, and we have
55/// exclusive access to the parameter for the duration of the function.
56///
57/// [`module!`]: macros::module
58unsafe extern "C" fn set_param<T>(val: *const c_char, param: *const bindings::kernel_param) -> c_int
59where
60 T: ModuleParam,
61{
62 // NOTE: If we start supporting arguments without values, val _is_ allowed
63 // to be null here.
64 if val.is_null() {
65 crate::pr_warn_once!("Null pointer passed to `module_param::set_param`\n");
66 return EINVAL.to_errno();
67 }
68
69 // SAFETY: By function safety requirement, val is non-null, null-terminated
70 // and valid for reads for the duration of this function.
71 let arg = unsafe { CStr::from_char_ptr(val) };
72 let arg: &BStr = arg.as_ref();
73
74 crate::error::from_result(|| {
75 let new_value = T::try_from_param_arg(arg)?;
76
77 // SAFETY: By function safety requirements, this access is safe.
78 let container = unsafe { &*((*param).__bindgen_anon_1.arg.cast::<SetOnce<T>>()) };
79
80 container
81 .populate(new_value)
82 .then_some(0)
83 .ok_or(kernel::error::code::EEXIST)
84 })
85}
86
87macro_rules! impl_int_module_param {
88 ($ty:ident) => {
89 impl ModuleParam for $ty {
90 fn try_from_param_arg(arg: &BStr) -> Result<Self> {
91 <$ty as crate::str::parse_int::ParseInt>::from_str(arg)
92 }
93 }
94 };
95}
96
97impl_int_module_param!(i8);
98impl_int_module_param!(u8);
99impl_int_module_param!(i16);
100impl_int_module_param!(u16);
101impl_int_module_param!(i32);
102impl_int_module_param!(u32);
103impl_int_module_param!(i64);
104impl_int_module_param!(u64);
105impl_int_module_param!(isize);
106impl_int_module_param!(usize);
107
108impl ModuleParam for bool {
109 fn try_from_param_arg(arg: &BStr) -> Result<Self> {
110 kstrtobool_bytes(arg)
111 }
112}
113
114/// A wrapper for kernel parameters.
115///
116/// This type is instantiated by the [`module!`] macro when module parameters are
117/// defined. You should never need to instantiate this type directly.
118///
119/// Note: This type is `pub` because it is used by module crates to access
120/// parameter values.
121pub struct ModuleParamAccess<T> {
122 value: SetOnce<T>,
123 default: T,
124}
125
126// SAFETY: We only create shared references to the contents of this container,
127// so if `T` is `Sync`, so is `ModuleParamAccess`.
128unsafe impl<T: Sync> Sync for ModuleParamAccess<T> {}
129
130impl<T> ModuleParamAccess<T> {
131 #[doc(hidden)]
132 pub const fn new(default: T) -> Self {
133 Self {
134 value: SetOnce::new(),
135 default,
136 }
137 }
138
139 /// Get a copy of the parameter value.
140 ///
141 /// Returns the value supplied at module load time, or the default value
142 /// if the parameter has not been set.
143 #[inline]
144 pub fn value(&self) -> T
145 where
146 T: Copy,
147 {
148 self.value.copy().unwrap_or(self.default)
149 }
150
151 /// Get a shared reference to the parameter value.
152 ///
153 /// Returns a reference to the value supplied at module load time, or a
154 /// reference to the default value if the parameter has not been set.
155 // Note: When sysfs access to parameters are enabled, we have to pass in a
156 // held lock guard here.
157 #[inline]
158 pub fn value_ref(&self) -> &T {
159 self.value.as_ref().unwrap_or(&self.default)
160 }
161
162 /// Get a mutable pointer to `self`.
163 ///
164 /// NOTE: In most cases it is not safe deref the returned pointer.
165 pub const fn as_void_ptr(&self) -> *mut c_void {
166 core::ptr::from_ref(self).cast_mut().cast()
167 }
168}
169
170#[doc(hidden)]
171/// Generate a static [`kernel_param_ops`](srctree/include/linux/moduleparam.h) struct.
172///
173/// # Examples
174///
175/// ```ignore
176/// make_param_ops!(
177/// /// Documentation for new param ops.
178/// PARAM_OPS_MYTYPE, // Name for the static.
179/// MyType // A type which implements [`ModuleParam`].
180/// );
181/// ```
182macro_rules! make_param_ops {
183 ($ops:ident, $ty:ty) => {
184 #[doc(hidden)]
185 pub static $ops: $crate::bindings::kernel_param_ops = $crate::bindings::kernel_param_ops {
186 flags: 0,
187 set: Some(set_param::<$ty>),
188 get: None,
189 free: None,
190 };
191 };
192}
193
194make_param_ops!(PARAM_OPS_I8, i8);
195make_param_ops!(PARAM_OPS_U8, u8);
196make_param_ops!(PARAM_OPS_I16, i16);
197make_param_ops!(PARAM_OPS_U16, u16);
198make_param_ops!(PARAM_OPS_I32, i32);
199make_param_ops!(PARAM_OPS_U32, u32);
200make_param_ops!(PARAM_OPS_I64, i64);
201make_param_ops!(PARAM_OPS_U64, u64);
202make_param_ops!(PARAM_OPS_ISIZE, isize);
203make_param_ops!(PARAM_OPS_USIZE, usize);
204make_param_ops!(PARAM_OPS_BOOL, bool);