module_param.rs

  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::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        // 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
 88macro_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
 98impl_int_module_param!(i8);
 99impl_int_module_param!(u8);
100impl_int_module_param!(i16);
101impl_int_module_param!(u16);
102impl_int_module_param!(i32);
103impl_int_module_param!(u32);
104impl_int_module_param!(i64);
105impl_int_module_param!(u64);
106impl_int_module_param!(isize);
107impl_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.
116pub 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`.
123unsafe impl<T: Sync> Sync for ModuleParamAccess<T> {}
124
125impl<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/// ```
161macro_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
173make_param_ops!(PARAM_OPS_I8, i8);
174make_param_ops!(PARAM_OPS_U8, u8);
175make_param_ops!(PARAM_OPS_I16, i16);
176make_param_ops!(PARAM_OPS_U16, u16);
177make_param_ops!(PARAM_OPS_I32, i32);
178make_param_ops!(PARAM_OPS_U32, u32);
179make_param_ops!(PARAM_OPS_I64, i64);
180make_param_ops!(PARAM_OPS_U64, u64);
181make_param_ops!(PARAM_OPS_ISIZE, isize);
182make_param_ops!(PARAM_OPS_USIZE, usize);