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 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 87 macro_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 97 impl_int_module_param!(i8); 98 impl_int_module_param!(u8); 99 impl_int_module_param!(i16); 100 impl_int_module_param!(u16); 101 impl_int_module_param!(i32); 102 impl_int_module_param!(u32); 103 impl_int_module_param!(i64); 104 impl_int_module_param!(u64); 105 impl_int_module_param!(isize); 106 impl_int_module_param!(usize); 107 108 /// A wrapper for kernel parameters. 109 /// 110 /// This type is instantiated by the [`module!`] macro when module parameters are 111 /// defined. You should never need to instantiate this type directly. 112 /// 113 /// Note: This type is `pub` because it is used by module crates to access 114 /// parameter values. 115 pub struct ModuleParamAccess<T> { 116 value: SetOnce<T>, 117 default: T, 118 } 119 120 // SAFETY: We only create shared references to the contents of this container, 121 // so if `T` is `Sync`, so is `ModuleParamAccess`. 122 unsafe impl<T: Sync> Sync for ModuleParamAccess<T> {} 123 124 impl<T> ModuleParamAccess<T> { 125 #[doc(hidden)] 126 pub const fn new(default: T) -> Self { 127 Self { 128 value: SetOnce::new(), 129 default, 130 } 131 } 132 133 /// Get a shared reference to the parameter value. 134 // Note: When sysfs access to parameters are enabled, we have to pass in a 135 // held lock guard here. 136 pub fn value(&self) -> &T { 137 self.value.as_ref().unwrap_or(&self.default) 138 } 139 140 /// Get a mutable pointer to `self`. 141 /// 142 /// NOTE: In most cases it is not safe deref the returned pointer. 143 pub const fn as_void_ptr(&self) -> *mut c_void { 144 core::ptr::from_ref(self).cast_mut().cast() 145 } 146 } 147 148 #[doc(hidden)] 149 /// Generate a static [`kernel_param_ops`](srctree/include/linux/moduleparam.h) struct. 150 /// 151 /// # Examples 152 /// 153 /// ```ignore 154 /// make_param_ops!( 155 /// /// Documentation for new param ops. 156 /// PARAM_OPS_MYTYPE, // Name for the static. 157 /// MyType // A type which implements [`ModuleParam`]. 158 /// ); 159 /// ``` 160 macro_rules! make_param_ops { 161 ($ops:ident, $ty:ty) => { 162 #[doc(hidden)] 163 pub static $ops: $crate::bindings::kernel_param_ops = $crate::bindings::kernel_param_ops { 164 flags: 0, 165 set: Some(set_param::<$ty>), 166 get: None, 167 free: None, 168 }; 169 }; 170 } 171 172 make_param_ops!(PARAM_OPS_I8, i8); 173 make_param_ops!(PARAM_OPS_U8, u8); 174 make_param_ops!(PARAM_OPS_I16, i16); 175 make_param_ops!(PARAM_OPS_U16, u16); 176 make_param_ops!(PARAM_OPS_I32, i32); 177 make_param_ops!(PARAM_OPS_U32, u32); 178 make_param_ops!(PARAM_OPS_I64, i64); 179 make_param_ops!(PARAM_OPS_U64, u64); 180 make_param_ops!(PARAM_OPS_ISIZE, isize); 181 make_param_ops!(PARAM_OPS_USIZE, usize); 182