rust/kernel/pwm.rs

Source file repositories/reference/linux-study-clean/rust/kernel/pwm.rs

File Facts

System
Linux kernel
Corpus path
rust/kernel/pwm.rs
Extension
.rs
Size
28102 bytes
Lines
742
Domain
Rust Kernel Layer
Bucket
Rust API Membrane
Inferred role
Rust Kernel Layer: implementation source
Status
source implementation candidate

Why This File Exists

Rust-side wrappers and abstractions around kernel C APIs, ownership contracts, allocation, synchronization, and module integration.

Dependency Surface

Detected Declarations

Annotated Snippet

fn inc_ref(&self) {
        // SAFETY: `self.0.get()` points to a valid `pwm_chip` because `self` exists.
        // The embedded `dev` is valid. `get_device` increments its refcount.
        unsafe { bindings::get_device(&raw mut (*self.0.get()).dev) };
    }

    #[inline]
    unsafe fn dec_ref(obj: NonNull<Chip<T>>) {
        let c_chip_ptr = obj.cast::<bindings::pwm_chip>().as_ptr();

        // SAFETY: `obj` is a valid pointer to a `Chip` (and thus `bindings::pwm_chip`)
        // with a non-zero refcount. `put_device` handles decrement and final release.
        unsafe { bindings::put_device(&raw mut (*c_chip_ptr).dev) };
    }
}

// SAFETY: `Chip` is a wrapper around `*mut bindings::pwm_chip`. The underlying C
// structure's state is managed and synchronized by the kernel's device model
// and PWM core locking mechanisms. Therefore, it is safe to move the `Chip`
// wrapper (and the pointer it contains) across threads.
unsafe impl<T: PwmOps> Send for Chip<T> {}

// SAFETY: It is safe for multiple threads to have shared access (`&Chip`) because
// the `Chip` data is immutable from the Rust side without holding the appropriate
// kernel locks, which the C core is responsible for. Any interior mutability is
// handled and synchronized by the C kernel code.
unsafe impl<T: PwmOps> Sync for Chip<T> {}

/// A wrapper around `ARef<Chip<T>>` that ensures that `register` can only be called once.
pub struct UnregisteredChip<'a, T: PwmOps> {
    chip: ARef<Chip<T>>,
    parent_dev: &'a device::Device<Bound>,
}

impl<T: PwmOps> UnregisteredChip<'_, T> {
    /// Registers a PWM chip with the PWM subsystem.
    ///
    /// Transfers its ownership to the `devres` framework, which ties its lifetime
    /// to the parent device.
    /// On unbind of the parent device, the `devres` entry will be dropped, automatically
    /// calling `pwmchip_remove`. This function should be called from the driver's `probe`.
    pub fn register(self) -> Result<ARef<Chip<T>>> {
        let c_chip_ptr = self.chip.as_raw();

        // SAFETY: `c_chip_ptr` points to a valid chip with its ops initialized.
        // `__pwmchip_add` is the C function to register the chip with the PWM core.
        to_result(unsafe { bindings::__pwmchip_add(c_chip_ptr, core::ptr::null_mut()) })?;

        let registration = Registration {
            chip: ARef::clone(&self.chip),
        };

        devres::register(self.parent_dev, registration, GFP_KERNEL)?;

        Ok(self.chip)
    }
}

impl<T: PwmOps> Deref for UnregisteredChip<'_, T> {
    type Target = Chip<T>;

    fn deref(&self) -> &Self::Target {
        &self.chip
    }
}

/// A resource guard that ensures `pwmchip_remove` is called on drop.
///
/// This struct is intended to be managed by the `devres` framework by transferring its ownership
/// via [`devres::register`]. This ties the lifetime of the PWM chip registration
/// to the lifetime of the underlying device.
struct Registration<T: PwmOps> {
    chip: ARef<Chip<T>>,
}

impl<T: PwmOps> Drop for Registration<T> {
    fn drop(&mut self) {
        let chip_raw = self.chip.as_raw();

        // SAFETY: `chip_raw` points to a chip that was successfully registered.
        // `bindings::pwmchip_remove` is the correct C function to unregister it.
        // This `drop` implementation is called automatically by `devres` on driver unbind.
        unsafe { bindings::pwmchip_remove(chip_raw) };
    }
}

/// Declares a kernel module that exposes a single PWM driver.
///
/// # Examples
///

Annotation

Implementation Notes