2
0
mirror of git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2025-09-04 20:19:47 +08:00

Compare commits

...

10 Commits

Author SHA1 Message Date
Linus Torvalds
52025b8fc9 Driver core fixes for 6.16-rc3
- Fix swapped handling of lru_gen and lru_gen_full debugfs files in
     vmscan.
 
   - Fix debugfs mount options (uid, gid, mode) being silently ignored.
 
   - Fix leak of devres action in the unwind path of Devres::new().
 
   - Documentation
 
     - Expand and fix documentation of (outdated) Device, DeviceContext
       and generic driver infrastructure.
 
     - Fix C header link of faux device abstractions.
 
     - Clarify expected interaction with the security team.
 
     - Smooth text flow in the security bug reporting process
       documentation.
 -----BEGIN PGP SIGNATURE-----
 
 iHUEABYKAB0WIQS2q/xV6QjXAdC7k+1FlHeO1qrKLgUCaKmYLgAKCRBFlHeO1qrK
 LuUiAQDMA7wZCdzvU8kZazpVpiN5t4Y/EeCztbZJlTG1b0F66QEAgKfgBbdKdgvu
 LNSXY0Mo6/t6RbFbW5+wR4R+sGn6PwQ=
 =wBy0
 -----END PGP SIGNATURE-----

Merge tag 'driver-core-6.17-rc3' of git://git.kernel.org/pub/scm/linux/kernel/git/driver-core/driver-core

Pull driver core fixes from Danilo Krummrich:

 - Fix swapped handling of lru_gen and lru_gen_full debugfs files in
   vmscan

 - Fix debugfs mount options (uid, gid, mode) being silently ignored

 - Fix leak of devres action in the unwind path of Devres::new()

 - Documentation:
     - Expand and fix documentation of (outdated) Device, DeviceContext
       and generic driver infrastructure
     - Fix C header link of faux device abstractions
     - Clarify expected interaction with the security team
     - Smooth text flow in the security bug reporting process
       documentation

* tag 'driver-core-6.17-rc3' of git://git.kernel.org/pub/scm/linux/kernel/git/driver-core/driver-core:
  Documentation: smooth the text flow in the security bug reporting process
  Documentation: clarify the expected collaboration with security bugs reporters
  debugfs: fix mount options not being applied
  rust: devres: fix leaking call to devm_add_action()
  rust: faux: fix C header link
  driver: rust: expand documentation for driver infrastructure
  device: rust: expand documentation for Device
  device: rust: expand documentation for DeviceContext
  mm/vmscan: fix inverted polarity in lru_gen_seq_show()
2025-08-23 09:04:32 -04:00
Willy Tarreau
3a68841d1d Documentation: smooth the text flow in the security bug reporting process
The text was presenting the team, the the e-mail address, then some of
the expectations, then what form of e-mail is expected. By switching
the e-mail paragraph two paragraphs later and dropping the "Contact"
sub-section, we can have a more natural flow that presents the team,
then its expectation, then how to best contribute, then where to send.

And more importantly, it increases the chances that reporters have read
the prerequisites before finding the e-mail address.

Signed-off-by: Willy Tarreau <w@1wt.eu>
Reviewed-by: Kees Cook <kees@kernel.org>
Link: https://lore.kernel.org/r/20250814192730.19252-2-w@1wt.eu
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2025-08-17 12:23:30 +02:00
Willy Tarreau
d49172bbd7 Documentation: clarify the expected collaboration with security bugs reporters
Some bug reports sent to the security team sometimes lack any explanation,
are only AI-generated without verification, or sometimes it can simply be
difficult to have a conversation with an invisible reporter belonging to
an opaque team. This fortunately remains rare but the trend has been
steadily increasing over the last years and it seems important to clarify
what developers expect from reporters to avoid frustration on any side and
keep the process efficient.

Signed-off-by: Willy Tarreau <w@1wt.eu>
Reviewed-by: Kees Cook <kees@kernel.org>
Link: https://lore.kernel.org/r/20250814192730.19252-1-w@1wt.eu
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2025-08-17 12:23:28 +02:00
Charalampos Mitrodimas
ba6cc29351 debugfs: fix mount options not being applied
Mount options (uid, gid, mode) are silently ignored when debugfs is
mounted. This is a regression introduced during the conversion to the
new mount API.

When the mount API conversion was done, the parsed options were never
applied to the superblock when it was reused. As a result, the mount
options were ignored when debugfs was mounted.

