From nobody Mon Oct 6 18:49:03 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (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 D1B3223E34C; Thu, 17 Jul 2025 22:48:20 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752792500; cv=none; b=I3wJ2BUaLUJXOOhSRsxwBlrPJcDf5MBjeYuvka846BzrTQZmuhOMovK0x6aDIj+SMZTbrIFBiJC7AWdlUOJ2n/mSAQvGLXHnQumKsMLP2+/UOl3T9Ow02ByIpfEcLORKmOKR/Vpmqi4qC0rneDRaCVGAqnJnHPo6qK6DWu9iq4c= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752792500; c=relaxed/simple; bh=NSomQBe9GsxuecBlz9tHDynvoC2dGHK58amK9Fm823s=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=JcvYc76hterUw5F0MBRbX5D1EjcD2wM3PCziyBfE4ST5ThcFvaxG66A/9hG6i/vJy1CXBUyXl3UXQgE56jTUzf+4nu3Fxs9BrkatOAUp6tAPeJBW/OwcK5OOlAQgjkXMvpTEQ3Hbc/XOnXe76mOg60tqR8F4iJvEpqVzbhC5U1s= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=mGHsz+tV; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="mGHsz+tV" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 82BAFC4CEEB; Thu, 17 Jul 2025 22:48:17 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1752792500; bh=NSomQBe9GsxuecBlz9tHDynvoC2dGHK58amK9Fm823s=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=mGHsz+tVPYdLfAclOygHZ9kC16UypYZ+dhDHjQVv/mGFz1YvotwRE5miTK+xUTF77 uMkBfag8qLryEBxHTH9cHUp/CLUah/CDJ4cuLBN97KY71W8M9eJYEQqmnhxKLkDO9R YTO3dEbSD+G+hHCbBNwnDfcXgyuxa/NOWkMRVFfMUzhK3aHIZpJFoxlEM8BijKEgGq PVn20sL0BxyYhTTjBIENEflrrAvKjWXtFDqcvUc4rXDQ0cjAoyM+CerBAcGvUq/gH1 J7a4VSrqhMtjucGsq5/M945JAvdmQkeMo9pevVbx2wyjTNoOx9NmZuZXtdqh6V/KZw pxfPvKEvBOp4A== From: Danilo Krummrich To: gregkh@linuxfoundation.org, rafael@kernel.org, ojeda@kernel.org, alex.gaynor@gmail.com, boqun.feng@gmail.com, gary@garyguo.net, bjorn3_gh@protonmail.com, lossin@kernel.org, a.hindborg@kernel.org, aliceryhl@google.com, tmgross@umich.edu Cc: rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org, Danilo Krummrich Subject: [PATCH 1/3] device: rust: documentation for DeviceContext Date: Fri, 18 Jul 2025 00:45:37 +0200 Message-ID: <20250717224806.54763-2-dakr@kernel.org> X-Mailer: git-send-email 2.50.0 In-Reply-To: <20250717224806.54763-1-dakr@kernel.org> References: <20250717224806.54763-1-dakr@kernel.org> 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 Content-Type: text/plain; charset="utf-8" Expand the documentation around DeviceContext states and types, in order to provide detailed information about their purpose and relationship with each other. Signed-off-by: Danilo Krummrich Reviewed-by: Greg Kroah-Hartman --- rust/kernel/device.rs | 63 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 52 insertions(+), 11 deletions(-) diff --git a/rust/kernel/device.rs b/rust/kernel/device.rs index ca82926fd67f..d7ac56628fe5 100644 --- a/rust/kernel/device.rs +++ b/rust/kernel/device.rs @@ -311,28 +311,69 @@ unsafe impl Send for Device {} // synchronization in `struct device`. unsafe impl Sync for Device {} =20 -/// Marker trait for the context of a bus specific device. +/// Marker trait for the context or scope of a bus specific device. /// -/// Some functions of a bus specific device should only be called from a c= ertain context, i.e. bus -/// callbacks, such as `probe()`. +/// [`DeviceContext`] is a marker trait for structures representing the co= ntext of a bus specific +/// [`Device`]. /// -/// This is the marker trait for structures representing the context of a = bus specific device. +/// The specific device context types are: [`CoreInternal`], [`Core`], [`B= ound`] and [`Normal`]. +/// +/// [`DeviceContext`] types are hierarchical, which means that there is a = strict hierarchy that +/// defines which [`DeviceContext`] type can be derived from another. For = instance, any +/// [`Device`] can dereference to a [`Device`]. +/// +/// The following enunumeration illustrates the dereference hierarchy of [= `DeviceContext`] types. +/// +/// - [`CoreInternal`] =3D> [`Core`] =3D> [`Bound`] =3D> [`Normal`] +/// - [`Core`] =3D> [`Bound`] =3D> [`Normal`] +/// - [`Bound`] =3D> [`Normal`] +/// - [`Normal`] +/// +/// Bus devices can automatically implement the dereference hierarchy by u= sing +/// [`impl_device_context_deref`](kernel::impl_device_context_deref). pub trait DeviceContext: private::Sealed {} =20 -/// The [`Normal`] context is the context of a bus specific device when it= is not an argument of -/// any bus callback. +/// The [`Normal`] context is the default [`DeviceContext`] of any [`Devic= e`]. +/// +/// The normal context does not indicate any specific scope. Any `Device` is also a valid +/// [`Device`]. It is the only [`DeviceContext`] for which it is v= alid to implement +/// [`AlwaysRefCounted`](kernel::types::AlwaysRefCounted) for. pub struct Normal; =20 -/// The [`Core`] context is the context of a bus specific device when it i= s supplied as argument of -/// any of the bus callbacks, such as `probe()`. +/// The [`Core`] context is the context of a bus specific device when it a= ppears as argument of +/// any bus specific callback, such as `probe()`. +/// +/// The core context indicates that the [`Device`] reference's scope= is limited to the bus +/// callback it appears in. It is intended to be used for synchronization = purposes. Bus device +/// implementations can implement methods for [`Device`], such that = they can only be called +/// from bus callbacks. pub struct Core; =20 -/// Semantically the same as [`Core`] but reserved for internal usage of t= he corresponding bus +/// Semantically the same as [`Core`], but reserved for internal usage of = the corresponding bus /// abstraction. +/// +/// The internal core context is intended to be used in exactly the same w= ay as the [Core] context, +/// with the difference that this [`DeviceContext`] is internal to the cor= responding bus +/// abstraction. +/// +/// This context mainly exists to share generic [`Device`] infrastructure = that should only be called +/// from bus callbacks with bus abstractions, but without making them acce= ssible for drivers. pub struct CoreInternal; =20 -/// The [`Bound`] context is the context of a bus specific device referenc= e when it is guaranteed to -/// be bound for the duration of its lifetime. +/// The [`Bound`] context is the [`DeviceContext`] of a bus specific devic= e when it is guaranteed to +/// be bound to a driver. +/// +/// The bound context indicates that for the entire duration of the lifeti= me of a [`Device`] +/// reference, the [`Device`] is guaranteed to be bound to a driver. +/// +/// Some APIs, such as [`dma::CoherentAllocation`](kernel::dma::CoherentAl= location) or +/// [`Devres`](kernel::devres::Devres) rely on the [`Device`] to be bound,= which can be proven with +/// the [`Bound`] device context. +/// +/// Any abstraction that can guarantee a scope where the corresponding bus= device is bound, should +/// provide a [`Device`] reference to its users for this scope. Thi= s allows users to benefit +/// from optimizations for accessing device resources, see also +/// [Devres::access](kernel::devres::Devres::access). pub struct Bound; =20 mod private { --=20 2.50.0 From nobody Mon Oct 6 18:49:03 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (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 D2BC6244686; Thu, 17 Jul 2025 22:48:23 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752792503; cv=none; b=pLfQ5wUG5GsjxgJBpcp0Z8Bjy1J6DWW4lBk+o57DBisl5WMYxMxxy+lftb4nXCVSl1qqkJA4GgVRviowOD9vhMe7qFkvrKUJypRoPl9yc/ySrHe/mgWv17mbj1dLhCewd1d4SE9eC+hVVWXUQmBDVo+/TMb9PaKlwdtOoBFZsGs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752792503; c=relaxed/simple; bh=qfqlSvvIDzTlxJUrCtARXaehrvsE3tyuylvblajHCyk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=mBYfaQ0A/ogUUZCZzuWNp4E2RN8zmjAuQjkEXPw48kc7NyAfzOSnlGhBgQnZd0s4NuaM9T977gZb8IAMFf82JHkNcZZH7zUypZo8k6yCw+5CF24xVU3w57nKmQpGckx52xlgR//Xt8hrVcrZH65qs7gmJ/pKNr2ClSg0PCquqmY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=i4KoN78m; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="i4KoN78m" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D1A72C4CEF0; Thu, 17 Jul 2025 22:48:20 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1752792503; bh=qfqlSvvIDzTlxJUrCtARXaehrvsE3tyuylvblajHCyk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=i4KoN78mLYULahr58Iq1zfSVPcbVHPKd5J0zj7xWMjCgxXBXwCWBL3zuo+9KOdF6n AUSrhL+tTjv3iOlfwf8Emb5YBTtvEMLjYwrpbhlXMX5CbfKuMRkORRmi+W55/6fbAb sGKM7XqnCCbTdgKvTtgrNNtBb0btnHA/SykGsCS/aSxskKK6TM5vpAAKXVa5YER3t+ tN7c+YqQPxltUHRYlvEi0Zi2xRAMpvmfAz/gt2DU94bUlkUcGJzlKjQvE2x0OJlE44 1z64MF4ooiMYXhzH//R75wAif/riP63Bqo56kSqG4SkziW/dsixqFZ+SdvvcwZu5/z PWKKa3IHSgVXA== From: Danilo Krummrich To: gregkh@linuxfoundation.org, rafael@kernel.org, ojeda@kernel.org, alex.gaynor@gmail.com, boqun.feng@gmail.com, gary@garyguo.net, bjorn3_gh@protonmail.com, lossin@kernel.org, a.hindborg@kernel.org, aliceryhl@google.com, tmgross@umich.edu Cc: rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org, Danilo Krummrich Subject: [PATCH 2/3] device: rust: expand documentation for Device Date: Fri, 18 Jul 2025 00:45:38 +0200 Message-ID: <20250717224806.54763-3-dakr@kernel.org> X-Mailer: git-send-email 2.50.0 In-Reply-To: <20250717224806.54763-1-dakr@kernel.org> References: <20250717224806.54763-1-dakr@kernel.org> 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 Content-Type: text/plain; charset="utf-8" The documentation for the generic Device type is outdated and deserves much more detail. Hence, expand the documentation and cover topics such as device types, device contexts, as well as information on how to use the generic device infrastructure to implement bus and class specific device types. Signed-off-by: Danilo Krummrich Reviewed-by: Daniel Almeida Reviewed-by: Greg Kroah-Hartman --- rust/kernel/device.rs | 135 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 122 insertions(+), 13 deletions(-) diff --git a/rust/kernel/device.rs b/rust/kernel/device.rs index d7ac56628fe5..1a2ae16d8f11 100644 --- a/rust/kernel/device.rs +++ b/rust/kernel/device.rs @@ -15,23 +15,132 @@ =20 pub mod property; =20 -/// A reference-counted device. +/// The core representation of a device in the kernel's driver model. /// -/// This structure represents the Rust abstraction for a C `struct device`= . This implementation -/// abstracts the usage of an already existing C `struct device` within Ru= st code that we get -/// passed from the C side. +/// This structure represents the Rust abstraction for a C `struct device`= . A [`Device`] can either +/// exist as temporary reference (see also [`Device::from_raw`]), which is= only valid within a +/// certain scope or as [`ARef`], owning a dedicated reference cou= nt. /// -/// An instance of this abstraction can be obtained temporarily or permane= nt. +/// # Device Types /// -/// A temporary one is bound to the lifetime of the C `struct device` poin= ter used for creation. -/// A permanent instance is always reference-counted and hence not restric= ted by any lifetime -/// boundaries. +/// A [`Device`] can represent either a bus device or a class device. /// -/// For subsystems it is recommended to create a permanent instance to wra= p into a subsystem -/// specific device structure (e.g. `pci::Device`). This is useful for pas= sing it to drivers in -/// `T::probe()`, such that a driver can store the `ARef` (equival= ent to storing a -/// `struct device` pointer in a C driver) for arbitrary purposes, e.g. al= locating DMA coherent -/// memory. +/// ## Bus Devices +/// +/// A bus device is a [`Device`] that is associated with a physical or vir= tual bus. Examples of +/// buses include PCI, USB, I2C, and SPI. Devices attached to a bus are re= gistered with a specific +/// bus type, which facilitates matching devices with appropriate drivers = based on IDs or other +/// identifying information. Bus devices are visible in sysfs under `/sys/= bus//devices/`. +/// +/// ## Class Devices +/// +/// A class device is a [`Device`] that is associated with a logical categ= ory of functionality +/// rather than a physical bus. Examples of classes include block devices,= network interfaces, sound +/// cards, and input devices. Class devices are grouped under a common cla= ss and exposed to +/// userspace via entries in `/sys/class//`. +/// +/// # Device Context +/// +/// [`Device`] references are generic over a [`DeviceContext`], which repr= esents the type state of +/// a [`Device`]. +/// +/// As the name indicates, this type state represents the context of the s= cope the [`Device`] +/// reference is valid in. For instance, the [`Bound`] context guarantees = that the [`Device`] is +/// bound to a driver for the entire duration of the existence of a [`Devi= ce`] reference. +/// +/// Other [`DeviceContext`] types besides [`Bound`] are [`Normal`], [`Core= `] and [`CoreInternal`]. +/// +/// Unless selected otherwise [`Device`] defaults to the [`Normal`] [`Devi= ceContext`], which by +/// itself has no additional requirements. +/// +/// It is always up to the caller of [`Device::from_raw`] to select the co= rrect [`DeviceContext`] +/// type for the corresponding scope the [`Device`] reference is created i= n. +/// +/// All [`DeviceContext`] types other than [`Normal`] are intended to be u= sed with +/// [bus devices](#bus-devices) only. +/// +/// # Implementing Bus Devices +/// +/// This section provides a guideline to implement bus specific devices, s= uch as +/// [`pci::Device`](kernel::pci::Device) or [`platform::Device`](kernel::p= latform::Device). +/// +/// A bus specific device should be defined as follows. +/// +/// ```ignore +/// #[repr(transparent)] +/// pub struct Device( +/// Opaque, +/// PhantomData, +/// ); +/// ``` +/// +/// Since devices are reference counted, [`AlwaysRefCounted`](kernel::type= s::AlwaysRefCounted) +/// should be implemented for `Device` (i.e. `Device`). Note that +/// [`AlwaysRefCounted`](kernel::types::AlwaysRefCounted) must not be impl= emented for any other +/// [`DeviceContext`], since all other device context types are only valid= in a certain scope. +/// +/// In order to be able to implement the [`DeviceContext`] dereference hie= rarchy, bus device +/// implementations should call the [`impl_device_context_deref`](kernel::= impl_device_context_deref) +/// macro as shown below. +/// +/// ```ignore +/// // SAFETY: `Device` is a transparent wrapper of a type that doesn't de= pend on `Device`'s +/// // generic argument. +/// kernel::impl_device_context_deref!(unsafe { Device }); +/// ``` +/// In order to convert from a any [`Device`] to [`ARef`], bu= s devices can implement +/// the following macro call. +/// +/// ```ignore +/// kernel::impl_device_context_into_aref!(Device); +/// ``` +/// Bus devices should also implement the following [`AsRef`] implementati= on, such that users can +/// easily derive a generic [`Device`] reference. +/// +/// ```ignore +/// impl AsRef> for Device= { +/// fn as_ref(&self) -> &device::Device { +/// ... +/// } +/// } +/// ``` +/// +/// # Implementing Class Devices +/// +/// Class device implementations require less infrastructure and depend sl= ightly more on the +/// specific subsystem. +/// +/// An example implementation for a class device could look like this. +/// +/// ```ignore +/// #[repr(C)] +/// #[pin_data] +/// pub struct Device { +/// dev: Opaque, +/// #[pin] +/// data: T::Data, +/// } +/// ``` +/// +/// This class device uses the sub-classing pattern to embed the driver's = private data within the +/// allocation of the class device. For this to be possible the class devi= ce is generic over the +/// class specific `Driver` trait implementation. +/// +/// Just like any device, class devices are reference counted and should h= ence implement +/// [`AlwaysRefCounted`](kernel::types::AlwaysRefCounted) for `Device`. +/// +/// Class devices should also implement the following [`AsRef`] implementa= tion, such that users can +/// easily derive a generic [`Device`] reference. +/// +/// ```ignore +/// impl AsRef for Device { +/// fn as_ref(&self) -> &device::Device { +/// ... +/// } +/// } +/// ``` +/// +/// An example for a class device implementation is [`drm::Device`](kernel= ::drm::Device). /// /// # Invariants /// --=20 2.50.0 From nobody Mon Oct 6 18:49:03 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (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 7288A246761; Thu, 17 Jul 2025 22:48:27 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752792507; cv=none; b=gP2OHWHqC3FWiXN8nGFBQLX6GTTDNSdjFmGGiV7B0ORWkCW0AiwEF37jHCBNJp8zTKvvCl+H3Abzvh21LobGrIE8fWL6PJ2O+KG/tejPsQCi6Fm3b8YqCj9tuvFlpgEPlmEeJgt9TG+pT858nTJTc68eNxSi0I0vcGTOZ5Wl4Ho= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752792507; c=relaxed/simple; bh=Psy3Z91cjDmHHJS7M86ndvJxDQH2Gx0mX4Zz1cgIEcw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=QAzQ5QU+GsUO8k4K52u0H/1kIFZDKrSdbKt7AoMowq5yJMtvZjgiyXzCUufuQ/Znt7PRtP3OXnCKn73XbS70AFGGrHbXGaD8coDjb98F1D772DS++Zt7Oe1sb9SRDnDcvrz8O/ZzpfVmp/amQ69DTGdmGhfQKRWtppxTZfPpmlg= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=pqvnImvn; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="pqvnImvn" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2C164C4CEE3; Thu, 17 Jul 2025 22:48:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1752792507; bh=Psy3Z91cjDmHHJS7M86ndvJxDQH2Gx0mX4Zz1cgIEcw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=pqvnImvnSer1Gge6lQzqMDGq8GzgNy5m1m0ykGAR9OwsR+dOGP3K/IKZoNFMsnsco 9suPF5g80A7LwFlq857f8rNCl/nJ0lbUOZQDNGtxIkSojG88Zl5MS4HK2x+GZBL+FF +REFhPtdTDpkl3cQc7TnKlKRa/fWsNyqWMyDpMghmF6BZ+0VfTdRbhkoqn/RYlUvNR c9rpUe8XKcrCo5JMa/AN+pqgAJF0NLjGN5D7ewIEWZd4T1bc1+5lQTGgc2muRSWxVX 3UG1KmgyXNqbeLT3LyfqujUg2rFXCvuwTuDi4qmzy6igag+u3ZTgTlAGXRwpUilPla /w/IhPz0gIdpg== From: Danilo Krummrich To: gregkh@linuxfoundation.org, rafael@kernel.org, ojeda@kernel.org, alex.gaynor@gmail.com, boqun.feng@gmail.com, gary@garyguo.net, bjorn3_gh@protonmail.com, lossin@kernel.org, a.hindborg@kernel.org, aliceryhl@google.com, tmgross@umich.edu Cc: rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org, Danilo Krummrich Subject: [PATCH 3/3] driver: rust: expand documentation for driver infrastructure Date: Fri, 18 Jul 2025 00:45:39 +0200 Message-ID: <20250717224806.54763-4-dakr@kernel.org> X-Mailer: git-send-email 2.50.0 In-Reply-To: <20250717224806.54763-1-dakr@kernel.org> References: <20250717224806.54763-1-dakr@kernel.org> 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 Content-Type: text/plain; charset="utf-8" Add documentation about generic driver infrastructure, representing a guideline on how the generic driver infrastructure is intended to be used to implement bus specific driver APIs. This covers aspects such as the bus specific driver trait, adapter implementation, driver registration and custom device ID types. Signed-off-by: Danilo Krummrich Reviewed-by: Daniel Almeida Reviewed-by: Greg Kroah-Hartman --- rust/kernel/driver.rs | 82 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 80 insertions(+), 2 deletions(-) diff --git a/rust/kernel/driver.rs b/rust/kernel/driver.rs index a8f2675ba7a7..0bb80ad7aea4 100644 --- a/rust/kernel/driver.rs +++ b/rust/kernel/driver.rs @@ -2,8 +2,86 @@ =20 //! Generic support for drivers of different buses (e.g., PCI, Platform, A= mba, etc.). //! -//! Each bus / subsystem is expected to implement [`RegistrationOps`], whi= ch allows drivers to -//! register using the [`Registration`] class. +//! This documentation describes how to implement a bus specific driver AP= I and how to align it with +//! the design of (bus specific) devices. +//! +//! Note: Readers are expected to know the content of the documentation of +//! [`Device`](device::Device) and [`device::DeviceContext`]. +//! +//! # Driver Trait +//! +//! The main driver interface is defined by a bus specific driver trait. F= or instance: +//! +//! ```ignore +//! pub trait Driver: Send { +//! /// The type holding information about each device ID supported by= the driver. +//! type IdInfo: 'static; +//! +//! /// The table of OF device ids supported by the driver. +//! const OF_ID_TABLE: Option> =3D None; +//! +//! /// The table of ACPI device ids supported by the driver. +//! const ACPI_ID_TABLE: Option> =3D None; +//! +//! /// Driver probe. +//! fn probe(dev: &Device, id_info: &Self::IdInfo) -> Re= sult>>; +//! +//! /// Driver unbind (optional). +//! fn unbind(dev: &Device, this: Pin<&Self>) { +//! let _ =3D (dev, this); +//! } +//! } +//! ``` +//! +//! For specific examples see [`pci::Driver`](kernel::pci::Driver), +//! [`platform::Driver`](kernel::platform::Driver) and +//! [`auxiliary::Driver`](kernel::auxiliary::Driver). +//! +//! The `probe()` callback should return a `Result>>`, i.e.= the driver's private +//! data. The bus abstraction should store the pointer in the correspondin= g bus device. The generic +//! [`Device`](device::Device) infrastructure provides common helpers for = this purpose on its +//! [`Device`](device::Device) impleme= ntation. +//! +//! All driver callbacks should provide a reference to the driver's privat= e data. Once the driver +//! is unbound from the device, the bus abstraction should take back the o= wnership of the driver's +//! private data from the corresponding [`Device`](device::Device) and [`d= rop`] it. +//! +//! All driver callbacks should provide a [`Device`](device::Device<= device::Core>) reference +//! (see also [`device::Core`]). +//! +//! # Adapter +//! +//! The adapter implementation of a bus represents the abstraction layer b= etween the C bus +//! callbacks and the Rust bus callbacks. It therefore has to be generic o= ver an implementation of +//! the [driver trait](#driver-trait). +//! +//! ```ignore +//! pub struct Adapter; +//! ``` +//! +//! There's a common [`Adapter`] trait that can be implemented to inherit = common driver +//! infrastructure, such as finding the ID info from an [`of::IdTable`] or= [`acpi::IdTable`]. +//! +//! # Driver Registration +//! +//! In order to register C driver types (such as `struct platform_driver`)= the [adapter](#adapter) +//! should implement the [`RegistrationOps`] trait. +//! +//! This trait implementation can be used to create the actual registratio= n with the common +//! [`Registration`] type. +//! +//! Typically, bus abstractions want to provide a bus specific `module_bus= _driver!` macro, which +//! creates a kernel module with exactly one [`Registration`] for the bus = specific adapter. +//! +//! The generic driver infrastructure provides a helper for this with the +//! [`module_driver`](kernel::module_driver) macro. +//! +//! # Device IDs +//! +//! Besides the common device ID types, such as [`of::DeviceId`] and [`acp= i::DeviceId`], most buses +//! may need to implement their own device ID types. +//! +//! For this purpose the generic infrastructure in [`device_id`](kernel::d= evice_id) should be used. =20 use crate::error::{Error, Result}; use crate::{acpi, device, of, str::CStr, try_pin_init, types::Opaque, This= Module}; --=20 2.50.0