From nobody Thu Oct 9 16:40:33 2025 Received: from mailout2.w1.samsung.com (mailout2.w1.samsung.com [210.118.77.12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id E5E192E88A5 for ; Tue, 17 Jun 2025 14:08:40 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=210.118.77.12 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750169323; cv=none; b=YR+/2PtkXGQs0+y6PcGKMkDoUg+ATVsSrxtU7XTE377TVdL434Qnn9A73aQwDosDIA13rBrH2VW4AQqOk5O5EhYdakOz5bUtzQPXj9ImIQ5nJbAaPWv2rH8i3PWk4dtl55b/15QZAKo1HeBQLgdsrR6bngXFbO6U8+7dE683ld8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750169323; c=relaxed/simple; bh=ju74EzJTUXYF36RcUpC17pYuS1lChtpc175U1ulUcNc=; h=From:Date:Subject:MIME-Version:Message-Id:In-Reply-To:To:Cc: Content-Type:References; b=lBKDVU1SPuSOHyRv+Oqwe+30hLeaMsHn1Xj3tu7JRb84XKk7JPDVs3ey5gBM2b9CCiY1mHa8tzugBXRGhrs/jNtephYhgOwApkGleF8UbHf/S6lKrH24SQLqIa+Msh20MP8zuURM8cPwDTbnZnU5CQ8Yk0mu8fJJfjBPATf+Nmc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=samsung.com; spf=pass smtp.mailfrom=samsung.com; dkim=pass (1024-bit key) header.d=samsung.com header.i=@samsung.com header.b=FMJ7/DP2; arc=none smtp.client-ip=210.118.77.12 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=samsung.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=samsung.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=samsung.com header.i=@samsung.com header.b="FMJ7/DP2" Received: from eucas1p2.samsung.com (unknown [182.198.249.207]) by mailout2.w1.samsung.com (KnoxPortal) with ESMTP id 20250617140837euoutp022efa61f384bb0e6eeaf532a573e5e1a4~J2bi_a-Jz0211802118euoutp02_ for ; Tue, 17 Jun 2025 14:08:37 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 mailout2.w1.samsung.com 20250617140837euoutp022efa61f384bb0e6eeaf532a573e5e1a4~J2bi_a-Jz0211802118euoutp02_ DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=samsung.com; s=mail20170921; t=1750169317; bh=qO3jU7spwp9AnsPu6rlaK9fzxjqj1cRECEod63pnXa0=; h=From:Date:Subject:In-Reply-To:To:Cc:References:From; b=FMJ7/DP2nk9W7Lw/N8GJcJEa1OGw+jt2V1rFSejISYpNfxdudyMFMUoGzcZpSHBj6 gjAxojbL/LRW+rXwvs1aspRaJgqvsHDfaDfAH/JgjyLaLerRUz/OGnCea88WH3EXWS eFwafNTzcYEHYw0v6XGY9EFwkf4a1MXesF0YWnxE= Received: from eusmtip1.samsung.com (unknown [203.254.199.221]) by eucas1p1.samsung.com (KnoxPortal) with ESMTPA id 20250617140836eucas1p1531fccff82c0fcec217ca3526ae09124~J2biTJd7d0447904479eucas1p19; Tue, 17 Jun 2025 14:08:36 +0000 (GMT) Received: from AMDC4942.eu.corp.samsungelectronics.net (unknown [106.210.136.40]) by eusmtip1.samsung.com (KnoxPortal) with ESMTPA id 20250617140835eusmtip1f182b6f740177efd358f7dc18d1468f8~J2bhITtQI2854428544eusmtip1I; Tue, 17 Jun 2025 14:08:35 +0000 (GMT) From: Michal Wilczynski Date: Tue, 17 Jun 2025 16:07:25 +0200 Subject: [PATCH v3 2/9] rust: pwm: Add core 'Device' and 'Chip' object wrappers Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Message-Id: <20250617-rust-next-pwm-working-fan-for-sending-v3-2-1cca847c6f9f@samsung.com> In-Reply-To: <20250617-rust-next-pwm-working-fan-for-sending-v3-0-1cca847c6f9f@samsung.com> To: =?utf-8?q?Uwe_Kleine-K=C3=B6nig?= , Miguel Ojeda , Alex Gaynor , Boqun Feng , Gary Guo , =?utf-8?q?Bj=C3=B6rn_Roy_Baron?= , Andreas Hindborg , Alice Ryhl , Trevor Gross , Danilo Krummrich , Michal Wilczynski , Drew Fustini , Guo Ren , Fu Wei , Rob Herring , Krzysztof Kozlowski , Conor Dooley , Paul Walmsley , Palmer Dabbelt , Albert Ou , Alexandre Ghiti , Marek Szyprowski , Benno Lossin , Michael Turquette , Stephen Boyd , Benno Lossin Cc: linux-kernel@vger.kernel.org, linux-pwm@vger.kernel.org, rust-for-linux@vger.kernel.org, linux-riscv@lists.infradead.org, devicetree@vger.kernel.org, linux-clk@vger.kernel.org X-Mailer: b4 0.15-dev X-CMS-MailID: 20250617140836eucas1p1531fccff82c0fcec217ca3526ae09124 X-Msg-Generator: CA Content-Type: text/plain; charset="utf-8" X-RootMTR: 20250617140836eucas1p1531fccff82c0fcec217ca3526ae09124 X-EPHeader: CA X-CMS-RootMailID: 20250617140836eucas1p1531fccff82c0fcec217ca3526ae09124 References: <20250617-rust-next-pwm-working-fan-for-sending-v3-0-1cca847c6f9f@samsung.com> Building on the basic data types, this commit introduces the central object abstractions for the PWM subsystem: Device and Chip. It also includes the core trait implementations that make the Chip wrapper a complete, safe, and managed object. The main components of this change are: - Device and Chip Structs: These structs wrap the underlying struct pwm_device and struct pwm_chip C objects, providing safe, idiomatic methods to access their fields. - Core Trait Implementations for Chip: - AlwaysRefCounted: Links the Chip's lifetime to its embedded struct device reference counter. This enables automatic lifetime management via ARef. - Send and Sync: Marks the Chip wrapper as safe for use across threads. This is sound because the C core handles all necessary locking for the underlying object's state. These wrappers and traits form a robust foundation for building PWM drivers in Rust. Signed-off-by: Michal Wilczynski --- rust/kernel/pwm.rs | 227 +++++++++++++++++++++++++++++++++++++++++++++++++= +++- 1 file changed, 225 insertions(+), 2 deletions(-) diff --git a/rust/kernel/pwm.rs b/rust/kernel/pwm.rs index ed681b228c414e7ae8bf80ca649ad497c9dc4ec3..8c4c27a4e4fc9da2fc8ea5015df= 2a315cfc6b932 100644 --- a/rust/kernel/pwm.rs +++ b/rust/kernel/pwm.rs @@ -8,10 +8,12 @@ =20 use crate::{ bindings, + device, + error, prelude::*, - types::Opaque, + types::{ARef, AlwaysRefCounted, ForeignOwnable, Opaque}, }; -use core::convert::TryFrom; +use core::{convert::TryFrom, ptr::NonNull}; =20 /// Maximum size for the hardware-specific waveform representation buffer. /// @@ -196,3 +198,224 @@ pub fn set_usage_power(&mut self, usage_power: bool) { self.0.usage_power =3D usage_power; } } + +/// Wrapper for a PWM device [`struct pwm_device`](srctree/include/linux/p= wm.h). +#[repr(transparent)] +pub struct Device(Opaque); + +impl Device { + /// Creates a temporary `&mut Device` from a raw C pointer for use in = callbacks. + /// + /// It returns a mutable reference (`&mut Self`) because the underlyin= g C APIs + /// for PWM operations use non-const pointers (`struct pwm_device *`).= This + /// signals that the functions in the vtable are permitted to mutate t= he + /// device's state (e.g., by writing to hardware registers). Using `&m= ut` + /// allows the `PwmOps` trait to accurately model this behavior and le= verage + /// Rust's aliasing rules for greater safety. + /// + /// # Safety + /// + /// The caller must ensure that `ptr` is a valid, non-null pointer to + /// `bindings::pwm_device` that is properly initialized. + /// The `pwm_device` must remain valid for the lifetime `'a`. + /// The caller must also ensure that Rust's aliasing rules are upheld. + pub(crate) unsafe fn from_ptr<'a>(ptr: *mut bindings::pwm_device) -> &= 'a mut Self { + // SAFETY: Caller guarantees `ptr` is valid and meets lifetime/ali= asing. + // `Self` is `#[repr(transparent)]`, so casting is valid. + unsafe { &mut *ptr.cast::() } + } + + /// Returns a raw pointer to the underlying `pwm_device`. + fn as_raw(&self) -> *mut bindings::pwm_device { + self.0.get() + } + + /// Gets the hardware PWM index for this device within its chip. + pub fn hwpwm(&self) -> u32 { + // SAFETY: `self.as_raw()` provides a valid pointer for `self`'s l= ifetime. + unsafe { (*self.as_raw()).hwpwm } + } + + /// Gets a reference to the parent `Chip` that this device belongs to. + pub fn chip(&self) -> &Chip { + // SAFETY: `self.as_raw()` provides a valid pointer. (*self.as_raw= ()).chip + // is assumed to be a valid pointer to `pwm_chip` managed by the k= ernel. + // Chip::from_ptr's safety conditions must be met. + unsafe { Chip::from_ptr((*self.as_raw()).chip) } + } + + /// Gets the label for this PWM device, if any. + pub fn label(&self) -> Option<&CStr> { + // SAFETY: self.as_raw() provides a valid pointer. + let label_ptr =3D unsafe { (*self.as_raw()).label }; + if label_ptr.is_null() { + None + } else { + // SAFETY: label_ptr is non-null and points to a C string + // managed by the kernel, valid for the lifetime of the PWM de= vice. + Some(unsafe { CStr::from_char_ptr(label_ptr) }) + } + } + + /// Gets a copy of the board-dependent arguments for this PWM device. + pub fn args(&self) -> Args { + // SAFETY: self.as_raw() gives a valid pointer to `pwm_device`. + // The `args` field is a valid `pwm_args` struct embedded within `= pwm_device`. + // `Args::from_c_ptr`'s safety conditions are met by providing thi= s pointer. + unsafe { Args::from_c_ptr(&(*self.as_raw()).args) } + } + + /// Gets a copy of the current state of this PWM device. + pub fn state(&self) -> State { + // SAFETY: `self.as_raw()` gives a valid pointer. `(*self.as_raw()= ).state` + // is a valid `pwm_state` struct. `State::from_c` copies this data. + State::from_c(unsafe { (*self.as_raw()).state }) + } + + /// Returns `true` if the PWM signal is currently enabled based on its= state. + pub fn is_enabled(&self) -> bool { + self.state().enabled() + } +} + +/// Wrapper for a PWM chip/controller ([`struct pwm_chip`](srctree/include= /linux/pwm.h)). +#[repr(transparent)] +pub struct Chip(Opaque); + +impl Chip { + /// Creates a temporary `&mut Chip` from a raw C pointer for use in ca= llbacks. + /// + /// It returns a mutable reference (`&mut Self`) because the underlyin= g C APIs + /// for PWM operations use non-const pointers (`struct pwm_chip *`). T= his + /// signals that the functions in the vtable are permitted to mutate t= he + /// chip's state (e.g., by calling `set_drvdata` or through operations= that + /// modify hardware registers). Using `&mut` is essential for these ca= ses. + /// + /// # Safety + /// + /// The caller must ensure that `ptr` is a valid, non-null pointer to + /// `bindings::pwm_chip` that is properly initialized. + /// The `pwm_chip` must remain valid for the lifetime `'a`. + /// The caller must also ensure that Rust's aliasing rules are upheld. + pub(crate) unsafe fn from_ptr<'a>(ptr: *mut bindings::pwm_chip) -> &'a= mut Self { + // SAFETY: Caller guarantees `ptr` is valid and meets lifetime/ali= asing. + // `Self` is `#[repr(transparent)]`, so casting is valid. + unsafe { &mut *ptr.cast::() } + } + + /// Returns a raw pointer to the underlying `pwm_chip`. + pub(crate) fn as_raw(&self) -> *mut bindings::pwm_chip { + self.0.get() + } + + /// Gets the number of PWM channels (hardware PWMs) on this chip. + pub fn npwm(&self) -> u32 { + // SAFETY: `self.as_raw()` provides a valid pointer for `self`'s l= ifetime. + unsafe { (*self.as_raw()).npwm } + } + + /// Returns `true` if the chip supports atomic operations for configur= ation. + pub fn is_atomic(&self) -> bool { + // SAFETY: `self.as_raw()` provides a valid pointer for `self`'s l= ifetime. + unsafe { (*self.as_raw()).atomic } + } + + /// Returns a reference to the embedded `struct device` abstraction. + pub fn device(&self) -> &device::Device { + // SAFETY: `self.as_raw()` provides a valid pointer to `bindings::= pwm_chip`. + // The `dev` field is an instance of `bindings::device` embedded w= ithin `pwm_chip`. + // Taking a pointer to this embedded field is valid. + // `device::Device` is `#[repr(transparent)]`. + // The lifetime of the returned reference is tied to `self`. + let dev_field_ptr =3D unsafe { core::ptr::addr_of!((*self.as_raw()= ).dev) }; + // SAFETY: `dev_field_ptr` is a valid pointer to `bindings::device= `. + // Casting and dereferencing is safe due to `repr(transparent)` an= d lifetime. + unsafe { &*(dev_field_ptr.cast::()) } + } + + /// Returns a reference to the parent device of this PWM chip's device. + pub fn parent_device(&self) -> Option<&device::Device> { + self.device().parent() + } + + /// Gets the *typed* driver-specific data associated with this chip's = embedded device. + pub fn drvdata(&self) -> Option<&T> { + // SAFETY: `self.as_raw()` gives a valid pwm_chip pointer. + // `bindings::pwmchip_get_drvdata` is the C function to retrieve d= river data. + let ptr =3D unsafe { bindings::pwmchip_get_drvdata(self.as_raw()) = }; + if ptr.is_null() { + None + } else { + // SAFETY: `ptr` is non-null. Caller ensures `T` is the correc= t type. + // Lifetime of data is managed by the driver that set it. + unsafe { Some(&*(ptr.cast::())) } + } + } + + /// Sets the *typed* driver-specific data associated with this chip's = embedded device. + pub fn set_drvdata(&self, data: T) { + // SAFETY: `self.as_raw()` gives a valid pwm_chip pointer. + // `bindings::pwmchip_set_drvdata` is the C function to set driver= data. + // `data.into_foreign()` provides a valid `*mut c_void`. + unsafe { bindings::pwmchip_set_drvdata(self.as_raw(), data.into_fo= reign().cast()) } + } + + /// Allocates and wraps a PWM chip using `bindings::pwmchip_alloc`. + /// + /// Returns an [`ARef`] managing the chip's lifetime via refcoun= ting + /// on its embedded `struct device`. + pub fn new(parent_dev: &device::Device, npwm: u32, sizeof_priv: usize)= -> Result> { + // SAFETY: `parent_device_for_dev_field.as_raw()` is valid. + // `bindings::pwmchip_alloc` returns a valid `*mut bindings::pwm_c= hip` (refcount 1) + // or an ERR_PTR. + let c_chip_ptr_raw =3D + unsafe { bindings::pwmchip_alloc(parent_dev.as_raw(), npwm, si= zeof_priv) }; + + let c_chip_ptr: *mut bindings::pwm_chip =3D error::from_err_ptr(c_= chip_ptr_raw)?; + + // Cast the `*mut bindings::pwm_chip` to `*mut Chip`. This is vali= d because + // `Chip` is `repr(transparent)` over `Opaque`= , and + // `Opaque` is `repr(transparent)` over `T`. + let chip_ptr_as_self =3D c_chip_ptr.cast::(); + + // SAFETY: `chip_ptr_as_self` points to a valid `Chip` (layout-com= patible with + // `bindings::pwm_chip`) whose embedded device has refcount 1. + // `ARef::from_raw` takes this pointer and manages it via `AlwaysR= efCounted`. + Ok(unsafe { ARef::from_raw(NonNull::new_unchecked(chip_ptr_as_self= )) }) + } +} + +// SAFETY: Implements refcounting for `Chip` using the embedded `struct de= vice`. +unsafe impl AlwaysRefCounted for Chip { + #[inline] + fn inc_ref(&self) { + // SAFETY: `self.0.get()` points to a valid `pwm_chip` because `se= lf` exists. + // The embedded `dev` is valid. `get_device` increments its refcou= nt. + unsafe { + bindings::get_device(core::ptr::addr_of_mut!((*self.0.get()).d= ev)); + } + } + + #[inline] + unsafe fn dec_ref(obj: NonNull) { + let c_chip_ptr =3D obj.cast::().as_ptr(); + + // SAFETY: `obj` is a valid pointer to a `Chip` (and thus `binding= s::pwm_chip`) + // with a non-zero refcount. `put_device` handles decrement and fi= nal release. + unsafe { + bindings::put_device(core::ptr::addr_of_mut!((*c_chip_ptr).dev= )); + } + } +} + +// SAFETY: `Chip` is a wrapper around `*mut bindings::pwm_chip`. The under= lying C +// structure's state is managed and synchronized by the kernel's device mo= del +// and PWM core locking mechanisms. Therefore, it is safe to move the `Chi= p` +// wrapper (and the pointer it contains) across threads. +unsafe impl Send for Chip {} + +// 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 app= ropriate +// kernel locks, which the C core is responsible for. Any interior mutabil= ity is +// handled and synchronized by the C kernel code. +unsafe impl Sync for Chip {} --=20 2.34.1