Commit 4823a580 authored by Viresh Kumar's avatar Viresh Kumar
Browse files

cpufreq: Convert `/// SAFETY` lines to `# Safety` sections 



Replace `/// SAFETY` comments in doc comments with proper `# Safety`
sections, as per rustdoc conventions.

Also mark the C FFI callbacks as `unsafe` to correctly reflect their
safety requirements.

Reported-by: default avatarMiguel Ojeda <ojeda@kernel.org>
Closes: https://github.com/Rust-for-Linux/linux/issues/1169


Signed-off-by: default avatarViresh Kumar <viresh.kumar@linaro.org>
parent 19272b37

rust/kernel/cpufreq.rs

+109 −37
Original line number Diff line number Diff line
@@ -1055,8 +1055,11 @@ pub fn new_foreign_owned(dev: &Device<Bound>) -> Result { 
impl<T: Driver> Registration<T> {

    /// Driver's `init` callback.

    ///

    /// SAFETY: Called from C. Inputs must be valid pointers.

    extern "C" fn init_callback(ptr: *mut bindings::cpufreq_policy) -> kernel::ffi::c_int {

    /// # Safety

    ///

    /// - This function may only be called from the cpufreq C infrastructure.

    /// - The pointer arguments must be valid pointers.

    unsafe extern "C" fn init_callback(ptr: *mut bindings::cpufreq_policy) -> kernel::ffi::c_int {

        from_result(|| {

            // SAFETY: The `ptr` is guaranteed to be valid by the contract with the C code for the

            // lifetime of `policy`.
@@ -1070,8 +1073,11 @@ extern "C" fn init_callback(ptr: *mut bindings::cpufreq_policy) -> kernel::ffi:: 


    /// Driver's `exit` callback.

    ///

    /// SAFETY: Called from C. Inputs must be valid pointers.

    extern "C" fn exit_callback(ptr: *mut bindings::cpufreq_policy) {

    /// # Safety

    ///

    /// - This function may only be called from the cpufreq C infrastructure.

    /// - The pointer arguments must be valid pointers.

    unsafe extern "C" fn exit_callback(ptr: *mut bindings::cpufreq_policy) {

        // SAFETY: The `ptr` is guaranteed to be valid by the contract with the C code for the

        // lifetime of `policy`.

        let policy = unsafe { Policy::from_raw_mut(ptr) };
@@ -1082,8 +1088,11 @@ extern "C" fn exit_callback(ptr: *mut bindings::cpufreq_policy) { 


    /// Driver's `online` callback.

    ///

    /// SAFETY: Called from C. Inputs must be valid pointers.

    extern "C" fn online_callback(ptr: *mut bindings::cpufreq_policy) -> kernel::ffi::c_int {

    /// # Safety

    ///

    /// - This function may only be called from the cpufreq C infrastructure.

    /// - The pointer arguments must be valid pointers.

    unsafe extern "C" fn online_callback(ptr: *mut bindings::cpufreq_policy) -> kernel::ffi::c_int {

        from_result(|| {

            // SAFETY: The `ptr` is guaranteed to be valid by the contract with the C code for the

            // lifetime of `policy`.
@@ -1094,8 +1103,13 @@ extern "C" fn online_callback(ptr: *mut bindings::cpufreq_policy) -> kernel::ffi 


    /// Driver's `offline` callback.

    ///

    /// SAFETY: Called from C. Inputs must be valid pointers.

    extern "C" fn offline_callback(ptr: *mut bindings::cpufreq_policy) -> kernel::ffi::c_int {

    /// # Safety

    ///

    /// - This function may only be called from the cpufreq C infrastructure.

    /// - The pointer arguments must be valid pointers.

    unsafe extern "C" fn offline_callback(

        ptr: *mut bindings::cpufreq_policy,

    ) -> kernel::ffi::c_int {

        from_result(|| {

            // SAFETY: The `ptr` is guaranteed to be valid by the contract with the C code for the

            // lifetime of `policy`.
@@ -1106,8 +1120,13 @@ extern "C" fn offline_callback(ptr: *mut bindings::cpufreq_policy) -> kernel::ff 


    /// Driver's `suspend` callback.

    ///

    /// SAFETY: Called from C. Inputs must be valid pointers.

    extern "C" fn suspend_callback(ptr: *mut bindings::cpufreq_policy) -> kernel::ffi::c_int {

    /// # Safety

    ///

    /// - This function may only be called from the cpufreq C infrastructure.

    /// - The pointer arguments must be valid pointers.

    unsafe extern "C" fn suspend_callback(

        ptr: *mut bindings::cpufreq_policy,

    ) -> kernel::ffi::c_int {

        from_result(|| {

            // SAFETY: The `ptr` is guaranteed to be valid by the contract with the C code for the

            // lifetime of `policy`.
@@ -1118,8 +1137,11 @@ extern "C" fn suspend_callback(ptr: *mut bindings::cpufreq_policy) -> kernel::ff 


    /// Driver's `resume` callback.

    ///

    /// SAFETY: Called from C. Inputs must be valid pointers.

    extern "C" fn resume_callback(ptr: *mut bindings::cpufreq_policy) -> kernel::ffi::c_int {

    /// # Safety

    ///

    /// - This function may only be called from the cpufreq C infrastructure.

    /// - The pointer arguments must be valid pointers.

    unsafe extern "C" fn resume_callback(ptr: *mut bindings::cpufreq_policy) -> kernel::ffi::c_int {

        from_result(|| {

            // SAFETY: The `ptr` is guaranteed to be valid by the contract with the C code for the

            // lifetime of `policy`.
@@ -1130,8 +1152,11 @@ extern "C" fn resume_callback(ptr: *mut bindings::cpufreq_policy) -> kernel::ffi 


    /// Driver's `ready` callback.

    ///

    /// SAFETY: Called from C. Inputs must be valid pointers.

    extern "C" fn ready_callback(ptr: *mut bindings::cpufreq_policy) {

    /// # Safety

    ///

    /// - This function may only be called from the cpufreq C infrastructure.

    /// - The pointer arguments must be valid pointers.

    unsafe extern "C" fn ready_callback(ptr: *mut bindings::cpufreq_policy) {

        // SAFETY: The `ptr` is guaranteed to be valid by the contract with the C code for the

        // lifetime of `policy`.

        let policy = unsafe { Policy::from_raw_mut(ptr) };
@@ -1140,8 +1165,13 @@ extern "C" fn ready_callback(ptr: *mut bindings::cpufreq_policy) { 


    /// Driver's `verify` callback.

    ///

    /// SAFETY: Called from C. Inputs must be valid pointers.

    extern "C" fn verify_callback(ptr: *mut bindings::cpufreq_policy_data) -> kernel::ffi::c_int {

    /// # Safety

    ///

    /// - This function may only be called from the cpufreq C infrastructure.

    /// - The pointer arguments must be valid pointers.

    unsafe extern "C" fn verify_callback(

        ptr: *mut bindings::cpufreq_policy_data,

    ) -> kernel::ffi::c_int {

        from_result(|| {

            // SAFETY: The `ptr` is guaranteed to be valid by the contract with the C code for the

            // lifetime of `policy`.
@@ -1152,8 +1182,13 @@ extern "C" fn verify_callback(ptr: *mut bindings::cpufreq_policy_data) -> kernel 


    /// Driver's `setpolicy` callback.

    ///

    /// SAFETY: Called from C. Inputs must be valid pointers.

    extern "C" fn setpolicy_callback(ptr: *mut bindings::cpufreq_policy) -> kernel::ffi::c_int {

    /// # Safety

    ///

    /// - This function may only be called from the cpufreq C infrastructure.

    /// - The pointer arguments must be valid pointers.

    unsafe extern "C" fn setpolicy_callback(

        ptr: *mut bindings::cpufreq_policy,

    ) -> kernel::ffi::c_int {

        from_result(|| {

            // SAFETY: The `ptr` is guaranteed to be valid by the contract with the C code for the

            // lifetime of `policy`.
@@ -1164,8 +1199,11 @@ extern "C" fn setpolicy_callback(ptr: *mut bindings::cpufreq_policy) -> kernel:: 


    /// Driver's `target` callback.

    ///

    /// SAFETY: Called from C. Inputs must be valid pointers.

    extern "C" fn target_callback(

    /// # Safety

    ///

    /// - This function may only be called from the cpufreq C infrastructure.

    /// - The pointer arguments must be valid pointers.

    unsafe extern "C" fn target_callback(

        ptr: *mut bindings::cpufreq_policy,

        target_freq: u32,

        relation: u32,
@@ -1180,8 +1218,11 @@ extern "C" fn target_callback( 


    /// Driver's `target_index` callback.

    ///

    /// SAFETY: Called from C. Inputs must be valid pointers.

    extern "C" fn target_index_callback(

    /// # Safety

    ///

    /// - This function may only be called from the cpufreq C infrastructure.

    /// - The pointer arguments must be valid pointers.

    unsafe extern "C" fn target_index_callback(

        ptr: *mut bindings::cpufreq_policy,

        index: u32,

    ) -> kernel::ffi::c_int {
@@ -1200,8 +1241,11 @@ extern "C" fn target_index_callback( 


    /// Driver's `fast_switch` callback.

    ///

    /// SAFETY: Called from C. Inputs must be valid pointers.

    extern "C" fn fast_switch_callback(

    /// # Safety

    ///

    /// - This function may only be called from the cpufreq C infrastructure.

    /// - The pointer arguments must be valid pointers.

    unsafe extern "C" fn fast_switch_callback(

        ptr: *mut bindings::cpufreq_policy,

        target_freq: u32,

    ) -> kernel::ffi::c_uint {
@@ -1212,7 +1256,11 @@ extern "C" fn fast_switch_callback( 
    }



    /// Driver's `adjust_perf` callback.

    extern "C" fn adjust_perf_callback(

    ///

    /// # Safety

    ///

    /// - This function may only be called from the cpufreq C infrastructure.

    unsafe extern "C" fn adjust_perf_callback(

        cpu: u32,

        min_perf: usize,

        target_perf: usize,
@@ -1225,8 +1273,11 @@ extern "C" fn adjust_perf_callback( 


    /// Driver's `get_intermediate` callback.

    ///

    /// SAFETY: Called from C. Inputs must be valid pointers.

    extern "C" fn get_intermediate_callback(

    /// # Safety

    ///

    /// - This function may only be called from the cpufreq C infrastructure.

    /// - The pointer arguments must be valid pointers.

    unsafe extern "C" fn get_intermediate_callback(

        ptr: *mut bindings::cpufreq_policy,

        index: u32,

    ) -> kernel::ffi::c_uint {
@@ -1243,8 +1294,11 @@ extern "C" fn get_intermediate_callback( 


    /// Driver's `target_intermediate` callback.

    ///

    /// SAFETY: Called from C. Inputs must be valid pointers.

    extern "C" fn target_intermediate_callback(

    /// # Safety

    ///

    /// - This function may only be called from the cpufreq C infrastructure.

    /// - The pointer arguments must be valid pointers.

    unsafe extern "C" fn target_intermediate_callback(

        ptr: *mut bindings::cpufreq_policy,

        index: u32,

    ) -> kernel::ffi::c_int {
@@ -1262,12 +1316,21 @@ extern "C" fn target_intermediate_callback( 
    }



    /// Driver's `get` callback.

    extern "C" fn get_callback(cpu: u32) -> kernel::ffi::c_uint {

    ///

    /// # Safety

    ///

    /// - This function may only be called from the cpufreq C infrastructure.

    unsafe extern "C" fn get_callback(cpu: u32) -> kernel::ffi::c_uint {

        PolicyCpu::from_cpu(cpu).map_or(0, |mut policy| T::get(&mut policy).map_or(0, |f| f))

    }



    /// Driver's `update_limit` callback.

    extern "C" fn update_limits_callback(ptr: *mut bindings::cpufreq_policy) {

    ///

    /// # Safety

    ///

    /// - This function may only be called from the cpufreq C infrastructure.

    /// - The pointer arguments must be valid pointers.

    unsafe extern "C" fn update_limits_callback(ptr: *mut bindings::cpufreq_policy) {

        // SAFETY: The `ptr` is guaranteed to be valid by the contract with the C code for the

        // lifetime of `policy`.

        let policy = unsafe { Policy::from_raw_mut(ptr) };
@@ -1276,8 +1339,11 @@ extern "C" fn update_limits_callback(ptr: *mut bindings::cpufreq_policy) { 


    /// Driver's `bios_limit` callback.

    ///

    /// SAFETY: Called from C. Inputs must be valid pointers.

    extern "C" fn bios_limit_callback(cpu: i32, limit: *mut u32) -> kernel::ffi::c_int {

    /// # Safety

    ///

    /// - This function may only be called from the cpufreq C infrastructure.

    /// - The pointer arguments must be valid pointers.

    unsafe extern "C" fn bios_limit_callback(cpu: i32, limit: *mut u32) -> kernel::ffi::c_int {

        from_result(|| {

            let mut policy = PolicyCpu::from_cpu(cpu as u32)?;
@@ -1288,8 +1354,11 @@ extern "C" fn bios_limit_callback(cpu: i32, limit: *mut u32) -> kernel::ffi::c_i 


    /// Driver's `set_boost` callback.

    ///

    /// SAFETY: Called from C. Inputs must be valid pointers.

    extern "C" fn set_boost_callback(

    /// # Safety

    ///

    /// - This function may only be called from the cpufreq C infrastructure.

    /// - The pointer arguments must be valid pointers.

    unsafe extern "C" fn set_boost_callback(

        ptr: *mut bindings::cpufreq_policy,

        state: i32,

    ) -> kernel::ffi::c_int {
@@ -1303,8 +1372,11 @@ extern "C" fn set_boost_callback( 


    /// Driver's `register_em` callback.

    ///

    /// SAFETY: Called from C. Inputs must be valid pointers.

    extern "C" fn register_em_callback(ptr: *mut bindings::cpufreq_policy) {

    /// # Safety

    ///

    /// - This function may only be called from the cpufreq C infrastructure.

    /// - The pointer arguments must be valid pointers.

    unsafe extern "C" fn register_em_callback(ptr: *mut bindings::cpufreq_policy) {

        // SAFETY: The `ptr` is guaranteed to be valid by the contract with the C code for the

        // lifetime of `policy`.

        let policy = unsafe { Policy::from_raw_mut(ptr) };