Fix this by following the same pattern as the tracefs fix in commit
e4d32142d1 ("tracing: Fix tracefs mount options"). Call
debugfs_reconfigure() in debugfs_get_tree() to apply the mount options
to the superblock after it has been created or reused.

As an example, with the bug the "mode" mount option is ignored:

  $ mount -o mode=0666 -t debugfs debugfs /tmp/debugfs_test
  $ mount | grep debugfs_test
  debugfs on /tmp/debugfs_test type debugfs (rw,relatime)
  $ ls -ld /tmp/debugfs_test
  drwx------ 25 root root 0 Aug  4 14:16 /tmp/debugfs_test

With the fix applied, it works as expected:

  $ mount -o mode=0666 -t debugfs debugfs /tmp/debugfs_test
  $ mount | grep debugfs_test
  debugfs on /tmp/debugfs_test type debugfs (rw,relatime,mode=666)
  $ ls -ld /tmp/debugfs_test
  drw-rw-rw- 37 root root 0 Aug  2 17:28 /tmp/debugfs_test

Fixes: a20971c187 ("vfs: Convert debugfs to use the new mount API")
Closes: https://bugzilla.kernel.org/show_bug.cgi?id=220406
Cc: stable <stable@kernel.org>
Reviewed-by: Eric Sandeen <sandeen@redhat.com>
Signed-off-by: Charalampos Mitrodimas <charmitro@posteo.net>
Link: https://lore.kernel.org/r/20250816-debugfs-mount-opts-v3-1-d271dad57b5b@posteo.net
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2025-08-17 12:22:25 +02:00
Danilo Krummrich
75a7b151e8 rust: devres: fix leaking call to devm_add_action()
When the data argument of Devres::new() is Err(), we leak the preceding
call to devm_add_action().

In order to fix this, call devm_add_action() in a unit type initializer in
try_pin_init!() after the initializers of all other fields.

Fixes: f5d3ef25d2 ("rust: devres: get rid of Devres' inner Arc")
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Reviewed-by: Benno Lossin <lossin@kernel.org>
Link: https://lore.kernel.org/r/20250812130928.11075-1-dakr@kernel.org
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
2025-08-14 01:52:15 +02:00
Miguel Ojeda
a5ba9ad417 rust: faux: fix C header link
Starting with Rust 1.91.0 (expected 2025-10-30), `rustdoc` has improved
some false negatives around intra-doc links [1], and it found a broken
intra-doc link we currently have:

    error: unresolved link to `include/linux/device/faux.h`
     --> rust/kernel/faux.rs:7:17
      |
    7 | //! C header: [`include/linux/device/faux.h`]
      |                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ no item named `include/linux/device/faux.h` in scope
      |
      = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
      = note: `-D rustdoc::broken-intra-doc-links` implied by `-D warnings`
      = help: to override `-D warnings` add `#[allow(rustdoc::broken_intra_doc_links)]`

Our `srctree/` C header links are not intra-doc links, thus they need
the link destination.

Thus fix it.

Cc: stable <stable@kernel.org>
Link: https://github.com/rust-lang/rust/pull/132748 [1]
Fixes: 78418f300d ("rust/kernel: Add faux device bindings")
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Reviewed-by: Benno Lossin <lossin@kernel.org>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Link: https://lore.kernel.org/r/20250804171311.1186538-1-ojeda@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2025-08-13 17:40:28 +02:00
Danilo Krummrich
970a7c6878 driver: rust: expand documentation for driver infrastructure
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.

Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Link: https://lore.kernel.org/r/20250722150110.23565-4-dakr@kernel.org
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
2025-08-12 15:23:49 +02:00
Danilo Krummrich
d6e26c1ae4 device: rust: expand documentation for Device
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.

Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Link: https://lore.kernel.org/r/20250722150110.23565-3-dakr@kernel.org
[ Add empty line after code blocks, "in" -> "within", remove unnecessary
  pin annotations in class device example. - Danilo ]
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
2025-08-12 15:23:46 +02:00
Danilo Krummrich
82b3644d3d device: rust: expand documentation for DeviceContext
Expand the documentation around DeviceContext states and types, in order
to provide detailed information about their purpose and relationship
with each other.

Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>
Link: https://lore.kernel.org/r/20250722150110.23565-2-dakr@kernel.org
[ Fix two minor typos. - Danilo ]
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
2025-08-12 15:23:38 +02:00
Danilo Krummrich
eb5ca9094a mm/vmscan: fix inverted polarity in lru_gen_seq_show()
Commit a7694ff11a ("vmscan: don't bother with debugfs_real_fops()")
started using debugfs_get_aux_num() to distinguish between the RW
"lru_gen" and the RO "lru_gen_full" file [1].

