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); 183