|
| 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 | +
|
| 7 | +use crate::prelude::*; |
| 8 | +use crate::str::BStr; |
| 9 | +use bindings; |
| 10 | +use kernel::sync::SetOnce; |
| 11 | + |
| 12 | +/// Newtype to make `bindings::kernel_param` [`Sync`]. |
| 13 | +#[repr(transparent)] |
| 14 | +#[doc(hidden)] |
| 15 | +pub struct KernelParam(bindings::kernel_param); |
| 16 | + |
| 17 | +impl 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. |
| 26 | +unsafe 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. |
| 30 | +pub 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 |
| 58 | +unsafe extern "C" fn set_param<T>(val: *const c_char, param: *const bindings::kernel_param) -> c_int |
| 59 | +where |
| 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 | + // TODO: Use pr_warn_once available. |
| 66 | + crate::pr_warn!("Null pointer passed to `module_param::set_param`"); |
| 67 | + return EINVAL.to_errno(); |
| 68 | + } |
| 69 | + |
| 70 | + // SAFETY: By function safety requirement, val is non-null, null-terminated |
| 71 | + // and valid for reads for the duration of this function. |
| 72 | + let arg = unsafe { CStr::from_char_ptr(val) }; |
| 73 | + let arg: &BStr = arg.as_ref(); |
| 74 | + |
| 75 | + crate::error::from_result(|| { |
| 76 | + let new_value = T::try_from_param_arg(arg)?; |
| 77 | + |
| 78 | + // SAFETY: By function safety requirements, this access is safe. |
| 79 | + let container = unsafe { &*((*param).__bindgen_anon_1.arg.cast::<SetOnce<T>>()) }; |
| 80 | + |
| 81 | + container |
| 82 | + .populate(new_value) |
| 83 | + .then_some(0) |
| 84 | + .ok_or(kernel::error::code::EEXIST) |
| 85 | + }) |
| 86 | +} |
| 87 | + |
| 88 | +macro_rules! impl_int_module_param { |
| 89 | + ($ty:ident) => { |
| 90 | + impl ModuleParam for $ty { |
| 91 | + fn try_from_param_arg(arg: &BStr) -> Result<Self> { |
| 92 | + <$ty as crate::str::parse_int::ParseInt>::from_str(arg) |
| 93 | + } |
| 94 | + } |
| 95 | + }; |
| 96 | +} |
| 97 | + |
| 98 | +impl_int_module_param!(i8); |
| 99 | +impl_int_module_param!(u8); |
| 100 | +impl_int_module_param!(i16); |
| 101 | +impl_int_module_param!(u16); |
| 102 | +impl_int_module_param!(i32); |
| 103 | +impl_int_module_param!(u32); |
| 104 | +impl_int_module_param!(i64); |
| 105 | +impl_int_module_param!(u64); |
| 106 | +impl_int_module_param!(isize); |
| 107 | +impl_int_module_param!(usize); |
| 108 | + |
| 109 | +/// A wrapper for kernel parameters. |
| 110 | +/// |
| 111 | +/// This type is instantiated by the [`module!`] macro when module parameters are |
| 112 | +/// defined. You should never need to instantiate this type directly. |
| 113 | +/// |
| 114 | +/// Note: This type is `pub` because it is used by module crates to access |
| 115 | +/// parameter values. |
| 116 | +pub struct ModuleParamAccess<T> { |
| 117 | + value: SetOnce<T>, |
| 118 | + default: T, |
| 119 | +} |
| 120 | + |
| 121 | +// SAFETY: We only create shared references to the contents of this container, |
| 122 | +// so if `T` is `Sync`, so is `ModuleParamAccess`. |
| 123 | +unsafe impl<T: Sync> Sync for ModuleParamAccess<T> {} |
| 124 | + |
| 125 | +impl<T> ModuleParamAccess<T> { |
| 126 | + #[doc(hidden)] |
| 127 | + pub const fn new(default: T) -> Self { |
| 128 | + Self { |
| 129 | + value: SetOnce::new(), |
| 130 | + default, |
| 131 | + } |
| 132 | + } |
| 133 | + |
| 134 | + /// Get a shared reference to the parameter value. |
| 135 | + // Note: When sysfs access to parameters are enabled, we have to pass in a |
| 136 | + // held lock guard here. |
| 137 | + pub fn value(&self) -> &T { |
| 138 | + self.value.as_ref().unwrap_or(&self.default) |
| 139 | + } |
| 140 | + |
| 141 | + /// Get a mutable pointer to `self`. |
| 142 | + /// |
| 143 | + /// NOTE: In most cases it is not safe deref the returned pointer. |
| 144 | + pub const fn as_void_ptr(&self) -> *mut c_void { |
| 145 | + core::ptr::from_ref(self).cast_mut().cast() |
| 146 | + } |
| 147 | +} |
| 148 | + |
| 149 | +#[doc(hidden)] |
| 150 | +/// Generate a static [`kernel_param_ops`](srctree/include/linux/moduleparam.h) struct. |
| 151 | +/// |
| 152 | +/// # Examples |
| 153 | +/// |
| 154 | +/// ```ignore |
| 155 | +/// make_param_ops!( |
| 156 | +/// /// Documentation for new param ops. |
| 157 | +/// PARAM_OPS_MYTYPE, // Name for the static. |
| 158 | +/// MyType // A type which implements [`ModuleParam`]. |
| 159 | +/// ); |
| 160 | +/// ``` |
| 161 | +macro_rules! make_param_ops { |
| 162 | + ($ops:ident, $ty:ty) => { |
| 163 | + #[doc(hidden)] |
| 164 | + pub static $ops: $crate::bindings::kernel_param_ops = $crate::bindings::kernel_param_ops { |
| 165 | + flags: 0, |
| 166 | + set: Some(set_param::<$ty>), |
| 167 | + get: None, |
| 168 | + free: None, |
| 169 | + }; |
| 170 | + }; |
| 171 | +} |
| 172 | + |
| 173 | +make_param_ops!(PARAM_OPS_I8, i8); |
| 174 | +make_param_ops!(PARAM_OPS_U8, u8); |
| 175 | +make_param_ops!(PARAM_OPS_I16, i16); |
| 176 | +make_param_ops!(PARAM_OPS_U16, u16); |
| 177 | +make_param_ops!(PARAM_OPS_I32, i32); |
| 178 | +make_param_ops!(PARAM_OPS_U32, u32); |
| 179 | +make_param_ops!(PARAM_OPS_I64, i64); |
| 180 | +make_param_ops!(PARAM_OPS_U64, u64); |
| 181 | +make_param_ops!(PARAM_OPS_ISIZE, isize); |
| 182 | +make_param_ops!(PARAM_OPS_USIZE, usize); |
0 commit comments