Willy reported the inverted polarity [2] and Al fixed it up in [3].

However, the patch in [1] was applied. Hence, fix this up accordingly.

Cc: Alexander Viro <viro@zeniv.linux.org.uk>
Cc: Matthew Wilcox <willy@infradead.org>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Link: https://lore.kernel.org/all/20250704040720.GP1880847@ZenIV/ [1]
Link: https://lore.kernel.org/all/aGZu3Z730FQtqxsE@casper.infradead.org/ [2]
Link: https://lore.kernel.org/all/20250704040720.GP1880847@ZenIV/ [3]
Fixes: a7694ff11a ("vmscan: don't bother with debugfs_real_fops()")
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Link: https://lore.kernel.org/r/20250727105937.7480-1-dakr@kernel.org
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
2025-08-10 19:02:56 +02:00
7 changed files with 318 additions and 48 deletions

View File

@ -8,8 +8,22 @@ like to know when a security bug is found so that it can be fixed and
disclosed as quickly as possible. Please report security bugs to the
Linux kernel security team.
Contact
-------
The security team and maintainers almost always require additional
information beyond what was initially provided in a report and rely on
active and efficient collaboration with the reporter to perform further
testing (e.g., verifying versions, configuration options, mitigations, or
patches). Before contacting the security team, the reporter must ensure
they are available to explain their findings, engage in discussions, and
run additional tests. Reports where the reporter does not respond promptly
or cannot effectively discuss their findings may be abandoned if the
communication does not quickly improve.
As it is with any bug, the more information provided the easier it
will be to diagnose and fix. Please review the procedure outlined in
'Documentation/admin-guide/reporting-issues.rst' if you are unclear about what
information is helpful. Any exploit code is very helpful and will not
be released without consent from the reporter unless it has already been
made public.
The Linux kernel security team can be contacted by email at
<security@kernel.org>. This is a private list of security officers
@ -19,13 +33,6 @@ that can speed up the process considerably. It is possible that the
security team will bring in extra help from area maintainers to
understand and fix the security vulnerability.
As it is with any bug, the more information provided the easier it
will be to diagnose and fix. Please review the procedure outlined in
'Documentation/admin-guide/reporting-issues.rst' if you are unclear about what
information is helpful. Any exploit code is very helpful and will not
be released without consent from the reporter unless it has already been
made public.
Please send plain text emails without attachments where possible.
It is much harder to have a context-quoted discussion about a complex
issue if all the details are hidden away in attachments. Think of it like a

View File

@ -183,6 +183,9 @@ static int debugfs_reconfigure(struct fs_context *fc)
struct debugfs_fs_info *sb_opts = sb->s_fs_info;
struct debugfs_fs_info *new_opts = fc->s_fs_info;
if (!new_opts)
return 0;
sync_filesystem(sb);
/* structure copy of new mount options to sb */
@ -282,10 +285,16 @@ static int debugfs_fill_super(struct super_block *sb, struct fs_context *fc)
static int debugfs_get_tree(struct fs_context *fc)
{
int err;
if (!(debugfs_allow & DEBUGFS_ALLOW_API))
return -EPERM;
return get_tree_single(fc, debugfs_fill_super);
err = get_tree_single(fc, debugfs_fill_super);
if (err)
return err;
return debugfs_reconfigure(fc);
}
static void debugfs_free_fc(struct fs_context *fc)

View File

@ -5772,9 +5772,9 @@ static int __init init_lru_gen(void)
if (sysfs_create_group(mm_kobj, &lru_gen_attr_group))
pr_err("lru_gen: failed to create sysfs group\n");
debugfs_create_file_aux_num("lru_gen", 0644, NULL, NULL, 1,
debugfs_create_file_aux_num("lru_gen", 0644, NULL, NULL, false,
&lru_gen_rw_fops);
debugfs_create_file_aux_num("lru_gen_full", 0444, NULL, NULL, 0,
debugfs_create_file_aux_num("lru_gen_full", 0444, NULL, NULL, true,
&lru_gen_ro_fops);
return 0;

View File

@ -15,23 +15,130 @@ use crate::c_str;
pub mod property;
/// 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 Rust 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<Device>`], owning a dedicated reference count.
///
/// An instance of this abstraction can be obtained temporarily or permanent.
/// # Device Types
///
/// A temporary one is bound to the lifetime of the C `struct device` pointer used for creation.
/// A permanent instance is always reference-counted and hence not restricted 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 wrap into a subsystem
/// specific device structure (e.g. `pci::Device`). This is useful for passing it to drivers in
/// `T::probe()`, such that a driver can store the `ARef<Device>` (equivalent to storing a
/// `struct device` pointer in a C driver) for arbitrary purposes, e.g. allocating DMA coherent
/// memory.
/// ## Bus Devices
///
/// A bus device is a [`Device`] that is associated with a physical or virtual bus. Examples of
/// buses include PCI, USB, I2C, and SPI. Devices attached to a bus are registered 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/<bus-name>/devices/`.
///
/// ## Class Devices
///
/// A class device is a [`Device`] that is associated with a logical category 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 class and exposed to
/// userspace via entries in `/sys/class/<class-name>/`.
///
/// # Device Context
///
/// [`Device`] references are generic over a [`DeviceContext`], which represents the type state of
/// a [`Device`].
///
/// As the name indicates, this type state represents the context of the scope 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 [`Device<Bound>`] reference.
///
/// Other [`DeviceContext`] types besides [`Bound`] are [`Normal`], [`Core`] and [`CoreInternal`].
///
/// Unless selected otherwise [`Device`] defaults to the [`Normal`] [`DeviceContext`], which by
/// itself has no additional requirements.
///
/// It is always up to the caller of [`Device::from_raw`] to select the correct [`DeviceContext`]
/// type for the corresponding scope the [`Device`] reference is created in.
///
/// All [`DeviceContext`] types other than [`Normal`] are intended to be used with
/// [bus devices](#bus-devices) only.
///
/// # Implementing Bus Devices
///
/// This section provides a guideline to implement bus specific devices, such as [`pci::Device`] or
/// [`platform::Device`].
///
/// A bus specific device should be defined as follows.
///
/// ```ignore
/// #[repr(transparent)]
/// pub struct Device<Ctx: device::DeviceContext = device::Normal>(
/// Opaque<bindings::bus_device_type>,
/// PhantomData<Ctx>,
/// );
/// ```
///
/// Since devices are reference counted, [`AlwaysRefCounted`] should be implemented for `Device`
/// (i.e. `Device<Normal>`). Note that [`AlwaysRefCounted`] must not be implemented for any other
/// [`DeviceContext`], since all other device context types are only valid within a certain scope.
///
/// In order to be able to implement the [`DeviceContext`] dereference hierarchy, bus device
/// implementations should call the [`impl_device_context_deref`] macro as shown below.
///
/// ```ignore
/// // SAFETY: `Device` is a transparent wrapper of a type that doesn't depend on `Device`'s
/// // generic argument.
/// kernel::impl_device_context_deref!(unsafe { Device });
/// ```
///
/// In order to convert from a any [`Device<Ctx>`] to [`ARef<Device>`], bus devices can implement
/// the following macro call.
///
/// ```ignore
/// kernel::impl_device_context_into_aref!(Device);
/// ```
///
/// Bus devices should also implement the following [`AsRef`] implementation, such that users can
/// easily derive a generic [`Device`] reference.
///
/// ```ignore
/// impl<Ctx: device::DeviceContext> AsRef<device::Device<Ctx>> for Device<Ctx> {
/// fn as_ref(&self) -> &device::Device<Ctx> {
/// ...
/// }
/// }
/// ```
///
/// # Implementing Class Devices
///
/// Class device implementations require less infrastructure and depend slightly more on the
/// specific subsystem.
///
/// An example implementation for a class device could look like this.
///
/// ```ignore
/// #[repr(C)]
/// pub struct Device<T: class::Driver> {
/// dev: Opaque<bindings::class_device_type>,
/// 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 device is generic over the
/// class specific `Driver` trait implementation.
///
/// Just like any device, class devices are reference counted and should hence implement
/// [`AlwaysRefCounted`] for `Device`.
///
/// Class devices should also implement the following [`AsRef`] implementation, such that users can
/// easily derive a generic [`Device`] reference.
///
/// ```ignore
/// impl<T: class::Driver> AsRef<device::Device> for Device<T> {
/// fn as_ref(&self) -> &device::Device {
/// ...
/// }
/// }
/// ```
///
/// An example for a class device implementation is [`drm::Device`].
///
/// # Invariants
///
@ -42,6 +149,12 @@ pub mod property;
///
/// `bindings::device::release` is valid to be called from any thread, hence `ARef<Device>` can be
/// dropped from any thread.
///
/// [`AlwaysRefCounted`]: kernel::types::AlwaysRefCounted
/// [`drm::Device`]: kernel::drm::Device
/// [`impl_device_context_deref`]: kernel::impl_device_context_deref
/// [`pci::Device`]: kernel::pci::Device
/// [`platform::Device`]: kernel::platform::Device
#[repr(transparent)]
pub struct Device<Ctx: DeviceContext = Normal>(Opaque<bindings::device>, PhantomData<Ctx>);
@ -311,28 +424,75 @@ unsafe impl Send for Device {}
// synchronization in `struct device`.
unsafe impl Sync for Device {}
/// 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 certain context, i.e. bus
/// callbacks, such as `probe()`.
/// [`DeviceContext`] is a marker trait for types representing the context 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`], [`Bound`] 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<Core>`] can dereference to a [`Device<Bound>`].
///
/// The following enumeration illustrates the dereference hierarchy of [`DeviceContext`] types.
///
/// - [`CoreInternal`] => [`Core`] => [`Bound`] => [`Normal`]
///
/// Bus devices can automatically implement the dereference hierarchy by using
/// [`impl_device_context_deref`].
///
/// Note that the guarantee for a [`Device`] reference to have a certain [`DeviceContext`] comes
/// from the specific scope the [`Device`] reference is valid in.
///
/// [`impl_device_context_deref`]: kernel::impl_device_context_deref
pub trait DeviceContext: private::Sealed {}
/// 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 [`Device`].
///
/// The normal context does not indicate any specific context. Any `Device<Ctx>` is also a valid
/// [`Device<Normal>`]. It is the only [`DeviceContext`] for which it is valid to implement
/// [`AlwaysRefCounted`] for.
///
/// [`AlwaysRefCounted`]: kernel::types::AlwaysRefCounted
pub struct Normal;
/// The [`Core`] context is the context of a bus specific device when it is 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 appears as argument of
/// any bus specific callback, such as `probe()`.
///
/// The core context indicates that the [`Device<Core>`] 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<Core>`], such that they can only be called
/// from bus callbacks.
pub struct Core;
/// Semantically the same as [`Core`] but reserved for internal usage of the 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 way as the [`Core`]
/// context, with the difference that this [`DeviceContext`] is internal to the corresponding 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 accessible for drivers.
pub struct CoreInternal;
/// The [`Bound`] context is the context of a bus specific device reference when it is guaranteed to
/// be bound for the duration of its lifetime.
/// The [`Bound`] context is the [`DeviceContext`] of a bus specific device when it is guaranteed to
/// be bound to a driver.
///
/// The bound context indicates that for the entire duration of the lifetime of a [`Device<Bound>`]
/// reference, the [`Device`] is guaranteed to be bound to a driver.
///
/// Some APIs, such as [`dma::CoherentAllocation`] or [`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<Bound>`] reference to its users for this scope. This allows users to benefit
/// from optimizations for accessing device resources, see also [`Devres::access`].
///
/// [`Devres`]: kernel::devres::Devres
/// [`Devres::access`]: kernel::devres::Devres::access
/// [`dma::CoherentAllocation`]: kernel::dma::CoherentAllocation
pub struct Bound;
mod private {

View File

@ -115,10 +115,11 @@ pub struct Devres<T: Send> {
/// Contains all the fields shared with [`Self::callback`].
// TODO: Replace with `UnsafePinned`, once available.
//
// Subsequently, the `drop_in_place()` in `Devres::drop` and the explicit `Send` and `Sync'
// impls can be removed.
// Subsequently, the `drop_in_place()` in `Devres::drop` and `Devres::new` as well as the
// explicit `Send` and `Sync' impls can be removed.
#[pin]
inner: Opaque<Inner<T>>,
_add_action: (),
}
impl<T: Send> Devres<T> {
@ -140,7 +141,15 @@ impl<T: Send> Devres<T> {
dev: dev.into(),
callback,
// INVARIANT: `inner` is properly initialized.
inner <- {
inner <- Opaque::pin_init(try_pin_init!(Inner {
devm <- Completion::new(),
revoke <- Completion::new(),
data <- Revocable::new(data),
})),
// TODO: Replace with "initializer code blocks" [1] once available.
//
// [1] https://github.com/Rust-for-Linux/pin-init/pull/69
_add_action: {
// SAFETY: `this` is a valid pointer to uninitialized memory.
let inner = unsafe { &raw mut (*this.as_ptr()).inner };
@ -152,13 +161,13 @@ impl<T: Send> Devres<T> {
// live at least as long as the returned `impl PinInit<Self, Error>`.
to_result(unsafe {
bindings::devm_add_action(dev.as_raw(), Some(callback), inner.cast())
})?;
}).inspect_err(|_| {
let inner = Opaque::cast_into(inner);
Opaque::pin_init(try_pin_init!(Inner {
devm <- Completion::new(),
revoke <- Completion::new(),
data <- Revocable::new(data),
}))
// SAFETY: `inner` is a valid pointer to an `Inner<T>` and valid for both reads
// and writes.
unsafe { core::ptr::drop_in_place(inner) };
})?;
},
})
}

View File

@ -2,8 +2,93 @@
//! Generic support for drivers of different buses (e.g., PCI, Platform, Amba, etc.).
//!
//! Each bus / subsystem is expected to implement [`RegistrationOps`], which allows drivers to
//! register using the [`Registration`] class.
//! This documentation describes how to implement a bus specific driver API 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`] and
//! [`DeviceContext`].
//!
//! # Driver Trait
//!
//! The main driver interface is defined by a bus specific driver trait. For 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<of::IdTable<Self::IdInfo>> = None;
//!
//! /// The table of ACPI device ids supported by the driver.
//! const ACPI_ID_TABLE: Option<acpi::IdTable<Self::IdInfo>> = None;
//!
//! /// Driver probe.
//! fn probe(dev: &Device<device::Core>, id_info: &Self::IdInfo) -> Result<Pin<KBox<Self>>>;
//!
//! /// Driver unbind (optional).
//! fn unbind(dev: &Device<device::Core>, this: Pin<&Self>) {
//! let _ = (dev, this);
//! }
//! }
//! ```
//!
//! For specific examples see [`auxiliary::Driver`], [`pci::Driver`] and [`platform::Driver`].
//!
//! The `probe()` callback should return a `Result<Pin<KBox<Self>>>`, i.e. the driver's private
//! data. The bus abstraction should store the pointer in the corresponding bus device. The generic
//! [`Device`] infrastructure provides common helpers for this purpose on its
//! [`Device<CoreInternal>`] implementation.
//!
//! All driver callbacks should provide a reference to the driver's private data. Once the driver
//! is unbound from the device, the bus abstraction should take back the ownership of the driver's
//! private data from the corresponding [`Device`] and [`drop`] it.
//!
//! All driver callbacks should provide a [`Device<Core>`] reference (see also [`device::Core`]).
//!
//! # Adapter
//!
//! The adapter implementation of a bus represents the abstraction layer between the C bus
//! callbacks and the Rust bus callbacks. It therefore has to be generic over an implementation of
//! the [driver trait](#driver-trait).
//!
//! ```ignore
//! pub struct Adapter<T: Driver>;
//! ```
//!
//! 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 registration 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`] macro.
//!
//! # Device IDs
//!
//! Besides the common device ID types, such as [`of::DeviceId`] and [`acpi::DeviceId`], most buses
//! may need to implement their own device ID types.
//!
//! For this purpose the generic infrastructure in [`device_id`] should be used.
//!
//! [`auxiliary::Driver`]: kernel::auxiliary::Driver
//! [`Core`]: device::Core
//! [`Device`]: device::Device
//! [`Device<Core>`]: device::Device<device::Core>
//! [`Device<CoreInternal>`]: device::Device<device::CoreInternal>
//! [`DeviceContext`]: device::DeviceContext
//! [`device_id`]: kernel::device_id
//! [`module_driver`]: kernel::module_driver
//! [`pci::Driver`]: kernel::pci::Driver
//! [`platform::Driver`]: kernel::platform::Driver
use crate::error::{Error, Result};
use crate::{acpi, device, of, str::CStr, try_pin_init, types::Opaque, ThisModule};

View File

@ -4,7 +4,7 @@
//!
//! This module provides bindings for working with faux devices in kernel modules.
//!
//! C header: [`include/linux/device/faux.h`]
//! C header: [`include/linux/device/faux.h`](srctree/include/linux/device/faux.h)
use crate::{bindings, device, error::code::*, prelude::*};
use core::ptr::{addr_of_mut, null, null_mut, NonNull};