Skip to contentSkip to conversation

DRM Rust abstractions and Nova

RFC PATCH Superseded Danilo Krummrich 9 participants 52 messages May 20, 2024 – Jun 11, 2024

Subsystems (7)

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

cover DRM Rust abstractions and Nova

This patch series implements some basic DRM Rust abstractions and a stub implementation of the Nova GPU driver.

Nova is intended to be developed upstream, starting out with just a stub driver to lift some initial required infrastructure upstream. A more detailed explanation can be found in [1].

This patch series is based on the "Device / Driver and PCI Rust abstractions" series [2].

The DRM bits can also be found in [3] and the Nova bits in [4].

[1] https://lore.kernel.org/dri-devel/Zfsj0_tb-0-tNrJy@cassiopeiae/T/#u
[2] Reply to this mail titled "Device / Driver and PCI Rust abstractions".
[3] https://gitlab.freedesktop.org/drm/misc/kernel/-/tree/topic/rust-drm
[4] https://gitlab.freedesktop.org/drm/nova/-/tree/nova-next

Asahi Lina (5):
rust: drm: ioctl: Add DRM ioctl abstraction
rust: Add a Sealed trait
rust: drm: Add Device and Driver abstractions
rust: drm: file: Add File abstraction
rust: drm: gem: Add GEM object abstraction

Danilo Krummrich (3):
rust: drm: implement AsRef for DRM device
rust: add firmware abstractions
nova: add initial driver stub

 MAINTAINERS                     |  10 +
 drivers/gpu/drm/Kconfig         |   2 +
 drivers/gpu/drm/Makefile        |   1 +
 drivers/gpu/drm/nova/Kconfig    |  11 +
 drivers/gpu/drm/nova/Makefile   |   3 +
 drivers/gpu/drm/nova/driver.rs  | 110 +++++++++
 drivers/gpu/drm/nova/file.rs    |  71 ++++++
 drivers/gpu/drm/nova/gem.rs     |  50 ++++
 drivers/gpu/drm/nova/gpu.rs     | 172 ++++++++++++++
 drivers/gpu/drm/nova/nova.rs    |  20 ++
 include/uapi/drm/nova_drm.h     | 101 ++++++++
 rust/bindings/bindings_helper.h |   6 +
 rust/helpers.c                  |  23 ++
 rust/kernel/drm/device.rs       |  95 ++++++++
 rust/kernel/drm/drv.rs          | 321 +++++++++++++++++++++++++
 rust/kernel/drm/file.rs         | 113 +++++++++
 rust/kernel/drm/gem/mod.rs      | 406 ++++++++++++++++++++++++++++++++
 rust/kernel/drm/ioctl.rs        | 153 ++++++++++++
 rust/kernel/drm/mod.rs          |   9 +
 rust/kernel/firmware.rs         |  74 ++++++
 rust/kernel/lib.rs              |   8 +
 rust/uapi/uapi_helper.h         |   2 +
 22 files changed, 1761 insertions(+)
 create mode 100644 drivers/gpu/drm/nova/Kconfig
 create mode 100644 drivers/gpu/drm/nova/Makefile
 create mode 100644 drivers/gpu/drm/nova/driver.rs
 create mode 100644 drivers/gpu/drm/nova/file.rs
 create mode 100644 drivers/gpu/drm/nova/gem.rs
 create mode 100644 drivers/gpu/drm/nova/gpu.rs
 create mode 100644 drivers/gpu/drm/nova/nova.rs
 create mode 100644 include/uapi/drm/nova_drm.h
 create mode 100644 rust/kernel/drm/device.rs
 create mode 100644 rust/kernel/drm/drv.rs
 create mode 100644 rust/kernel/drm/file.rs
 create mode 100644 rust/kernel/drm/gem/mod.rs
 create mode 100644 rust/kernel/drm/ioctl.rs
 create mode 100644 rust/kernel/drm/mod.rs
 create mode 100644 rust/kernel/firmware.rs

base-commit: 4a67fc8e2330cbd57b49d8ea703ffbf7292ef828

Signature · 1 line
2.45.1
#1 lore raw

RFC PATCH 1/8 rust: drm: ioctl: Add DRM ioctl abstraction

From: Asahi Lina <[email protected]>

DRM drivers need to be able to declare which driver-specific ioctls they support. Add an abstraction implementing the required types and a helper macro to generate the ioctl definition inside the DRM driver.

Note that this macro is not usable until further bits of the abstraction are in place (but it will not fail to compile on its own, if not called).

---
 rust/bindings/bindings_helper.h |   1 +
 rust/kernel/drm/ioctl.rs        | 153 ++++++++++++++++++++++++++++++++
 rust/kernel/drm/mod.rs          |   5 ++
 rust/kernel/lib.rs              |   2 +
 rust/uapi/uapi_helper.h         |   1 +
 5 files changed, 162 insertions(+)
 create mode 100644 rust/kernel/drm/ioctl.rs
 create mode 100644 rust/kernel/drm/mod.rs
rust/bindings/bindings_helper.h +1 -0
index 32221de16e57..14188034285a 100644
@@ -6,6 +6,7 @@
  * Sorted alphabetically.
  */
 
+#include <drm/drm_ioctl.h>
 #include <kunit/test.h>
 #include <linux/errname.h>
 #include <linux/ethtool.h>
rust/kernel/drm/ioctl.rs new file +153 -0

153 lines not on this page · raw message

rust/kernel/drm/mod.rs new file +5 -0
new file mode 100644
index 000000000000..9ec6d7cbcaf3
@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: GPL-2.0 OR MIT
+
+//! DRM subsystem abstractions.
+
+pub mod ioctl;
rust/kernel/lib.rs +2 -0
index 15730deca822..cb0dd3d76729 100644
@@ -32,6 +32,8 @@
 pub mod device;
 pub mod devres;
 pub mod driver;
+#[cfg(CONFIG_DRM = "y")]
+pub mod drm;
 pub mod error;
 pub mod init;
 pub mod ioctl;
rust/uapi/uapi_helper.h +1 -0
index 08f5e9334c9e..ed42a456da2e 100644
@@ -7,5 +7,6 @@
  */
 
 #include <uapi/asm-generic/ioctl.h>
+#include <uapi/drm/drm.h>
 #include <uapi/linux/mii.h>
 #include <uapi/linux/ethtool.h>
Signature · 1 line
2.45.1
#2 lore raw

RFC PATCH 2/8 rust: Add a Sealed trait

In reply to Danilo Krummrich

From: Asahi Lina <[email protected]>

Some traits exposed by the kernel crate may not be intended to be implemented by downstream modules. Add a Sealed trait to allow avoiding this using the sealed trait pattern.

---
 rust/kernel/lib.rs | 5 +++++
 1 file changed, 5 insertions(+)
rust/kernel/lib.rs +5 -0
index cb0dd3d76729..6415968ee3b8 100644
@@ -65,6 +65,11 @@
 #[doc(hidden)]
 pub use build_error::build_error;
 
+pub(crate) mod private {
+    #[allow(unreachable_pub)]
+    pub trait Sealed {}
+}
+
 /// Prefix to appear before log messages printed from within the `kernel` crate.
 const __LOG_PREFIX: &[u8] = b"rust_kernel\0";
 
Signature · 1 line
2.45.1
#3 lore raw

RFC PATCH 3/8 rust: drm: Add Device and Driver abstractions

In reply to Danilo Krummrich

From: Asahi Lina <[email protected]>

Add abstractions for DRM drivers and devices. These go together in one commit since both are fairly tightly coupled types.

A few things have been stubbed out, to be implemented as further bits of the DRM subsystem are introduced.

---
 rust/bindings/bindings_helper.h |   2 +
 rust/kernel/drm/device.rs       |  87 +++++++++
 rust/kernel/drm/drv.rs          | 318 ++++++++++++++++++++++++++++++++
 rust/kernel/drm/mod.rs          |   2 +
 4 files changed, 409 insertions(+)
 create mode 100644 rust/kernel/drm/device.rs
 create mode 100644 rust/kernel/drm/drv.rs
rust/bindings/bindings_helper.h +2 -0
index 14188034285a..831fbfe03a47 100644
@@ -6,6 +6,8 @@
  * Sorted alphabetically.
  */
 
+#include <drm/drm_device.h>
+#include <drm/drm_drv.h>
 #include <drm/drm_ioctl.h>
 #include <kunit/test.h>
 #include <linux/errname.h>
rust/kernel/drm/device.rs new file +87 -0

87 lines not on this page · raw message

rust/kernel/drm/drv.rs new file +318 -0

318 lines not on this page · raw message

rust/kernel/drm/mod.rs +2 -0
index 9ec6d7cbcaf3..69376b3c6db9 100644
@@ -2,4 +2,6 @@
 
 //! DRM subsystem abstractions.
 
+pub mod device;
+pub mod drv;
 pub mod ioctl;
Signature · 1 line
2.45.1
#4 lore raw

Re: [RFC PATCH 3/8] rust: drm: Add Device and Driver abstractions

Quoted 19 lines · Danilo Krummrich

From: Asahi Lina <[email protected]>

Add abstractions for DRM drivers and devices. These go together in one commit since both are fairly tightly coupled types.

A few things have been stubbed out, to be implemented as further bits of the DRM subsystem are introduced.

---
 rust/bindings/bindings_helper.h |   2 +
 rust/kernel/drm/device.rs       |  87 +++++++++
 rust/kernel/drm/drv.rs          | 318 ++++++++++++++++++++++++++++++++
 rust/kernel/drm/mod.rs          |   2 +
 4 files changed, 409 insertions(+)
 create mode 100644 rust/kernel/drm/device.rs
 create mode 100644 rust/kernel/drm/drv.rs

[...]

Quoted 36 lines
rust/kernel/drm/drv.rs new file +30 -0
new file mode 100644
index 000000000000..5dd8f3f8df7c
@@ -0,0 +1,318 @@
+// SPDX-License-Identifier: GPL-2.0 OR MIT
+
+//! DRM driver core.
+//!
+//! C header: [`include/linux/drm/drm_drv.h`](../../../../include/linux/drm/drm_drv.h)
+
+use crate::{
+    alloc::flags::*,
+    bindings, device, drm,
+    error::code::*,
+    error::{Error, Result},
+    prelude::*,
+    private::Sealed,
+    str::CStr,
+    types::{ARef, ForeignOwnable},
+    ThisModule,
+};
+use core::{
+    marker::{PhantomData, PhantomPinned},
+    pin::Pin,
+};
+use macros::vtable;
+
+/// Driver use the GEM memory manager. This should be set for all modern drivers.
+pub const FEAT_GEM: u32 = bindings::drm_driver_feature_DRIVER_GEM;
+/// Driver supports mode setting interfaces (KMS).
+pub const FEAT_MODESET: u32 = bindings::drm_driver_feature_DRIVER_MODESET;
+/// Driver supports dedicated render nodes.
+pub const FEAT_RENDER: u32 = bindings::drm_driver_feature_DRIVER_RENDER;
+/// Driver supports the full atomic modesetting userspace API.

rust/kernel/drm/drv.rs line 40

Quoted 10 lines
rust/kernel/drm/drv.rs new file +10 -0
+///
+/// Drivers which only use atomic internally, but do not support the full userspace API (e.g. not
+/// all properties converted to atomic, or multi-plane updates are not guaranteed to be tear-free)
+/// should not set this flag.
+pub const FEAT_ATOMIC: u32 = bindings::drm_driver_feature_DRIVER_ATOMIC;
+/// Driver supports DRM sync objects for explicit synchronization of command submission.
+pub const FEAT_SYNCOBJ: u32 = bindings::drm_driver_feature_DRIVER_SYNCOBJ;
+/// Driver supports the timeline flavor of DRM sync objects for explicit synchronization of command
+/// submission.
+pub const FEAT_SYNCOBJ_TIMELINE: u32 = bindings::drm_driver_feature_DRIVER_SYNCOBJ_TIMELINE;

This is missing an entry for DRIVER_GEM_GPUVA. And some others perhaps. I suppose some are legacy which won't be needed any time soon if ever. Not sure if you intend for this to be complete, or you are just adding what you are using? Only FEAT_GEM is used by nova ATM.

Rob

#5 lore raw

Re: [RFC PATCH 3/8] rust: drm: Add Device and Driver abstractions

Quoted 66 lines · Rob Herring
Quoted 19 lines · Danilo Krummrich

From: Asahi Lina <[email protected]>

Add abstractions for DRM drivers and devices. These go together in one commit since both are fairly tightly coupled types.

A few things have been stubbed out, to be implemented as further bits of the DRM subsystem are introduced.

---
 rust/bindings/bindings_helper.h |   2 +
 rust/kernel/drm/device.rs       |  87 +++++++++
 rust/kernel/drm/drv.rs          | 318 ++++++++++++++++++++++++++++++++
 rust/kernel/drm/mod.rs          |   2 +
 4 files changed, 409 insertions(+)
 create mode 100644 rust/kernel/drm/device.rs
 create mode 100644 rust/kernel/drm/drv.rs

[...]

Quoted 43 lines
rust/kernel/drm/drv.rs new file +37 -0
new file mode 100644
index 000000000000..5dd8f3f8df7c
@@ -0,0 +1,318 @@
+// SPDX-License-Identifier: GPL-2.0 OR MIT
+
+//! DRM driver core.
+//!
+//! C header: [`include/linux/drm/drm_drv.h`](../../../../include/linux/drm/drm_drv.h)
+
+use crate::{
+    alloc::flags::*,
+    bindings, device, drm,
+    error::code::*,
+    error::{Error, Result},
+    prelude::*,
+    private::Sealed,
+    str::CStr,
+    types::{ARef, ForeignOwnable},
+    ThisModule,
+};
+use core::{
+    marker::{PhantomData, PhantomPinned},
+    pin::Pin,
+};
+use macros::vtable;
+
+/// Driver use the GEM memory manager. This should be set for all modern drivers.
+pub const FEAT_GEM: u32 = bindings::drm_driver_feature_DRIVER_GEM;
+/// Driver supports mode setting interfaces (KMS).
+pub const FEAT_MODESET: u32 = bindings::drm_driver_feature_DRIVER_MODESET;
+/// Driver supports dedicated render nodes.
+pub const FEAT_RENDER: u32 = bindings::drm_driver_feature_DRIVER_RENDER;
+/// Driver supports the full atomic modesetting userspace API.
+///
+/// Drivers which only use atomic internally, but do not support the full userspace API (e.g. not
+/// all properties converted to atomic, or multi-plane updates are not guaranteed to be tear-free)
+/// should not set this flag.
+pub const FEAT_ATOMIC: u32 = bindings::drm_driver_feature_DRIVER_ATOMIC;
+/// Driver supports DRM sync objects for explicit synchronization of command submission.
+pub const FEAT_SYNCOBJ: u32 = bindings::drm_driver_feature_DRIVER_SYNCOBJ;
Quoted 8 lines

rust/kernel/drm/drv.rs line 40

Quoted 3 lines
rust/kernel/drm/drv.rs new file +3 -0
+/// Driver supports the timeline flavor of DRM sync objects for explicit synchronization of command
+/// submission.
+pub const FEAT_SYNCOBJ_TIMELINE: u32 = bindings::drm_driver_feature_DRIVER_SYNCOBJ_TIMELINE;

This is missing an entry for DRIVER_GEM_GPUVA. And some others perhaps. I suppose some are legacy which won't be needed any time soon if ever. Not sure if you intend for this to be complete, or you are just adding what you are using? Only FEAT_GEM is used by nova ATM.

Good catch, I think we should add all of them, except the legacy ones. If no one disagrees, I will fix this in v2.

Quoted 3 lines

Rob

#6 lore raw

Re: [RFC PATCH 3/8] rust: drm: Add Device and Driver abstractions

In reply to Rob Herring
Quoted 66 lines · Rob Herring
Quoted 19 lines · Danilo Krummrich

From: Asahi Lina <[email protected]>

Add abstractions for DRM drivers and devices. These go together in one commit since both are fairly tightly coupled types.

A few things have been stubbed out, to be implemented as further bits of the DRM subsystem are introduced.

---
 rust/bindings/bindings_helper.h |   2 +
 rust/kernel/drm/device.rs       |  87 +++++++++
 rust/kernel/drm/drv.rs          | 318 ++++++++++++++++++++++++++++++++
 rust/kernel/drm/mod.rs          |   2 +
 4 files changed, 409 insertions(+)
 create mode 100644 rust/kernel/drm/device.rs
 create mode 100644 rust/kernel/drm/drv.rs

[...]

Quoted 43 lines
rust/kernel/drm/drv.rs new file +37 -0
new file mode 100644
index 000000000000..5dd8f3f8df7c
@@ -0,0 +1,318 @@
+// SPDX-License-Identifier: GPL-2.0 OR MIT
+
+//! DRM driver core.
+//!
+//! C header: [`include/linux/drm/drm_drv.h`](../../../../include/linux/drm/drm_drv.h)
+
+use crate::{
+    alloc::flags::*,
+    bindings, device, drm,
+    error::code::*,
+    error::{Error, Result},
+    prelude::*,
+    private::Sealed,
+    str::CStr,
+    types::{ARef, ForeignOwnable},
+    ThisModule,
+};
+use core::{
+    marker::{PhantomData, PhantomPinned},
+    pin::Pin,
+};
+use macros::vtable;
+
+/// Driver use the GEM memory manager. This should be set for all modern drivers.
+pub const FEAT_GEM: u32 = bindings::drm_driver_feature_DRIVER_GEM;
+/// Driver supports mode setting interfaces (KMS).
+pub const FEAT_MODESET: u32 = bindings::drm_driver_feature_DRIVER_MODESET;
+/// Driver supports dedicated render nodes.
+pub const FEAT_RENDER: u32 = bindings::drm_driver_feature_DRIVER_RENDER;
+/// Driver supports the full atomic modesetting userspace API.
+///
+/// Drivers which only use atomic internally, but do not support the full userspace API (e.g. not
+/// all properties converted to atomic, or multi-plane updates are not guaranteed to be tear-free)
+/// should not set this flag.
+pub const FEAT_ATOMIC: u32 = bindings::drm_driver_feature_DRIVER_ATOMIC;
+/// Driver supports DRM sync objects for explicit synchronization of command submission.
+pub const FEAT_SYNCOBJ: u32 = bindings::drm_driver_feature_DRIVER_SYNCOBJ;
Quoted 9 lines

rust/kernel/drm/drv.rs line 40

Quoted 3 lines
rust/kernel/drm/drv.rs new file +3 -0
+/// Driver supports the timeline flavor of DRM sync objects for explicit synchronization of command
+/// submission.
+pub const FEAT_SYNCOBJ_TIMELINE: u32 = bindings::drm_driver_feature_DRIVER_SYNCOBJ_TIMELINE;

This is missing an entry for DRIVER_GEM_GPUVA. And some others perhaps. I suppose some are legacy which won't be needed any time soon if ever. Not sure if you intend for this to be complete, or you are just adding what you are using? Only FEAT_GEM is used by nova ATM.

This was developed before DRIVER_GEM_GPUVA existed ^^

I have this in my branch since I'm using the GPUVA manager now. Danilo, what tree are you using for this submission? It would be good to coordinate this and try to keep the WIP branches from diverging too much...

That said, I don't think there's reason to support all features unless we expect new drivers to actually use them. The goal of the abstractions is to serve the drivers that will use them, and to evolve together with them and any newer drivers, not to attempt to be feature-complete from the get go (it's very difficult to evaluate an abstraction if it has no users!). In general my approach when writing them was to abstract what I need and add "obvious" extra trivial features that didn't require much thought even if I wasn't using them, but otherwise not attempt to comprehensively cover everything.

~~ Lina

#7 lore raw

Re: [RFC PATCH 3/8] rust: drm: Add Device and Driver abstractions

Hi Lina,

Welcome back!

Quoted 11 lines · Asahi Lina
Quoted 7 lines · Rob Herring
Quoted 1 line · Danilo Krummrich

From: Asahi Lina <[email protected]>

This is missing an entry for DRIVER_GEM_GPUVA. And some others perhaps. I suppose some are legacy which won't be needed any time soon if ever. Not sure if you intend for this to be complete, or you are just adding what you are using? Only FEAT_GEM is used by nova ATM.

Quoted 5 lines

This was developed before DRIVER_GEM_GPUVA existed ^^

I have this in my branch since I'm using the GPUVA manager now. Danilo, what tree are you using for this submission? It would be good to coordinate this and try to keep the WIP branches from diverging too much...

Trying to prevent things from diverging was one of my main objectives when I started those efforts a couple of month ago (I also sent you a mail for that purpose back then).

I am maintaining a couple of branches:

In the RfL repository [1]:

- staging/rust-device [2] (Device / driver, devres infrastructure)
- staging/dev [3] (common branch containing all the Rust infrastructure I'm currently upstreaming, including PCI and firmware abstractions)

In the drm-misc repository [4]:
- topic/rust-drm [5] (all the DRM abstractions)

In the Nova repository [6]
- nova-next [7] (the Nova stub driver making use of everything)

I regularly rebase those branches and keep them up to date with improvements and feedback from the mailing list.

The device / driver and PCI abstractions are getting most of my attention currently, but there are some recent changes (besides some minor ones) on the DRM abstractions I plan to send in a v2 as well:

- static const allocation of driver and fops structures
- rework of the Registration type to use Devres and combine the new() and register() methods to register in new() already

There is also some more information regarding those branches in the cover letters of the series and the links included there.

[1] https://github.com/Rust-for-Linux/linux
[2] https://github.com/Rust-for-Linux/linux/tree/staging/rust-device
[3] https://github.com/Rust-for-Linux/linux/tree/staging/dev
[4] https://gitlab.freedesktop.org/drm/misc/kernel
[5] https://gitlab.freedesktop.org/drm/misc/kernel/-/tree/topic/rust-drm
[6] https://gitlab.freedesktop.org/drm/nova
[7] https://gitlab.freedesktop.org/drm/nova/-/tree/nova-next

Quoted 10 lines

That said, I don't think there's reason to support all features unless we expect new drivers to actually use them. The goal of the abstractions is to serve the drivers that will use them, and to evolve together with them and any newer drivers, not to attempt to be feature-complete from the get go (it's very difficult to evaluate an abstraction if it has no users!). In general my approach when writing them was to abstract what I need and add "obvious" extra trivial features that didn't require much thought even if I wasn't using them, but otherwise not attempt to comprehensively cover everything.

Fully agree, I think the point here only was whether we want to list all the feature flags in the abstraction already. Which I think is something we can do. However, I'm also find with only listing the ones we actually use and keep adding further ones subsequently. It just shouldn't be random.

- Danilo

Quoted 3 lines

~~ Lina

#8 lore raw

Re: [RFC PATCH 3/8] rust: drm: Add Device and Driver abstractions

In reply to Asahi Lina
Quoted 80 lines · Asahi Lina
Quoted 66 lines · Rob Herring
Quoted 19 lines · Danilo Krummrich

From: Asahi Lina <[email protected]>

Add abstractions for DRM drivers and devices. These go together in one commit since both are fairly tightly coupled types.

A few things have been stubbed out, to be implemented as further bits of the DRM subsystem are introduced.

---
 rust/bindings/bindings_helper.h |   2 +
 rust/kernel/drm/device.rs       |  87 +++++++++
 rust/kernel/drm/drv.rs          | 318 ++++++++++++++++++++++++++++++++
 rust/kernel/drm/mod.rs          |   2 +
 4 files changed, 409 insertions(+)
 create mode 100644 rust/kernel/drm/device.rs
 create mode 100644 rust/kernel/drm/drv.rs

[...]

Quoted 43 lines
rust/kernel/drm/drv.rs new file +37 -0
new file mode 100644
index 000000000000..5dd8f3f8df7c
@@ -0,0 +1,318 @@
+// SPDX-License-Identifier: GPL-2.0 OR MIT
+
+//! DRM driver core.
+//!
+//! C header: [`include/linux/drm/drm_drv.h`](../../../../include/linux/drm/drm_drv.h)
+
+use crate::{
+    alloc::flags::*,
+    bindings, device, drm,
+    error::code::*,
+    error::{Error, Result},
+    prelude::*,
+    private::Sealed,
+    str::CStr,
+    types::{ARef, ForeignOwnable},
+    ThisModule,
+};
+use core::{
+    marker::{PhantomData, PhantomPinned},
+    pin::Pin,
+};
+use macros::vtable;
+
+/// Driver use the GEM memory manager. This should be set for all modern drivers.
+pub const FEAT_GEM: u32 = bindings::drm_driver_feature_DRIVER_GEM;
+/// Driver supports mode setting interfaces (KMS).
+pub const FEAT_MODESET: u32 = bindings::drm_driver_feature_DRIVER_MODESET;
+/// Driver supports dedicated render nodes.
+pub const FEAT_RENDER: u32 = bindings::drm_driver_feature_DRIVER_RENDER;
+/// Driver supports the full atomic modesetting userspace API.
+///
+/// Drivers which only use atomic internally, but do not support the full userspace API (e.g. not
+/// all properties converted to atomic, or multi-plane updates are not guaranteed to be tear-free)
+/// should not set this flag.
+pub const FEAT_ATOMIC: u32 = bindings::drm_driver_feature_DRIVER_ATOMIC;
+/// Driver supports DRM sync objects for explicit synchronization of command submission.
+pub const FEAT_SYNCOBJ: u32 = bindings::drm_driver_feature_DRIVER_SYNCOBJ;
Quoted 9 lines

rust/kernel/drm/drv.rs line 40

Quoted 3 lines
rust/kernel/drm/drv.rs new file +3 -0
+/// Driver supports the timeline flavor of DRM sync objects for explicit synchronization of command
+/// submission.
+pub const FEAT_SYNCOBJ_TIMELINE: u32 = bindings::drm_driver_feature_DRIVER_SYNCOBJ_TIMELINE;

This is missing an entry for DRIVER_GEM_GPUVA. And some others perhaps. I suppose some are legacy which won't be needed any time soon if ever. Not sure if you intend for this to be complete, or you are just adding what you are using? Only FEAT_GEM is used by nova ATM.

Quoted 3 lines

This was developed before DRIVER_GEM_GPUVA existed ^^

I have this in my branch since I'm using the GPUVA manager now.

TBC, I'm using it as well, not just providing drive-by comments. I'm starting to look at converting panthor to rust.

Quoted 3 lines

Danilo,
what tree are you using for this submission? It would be good to coordinate this and try to keep the WIP branches from diverging too much...

Yes, please!

Besides asahi of course, there's several people[1][2][3] using the platform and DT abstractions and we're all rebasing those. I'd volunteer to maintain, but I don't know rust well enough yet to even be dangerous... :)

Rob

[1] https://lore.kernel.org/all/[email protected]/
[2] https://lore.kernel.org/all/[email protected]/
[3] https://lore.kernel.org/all/CAPFo5VLoYGq_OgC5dqcueTyymuSCsLpjasLZnKO1jpY6gV7s2g@mail.gmail.com/

#9 lore raw

RFC PATCH 4/8 rust: drm: implement `AsRef` for DRM device

In reply to Danilo Krummrich

Implement AsRef<device::Device> for drm::device::Device such that dev_* print macros can be used conveniently.

---
 rust/kernel/drm/device.rs | 8 ++++++++
 1 file changed, 8 insertions(+)
rust/kernel/drm/device.rs +8 -0
index f72bab8dd42d..aef947893dab 100644
@@ -79,6 +79,14 @@ unsafe fn dec_ref(obj: NonNull<Self>) {
     }
 }
 
+impl<T: drm::drv::Driver> AsRef<device::Device> for Device<T> {
+    fn as_ref(&self) -> &device::Device {
+        // SAFETY: `bindings::drm_device::dev` is valid as long as the DRM device itself is valid,
+        // which is guaranteed by the type invariant.
+        unsafe { device::Device::as_ref((*self.as_raw()).dev) }
+    }
+}
+
 // SAFETY: `Device` only holds a pointer to a C device, which is safe to be used from any thread.
 unsafe impl<T: drm::drv::Driver> Send for Device<T> {}
 
Signature · 1 line
2.45.1
#10 lore raw

RFC PATCH 4/8 rust: drm: implement `AsRef` for DRM device

In reply to Danilo Krummrich

Implement AsRef<device::Device> for drm::device::Device such that dev_* print macros can be used conveniently.

---
 rust/kernel/drm/device.rs | 8 ++++++++
 1 file changed, 8 insertions(+)
rust/kernel/drm/device.rs +8 -0
index f72bab8dd42d..aef947893dab 100644
@@ -79,6 +79,14 @@ unsafe fn dec_ref(obj: NonNull<Self>) {
     }
 }
 
+impl<T: drm::drv::Driver> AsRef<device::Device> for Device<T> {
+    fn as_ref(&self) -> &device::Device {
+        // SAFETY: `bindings::drm_device::dev` is valid as long as the DRM device itself is valid,
+        // which is guaranteed by the type invariant.
+        unsafe { device::Device::as_ref((*self.as_raw()).dev) }
+    }
+}
+
 // SAFETY: `Device` only holds a pointer to a C device, which is safe to be used from any thread.
 unsafe impl<T: drm::drv::Driver> Send for Device<T> {}
 
Signature · 1 line
2.45.1
#11 lore raw

RFC PATCH 5/8 rust: drm: file: Add File abstraction

In reply to Danilo Krummrich

From: Asahi Lina <[email protected]>

A DRM File is the DRM counterpart to a kernel file structure, representing an open DRM file descriptor. Add a Rust abstraction to allow drivers to implement their own File types that implement the DriverFile trait.

---
 rust/bindings/bindings_helper.h |   1 +
 rust/kernel/drm/drv.rs          |   7 +-
 rust/kernel/drm/file.rs         | 113 ++++++++++++++++++++++++++++++++
 rust/kernel/drm/mod.rs          |   1 +
 4 files changed, 120 insertions(+), 2 deletions(-)
 create mode 100644 rust/kernel/drm/file.rs
rust/bindings/bindings_helper.h +1 -0
index 831fbfe03a47..c591811ccb67 100644
@@ -8,6 +8,7 @@
 
 #include <drm/drm_device.h>
 #include <drm/drm_drv.h>
+#include <drm/drm_file.h>
 #include <drm/drm_ioctl.h>
 #include <kunit/test.h>
 #include <linux/errname.h>
rust/kernel/drm/drv.rs +5 -2
index 5dd8f3f8df7c..c5a63663ea21 100644
@@ -131,6 +131,9 @@ pub trait Driver {
     /// Should be either `drm::gem::Object<T>` or `drm::gem::shmem::Object<T>`.
     type Object: AllocImpl;
 
+    /// The type used to represent a DRM File (client)
+    type File: drm::file::DriverFile;
+
     /// Driver metadata
     const INFO: DriverInfo;
 
@@ -200,8 +203,8 @@ macro_rules! drm_device_register {
 impl<T: Driver> Registration<T> {
     const VTABLE: bindings::drm_driver = drm_legacy_fields! {
         load: None,
-        open: None, // TODO: File abstraction
-        postclose: None, // TODO: File abstraction
+        open: Some(drm::file::open_callback::<T::File>),
+        postclose: Some(drm::file::postclose_callback::<T::File>),
         lastclose: None,
         unload: None,
         release: None,
rust/kernel/drm/file.rs new file +113 -0

113 lines not on this page · raw message

rust/kernel/drm/mod.rs +1 -0
index 69376b3c6db9..a767942d0b52 100644
@@ -4,4 +4,5 @@
 
 pub mod device;
 pub mod drv;
+pub mod file;
 pub mod ioctl;
Signature · 1 line
2.45.1
#12 lore raw

RFC PATCH 6/8 rust: drm: gem: Add GEM object abstraction

In reply to Danilo Krummrich

From: Asahi Lina <[email protected]>

The DRM GEM subsystem is the DRM memory management subsystem used by most modern drivers. Add a Rust abstraction to allow Rust DRM driver implementations to use it.

---
 rust/bindings/bindings_helper.h |   1 +
 rust/helpers.c                  |  23 ++
 rust/kernel/drm/drv.rs          |   4 +-
 rust/kernel/drm/gem/mod.rs      | 406 ++++++++++++++++++++++++++++++++
 rust/kernel/drm/mod.rs          |   1 +
 5 files changed, 433 insertions(+), 2 deletions(-)
 create mode 100644 rust/kernel/drm/gem/mod.rs
rust/bindings/bindings_helper.h +1 -0
index c591811ccb67..b245db8d5a87 100644
@@ -9,6 +9,7 @@
 #include <drm/drm_device.h>
 #include <drm/drm_drv.h>
 #include <drm/drm_file.h>
+#include <drm/drm_gem.h>
 #include <drm/drm_ioctl.h>
 #include <kunit/test.h>
 #include <linux/errname.h>
rust/helpers.c +23 -0
index dc2405772b1a..30e86bf00337 100644
@@ -20,6 +20,7 @@
  * Sorted alphabetically.
  */
 
+#include <drm/drm_gem.h>
 #include <kunit/test-bug.h>
 #include <linux/bug.h>
 #include <linux/build_bug.h>
@@ -302,6 +303,28 @@ u64 rust_helper_pci_resource_len(struct pci_dev *pdev, int barnr)
 	return pci_resource_len(pdev, barnr);
 }
 
+#ifdef CONFIG_DRM
+
+void rust_helper_drm_gem_object_get(struct drm_gem_object *obj)
+{
+	drm_gem_object_get(obj);
+}
+EXPORT_SYMBOL_GPL(rust_helper_drm_gem_object_get);
+
+void rust_helper_drm_gem_object_put(struct drm_gem_object *obj)
+{
+	drm_gem_object_put(obj);
+}
+EXPORT_SYMBOL_GPL(rust_helper_drm_gem_object_put);
+
+__u64 rust_helper_drm_vma_node_offset_addr(struct drm_vma_offset_node *node)
+{
+	return drm_vma_node_offset_addr(node);
+}
+EXPORT_SYMBOL_GPL(rust_helper_drm_vma_node_offset_addr);
+
+#endif
+
 /*
  * `bindgen` binds the C `size_t` type as the Rust `usize` type, so we can
  * use it in contexts where Rust expects a `usize` like slice (array) indices.
rust/kernel/drm/drv.rs +2 -2
index c5a63663ea21..063b420f57e5 100644
@@ -113,7 +113,7 @@ pub struct AllocOps {
 }
 
 /// Trait for memory manager implementations. Implemented internally.
-pub trait AllocImpl: Sealed {
+pub trait AllocImpl: Sealed + drm::gem::IntoGEMObject {
     /// The C callback operations for this memory manager.
     const ALLOC_OPS: AllocOps;
 }
@@ -243,7 +243,7 @@ pub fn new(parent: &device::Device) -> Result<Self> {
             drm: drm::device::Device::new(parent, &vtable)?,
             registered: false,
             vtable,
-            fops: Default::default(), // TODO: GEM abstraction
+            fops: drm::gem::create_fops(),
             _pin: PhantomPinned,
             _p: PhantomData,
         })
rust/kernel/drm/gem/mod.rs new file +406 -0

406 lines not on this page · raw message

rust/kernel/drm/mod.rs +1 -0
index a767942d0b52..c44760a1332f 100644
@@ -5,4 +5,5 @@
 pub mod device;
 pub mod drv;
 pub mod file;
+pub mod gem;
 pub mod ioctl;
Signature · 1 line
2.45.1
reviewer Reviewed-by on v1 6/8
#13 lore raw

Re: [RFC PATCH 6/8] rust: drm: gem: Add GEM object abstraction

Hi Danilo, Lina

Quoted 117 lines · Danilo Krummrich

From: Asahi Lina <[email protected]>

The DRM GEM subsystem is the DRM memory management subsystem used by most modern drivers. Add a Rust abstraction to allow Rust DRM driver implementations to use it.

---

rust/bindings/bindings_helper.h |   1 +
rust/helpers.c                  |  23 ++
rust/kernel/drm/drv.rs          |   4 +-
rust/kernel/drm/gem/mod.rs      | 406 ++++++++++++++++++++++++++++++++
rust/kernel/drm/mod.rs          |   1 +
5 files changed, 433 insertions(+), 2 deletions(-)

create mode 100644 rust/kernel/drm/gem/mod.rs

rust/bindings/bindings_helper.h +1 -0
index c591811ccb67..b245db8d5a87 100644
@@ -9,6 +9,7 @@
 #include <drm/drm_device.h>
 #include <drm/drm_drv.h>
 #include <drm/drm_file.h>
+#include <drm/drm_gem.h>
 #include <drm/drm_ioctl.h>
 #include <kunit/test.h>
 #include <linux/errname.h>
rust/helpers.c +23 -0
index dc2405772b1a..30e86bf00337 100644
@@ -20,6 +20,7 @@
 * Sorted alphabetically.
 */
 
+#include <drm/drm_gem.h>
 #include <kunit/test-bug.h>
 #include <linux/bug.h>
 #include <linux/build_bug.h>
@@ -302,6 +303,28 @@ u64 rust_helper_pci_resource_len(struct pci_dev *pdev, int barnr)
 return pci_resource_len(pdev, barnr);
 }
 
+#ifdef CONFIG_DRM
+
+void rust_helper_drm_gem_object_get(struct drm_gem_object *obj)
+{
+ drm_gem_object_get(obj);
+}
+EXPORT_SYMBOL_GPL(rust_helper_drm_gem_object_get);
+
+void rust_helper_drm_gem_object_put(struct drm_gem_object *obj)
+{
+ drm_gem_object_put(obj);
+}
+EXPORT_SYMBOL_GPL(rust_helper_drm_gem_object_put);
+
+__u64 rust_helper_drm_vma_node_offset_addr(struct drm_vma_offset_node *node)
+{
+ return drm_vma_node_offset_addr(node);
+}
+EXPORT_SYMBOL_GPL(rust_helper_drm_vma_node_offset_addr);
+
+#endif
+
 /*
 * `bindgen` binds the C `size_t` type as the Rust `usize` type, so we can
 * use it in contexts where Rust expects a `usize` like slice (array) indices.
rust/kernel/drm/drv.rs +2 -2
index c5a63663ea21..063b420f57e5 100644
@@ -113,7 +113,7 @@ pub struct AllocOps {
 }
 
 /// Trait for memory manager implementations. Implemented internally.
-pub trait AllocImpl: Sealed {
+pub trait AllocImpl: Sealed + drm::gem::IntoGEMObject {
    /// The C callback operations for this memory manager.
    const ALLOC_OPS: AllocOps;
 }
@@ -243,7 +243,7 @@ pub fn new(parent: &device::Device) -> Result<Self> {
            drm: drm::device::Device::new(parent, &vtable)?,
            registered: false,
            vtable,
-            fops: Default::default(), // TODO: GEM abstraction
+            fops: drm::gem::create_fops(),
            _pin: PhantomPinned,
            _p: PhantomData,
        })
rust/kernel/drm/gem/mod.rs new file +16 -0
new file mode 100644
index 000000000000..4cd85d5f1df8
@@ -0,0 +1,406 @@
+// SPDX-License-Identifier: GPL-2.0 OR MIT
+
+//! DRM GEM API
+//!
+//! C header: [`include/linux/drm/drm_gem.h`](../../../../include/linux/drm/drm_gem.h)
+
+use alloc::boxed::Box;
+
+use crate::{
+    alloc::flags::*,
+    bindings,
+    drm::{device, drv, file},
+    error::{to_result, Result},
+    prelude::*,
+};
+use core::{marker::PhantomPinned, mem, ops::Deref, ops::DerefMut};

rust/kernel/drm/gem/mod.rs line 26

Quoted 10 lines
rust/kernel/drm/gem/mod.rs new file +10 -0
+
+/// GEM object functions, which must be implemented by drivers.
+pub trait BaseDriverObject<T: BaseObject>: Sync + Send + Sized {
+    /// Create a new driver data object for a GEM object of a given size.
+    fn new(dev: &device::Device<T::Driver>, size: usize) -> impl PinInit<Self, Error>;
+
+    /// Open a new handle to an existing object, associated with a File.
+    fn open(
+        _obj: &<<T as IntoGEMObject>::Driver as drv::Driver>::Object,
+        _file: &file::File<<<T as IntoGEMObject>::Driver as drv::Driver>::File>,

I wonder if these can be put into a type alias? As in,

type File<T: IntoGEMObject> = file::File<<<T as IntoGEMObject>::Driver as drv::Driver>::File>;

etc

That would clean things up a bit.

Quoted 167 lines
rust/kernel/drm/gem/mod.rs new file +167 -0
+    ) -> Result {
+        Ok(())
+    }
+
+    /// Close a handle to an existing object, associated with a File.
+    fn close(
+        _obj: &<<T as IntoGEMObject>::Driver as drv::Driver>::Object,
+        _file: &file::File<<<T as IntoGEMObject>::Driver as drv::Driver>::File>,
+    ) {
+    }
+}
+
+/// Trait that represents a GEM object subtype
+pub trait IntoGEMObject: Sized + crate::private::Sealed {
+    /// Owning driver for this type
+    type Driver: drv::Driver;
+
+    /// Returns a reference to the raw `drm_gem_object` structure, which must be valid as long as
+    /// this owning object is valid.
+    fn gem_obj(&self) -> &bindings::drm_gem_object;
+
+    /// Converts a pointer to a `drm_gem_object` into a pointer to this type.
+    fn from_gem_obj(obj: *mut bindings::drm_gem_object) -> *mut Self;
+}
+
+/// Trait which must be implemented by drivers using base GEM objects.
+pub trait DriverObject: BaseDriverObject<Object<Self>> {
+    /// Parent `Driver` for this object.
+    type Driver: drv::Driver;
+}
+
+unsafe extern "C" fn free_callback<T: DriverObject>(obj: *mut bindings::drm_gem_object) {
+    // SAFETY: All of our objects are Object<T>.
+    let this = unsafe { crate::container_of!(obj, Object<T>, obj) } as *mut Object<T>;
+
+    // SAFETY: The pointer we got has to be valid
+    unsafe { bindings::drm_gem_object_release(obj) };
+
+    // SAFETY: All of our objects are allocated via Box<>, and we're in the
+    // free callback which guarantees this object has zero remaining references,
+    // so we can drop it
+    unsafe {
+        let _ = Box::from_raw(this);
+    };
+}
+
+unsafe extern "C" fn open_callback<T: BaseDriverObject<U>, U: BaseObject>(
+    raw_obj: *mut bindings::drm_gem_object,
+    raw_file: *mut bindings::drm_file,
+) -> core::ffi::c_int {
+    // SAFETY: The pointer we got has to be valid.
+    let file = unsafe {
+        file::File::<<<U as IntoGEMObject>::Driver as drv::Driver>::File>::from_raw(raw_file)
+    };
+    let obj =
+        <<<U as IntoGEMObject>::Driver as drv::Driver>::Object as IntoGEMObject>::from_gem_obj(
+            raw_obj,
+        );
+
+    // SAFETY: from_gem_obj() returns a valid pointer as long as the type is
+    // correct and the raw_obj we got is valid.
+    match T::open(unsafe { &*obj }, &file) {
+        Err(e) => e.to_errno(),
+        Ok(()) => 0,
+    }
+}
+
+unsafe extern "C" fn close_callback<T: BaseDriverObject<U>, U: BaseObject>(
+    raw_obj: *mut bindings::drm_gem_object,
+    raw_file: *mut bindings::drm_file,
+) {
+    // SAFETY: The pointer we got has to be valid.
+    let file = unsafe {
+        file::File::<<<U as IntoGEMObject>::Driver as drv::Driver>::File>::from_raw(raw_file)
+    };
+    let obj =
+        <<<U as IntoGEMObject>::Driver as drv::Driver>::Object as IntoGEMObject>::from_gem_obj(
+            raw_obj,
+        );
+
+    // SAFETY: from_gem_obj() returns a valid pointer as long as the type is
+    // correct and the raw_obj we got is valid.
+    T::close(unsafe { &*obj }, &file);
+}
+
+impl<T: DriverObject> IntoGEMObject for Object<T> {
+    type Driver = T::Driver;
+
+    fn gem_obj(&self) -> &bindings::drm_gem_object {
+        &self.obj
+    }
+
+    fn from_gem_obj(obj: *mut bindings::drm_gem_object) -> *mut Object<T> {
+        unsafe { crate::container_of!(obj, Object<T>, obj) as *mut Object<T> }
+    }
+}
+
+/// Base operations shared by all GEM object classes
+pub trait BaseObject: IntoGEMObject {
+    /// Returns the size of the object in bytes.
+    fn size(&self) -> usize {
+        self.gem_obj().size
+    }
+
+    /// Creates a new reference to the object.
+    fn reference(&self) -> ObjectRef<Self> {
+        // SAFETY: Having a reference to an Object implies holding a GEM reference
+        unsafe {
+            bindings::drm_gem_object_get(self.gem_obj() as *const _ as *mut _);
+        }
+        ObjectRef {
+            ptr: self as *const _,
+        }
+    }
+
+    /// Creates a new handle for the object associated with a given `File`
+    /// (or returns an existing one).
+    fn create_handle(
+        &self,
+        file: &file::File<<<Self as IntoGEMObject>::Driver as drv::Driver>::File>,
+    ) -> Result<u32> {
+        let mut handle: u32 = 0;
+        // SAFETY: The arguments are all valid per the type invariants.
+        to_result(unsafe {
+            bindings::drm_gem_handle_create(
+                file.raw() as *mut _,
+                self.gem_obj() as *const _ as *mut _,
+                &mut handle,
+            )
+        })?;
+        Ok(handle)
+    }
+
+    /// Looks up an object by its handle for a given `File`.
+    fn lookup_handle(
+        file: &file::File<<<Self as IntoGEMObject>::Driver as drv::Driver>::File>,
+        handle: u32,
+    ) -> Result<ObjectRef<Self>> {
+        // SAFETY: The arguments are all valid per the type invariants.
+        let ptr = unsafe { bindings::drm_gem_object_lookup(file.raw() as *mut _, handle) };
+
+        if ptr.is_null() {
+            Err(ENOENT)
+        } else {
+            Ok(ObjectRef {
+                ptr: ptr as *const _,
+            })
+        }
+    }
+
+    /// Creates an mmap offset to map the object from userspace.
+    fn create_mmap_offset(&self) -> Result<u64> {
+        // SAFETY: The arguments are valid per the type invariant.
+        to_result(unsafe {
+            bindings::drm_gem_create_mmap_offset(self.gem_obj() as *const _ as *mut _)
+        })?;
+        Ok(unsafe {
+            bindings::drm_vma_node_offset_addr(&self.gem_obj().vma_node as *const _ as *mut _)
+        })
+    }
+}
+
+impl<T: IntoGEMObject> BaseObject for T {}
+
+/// A base GEM object.
+#[repr(C)]
+#[pin_data]

rust/kernel/drm/gem/mod.rs line 203

Quoted 10 lines
rust/kernel/drm/gem/mod.rs new file +10 -0
+pub struct Object<T: DriverObject> {
+    obj: bindings::drm_gem_object,
+    // The DRM core ensures the Device exists as long as its objects exist, so we don't need to
+    // manage the reference count here.
+    dev: *const bindings::drm_device,
+    #[pin]
+    inner: T,
+    #[pin]
+    _p: PhantomPinned,
+}

A bit minor, but why is PhantomPinned structurally pinned here?

Maybe Benno can also chime in, but, at a first glance, I do not see any reason for a marker type to be pinned.

Quoted 215 lines
rust/kernel/drm/gem/mod.rs new file +203 -0
+
+// SAFETY: This struct is safe to zero-initialize
+unsafe impl init::Zeroable for bindings::drm_gem_object {}
+
+impl<T: DriverObject> Object<T> {
+    /// The size of this object's structure.
+    pub const SIZE: usize = mem::size_of::<Self>();
+
+    const OBJECT_FUNCS: bindings::drm_gem_object_funcs = bindings::drm_gem_object_funcs {
+        free: Some(free_callback::<T>),
+        open: Some(open_callback::<T, Object<T>>),
+        close: Some(close_callback::<T, Object<T>>),
+        print_info: None,
+        export: None,
+        pin: None,
+        unpin: None,
+        get_sg_table: None,
+        vmap: None,
+        vunmap: None,
+        mmap: None,
+        status: None,
+        vm_ops: core::ptr::null_mut(),
+        evict: None,
+        rss: None,
+    };
+
+    /// Create a new GEM object.
+    pub fn new(dev: &device::Device<T::Driver>, size: usize) -> Result<Pin<UniqueObjectRef<Self>>> {
+        let obj: Pin<Box<Self>> = Box::pin_init(
+            try_pin_init!(Self {
+                // SAFETY: This struct is expected to be zero-initialized
+                obj: bindings::drm_gem_object {
+                    funcs: &Self::OBJECT_FUNCS,
+                    ..Default::default()
+                },
+                inner <- T::new(dev, size),
+                // SAFETY: The drm subsystem guarantees that the drm_device will live as long as
+                // the GEM object lives, so we can conjure a reference out of thin air.
+                dev: dev.as_raw(),
+                _p: PhantomPinned
+            }),
+            GFP_KERNEL,
+        )?;
+
+        to_result(unsafe {
+            bindings::drm_gem_object_init(dev.as_raw(), &obj.obj as *const _ as *mut _, size)
+        })?;
+
+        // SAFETY: We never move out of self
+        let obj_ref = unsafe {
+            Pin::new_unchecked(UniqueObjectRef {
+                // SAFETY: We never move out of the Box
+                ptr: Box::leak(Pin::into_inner_unchecked(obj)),
+                _p: PhantomPinned,
+            })
+        };
+
+        Ok(obj_ref)
+    }
+
+    /// Returns the `Device` that owns this GEM object.
+    pub fn dev(&self) -> &device::Device<T::Driver> {
+        // SAFETY: The drm subsystem guarantees that the drm_device will live as long as
+        // the GEM object lives, so we can just borrow from the raw pointer.
+        unsafe { device::Device::borrow(self.dev) }
+    }
+}
+
+impl<T: DriverObject> crate::private::Sealed for Object<T> {}
+
+impl<T: DriverObject> Deref for Object<T> {
+    type Target = T;
+
+    fn deref(&self) -> &Self::Target {
+        &self.inner
+    }
+}
+
+impl<T: DriverObject> DerefMut for Object<T> {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.inner
+    }
+}
+
+impl<T: DriverObject> drv::AllocImpl for Object<T> {
+    const ALLOC_OPS: drv::AllocOps = drv::AllocOps {
+        gem_create_object: None,
+        prime_handle_to_fd: None,
+        prime_fd_to_handle: None,
+        gem_prime_import: None,
+        gem_prime_import_sg_table: None,
+        dumb_create: None,
+        dumb_map_offset: None,
+    };
+}
+
+/// A reference-counted shared reference to a base GEM object.
+pub struct ObjectRef<T: IntoGEMObject> {
+    // Invariant: the pointer is valid and initialized, and this ObjectRef owns a reference to it.
+    ptr: *const T,
+}
+
+impl<T: IntoGEMObject> ObjectRef<T> {
+    /// Downgrade this reference to a shared reference.
+    pub fn from_pinned_unique(pin: Pin<UniqueObjectRef<T>>) -> Self {
+        // SAFETY: A (shared) `ObjectRef` doesn't need to be pinned, since it doesn't allow us to
+        // optain a mutable reference.
+        let uq = unsafe { Pin::into_inner_unchecked(pin) };
+
+        uq.into_ref()
+    }
+}
+
+/// SAFETY: GEM object references are safe to share between threads.
+unsafe impl<T: IntoGEMObject> Send for ObjectRef<T> {}
+unsafe impl<T: IntoGEMObject> Sync for ObjectRef<T> {}
+
+impl<T: IntoGEMObject> Clone for ObjectRef<T> {
+    fn clone(&self) -> Self {
+        self.reference()
+    }
+}
+
+impl<T: IntoGEMObject> Drop for ObjectRef<T> {
+    fn drop(&mut self) {
+        // SAFETY: Having an ObjectRef implies holding a GEM reference.
+        // The free callback will take care of deallocation.
+        unsafe {
+            bindings::drm_gem_object_put((*self.ptr).gem_obj() as *const _ as *mut _);
+        }
+    }
+}
+
+impl<T: IntoGEMObject> Deref for ObjectRef<T> {
+    type Target = T;
+
+    fn deref(&self) -> &Self::Target {
+        // SAFETY: The pointer is valid per the invariant
+        unsafe { &*self.ptr }
+    }
+}
+
+/// A unique reference to a base GEM object.
+pub struct UniqueObjectRef<T: IntoGEMObject> {
+    // Invariant: the pointer is valid and initialized, and this ObjectRef owns the only reference
+    // to it.
+    ptr: *mut T,
+    _p: PhantomPinned,
+}
+
+impl<T: IntoGEMObject> UniqueObjectRef<T> {
+    /// Downgrade this reference to a shared reference.
+    pub fn into_ref(self) -> ObjectRef<T> {
+        let ptr = self.ptr as *const _;
+        core::mem::forget(self);
+
+        ObjectRef { ptr }
+    }
+}
+
+impl<T: IntoGEMObject> Drop for UniqueObjectRef<T> {
+    fn drop(&mut self) {
+        // SAFETY: Having a UniqueObjectRef implies holding a GEM
+        // reference. The free callback will take care of deallocation.
+        unsafe {
+            bindings::drm_gem_object_put((*self.ptr).gem_obj() as *const _ as *mut _);
+        }
+    }
+}
+
+impl<T: IntoGEMObject> Deref for UniqueObjectRef<T> {
+    type Target = T;
+
+    fn deref(&self) -> &Self::Target {
+        // SAFETY: The pointer is valid per the invariant
+        unsafe { &*self.ptr }
+    }
+}
+
+impl<T: IntoGEMObject> DerefMut for UniqueObjectRef<T> {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        // SAFETY: The pointer is valid per the invariant
+        unsafe { &mut *self.ptr }
+    }
+}
+
+pub(super) fn create_fops() -> bindings::file_operations {
+    bindings::file_operations {
+        owner: core::ptr::null_mut(),
+        open: Some(bindings::drm_open),
+        release: Some(bindings::drm_release),
+        unlocked_ioctl: Some(bindings::drm_ioctl),
+        #[cfg(CONFIG_COMPAT)]
+        compat_ioctl: Some(bindings::drm_compat_ioctl),
+        #[cfg(not(CONFIG_COMPAT))]
+        compat_ioctl: None,
+        poll: Some(bindings::drm_poll),
+        read: Some(bindings::drm_read),
+        llseek: Some(bindings::noop_llseek),
+        mmap: Some(bindings::drm_gem_mmap),
+        ..Default::default()
+    }
+}
rust/kernel/drm/mod.rs +1 -0
index a767942d0b52..c44760a1332f 100644
@@ -5,4 +5,5 @@
 pub mod device;
 pub mod drv;
 pub mod file;
+pub mod gem;
 pub mod ioctl;
Signature · 1 line
2.45.1

This looks good to me,

#14 lore raw

RFC PATCH 7/8 rust: add firmware abstractions

In reply to Danilo Krummrich

Add an abstraction around the kernels firmware API to request firmware images. The abstraction provides functions to access the firmware buffer and / or copy it to a new buffer allocated with a given allocator backend.

The firmware is released once the abstraction is dropped.

---
 rust/bindings/bindings_helper.h |  1 +
 rust/kernel/firmware.rs         | 74 +++++++++++++++++++++++++++++++++
 rust/kernel/lib.rs              |  1 +
 3 files changed, 76 insertions(+)
 create mode 100644 rust/kernel/firmware.rs
rust/bindings/bindings_helper.h +1 -0
index b245db8d5a87..e4ffc47da5ec 100644
@@ -14,6 +14,7 @@
 #include <kunit/test.h>
 #include <linux/errname.h>
 #include <linux/ethtool.h>
+#include <linux/firmware.h>
 #include <linux/jiffies.h>
 #include <linux/mdio.h>
 #include <linux/pci.h>
rust/kernel/firmware.rs new file +74 -0

74 lines not on this page · raw message

rust/kernel/lib.rs +1 -0
index 6415968ee3b8..ed97d131661a 100644
@@ -35,6 +35,7 @@
 #[cfg(CONFIG_DRM = "y")]
 pub mod drm;
 pub mod error;
+pub mod firmware;
 pub mod init;
 pub mod ioctl;
 #[cfg(CONFIG_KUNIT)]
Signature · 1 line
2.45.1
#15 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 5 lines · On Mon, 20 May 2024 19:24:19 +0200 Danilo Krummrich <[email protected]> wrote:

Add an abstraction around the kernels firmware API to request firmware images. The abstraction provides functions to access the firmware buffer and / or copy it to a new buffer allocated with a given allocator backend.

Was playing with firmware extractions based on this patch. Unfortunately I ended up with a lot of pointer operations, unsafe statements.

As we know many vendors have a C headers for the definitions of the firwmare content, the driver extract the data by applying a struct pointer on it.

But in rust, I feel it would nice that we can also have a common firmware extractor for drivers, that can wrap the pointer operations, take a list of the firmware struct members that converted from C headers as the input, offer the driver some common ABI methods to query them. Maybe that would ease the pain a lot.

Thanks,
Zhi.

Quoted 120 lines

The firmware is released once the abstraction is dropped.

---
 rust/bindings/bindings_helper.h |  1 +
 rust/kernel/firmware.rs         | 74
+++++++++++++++++++++++++++++++++ rust/kernel/lib.rs              |
1 + 3 files changed, 76 insertions(+)
 create mode 100644 rust/kernel/firmware.rs
(quoted diff) +0 -0

b/rust/bindings/bindings_helper.h index b245db8d5a87..e4ffc47da5ec 100644 --- a/rust/bindings/bindings_helper.h
+++ b/rust/bindings/bindings_helper.h

rust/bindings/bindings_helper.h +1 -0
@@ -14,6 +14,7 @@
 #include <kunit/test.h>
 #include <linux/errname.h>
 #include <linux/ethtool.h>
+#include <linux/firmware.h>
 #include <linux/jiffies.h>
 #include <linux/mdio.h>
 #include <linux/pci.h>
rust/kernel/firmware.rs new file +5 -0
new file mode 100644
index 000000000000..700504fb3c9c
@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Firmware abstraction
+//!
+//! C header:

[include/linux/firmware.h](../../../../include/linux/firmware.h") + +use crate::{bindings, device::Device, error::Error, error::Result, str::CStr, types::Opaque}; +

rust/kernel/firmware.rs new file +3 -0
+/// Abstraction around a C firmware struct.
+///
+/// This is a simple abstraction around the C firmware API. Just

like with the C API, firmware can +/// be requested. Once requested the abstraction provides direct access to the firmware buffer as +/// &[u8]. Alternatively, the firmware can be copied to a new buffer using Firmware::copy. The +/// firmware is released once [Firmware] is dropped. +/// +/// # Examples

rust/kernel/firmware.rs new file +3 -0
+///
+/// ```
+/// let fw = Firmware::request("path/to/firmware.bin",

dev.as_ref())?; +/// driver_load_firmware(fw.data());

rust/kernel/firmware.rs new file +5 -0
+/// ```
+pub struct Firmware(Opaque<*const bindings::firmware>);
+
+impl Firmware {
+    /// Send a firmware request and wait for it. See also

bindings::request_firmware.

rust/kernel/firmware.rs new file +4 -0
+    pub fn request(name: &CStr, dev: &Device) -> Result<Self> {
+        let fw = Opaque::uninit();
+
+        let ret = unsafe { bindings::request_firmware(fw.get(),

name.as_char_ptr(), dev.as_raw()) };

rust/kernel/firmware.rs new file +8 -0
+        if ret != 0 {
+            return Err(Error::from_errno(ret));
+        }
+
+        Ok(Firmware(fw))
+    }
+
+    /// Send a request for an optional fw module. See also

bindings::request_firmware_nowarn.
+ pub fn request_nowarn(name: &CStr, dev: &Device) -> Result<Self>
{

rust/kernel/firmware.rs new file +4 -0
+        let fw = Opaque::uninit();
+
+        let ret = unsafe {
+            bindings::firmware_request_nowarn(fw.get(),

name.as_char_ptr(), dev.as_raw())

rust/kernel/firmware.rs new file +16 -0
+        };
+        if ret != 0 {
+            return Err(Error::from_errno(ret));
+        }
+
+        Ok(Firmware(fw))
+    }
+
+    /// Returns the size of the requested firmware in bytes.
+    pub fn size(&self) -> usize {
+        unsafe { (*(*self.0.get())).size }
+    }
+
+    /// Returns the requested firmware as `&[u8]`.
+    pub fn data(&self) -> &[u8] {
+        unsafe {

core::slice::from_raw_parts((*(*self.0.get())).data, self.size()) }

rust/kernel/firmware.rs new file +10 -0
+    }
+}
+
+impl Drop for Firmware {
+    fn drop(&mut self) {
+        unsafe { bindings::release_firmware(*self.0.get()) };
+    }
+}
+
+// SAFETY: `Firmware` only holds a pointer to a C firmware struct,

which is safe to be used from any +// thread.

rust/kernel/firmware.rs new file +3 -0
+unsafe impl Send for Firmware {}
+
+// SAFETY: `Firmware` only holds a pointer to a C firmware struct,

references to which are safe to +// be used from any thread.

rust/kernel/firmware.rs new file +1 -0
+unsafe impl Sync for Firmware {}
rust/kernel/lib.rs +1 -0
index 6415968ee3b8..ed97d131661a 100644
@@ -35,6 +35,7 @@
 #[cfg(CONFIG_DRM = "y")]
 pub mod drm;
 pub mod error;
+pub mod firmware;
 pub mod init;
 pub mod ioctl;
 #[cfg(CONFIG_KUNIT)]
#16 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 17 lines · Zhi Wang
Quoted 5 lines · On Mon, 20 May 2024 19:24:19 +0200 Danilo Krummrich <[email protected]> wrote:

Add an abstraction around the kernels firmware API to request firmware images. The abstraction provides functions to access the firmware buffer and / or copy it to a new buffer allocated with a given allocator backend.

Was playing with firmware extractions based on this patch. Unfortunately I ended up with a lot of pointer operations, unsafe statements.

As we know many vendors have a C headers for the definitions of the firwmare content, the driver extract the data by applying a struct pointer on it.

Quoted 5 lines

But in rust, I feel it would nice that we can also have a common firmware extractor for drivers, that can wrap the pointer operations, take a list of the firmware struct members that converted from C headers as the input, offer the driver some common ABI methods to query them. Maybe that would ease the pain a lot.

So, you mean some abstraction that takes a list of types, offsets in the firmware and a reference to the firmware itself and provides references to the corresponding objects?

I agree it might be helpful to have some common infrastructure for this, but the operations on it would still be unsafe, since ultimately it involves dereferencing pointers.

Quoted 125 lines

Thanks,
Zhi.

Quoted 120 lines

The firmware is released once the abstraction is dropped.

---
 rust/bindings/bindings_helper.h |  1 +
 rust/kernel/firmware.rs         | 74
+++++++++++++++++++++++++++++++++ rust/kernel/lib.rs              |
1 + 3 files changed, 76 insertions(+)
 create mode 100644 rust/kernel/firmware.rs
(quoted diff) +0 -0

b/rust/bindings/bindings_helper.h index b245db8d5a87..e4ffc47da5ec 100644 --- a/rust/bindings/bindings_helper.h
+++ b/rust/bindings/bindings_helper.h

rust/bindings/bindings_helper.h +1 -0
@@ -14,6 +14,7 @@
 #include <kunit/test.h>
 #include <linux/errname.h>
 #include <linux/ethtool.h>
+#include <linux/firmware.h>
 #include <linux/jiffies.h>
 #include <linux/mdio.h>
 #include <linux/pci.h>
rust/kernel/firmware.rs new file +5 -0
new file mode 100644
index 000000000000..700504fb3c9c
@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Firmware abstraction
+//!
+//! C header:

[include/linux/firmware.h](../../../../include/linux/firmware.h") + +use crate::{bindings, device::Device, error::Error, error::Result, str::CStr, types::Opaque}; +

rust/kernel/firmware.rs new file +3 -0
+/// Abstraction around a C firmware struct.
+///
+/// This is a simple abstraction around the C firmware API. Just

like with the C API, firmware can +/// be requested. Once requested the abstraction provides direct access to the firmware buffer as +/// &[u8]. Alternatively, the firmware can be copied to a new buffer using Firmware::copy. The +/// firmware is released once [Firmware] is dropped. +/// +/// # Examples

rust/kernel/firmware.rs new file +3 -0
+///
+/// ```
+/// let fw = Firmware::request("path/to/firmware.bin",

dev.as_ref())?; +/// driver_load_firmware(fw.data());

rust/kernel/firmware.rs new file +5 -0
+/// ```
+pub struct Firmware(Opaque<*const bindings::firmware>);
+
+impl Firmware {
+    /// Send a firmware request and wait for it. See also

bindings::request_firmware.

rust/kernel/firmware.rs new file +4 -0
+    pub fn request(name: &CStr, dev: &Device) -> Result<Self> {
+        let fw = Opaque::uninit();
+
+        let ret = unsafe { bindings::request_firmware(fw.get(),

name.as_char_ptr(), dev.as_raw()) };

rust/kernel/firmware.rs new file +8 -0
+        if ret != 0 {
+            return Err(Error::from_errno(ret));
+        }
+
+        Ok(Firmware(fw))
+    }
+
+    /// Send a request for an optional fw module. See also

bindings::request_firmware_nowarn.
+ pub fn request_nowarn(name: &CStr, dev: &Device) -> Result<Self>
{

rust/kernel/firmware.rs new file +4 -0
+        let fw = Opaque::uninit();
+
+        let ret = unsafe {
+            bindings::firmware_request_nowarn(fw.get(),

name.as_char_ptr(), dev.as_raw())

rust/kernel/firmware.rs new file +16 -0
+        };
+        if ret != 0 {
+            return Err(Error::from_errno(ret));
+        }
+
+        Ok(Firmware(fw))
+    }
+
+    /// Returns the size of the requested firmware in bytes.
+    pub fn size(&self) -> usize {
+        unsafe { (*(*self.0.get())).size }
+    }
+
+    /// Returns the requested firmware as `&[u8]`.
+    pub fn data(&self) -> &[u8] {
+        unsafe {

core::slice::from_raw_parts((*(*self.0.get())).data, self.size()) }

rust/kernel/firmware.rs new file +10 -0
+    }
+}
+
+impl Drop for Firmware {
+    fn drop(&mut self) {
+        unsafe { bindings::release_firmware(*self.0.get()) };
+    }
+}
+
+// SAFETY: `Firmware` only holds a pointer to a C firmware struct,

which is safe to be used from any +// thread.

rust/kernel/firmware.rs new file +3 -0
+unsafe impl Send for Firmware {}
+
+// SAFETY: `Firmware` only holds a pointer to a C firmware struct,

references to which are safe to +// be used from any thread.

rust/kernel/firmware.rs new file +1 -0
+unsafe impl Sync for Firmware {}
rust/kernel/lib.rs +1 -0
index 6415968ee3b8..ed97d131661a 100644
@@ -35,6 +35,7 @@
 #[cfg(CONFIG_DRM = "y")]
 pub mod drm;
 pub mod error;
+pub mod firmware;
 pub mod init;
 pub mod ioctl;
 #[cfg(CONFIG_KUNIT)]
#17 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 27 lines · Danilo Krummrich

External email: Use caution opening links or attachments

Quoted 17 lines · Zhi Wang
Quoted 5 lines · On Mon, 20 May 2024 19:24:19 +0200 Danilo Krummrich <[email protected]> wrote:

Add an abstraction around the kernels firmware API to request firmware images. The abstraction provides functions to access the firmware buffer and / or copy it to a new buffer allocated with a given allocator backend.

Was playing with firmware extractions based on this patch. Unfortunately I ended up with a lot of pointer operations, unsafe statements.

As we know many vendors have a C headers for the definitions of the firwmare content, the driver extract the data by applying a struct pointer on it.

Quoted 5 lines

But in rust, I feel it would nice that we can also have a common firmware extractor for drivers, that can wrap the pointer operations, take a list of the firmware struct members that converted from C headers as the input, offer the driver some common ABI methods to query them. Maybe that would ease the pain a lot.

Quoted 8 lines

So, you mean some abstraction that takes a list of types, offsets in the firmware and a reference to the firmware itself and provides references to the corresponding objects?

I agree it might be helpful to have some common infrastructure for this, but the operations on it would still be unsafe, since ultimately it involves dereferencing pointers.

I think the goal is to 1) concentrate the "unsafe" operations in a abstraction so the driver doesn't have to write explanation of unsafe operations here and there, improve the readability of the driver that interacts with vendor-firmware buffer. 2) ease the driver maintenance burden.

Some solutions I saw in different projects written in rust for de-referencing a per-defined struct:

1) Take the vendor firmware buffer as a whole, invent methods like read/write with offset for operating the buffer.

In this scheme, the driver is responsible for taking care of each data member in a vendor firmware struct and also its valid offset. The abstraction only covers the boundary of the whole firmware buffer.

The cons is the readability of the operation of the vendor firmware buffer in the driver is not good comparing with C code.

Hate to think a lot of xxx = vendor_firmware_struct.read(offset); // reading item A in the code.

2) Define the firmware struct in rust (might need to find a better way to handle "union" in the definition of the vendor firmware struct). Use macros to generate methods of accessing each data member for the vendor firmware struct.

Then the code in the driver will be like xxx =
vendor_firmware_struct.item_a(); in the driver.

In this scheme, the abstraction and the generated methods covers the boundary check. The "unsafe" statement can stay in the generated struct-access methods.

This might even be implemented as a more generic rust feature in the kernel.

The cons is still the driver might need to sync between the C-version definition and rust-version definition.

3) Also re-using C bindings generation in the kernel came to my mind when thinking of this problem, since it allows the rust code to access the C struct, but they don't have the boundary check. Still need another layer/macros to wrap it.

Quoted 126 lines
Quoted 125 lines

Thanks,
Zhi.

Quoted 120 lines

The firmware is released once the abstraction is dropped.

---
  rust/bindings/bindings_helper.h |  1 +
  rust/kernel/firmware.rs         | 74

+++++++++++++++++++++++++++++++++ rust/kernel/lib.rs |
1 + 3 files changed, 76 insertions(+)
create mode 100644 rust/kernel/firmware.rs

(quoted diff) +0 -0

b/rust/bindings/bindings_helper.h index b245db8d5a87..e4ffc47da5ec 100644 --- a/rust/bindings/bindings_helper.h
+++ b/rust/bindings/bindings_helper.h

rust/bindings/bindings_helper.h +1 -0
@@ -14,6 +14,7 @@
  #include <kunit/test.h>
  #include <linux/errname.h>
  #include <linux/ethtool.h>
+#include <linux/firmware.h>
  #include <linux/jiffies.h>
  #include <linux/mdio.h>
  #include <linux/pci.h>
rust/kernel/firmware.rs new file +5 -0
new file mode 100644
index 000000000000..700504fb3c9c
@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Firmware abstraction
+//!
+//! C header:

[include/linux/firmware.h](../../../../include/linux/firmware.h") + +use crate::{bindings, device::Device, error::Error, error::Result, str::CStr, types::Opaque}; +

rust/kernel/firmware.rs new file +3 -0
+/// Abstraction around a C firmware struct.
+///
+/// This is a simple abstraction around the C firmware API. Just

like with the C API, firmware can +/// be requested. Once requested the abstraction provides direct access to the firmware buffer as +/// &[u8]. Alternatively, the firmware can be copied to a new buffer using Firmware::copy. The +/// firmware is released once [Firmware] is dropped. +/// +/// # Examples

rust/kernel/firmware.rs new file +3 -0
+///
+/// ```
+/// let fw = Firmware::request("path/to/firmware.bin",

dev.as_ref())?; +/// driver_load_firmware(fw.data());

rust/kernel/firmware.rs new file +5 -0
+/// ```
+pub struct Firmware(Opaque<*const bindings::firmware>);
+
+impl Firmware {
+    /// Send a firmware request and wait for it. See also

bindings::request_firmware.

rust/kernel/firmware.rs new file +4 -0
+    pub fn request(name: &CStr, dev: &Device) -> Result<Self> {
+        let fw = Opaque::uninit();
+
+        let ret = unsafe { bindings::request_firmware(fw.get(),

name.as_char_ptr(), dev.as_raw()) };

rust/kernel/firmware.rs new file +8 -0
+        if ret != 0 {
+            return Err(Error::from_errno(ret));
+        }
+
+        Ok(Firmware(fw))
+    }
+
+    /// Send a request for an optional fw module. See also

bindings::request_firmware_nowarn.
+ pub fn request_nowarn(name: &CStr, dev: &Device) -> Result<Self>
{

rust/kernel/firmware.rs new file +4 -0
+        let fw = Opaque::uninit();
+
+        let ret = unsafe {
+            bindings::firmware_request_nowarn(fw.get(),

name.as_char_ptr(), dev.as_raw())

rust/kernel/firmware.rs new file +16 -0
+        };
+        if ret != 0 {
+            return Err(Error::from_errno(ret));
+        }
+
+        Ok(Firmware(fw))
+    }
+
+    /// Returns the size of the requested firmware in bytes.
+    pub fn size(&self) -> usize {
+        unsafe { (*(*self.0.get())).size }
+    }
+
+    /// Returns the requested firmware as `&[u8]`.
+    pub fn data(&self) -> &[u8] {
+        unsafe {

core::slice::from_raw_parts((*(*self.0.get())).data, self.size()) }

rust/kernel/firmware.rs new file +10 -0
+    }
+}
+
+impl Drop for Firmware {
+    fn drop(&mut self) {
+        unsafe { bindings::release_firmware(*self.0.get()) };
+    }
+}
+
+// SAFETY: `Firmware` only holds a pointer to a C firmware struct,

which is safe to be used from any +// thread.

rust/kernel/firmware.rs new file +3 -0
+unsafe impl Send for Firmware {}
+
+// SAFETY: `Firmware` only holds a pointer to a C firmware struct,

references to which are safe to +// be used from any thread.

rust/kernel/firmware.rs new file +1 -0
+unsafe impl Sync for Firmware {}
rust/kernel/lib.rs +1 -0
index 6415968ee3b8..ed97d131661a 100644
@@ -35,6 +35,7 @@
  #[cfg(CONFIG_DRM = "y")]
  pub mod drm;
  pub mod error;
+pub mod firmware;
  pub mod init;
  pub mod ioctl;
  #[cfg(CONFIG_KUNIT)]
#18 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Hi,

Quoted 37 lines · On Tue, 28 May 2024 08:40:20 +0000 Zhi Wang <[email protected]> wrote:
Quoted 27 lines · Danilo Krummrich

External email: Use caution opening links or attachments

Quoted 17 lines · Zhi Wang
Quoted 5 lines · On Mon, 20 May 2024 19:24:19 +0200 Danilo Krummrich <[email protected]> wrote:

Add an abstraction around the kernels firmware API to request firmware images. The abstraction provides functions to access the firmware buffer and / or copy it to a new buffer allocated with a given allocator backend.

Was playing with firmware extractions based on this patch. Unfortunately I ended up with a lot of pointer operations, unsafe statements.

As we know many vendors have a C headers for the definitions of the firwmare content, the driver extract the data by applying a struct pointer on it.

Quoted 5 lines

But in rust, I feel it would nice that we can also have a common firmware extractor for drivers, that can wrap the pointer operations, take a list of the firmware struct members that converted from C headers as the input, offer the driver some common ABI methods to query them. Maybe that would ease the pain a lot.

Quoted 8 lines

So, you mean some abstraction that takes a list of types, offsets in the firmware and a reference to the firmware itself and provides references to the corresponding objects?

I agree it might be helpful to have some common infrastructure for this, but the operations on it would still be unsafe, since ultimately it involves dereferencing pointers.

Quoted 8 lines

I think the goal is to 1) concentrate the "unsafe" operations in a abstraction so the driver doesn't have to write explanation of unsafe operations here and there, improve the readability of the driver that interacts with vendor-firmware buffer. 2) ease the driver maintenance burden.

Some solutions I saw in different projects written in rust for de-referencing a per-defined struct:

Aren't there other abstractions that require that functionality, not just the firmware abstractions?

#19 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 51 lines · FUJITA Tomonori

External email: Use caution opening links or attachments

Hi,

Quoted 43 lines · On Tue, 28 May 2024 08:40:20 +0000 Zhi Wang <[email protected]> wrote:
Quoted 27 lines · Danilo Krummrich

External email: Use caution opening links or attachments

Quoted 17 lines · Zhi Wang
Quoted 5 lines · On Mon, 20 May 2024 19:24:19 +0200 Danilo Krummrich <[email protected]> wrote:

Add an abstraction around the kernels firmware API to request firmware images. The abstraction provides functions to access the firmware buffer and / or copy it to a new buffer allocated with a given allocator backend.

Was playing with firmware extractions based on this patch. Unfortunately I ended up with a lot of pointer operations, unsafe statements.

As we know many vendors have a C headers for the definitions of the firwmare content, the driver extract the data by applying a struct pointer on it.

Quoted 5 lines

But in rust, I feel it would nice that we can also have a common firmware extractor for drivers, that can wrap the pointer operations, take a list of the firmware struct members that converted from C headers as the input, offer the driver some common ABI methods to query them. Maybe that would ease the pain a lot.

Quoted 8 lines

So, you mean some abstraction that takes a list of types, offsets in the firmware and a reference to the firmware itself and provides references to the corresponding objects?

I agree it might be helpful to have some common infrastructure for this, but the operations on it would still be unsafe, since ultimately it involves dereferencing pointers.

I think the goal is to 1) concentrate the "unsafe" operations in a abstraction so the driver doesn't have to write explanation of unsafe operations here and there, improve the readability of the driver that interacts with vendor-firmware buffer. 2) ease the driver maintenance burden.

Quoted 5 lines
Quoted 2 lines

Some solutions I saw in different projects written in rust for de-referencing a per-defined struct:

Aren't there other abstractions that require that functionality, not just the firmware abstractions?

Sure, but they might implement it in a different way due to their different scale and requirements of maintenance.

I am more interested in what is the better option for firmware abstractions based on its scale and requirements. 1) how to improve the readability of the driver, meanwhile keep the operations safe. 2) there has been C-version vendor-firmware definitions, what would be the best for the rust driver to leverage it based on the routines that the rust kernel has already had. 3) how to avoid syncing the headers of vendor firmware between C and rust version, as the definition can scale up due to HW generations or ABI changes.

Thanks,
Zhi.

#20 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

In reply to Zhi Wang
Quoted 37 lines · Zhi Wang
Quoted 27 lines · Danilo Krummrich

External email: Use caution opening links or attachments

Quoted 17 lines · Zhi Wang
Quoted 5 lines · On Mon, 20 May 2024 19:24:19 +0200 Danilo Krummrich <[email protected]> wrote:

Add an abstraction around the kernels firmware API to request firmware images. The abstraction provides functions to access the firmware buffer and / or copy it to a new buffer allocated with a given allocator backend.

Was playing with firmware extractions based on this patch. Unfortunately I ended up with a lot of pointer operations, unsafe statements.

As we know many vendors have a C headers for the definitions of the firwmare content, the driver extract the data by applying a struct pointer on it.

Quoted 5 lines

But in rust, I feel it would nice that we can also have a common firmware extractor for drivers, that can wrap the pointer operations, take a list of the firmware struct members that converted from C headers as the input, offer the driver some common ABI methods to query them. Maybe that would ease the pain a lot.

Quoted 8 lines

So, you mean some abstraction that takes a list of types, offsets in the firmware and a reference to the firmware itself and provides references to the corresponding objects?

I agree it might be helpful to have some common infrastructure for this, but the operations on it would still be unsafe, since ultimately it involves dereferencing pointers.

Quoted 5 lines

I think the goal is to 1) concentrate the "unsafe" operations in a abstraction so the driver doesn't have to write explanation of unsafe operations here and there, improve the readability of the driver that interacts with vendor-firmware buffer. 2) ease the driver maintenance burden.

With a generic abstraction, as in 1), at lest some of the abstraction's functions would be unsafe themselves, since they have to rely on the layout (or offset) passed by the driver being correct. What if I pass a wrong layout / offset for a structure that contains a pointer? This might still result in an invalid pointer dereference. Am I missing something?

Quoted 22 lines

Some solutions I saw in different projects written in rust for de-referencing a per-defined struct:

1) Take the vendor firmware buffer as a whole, invent methods like read/write with offset for operating the buffer.

In this scheme, the driver is responsible for taking care of each data member in a vendor firmware struct and also its valid offset. The abstraction only covers the boundary of the whole firmware buffer.

The cons is the readability of the operation of the vendor firmware buffer in the driver is not good comparing with C code.

Hate to think a lot of xxx = vendor_firmware_struct.read(offset); // reading item A in the code.

2) Define the firmware struct in rust (might need to find a better way to handle "union" in the definition of the vendor firmware struct). Use macros to generate methods of accessing each data member for the vendor firmware struct.

Quoted 8 lines

Then the code in the driver will be like xxx =
vendor_firmware_struct.item_a(); in the driver.

In this scheme, the abstraction and the generated methods covers the boundary check. The "unsafe" statement can stay in the generated struct-access methods.

This might even be implemented as a more generic rust feature in the kernel.

This sounds more like a driver specific abstraction to me, which, as you write, we can probably come up with some macros that help implementing it.

But again, what if the offsets are within the boundary, but still at a wrong offset? What if the data obtained from a wrong offset leads to other safety implications when further processing them? I think no generic abstraction can ever cover the safety parts of this (entirely). I think there are always semanic parts to this the driver has to cover.

Generally, I think we should aim for some generalization, but I think we should not expect it to cover all the safety aspects.

Quoted 3 lines

The cons is still the driver might need to sync between the C-version definition and rust-version definition.

What do you mean with the driver needs to sync between a C and a Rust version of structure definitions?

Quoted 5 lines

3) Also re-using C bindings generation in the kernel came to my mind when thinking of this problem, since it allows the rust code to access the C struct, but they don't have the boundary check. Still need another layer/macros to wrap it.

I think we should have the structure definitions in Rust directly.

- Danilo

Quoted 6 lines
Quoted 6 lines
Quoted 6 lines

Thanks,
Zhi.

#21 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 84 lines · Danilo Krummrich

External email: Use caution opening links or attachments

Quoted 37 lines · Zhi Wang
Quoted 27 lines · Danilo Krummrich

External email: Use caution opening links or attachments

Quoted 17 lines · Zhi Wang
Quoted 5 lines · On Mon, 20 May 2024 19:24:19 +0200 Danilo Krummrich <[email protected]> wrote:

Add an abstraction around the kernels firmware API to request firmware images. The abstraction provides functions to access the firmware buffer and / or copy it to a new buffer allocated with a given allocator backend.

Was playing with firmware extractions based on this patch. Unfortunately I ended up with a lot of pointer operations, unsafe statements.

As we know many vendors have a C headers for the definitions of the firwmare content, the driver extract the data by applying a struct pointer on it.

Quoted 5 lines

But in rust, I feel it would nice that we can also have a common firmware extractor for drivers, that can wrap the pointer operations, take a list of the firmware struct members that converted from C headers as the input, offer the driver some common ABI methods to query them. Maybe that would ease the pain a lot.

Quoted 8 lines

So, you mean some abstraction that takes a list of types, offsets in the firmware and a reference to the firmware itself and provides references to the corresponding objects?

I agree it might be helpful to have some common infrastructure for this, but the operations on it would still be unsafe, since ultimately it involves dereferencing pointers.

Quoted 5 lines

I think the goal is to 1) concentrate the "unsafe" operations in a abstraction so the driver doesn't have to write explanation of unsafe operations here and there, improve the readability of the driver that interacts with vendor-firmware buffer. 2) ease the driver maintenance burden.

With a generic abstraction, as in 1), at lest some of the abstraction's functions would be unsafe themselves, since they have to rely on the layout (or offset) passed by the driver being correct. What if I pass a wrong layout / offset for a structure that contains a pointer? This might still result in an invalid pointer dereference. Am I missing something?

Quoted 22 lines

Some solutions I saw in different projects written in rust for de-referencing a per-defined struct:

1) Take the vendor firmware buffer as a whole, invent methods like read/write with offset for operating the buffer.

In this scheme, the driver is responsible for taking care of each data member in a vendor firmware struct and also its valid offset. The abstraction only covers the boundary of the whole firmware buffer.

The cons is the readability of the operation of the vendor firmware buffer in the driver is not good comparing with C code.

Hate to think a lot of xxx = vendor_firmware_struct.read(offset); // reading item A in the code.

2) Define the firmware struct in rust (might need to find a better way to handle "union" in the definition of the vendor firmware struct). Use macros to generate methods of accessing each data member for the vendor firmware struct.

Quoted 8 lines

Then the code in the driver will be like xxx =
vendor_firmware_struct.item_a(); in the driver.

In this scheme, the abstraction and the generated methods covers the boundary check. The "unsafe" statement can stay in the generated struct-access methods.

This might even be implemented as a more generic rust feature in the kernel.

Quoted 9 lines

This sounds more like a driver specific abstraction to me, which, as you write, we can probably come up with some macros that help implementing it.

But again, what if the offsets are within the boundary, but still at a wrong offset? What if the data obtained from a wrong offset leads to other safety implications when further processing them? I think no generic abstraction can ever cover the safety parts of this (entirely). I think there are always semanic parts to this the driver has to cover.

I was thinking of a proc_macro that takes a vender-firmware struct definition. As it can get the type and the name of each member, then it can generate methods like xxx::member_a() that returns the value from the "unsafe {*(type *)(pointer + offset)}". Thus, the unsafe stuff stays in the generated methods.

For offset, I was hoping the macro can automatically calculate it based on the member offset (the vendor-firmware definition) when generating xxx::member_x(). (Maybe it can also take alignment into account)

As the return value has a rust type, rust should catch it if the caller wants to do something crazy there.

Quoted 3 lines

Generally, I think we should aim for some generalization, but I think we should not expect it to cover all the safety aspects.

I agree. I was mostly thinking how to ease the pain of driver and see how the best we can do for it.

Quoted 7 lines
Quoted 3 lines

The cons is still the driver might need to sync between the C-version definition and rust-version definition.

What do you mean with the driver needs to sync between a C and a Rust version of structure definitions?

Let's say a C driver maintains quite some headers and support some not very new HWs. A new rust driver maintains some headers that written in rust, it needs those headers as well. Now the firmware updates, both the C headers and rust headers needs to be updated accordingly due to ABI changes.

I was thinking if that process can be optimized, at least trying to avoid the sync process, which might be painful if the amount of the headers are huge.

Quoted 17 lines
Quoted 5 lines

3) Also re-using C bindings generation in the kernel came to my mind when thinking of this problem, since it allows the rust code to access the C struct, but they don't have the boundary check. Still need another layer/macros to wrap it.

I think we should have the structure definitions in Rust directly.

- Danilo

Quoted 6 lines
Quoted 6 lines
Quoted 6 lines

Thanks,
Zhi.

#22 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

In reply to Danilo Krummrich

Hi,
Thanks for working on the firmware API!

Quoted 45 lines · On Mon, 20 May 2024 19:24:19 +0200 Danilo Krummrich <[email protected]> wrote:

Add an abstraction around the kernels firmware API to request firmware images. The abstraction provides functions to access the firmware buffer and / or copy it to a new buffer allocated with a given allocator backend.

The firmware is released once the abstraction is dropped.

---
 rust/bindings/bindings_helper.h |  1 +
 rust/kernel/firmware.rs         | 74 +++++++++++++++++++++++++++++++++
 rust/kernel/lib.rs              |  1 +
 3 files changed, 76 insertions(+)
 create mode 100644 rust/kernel/firmware.rs
rust/bindings/bindings_helper.h +1 -0
index b245db8d5a87..e4ffc47da5ec 100644
@@ -14,6 +14,7 @@
 #include <kunit/test.h>
 #include <linux/errname.h>
 #include <linux/ethtool.h>
+#include <linux/firmware.h>
 #include <linux/jiffies.h>
 #include <linux/mdio.h>
 #include <linux/pci.h>
rust/kernel/firmware.rs new file +12 -0
new file mode 100644
index 000000000000..700504fb3c9c
@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Firmware abstraction
+//!
+//! C header: [`include/linux/firmware.h`](../../../../include/linux/firmware.h")
+
+use crate::{bindings, device::Device, error::Error, error::Result, str::CStr, types::Opaque};
+
+/// Abstraction around a C firmware struct.
+///
+/// This is a simple abstraction around the C firmware API. Just like with the C API, firmware can
+/// be requested. Once requested the abstraction provides direct access to the firmware buffer as

rust/kernel/firmware.rs line 22

Quoted 10 lines
rust/kernel/firmware.rs new file +10 -0
+/// `&[u8]`. Alternatively, the firmware can be copied to a new buffer using `Firmware::copy`. The
+/// firmware is released once [`Firmware`] is dropped.
+///
+/// # Examples
+///
+/// ```
+/// let fw = Firmware::request("path/to/firmware.bin", dev.as_ref())?;
+/// driver_load_firmware(fw.data());
+/// ```
+pub struct Firmware(Opaque<*const bindings::firmware>);

Wrapping a raw pointer is not the intended use of Qpaque type?

#23 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 65 lines · FUJITA Tomonori

Hi,
Thanks for working on the firmware API!

Quoted 59 lines · On Mon, 20 May 2024 19:24:19 +0200 Danilo Krummrich <[email protected]> wrote:

Add an abstraction around the kernels firmware API to request firmware
images. The abstraction provides functions to access the firmware buffer and / or copy it to a new buffer allocated with a given allocator
backend.

The firmware is released once the abstraction is dropped.

---
  rust/bindings/bindings_helper.h |  1 +
  rust/kernel/firmware.rs         | 74
+++++++++++++++++++++++++++++++++
  rust/kernel/lib.rs              |  1 +

  3 files changed, 76 insertions(+)

  create mode 100644 rust/kernel/firmware.rs

rust/bindings/bindings_helper.h +1 -0
index b245db8d5a87..e4ffc47da5ec 100644
@@ -14,6 +14,7 @@
   #include <kunit/test.h>
   #include <linux/errname.h>
   #include <linux/ethtool.h>
+#include <linux/firmware.h>
   #include <linux/jiffies.h>
   #include <linux/mdio.h>
   #include <linux/pci.h>
rust/kernel/firmware.rs new file +5 -0
new file mode 100644
index 000000000000..700504fb3c9c
@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Firmware abstraction
+//!
+//! C header:

[include/linux/firmware.h](../../../../include/linux/firmware.h")

rust/kernel/firmware.rs new file +2 -0
+
+use crate::{bindings, device::Device, error::Error, error::Result,

str::CStr, types::Opaque};

rust/kernel/firmware.rs new file +4 -0
+
+/// Abstraction around a C firmware struct.
+///
+/// This is a simple abstraction around the C firmware API. Just

like with the C API, firmware can
+/// be requested. Once requested the abstraction provides direct access to the firmware buffer as
+/// &[u8]. Alternatively, the firmware can be copied to a new buffer using Firmware::copy. The

rust/kernel/firmware.rs new file +4 -0
+/// firmware is released once [`Firmware`] is dropped.
+///
+/// # Examples
+///
Quoted 9 lines

rust/kernel/firmware.rs line 22

Quoted 6 lines
rust/kernel/firmware.rs new file +2 -0
+/// ```
+/// let fw = Firmware::request("path/to/firmware.bin",

dev.as_ref())?;

rust/kernel/firmware.rs new file +3 -0
+/// driver_load_firmware(fw.data());
+/// ```
+pub struct Firmware(Opaque<*const bindings::firmware>);

Wrapping a raw pointer is not the intended use of Qpaque type?

What is the intended use?
As I see it, all uses wrapp some binding::* – but a rawpointer to a binding shouldn't be wrapped by it?

Maybe we can add something to the docu in kernel/types.rs:

/// Stores an opaque value.
///
/// This is meant to be used with FFI objects that are never interpreted by Rust code. #[repr(transparent)]
pub struct Opaque<T> {

P.

#24 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Hi,

Quoted 22 lines · On Wed, 22 May 2024 09:37:30 +0200 Philipp Stanner <[email protected]> wrote:
Quoted 12 lines
Quoted 12 lines
rust/kernel/firmware.rs new file +3 -0
+/// Abstraction around a C firmware struct.
+///
+/// This is a simple abstraction around the C firmware API. Just

like with the C API, firmware can
+/// be requested. Once requested the abstraction provides direct access to the firmware buffer as
+/// &[u8]. Alternatively, the firmware can be copied to a new buffer using Firmware::copy. The

rust/kernel/firmware.rs new file +4 -0
+/// firmware is released once [`Firmware`] is dropped.
+///
+/// # Examples
+///
Quoted 9 lines

rust/kernel/firmware.rs line 22

Quoted 6 lines
(quoted diff) +2 -0
+/// ```
+/// let fw = Firmware::request("path/to/firmware.bin",

dev.as_ref())?;

rust/kernel/firmware.rs new file +3 -0
+/// driver_load_firmware(fw.data());
+/// ```
+pub struct Firmware(Opaque<*const bindings::firmware>);

Wrapping a raw pointer is not the intended use of Qpaque type?

Quoted 3 lines

What is the intended use?
As I see it, all uses wrapp some binding::* – but a rawpointer to a binding shouldn't be wrapped by it?

If I understand correctly, it's for embedding C's struct in Rust's struct (as all the usage in the tree do). It gives the tricks for initialization and a pointer to the embedded object.

The C's firmware API gives a pointer to an initialized object so no reason to use Opaque.

With such C API, Rust's struct simply uses raw pointers in old rust branch. For example,

https://github.com/Rust-for-Linux/linux/blob/rust/rust/kernel/chrdev.rs#L28

struct Cdev(*mut bindings::cdev);

Another choice that I know is NonNull:

https://lore.kernel.org/lkml/[email protected]/

pub struct Page {
page: NonNull<bindings::page>,
}

#25 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 31 lines · FUJITA Tomonori

Hi,

Quoted 25 lines · On Wed, 22 May 2024 09:37:30 +0200 Philipp Stanner <[email protected]> wrote:
Quoted 12 lines
Quoted 12 lines
rust/kernel/firmware.rs new file +3 -0
+/// Abstraction around a C firmware struct.
+///
+/// This is a simple abstraction around the C firmware API. Just

like with the C API, firmware can
+/// be requested. Once requested the abstraction provides direct access to the firmware buffer as
+/// &[u8]. Alternatively, the firmware can be copied to a new buffer using Firmware::copy. The

rust/kernel/firmware.rs new file +4 -0
+/// firmware is released once [`Firmware`] is dropped.
+///
+/// # Examples
+///
Quoted 9 lines

rust/kernel/firmware.rs line 22

Quoted 6 lines
(quoted diff) +2 -0
+/// ```
+/// let fw = Firmware::request("path/to/firmware.bin",

dev.as_ref())?;

rust/kernel/firmware.rs new file +3 -0
+/// driver_load_firmware(fw.data());
+/// ```
+pub struct Firmware(Opaque<*const bindings::firmware>);

Wrapping a raw pointer is not the intended use of Qpaque type?

What is the intended use?
As I see it, all uses wrapp some binding::* – but a rawpointer to a binding shouldn't be wrapped by it?

Thank you Tomo for calling this out!

And yes, using Opaque on a pointer is weird. A Opaque<T> is UnsafeCell<MayUninit<T>>, UnsafeCell means the inner T may be accessed by C code at anytime, and MayUninit means that the inner T may not be properly initialized by the C code. So as the doc says:

This is meant to be used with FFI objects that are never interpreted by Rust code.

that is, Rust code should never create a &T or &mut T, it should only be accessed with Opaque::get() or its friends (i.e. accessing it via a raw pointer), much like a black box to Rust code in some sense.

Hence putting Opaque on a raw pointer is not what you want to do.

Quoted 15 lines

If I understand correctly, it's for embedding C's struct in Rust's struct (as all the usage in the tree do). It gives the tricks for initialization and a pointer to the embedded object.

The C's firmware API gives a pointer to an initialized object so no reason to use Opaque.

With such C API, Rust's struct simply uses raw pointers in old rust branch. For example,

https://github.com/Rust-for-Linux/linux/blob/rust/rust/kernel/chrdev.rs#L28

struct Cdev(*mut bindings::cdev);

Quoted 7 lines

Another choice that I know is NonNull:

https://lore.kernel.org/lkml/[email protected]/

pub struct Page {
page: NonNull<bindings::page>,
}

Both are reasonable for temporary use, although, we could generify the "wrapping on pointer which owns the underlying object" in the future.

Regards,
Boqun

#26 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

In reply to FUJITA Tomonori
Quoted 55 lines · FUJITA Tomonori

Hi,
Thanks for working on the firmware API!

Quoted 49 lines · On Mon, 20 May 2024 19:24:19 +0200 Danilo Krummrich <[email protected]> wrote:

Add an abstraction around the kernels firmware API to request firmware images. The abstraction provides functions to access the firmware buffer and / or copy it to a new buffer allocated with a given allocator backend.

The firmware is released once the abstraction is dropped.

---
 rust/bindings/bindings_helper.h |  1 +
 rust/kernel/firmware.rs         | 74 +++++++++++++++++++++++++++++++++
 rust/kernel/lib.rs              |  1 +
 3 files changed, 76 insertions(+)
 create mode 100644 rust/kernel/firmware.rs
rust/bindings/bindings_helper.h +1 -0
index b245db8d5a87..e4ffc47da5ec 100644
@@ -14,6 +14,7 @@
 #include <kunit/test.h>
 #include <linux/errname.h>
 #include <linux/ethtool.h>
+#include <linux/firmware.h>
 #include <linux/jiffies.h>
 #include <linux/mdio.h>
 #include <linux/pci.h>
rust/kernel/firmware.rs new file +16 -0
new file mode 100644
index 000000000000..700504fb3c9c
@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Firmware abstraction
+//!
+//! C header: [`include/linux/firmware.h`](../../../../include/linux/firmware.h")
+
+use crate::{bindings, device::Device, error::Error, error::Result, str::CStr, types::Opaque};
+
+/// Abstraction around a C firmware struct.
+///
+/// This is a simple abstraction around the C firmware API. Just like with the C API, firmware can
+/// be requested. Once requested the abstraction provides direct access to the firmware buffer as
+/// `&[u8]`. Alternatively, the firmware can be copied to a new buffer using `Firmware::copy`. The
+/// firmware is released once [`Firmware`] is dropped.
+///
+/// # Examples
Quoted 9 lines

rust/kernel/firmware.rs line 22

Quoted 6 lines
rust/kernel/firmware.rs new file +6 -0
+///
+/// ```
+/// let fw = Firmware::request("path/to/firmware.bin", dev.as_ref())?;
+/// driver_load_firmware(fw.data());
+/// ```
+pub struct Firmware(Opaque<*const bindings::firmware>);

Wrapping a raw pointer is not the intended use of Qpaque type?

Indeed, will fix this in v2 and use NonNull instead. I'll also offload most of the boilerplate in the 'request' functions to some common 'request_internal' one.

#27 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 18 lines · On Mon, 27 May 2024 21:22:47 +0200 Danilo Krummrich <[email protected]> wrote:
Quoted 8 lines
Quoted 8 lines
rust/kernel/firmware.rs new file +8 -0
+/// Abstraction around a C firmware struct.
+///
+/// This is a simple abstraction around the C firmware API. Just like with the C API, firmware can
+/// be requested. Once requested the abstraction provides direct access to the firmware buffer as
+/// `&[u8]`. Alternatively, the firmware can be copied to a new buffer using `Firmware::copy`. The
+/// firmware is released once [`Firmware`] is dropped.
+///
+/// # Examples
Quoted 9 lines

rust/kernel/firmware.rs line 22

Quoted 6 lines
rust/kernel/firmware.rs new file +6 -0
+///
+/// ```
+/// let fw = Firmware::request("path/to/firmware.bin", dev.as_ref())?;
+/// driver_load_firmware(fw.data());
+/// ```
+pub struct Firmware(Opaque<*const bindings::firmware>);

Wrapping a raw pointer is not the intended use of Qpaque type?

Quoted 2 lines

Indeed, will fix this in v2 and use NonNull instead. I'll also offload most of the boilerplate in the 'request' functions to some common 'request_internal' one.

You might need to add 'Invariants' comment on Firmware struct.

BTW, what merge window are you aiming for? As I wrote before, I have a driver that needs the firmware abstractions (the minimum device abstractions is enough; Device::as_raw() and as_ref()). So the sooner, the better for me.

#28 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 21 lines · FUJITA Tomonori
Quoted 18 lines · On Mon, 27 May 2024 21:22:47 +0200 Danilo Krummrich <[email protected]> wrote:
Quoted 17 lines
Quoted 4 lines
rust/kernel/firmware.rs new file +4 -0
+/// Abstraction around a C firmware struct.
+///
+/// This is a simple abstraction around the C firmware API. Just like with the C API, firmware can
+/// be requested. Once requested the abstraction provides direct access to the firmware buffer as

rust/kernel/firmware.rs line 22

Quoted 10 lines
rust/kernel/firmware.rs new file +10 -0
+/// `&[u8]`. Alternatively, the firmware can be copied to a new buffer using `Firmware::copy`. The
+/// firmware is released once [`Firmware`] is dropped.
+///
+/// # Examples
+///
+/// ```
+/// let fw = Firmware::request("path/to/firmware.bin", dev.as_ref())?;
+/// driver_load_firmware(fw.data());
+/// ```
+pub struct Firmware(Opaque<*const bindings::firmware>);

Wrapping a raw pointer is not the intended use of Qpaque type?

Quoted 4 lines
Quoted 2 lines

Indeed, will fix this in v2 and use NonNull instead. I'll also offload most of the boilerplate in the 'request' functions to some common 'request_internal' one.

You might need to add 'Invariants' comment on Firmware struct.

Which ones do you think should be documented?

Quoted 5 lines

BTW, what merge window are you aiming for? As I wrote before, I have a driver that needs the firmware abstractions (the minimum device abstractions is enough; Device::as_raw() and as_ref()). So the sooner, the better for me.

I'm not aiming this on a specific merge window.

However, if you have a driver that needs the firmware abstractions, I would be surprised if there were any hesitations to already merge the minimum device abstractions [1] and this one (once reviewed) without the rest. At least there aren't any from my side.

[1] https://lore.kernel.org/rust-for-linux/[email protected]/

Quoted 1 line
maintainer
#29 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 6 lines · Danilo Krummrich

However, if you have a driver that needs the firmware abstractions, I would be surprised if there were any hesitations to already merge the minimum device abstractions [1] and this one (once reviewed) without the rest. At least there aren't any from my side.

[1] https://lore.kernel.org/rust-for-linux/[email protected]/

No, the device abstractions are NOT ready for merging just yet, sorry, if for no other reason than a non-RFC has never been posted :)

greg k-h

#30 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 10 lines · Greg KH
Quoted 6 lines · Danilo Krummrich

However, if you have a driver that needs the firmware abstractions, I would be surprised if there were any hesitations to already merge the minimum device abstractions [1] and this one (once reviewed) without the rest. At least there aren't any from my side.

[1] https://lore.kernel.org/rust-for-linux/[email protected]/

No, the device abstractions are NOT ready for merging just yet, sorry, if for no other reason than a non-RFC has never been posted :)

I did not say they are ready. I said that I'd be surprised if we couldn't merge
[1] once it is ready even without the rest being ready. :)

Quoted 3 lines

greg k-h

#31 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

In reply to Greg KH

Hi,

Quoted 10 lines · On Tue, 28 May 2024 14:45:02 +0200 Greg KH <[email protected]> wrote:
Quoted 6 lines · Danilo Krummrich

However, if you have a driver that needs the firmware abstractions, I would be surprised if there were any hesitations to already merge the minimum device abstractions [1] and this one (once reviewed) without the rest. At least there aren't any from my side.

[1] https://lore.kernel.org/rust-for-linux/[email protected]/

No, the device abstractions are NOT ready for merging just yet, sorry, if for no other reason than a non-RFC has never been posted :)

Indeed, I understand that you aren't convinced.

We can start with much simpler device abstractions than the above minimum for the firmware abstractions.

All the firmware abstractions need is wrapping C's pointer to a device object with Rust struct only during a caller knows the pointer is valid. No play with the reference count of a struct device.

For a Rust PHY driver, you know that you have a valid pointer to C's device object of C's PHY device during the probe callback. The driver creates a Rust device object to wrap the C pointer to the C's device object and passes it to the firmware abstractions. The firmware abstractions gets the C's pointer from the Rust object and calls C's function to load firmware, returns the result.

You have concerns about the simple code like the following?

rust/kernel/device.rs new file +30 -0
new file mode 100644
index 000000000000..6144437984a9
@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Generic devices that are part of the kernel's driver model.
+//!
+//! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
+
+use crate::types::Opaque;
+
+#[repr(transparent)]
+pub struct Device(Opaque<bindings::device>);
+
+impl Device {
+    /// Creates a new [`Device`] instance from a raw pointer.
+    ///
+    /// # Safety
+    ///
+    /// For the duration of 'a, the pointer must point at a valid `device`.
+    pub unsafe fn from_raw<'a>(ptr: *mut bindings::device) -> &'a Self {
+        // CAST: `Self` is a `repr(transparent)` wrapper around `bindings::device`.
+        let ptr = ptr.cast::<Self>();
+        // SAFETY: by the function requirements the pointer is valid and we have unique access for
+        // the duration of `'a`.
+        unsafe { &mut *ptr }
+    }
+
+    /// Returns the raw pointer to the device.
+    pub fn as_raw(&self) -> *mut bindings::device {
+        self.0.get()
+    }
+}
maintainer
#32 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 16 lines · FUJITA Tomonori

Hi,

Quoted 10 lines · On Tue, 28 May 2024 14:45:02 +0200 Greg KH <[email protected]> wrote:
Quoted 6 lines · Danilo Krummrich

However, if you have a driver that needs the firmware abstractions, I would be surprised if there were any hesitations to already merge the minimum device abstractions [1] and this one (once reviewed) without the rest. At least there aren't any from my side.

[1] https://lore.kernel.org/rust-for-linux/[email protected]/

No, the device abstractions are NOT ready for merging just yet, sorry, if for no other reason than a non-RFC has never been posted :)

Quoted 8 lines

Indeed, I understand that you aren't convinced.

We can start with much simpler device abstractions than the above minimum for the firmware abstractions.

All the firmware abstractions need is wrapping C's pointer to a device object with Rust struct only during a caller knows the pointer is valid. No play with the reference count of a struct device.

Makes sense, but note that almost no one should be dealing with "raw" struct device pointers :)

Quoted 23 lines

For a Rust PHY driver, you know that you have a valid pointer to C's device object of C's PHY device during the probe callback. The driver creates a Rust device object to wrap the C pointer to the C's device object and passes it to the firmware abstractions. The firmware abstractions gets the C's pointer from the Rust object and calls C's function to load firmware, returns the result.

You have concerns about the simple code like the following?

rust/kernel/device.rs new file +7 -0
new file mode 100644
index 000000000000..6144437984a9
@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Generic devices that are part of the kernel's driver model.
+//!
+//! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
+
+use crate::types::Opaque;

rust/kernel/device.rs line 17

Quoted 10 lines
rust/kernel/device.rs new file +10 -0
+
+#[repr(transparent)]
+pub struct Device(Opaque<bindings::device>);
+
+impl Device {
+    /// Creates a new [`Device`] instance from a raw pointer.
+    ///
+    /// # Safety
+    ///
+    /// For the duration of 'a, the pointer must point at a valid `device`.

If the following rust code does what this comment says, then sure, I'm ok with it for now if it helps you all out with stuff like the firmware interface for the phy rust code.

thanks,

greg k-h

#33 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Hi,

Quoted 29 lines · On Wed, 29 May 2024 21:57:03 +0200 Greg KH <[email protected]> wrote:
Quoted 29 lines

For a Rust PHY driver, you know that you have a valid pointer to C's device object of C's PHY device during the probe callback. The driver creates a Rust device object to wrap the C pointer to the C's device object and passes it to the firmware abstractions. The firmware abstractions gets the C's pointer from the Rust object and calls C's function to load firmware, returns the result.

You have concerns about the simple code like the following?

rust/kernel/device.rs new file +13 -0
new file mode 100644
index 000000000000..6144437984a9
@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Generic devices that are part of the kernel's driver model.
+//!
+//! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
+
+use crate::types::Opaque;
+
+#[repr(transparent)]
+pub struct Device(Opaque<bindings::device>);
+
+impl Device {
+    /// Creates a new [`Device`] instance from a raw pointer.
Quoted 8 lines

rust/kernel/device.rs line 17

Quoted 4 lines
rust/kernel/device.rs new file +4 -0
+    ///
+    /// # Safety
+    ///
+    /// For the duration of 'a, the pointer must point at a valid `device`.

If the following rust code does what this comment says, then sure, I'm ok with it for now if it helps you all out with stuff like the firmware interface for the phy rust code.

Great, thanks a lot!

Danilo and Wedson, are there any concerns about pushing this patch [1] for the firmware abstractions?

I you prefer to be the author of the patch, please let me know. Who the author is doesn't matter to me. Otherwise, I'll add Co-developed-by tag.

[1] https://lore.kernel.org/rust-for-linux/[email protected]/

#34 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 43 lines · FUJITA Tomonori

Hi,

Quoted 29 lines · On Wed, 29 May 2024 21:57:03 +0200 Greg KH <[email protected]> wrote:
Quoted 29 lines

For a Rust PHY driver, you know that you have a valid pointer to C's device object of C's PHY device during the probe callback. The driver creates a Rust device object to wrap the C pointer to the C's device object and passes it to the firmware abstractions. The firmware abstractions gets the C's pointer from the Rust object and calls C's function to load firmware, returns the result.

You have concerns about the simple code like the following?

rust/kernel/device.rs new file +13 -0
new file mode 100644
index 000000000000..6144437984a9
@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Generic devices that are part of the kernel's driver model.
+//!
+//! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
+
+use crate::types::Opaque;
+
+#[repr(transparent)]
+pub struct Device(Opaque<bindings::device>);
+
+impl Device {
+    /// Creates a new [`Device`] instance from a raw pointer.
Quoted 8 lines

rust/kernel/device.rs line 17

Quoted 4 lines
rust/kernel/device.rs new file +4 -0
+    ///
+    /// # Safety
+    ///
+    /// For the duration of 'a, the pointer must point at a valid `device`.

If the following rust code does what this comment says, then sure, I'm ok with it for now if it helps you all out with stuff like the firmware interface for the phy rust code.

Quoted 4 lines

Great, thanks a lot!

Danilo and Wedson, are there any concerns about pushing this patch [1] for the firmware abstractions?

Well, if everyone is fine with this one I don't see why we can't we go with [1] directly? AFAICS, we'd only need the following fix:

-//! C header: [include/linux/device.h](../../../../include/linux/device.h) +//! C header: [include/linux/device.h](srctree/include/linux/device.h)

[1] https://lore.kernel.org/rust-for-linux/[email protected]/

Quoted 7 lines

I you prefer to be the author of the patch, please let me know. Who the author is doesn't matter to me. Otherwise, I'll add Co-developed-by tag.

[1] https://lore.kernel.org/rust-for-linux/[email protected]/

#35 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Hi,

Quoted 55 lines · On Thu, 30 May 2024 04:01:39 +0200 Danilo Krummrich <[email protected]> wrote:
Quoted 43 lines · FUJITA Tomonori

Hi,

Quoted 29 lines · On Wed, 29 May 2024 21:57:03 +0200 Greg KH <[email protected]> wrote:
Quoted 29 lines

For a Rust PHY driver, you know that you have a valid pointer to C's device object of C's PHY device during the probe callback. The driver creates a Rust device object to wrap the C pointer to the C's device object and passes it to the firmware abstractions. The firmware abstractions gets the C's pointer from the Rust object and calls C's function to load firmware, returns the result.

You have concerns about the simple code like the following?

rust/kernel/device.rs new file +13 -0
new file mode 100644
index 000000000000..6144437984a9
@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Generic devices that are part of the kernel's driver model.
+//!
+//! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
+
+use crate::types::Opaque;
+
+#[repr(transparent)]
+pub struct Device(Opaque<bindings::device>);
+
+impl Device {
+    /// Creates a new [`Device`] instance from a raw pointer.
Quoted 8 lines

rust/kernel/device.rs line 17

Quoted 4 lines
rust/kernel/device.rs new file +4 -0
+    ///
+    /// # Safety
+    ///
+    /// For the duration of 'a, the pointer must point at a valid `device`.

If the following rust code does what this comment says, then sure, I'm ok with it for now if it helps you all out with stuff like the firmware interface for the phy rust code.

Quoted 4 lines

Great, thanks a lot!

Danilo and Wedson, are there any concerns about pushing this patch [1] for the firmware abstractions?

Well, if everyone is fine with this one I don't see why we can't we go with [1] directly? AFAICS, we'd only need the following fix:

(quoted diff) +1 -1
-//! C header: [`include/linux/device.h`](../../../../include/linux/device.h)
+//! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
Quoted 1 line

[1] https://lore.kernel.org/rust-for-linux/[email protected]/

The difference is that your patch touches the reference count of a struct device. My patch doesn't.

The following part in your patch allows the rust code to freely play with the reference count of a struct device. Your Rust drm driver interact with the reference count in a different way than C's drm drivers if I understand correctly. I'm not sure that Greg will be convinenced with that approach.

+// SAFETY: Instances of Device are always ref-counted. +unsafe impl crate::types::AlwaysRefCounted for Device {
+ fn inc_ref(&self) {
+ // SAFETY: The existence of a shared reference guarantees that the refcount is nonzero.
+ unsafe { bindings::get_device(self.as_raw()) };
+ }
+
+ unsafe fn dec_ref(obj: ptr::NonNull<Self>) {
+ // SAFETY: The safety requirements guarantee that the refcount is nonzero.
+ unsafe { bindings::put_device(obj.cast().as_ptr()) }
+ }
+}

The following comments give the impression that Rust abstractions wrongly interact with the reference count; callers check out the reference counter. Nobody should do that.

+ /// Callers must ensure that ptr is valid, non-null, and has a non-zero reference count.
+ pub unsafe fn from_raw(ptr: *mut bindings::device) -> ARef<Self> {

+    /// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count for
+    /// the entire duration when the returned reference exists.
+    pub unsafe fn as_ref<'a>(ptr: *mut bindings::device) -> &'a Self {

+ // SAFETY: Guaranteed by the safety requirements of the function.
+ unsafe { &*ptr.cast() }
+ }

#36 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 65 lines · FUJITA Tomonori

Hi,

Quoted 55 lines · On Thu, 30 May 2024 04:01:39 +0200 Danilo Krummrich <[email protected]> wrote:
Quoted 43 lines · FUJITA Tomonori

Hi,

Quoted 29 lines · On Wed, 29 May 2024 21:57:03 +0200 Greg KH <[email protected]> wrote:
Quoted 29 lines

For a Rust PHY driver, you know that you have a valid pointer to C's device object of C's PHY device during the probe callback. The driver creates a Rust device object to wrap the C pointer to the C's device object and passes it to the firmware abstractions. The firmware abstractions gets the C's pointer from the Rust object and calls C's function to load firmware, returns the result.

You have concerns about the simple code like the following?

rust/kernel/device.rs new file +13 -0
new file mode 100644
index 000000000000..6144437984a9
@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Generic devices that are part of the kernel's driver model.
+//!
+//! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
+
+use crate::types::Opaque;
+
+#[repr(transparent)]
+pub struct Device(Opaque<bindings::device>);
+
+impl Device {
+    /// Creates a new [`Device`] instance from a raw pointer.
Quoted 8 lines

rust/kernel/device.rs line 17

Quoted 4 lines
rust/kernel/device.rs new file +4 -0
+    ///
+    /// # Safety
+    ///
+    /// For the duration of 'a, the pointer must point at a valid `device`.

If the following rust code does what this comment says, then sure, I'm ok with it for now if it helps you all out with stuff like the firmware interface for the phy rust code.

Quoted 4 lines

Great, thanks a lot!

Danilo and Wedson, are there any concerns about pushing this patch [1] for the firmware abstractions?

Well, if everyone is fine with this one I don't see why we can't we go with [1] directly? AFAICS, we'd only need the following fix:

(quoted diff) +1 -1
-//! C header: [`include/linux/device.h`](../../../../include/linux/device.h)
+//! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
Quoted 1 line

[1] https://lore.kernel.org/rust-for-linux/[email protected]/

The difference is that your patch touches the reference count of a struct device. My patch doesn't.

Quoted 5 lines

The following part in your patch allows the rust code to freely play with the reference count of a struct device. Your Rust drm driver interact with the reference count in a different way than C's drm drivers if I understand correctly. I'm not sure that Greg will be convinenced with that approach.

I don't see how this is different than what we do in C. If you (for whatever reason) want to keep a pointer to a struct device you should make sure to increase the reference count of this device, such that it can't get freed for the time being.

This is a 1:1 representation of that and conceptually identical.

Quoted 14 lines
(quoted diff) +12 -0
+// SAFETY: Instances of `Device` are always ref-counted.
+unsafe impl crate::types::AlwaysRefCounted for Device {
+    fn inc_ref(&self) {
+        // SAFETY: The existence of a shared reference guarantees that the refcount is nonzero.
+        unsafe { bindings::get_device(self.as_raw()) };
+    }
+
+    unsafe fn dec_ref(obj: ptr::NonNull<Self>) {
+        // SAFETY: The safety requirements guarantee that the refcount is nonzero.
+        unsafe { bindings::put_device(obj.cast().as_ptr()) }
+    }
+}
Quoted 3 lines

The following comments give the impression that Rust abstractions wrongly interact with the reference count; callers check out the reference counter. Nobody should do that.

No, saying that the caller must ensure that the device "has a non-zero reference count" is a perfectly valid requirement.

It doensn't mean that the calling code has to peek the actual reference count, but it means that it must be ensured that while we try to increase the reference count it can't drop to zero unexpectedly.

Your patch, as a subset of this one, has the same requirements as listed below.

Quoted 11 lines
(quoted diff) +8 -0
+    /// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count.
+    pub unsafe fn from_raw(ptr: *mut bindings::device) -> ARef<Self> {
 
+    /// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count for
+    /// the entire duration when the returned reference exists.
+    pub unsafe fn as_ref<'a>(ptr: *mut bindings::device) -> &'a Self {
+        // SAFETY: Guaranteed by the safety requirements of the function.
+        unsafe { &*ptr.cast() }
+    }
#37 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 60 lines · On Thu, 30 May 2024 08:47:25 +0200 Danilo Krummrich <[email protected]> wrote:
Quoted 54 lines
Quoted 49 lines
Quoted 38 lines
Quoted 29 lines
Quoted 29 lines

For a Rust PHY driver, you know that you have a valid pointer to C's device object of C's PHY device during the probe callback. The driver creates a Rust device object to wrap the C pointer to the C's device object and passes it to the firmware abstractions. The firmware abstractions gets the C's pointer from the Rust object and calls C's function to load firmware, returns the result.

You have concerns about the simple code like the following?

rust/kernel/device.rs new file +13 -0
new file mode 100644
index 000000000000..6144437984a9
@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Generic devices that are part of the kernel's driver model.
+//!
+//! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
+
+use crate::types::Opaque;
+
+#[repr(transparent)]
+pub struct Device(Opaque<bindings::device>);
+
+impl Device {
+    /// Creates a new [`Device`] instance from a raw pointer.
Quoted 8 lines

rust/kernel/device.rs line 17

Quoted 4 lines
rust/kernel/device.rs new file +4 -0
+    ///
+    /// # Safety
+    ///
+    /// For the duration of 'a, the pointer must point at a valid `device`.

If the following rust code does what this comment says, then sure, I'm ok with it for now if it helps you all out with stuff like the firmware interface for the phy rust code.

Quoted 4 lines

Great, thanks a lot!

Danilo and Wedson, are there any concerns about pushing this patch [1] for the firmware abstractions?

Well, if everyone is fine with this one I don't see why we can't we go with [1] directly? AFAICS, we'd only need the following fix:

(quoted diff) +1 -1
-//! C header: [`include/linux/device.h`](../../../../include/linux/device.h)
+//! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
Quoted 1 line

[1] https://lore.kernel.org/rust-for-linux/[email protected]/

The difference is that your patch touches the reference count of a struct device. My patch doesn't.

Quoted 5 lines

The following part in your patch allows the rust code to freely play with the reference count of a struct device. Your Rust drm driver interact with the reference count in a different way than C's drm drivers if I understand correctly. I'm not sure that Greg will be convinenced with that approach.

Quoted 6 lines

I don't see how this is different than what we do in C. If you (for whatever reason) want to keep a pointer to a struct device you should make sure to increase the reference count of this device, such that it can't get freed for the time being.

This is a 1:1 representation of that and conceptually identical.

A drm driver does such? If a drm driver allocates two types of driver-specific data and keep a pointer to the pci device, then the driver calls get_device() twice to increase the reference count of the pci's device?

At the very least, network device drivers don't. a driver doesn't play with the reference count. The network subsystem does. And, the network subsystem doesn't care about how many pointers to a pci device a driver keeps.

With the patch [1], a driver plays with the reference count of a device and directly calls get/put_device. It's a different than C drivers for me (not sure about drm subsystem though).

But I might be misunderstanding that Greg isn't convinced with this reference count thing. We need to wait for his response.

Quoted 20 lines
Quoted 13 lines
(quoted diff) +12 -0
+// SAFETY: Instances of `Device` are always ref-counted.
+unsafe impl crate::types::AlwaysRefCounted for Device {
+    fn inc_ref(&self) {
+        // SAFETY: The existence of a shared reference guarantees that the refcount is nonzero.
+        unsafe { bindings::get_device(self.as_raw()) };
+    }
+
+    unsafe fn dec_ref(obj: ptr::NonNull<Self>) {
+        // SAFETY: The safety requirements guarantee that the refcount is nonzero.
+        unsafe { bindings::put_device(obj.cast().as_ptr()) }
+    }
+}
Quoted 3 lines

The following comments give the impression that Rust abstractions wrongly interact with the reference count; callers check out the reference counter. Nobody should do that.

No, saying that the caller must ensure that the device "has a non-zero reference count" is a perfectly valid requirement.

Quoted 3 lines

It doensn't mean that the calling code has to peek the actual reference count, but it means that it must be ensured that while we try to increase the reference count it can't drop to zero unexpectedly.

Yeah, the same requirements but expressed differently.

But again, I might be misunderstanding. Greg might have a different reason.

Quoted 15 lines

Your patch, as a subset of this one, has the same requirements as listed below.

Quoted 11 lines
(quoted diff) +8 -0
+    /// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count.
+    pub unsafe fn from_raw(ptr: *mut bindings::device) -> ARef<Self> {
 
+    /// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count for
+    /// the entire duration when the returned reference exists.
+    pub unsafe fn as_ref<'a>(ptr: *mut bindings::device) -> &'a Self {
+        // SAFETY: Guaranteed by the safety requirements of the function.
+        unsafe { &*ptr.cast() }
+    }
#38 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 68 lines · FUJITA Tomonori
Quoted 65 lines · On Thu, 30 May 2024 08:47:25 +0200 Danilo Krummrich <[email protected]> wrote:
Quoted 54 lines
Quoted 49 lines
Quoted 38 lines
Quoted 29 lines
Quoted 29 lines

For a Rust PHY driver, you know that you have a valid pointer to C's device object of C's PHY device during the probe callback. The driver creates a Rust device object to wrap the C pointer to the C's device object and passes it to the firmware abstractions. The firmware abstractions gets the C's pointer from the Rust object and calls C's function to load firmware, returns the result.

You have concerns about the simple code like the following?

rust/kernel/device.rs new file +13 -0
new file mode 100644
index 000000000000..6144437984a9
@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Generic devices that are part of the kernel's driver model.
+//!
+//! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
+
+use crate::types::Opaque;
+
+#[repr(transparent)]
+pub struct Device(Opaque<bindings::device>);
+
+impl Device {
+    /// Creates a new [`Device`] instance from a raw pointer.
Quoted 8 lines

rust/kernel/device.rs line 17

Quoted 4 lines
rust/kernel/device.rs new file +4 -0
+    ///
+    /// # Safety
+    ///
+    /// For the duration of 'a, the pointer must point at a valid `device`.

If the following rust code does what this comment says, then sure, I'm ok with it for now if it helps you all out with stuff like the firmware interface for the phy rust code.

Quoted 4 lines

Great, thanks a lot!

Danilo and Wedson, are there any concerns about pushing this patch [1] for the firmware abstractions?

Well, if everyone is fine with this one I don't see why we can't we go with [1] directly? AFAICS, we'd only need the following fix:

(quoted diff) +1 -1
-//! C header: [`include/linux/device.h`](../../../../include/linux/device.h)
+//! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
Quoted 1 line

[1] https://lore.kernel.org/rust-for-linux/[email protected]/

The difference is that your patch touches the reference count of a struct device. My patch doesn't.

Quoted 5 lines

The following part in your patch allows the rust code to freely play with the reference count of a struct device. Your Rust drm driver interact with the reference count in a different way than C's drm drivers if I understand correctly. I'm not sure that Greg will be convinenced with that approach.

I don't see how this is different than what we do in C. If you (for whatever reason) want to keep a pointer to a struct device you should make sure to increase the reference count of this device, such that it can't get freed for the time being.

Quoted 6 lines
Quoted 1 line

This is a 1:1 representation of that and conceptually identical.

A drm driver does such? If a drm driver allocates two types of driver-specific data and keep a pointer to the pci device, then the driver calls get_device() twice to increase the reference count of the pci's device?

Think about it more generically. If you store a pointer to a device in some structure (driver private data, generic subsystem structure, etc.), can you guarantee that without acquiring a reference that the device' reference count doesn't drop to zero while your structure is alive?

There are cases where you can't, e.g. with Arc<device::Data>. How do you guarantee (generically for every driver) the last reference of your device data is dropped with the driver's remove callback? If we make it the driver's responsibility to care about this the whole thing is unsafe as in C.

In some cases you can, mostly the ones where you free a structure in the driver's remove callback. But again, then there is no advantage over what we do in C. What if you change the lifetime of your structure later on, then you may introduce a bug.

Quoted 3 lines

At the very least, network device drivers don't. a driver doesn't play with the reference count. The network subsystem does. And, the network

A quick 'grep' shows 23 occurrences of get_device() in network drivers.

Quoted 2 lines

subsystem doesn't care about how many pointers to a pci device a driver keeps.

If none of the drivers has structures storing a pointer to a pci device that out live the driver's remove callback that's fine.

Quoted 4 lines

With the patch [1], a driver plays with the reference count of a device and directly calls get/put_device. It's a different than C drivers for me (not sure about drm subsystem though).

It's not different. Again, when a C driver stores a device pointer in a structure whose lifetime is not bound a special boundary, like the device remove callback, it must increase the reference count.

It's just that most of the time we are moving within this boundary and in C we just rely on that. In Rust we can only get this safe by taking a reference for every pointer we store. And making it safe to use seems to be the goal.

Generally, the whole point of a reference count is that everyone who owns a pointer to this shared structure increases / decreases the reference count accordingly.

Quoted 25 lines

But I might be misunderstanding that Greg isn't convinced with this reference count thing. We need to wait for his response.

Quoted 20 lines
Quoted 13 lines
(quoted diff) +12 -0
+// SAFETY: Instances of `Device` are always ref-counted.
+unsafe impl crate::types::AlwaysRefCounted for Device {
+    fn inc_ref(&self) {
+        // SAFETY: The existence of a shared reference guarantees that the refcount is nonzero.
+        unsafe { bindings::get_device(self.as_raw()) };
+    }
+
+    unsafe fn dec_ref(obj: ptr::NonNull<Self>) {
+        // SAFETY: The safety requirements guarantee that the refcount is nonzero.
+        unsafe { bindings::put_device(obj.cast().as_ptr()) }
+    }
+}
Quoted 3 lines

The following comments give the impression that Rust abstractions wrongly interact with the reference count; callers check out the reference counter. Nobody should do that.

No, saying that the caller must ensure that the device "has a non-zero reference count" is a perfectly valid requirement.

Quoted 5 lines
Quoted 3 lines

It doensn't mean that the calling code has to peek the actual reference count, but it means that it must be ensured that while we try to increase the reference count it can't drop to zero unexpectedly.

Yeah, the same requirements but expressed differently.

Well, instead of

"ensure that ptr is valid, non-null, and has a non-zero reference count"

you propose

"the pointer must point at a valid device".

When I ask you to specify what "pointer to valid device" means, what would be the answer?

Since we're still discussing this in the thread of the firmware abstraction, if you have any further concerns, let's discuss them in the thread for the corresponding patch.

Once we get to a conclusion I can send a series with only the device and firmare abstractions such that we can get them in outside of the scope of the reset of both series to get your driver going.

- Danilo

Quoted 19 lines

But again, I might be misunderstanding. Greg might have a different reason.

Quoted 15 lines

Your patch, as a subset of this one, has the same requirements as listed below.

Quoted 11 lines
(quoted diff) +8 -0
+    /// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count.
+    pub unsafe fn from_raw(ptr: *mut bindings::device) -> ARef<Self> {
 
+    /// Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count for
+    /// the entire duration when the returned reference exists.
+    pub unsafe fn as_ref<'a>(ptr: *mut bindings::device) -> &'a Self {
+        // SAFETY: Guaranteed by the safety requirements of the function.
+        unsafe { &*ptr.cast() }
+    }
Acked-by Greg Kroah-Hartman
#39 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Hi,

Quoted 3 lines · On Fri, 31 May 2024 11:59:47 +0200 Danilo Krummrich <[email protected]> wrote:

Once we get to a conclusion I can send a series with only the device and firmare abstractions such that we can get them in outside of the scope of the reset of both series to get your driver going.

Since your discussion with Greg seems to continue for a while, let me include the following patch that Greg approved with the next version of the PHY driver patchset.

You have the new version of the firmware patch? The unused functions will not be merged so only request_firmware() and release_firmware() can be included. If not, I can include my firmware patch that I wrote before.

=
From: Danilo Krummrich <[email protected]>
Date: Fri, 7 Jun 2024 20:14:59 +0900
Subject: [PATCH] add abstraction for struct device

Add abstraction for struct device. This implements only the minimum necessary functions required for the abstractions of firmware API; that is, wrapping C's pointer to a device object with Rust struct only during a caller knows the pointer is valid (e.g., the probe callback).

---
 rust/kernel/device.rs | 31 +++++++++++++++++++++++++++++++
 rust/kernel/lib.rs    |  1 +
 2 files changed, 32 insertions(+)
 create mode 100644 rust/kernel/device.rs
rust/kernel/device.rs new file +31 -0
new file mode 100644
index 000000000000..55ec4f364628
@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Generic devices that are part of the kernel's driver model.
+//!
+//! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
+
+use crate::types::Opaque;
+
+/// Wraps the kernel's `struct task_struct`.
+#[repr(transparent)]
+pub struct Device(Opaque<bindings::device>);
+
+impl Device {
+    /// Creates a new [`Device`] instance from a raw pointer.
+    ///
+    /// # Safety
+    ///
+    /// For the duration of 'a, the pointer must point at a valid `device`.
+    pub unsafe fn from_raw<'a>(ptr: *mut bindings::device) -> &'a Self {
+        // CAST: `Self` is a `repr(transparent)` wrapper around `bindings::device`.
+        let ptr = ptr.cast::<Self>();
+        // SAFETY: by the function requirements the pointer is valid and we have unique access for
+        // the duration of `'a`.
+        unsafe { &mut *ptr }
+    }
+
+    /// Returns the raw pointer to the device.
+    pub(crate) fn as_raw(&self) -> *mut bindings::device {
+        self.0.get()
+    }
+}
rust/kernel/lib.rs +1 -0
index fbd91a48ff8b..dd1207f1a873 100644
@@ -28,6 +28,7 @@
 
 pub mod alloc;
 mod build_assert;
+pub mod device;
 pub mod error;
 pub mod init;
 pub mod ioctl;
Signature · 1 line
2.34.1
maintainer
#40 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 5 lines · FUJITA Tomonori

Hi,

On Fri, 31 May 2024 11:59:47 +0200
Danilo Krummrich <[email protected]> wrote:

Quoted 7 lines
Quoted 3 lines

Once we get to a conclusion I can send a series with only the device and firmare abstractions such that we can get them in outside of the scope of the reset of both series to get your driver going.

Since your discussion with Greg seems to continue for a while, let me include the following patch that Greg approved with the next version of the PHY driver patchset.

Yes, please take this one now. We can build on it from there.

I had a meeting yesterday with a lot of rust kernel and userspace people at Microsoft and talked a bunch about this and how to move forward. I think we need to take much smaller "steps" and even encourage most drivers to start out as a mix of c and rust as there is no real "requirement" that a driver be "pure" rust at all. This should both make the interface logic simpler to start with, AND provide a base so that people can just write the majority of their driver logic in rust, which is where the language "safety" issues are most needed, not in the lifecycle rules involving the internal driver model infrastructure.

Anyway, that's all hand-wavy right now, sorry, to get back to the point here, again, let's take this, which will allow the firmware bindings to be resubmitted and hopefully accepted, and we can move forward from there to "real" things like a USB or PCI or even platform device and driver binding stuff.

thanks,

greg k-h

#41 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 10 lines · Greg KH
Quoted 9 lines · FUJITA Tomonori

Hi,

Quoted 3 lines · On Fri, 31 May 2024 11:59:47 +0200 Danilo Krummrich <[email protected]> wrote:

Once we get to a conclusion I can send a series with only the device and firmare abstractions such that we can get them in outside of the scope of the reset of both series to get your driver going.

Quoted 5 lines
Quoted 3 lines

Since your discussion with Greg seems to continue for a while, let me include the following patch that Greg approved with the next version of the PHY driver patchset.

Yes, please take this one now. We can build on it from there.

This patch still contains the points *you* are discussing on the original one. Why do I spend my time on this discussion if those points don't seem to matter for you now?

Also, why would we want to have this patch (and the firmware one) in two separate submissions? If we urgently want to land the firmware abstractions I can send a separate series with just the device and firmware abstraction patches.

Quoted 10 lines

I had a meeting yesterday with a lot of rust kernel and userspace people at Microsoft and talked a bunch about this and how to move forward. I think we need to take much smaller "steps" and even encourage most drivers to start out as a mix of c and rust as there is no real "requirement" that a driver be "pure" rust at all. This should both make the interface logic simpler to start with, AND provide a base so that people can just write the majority of their driver logic in rust, which is where the language "safety" issues are most needed, not in the lifecycle rules involving the internal driver model infrastructure.

What do you mean by "drivers to start out as mix of C and Rust".

I don' think this is desireable. Writing abstractions for C core infrastructure already is a lot of effort and sometimes rather difficult in certain aspects, (e.g. align lifetimes).

An immediate concern I have is that this is an invitation for drivers to write their own abstractions, as in interfacing with C core infrastructure in C and and do a driver specific abstraction.

Quoted 6 lines

Anyway, that's all hand-wavy right now, sorry, to get back to the point here, again, let's take this, which will allow the firmware bindings to be resubmitted and hopefully accepted, and we can move forward from there to "real" things like a USB or PCI or even platform device and driver binding stuff.

The abstractions for that are on the list and in the sense of what you say above for "smaller steps, they are quite minimal. I don't see how we could break this down even further.

Quoted 5 lines

thanks,

greg k-h

#42 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

In reply to Greg KH
Quoted 5 lines · Greg KH

Anyway, that's all hand-wavy right now, sorry, to get back to the point here, again, let's take this, which will allow the firmware bindings to be resubmitted and hopefully accepted, and we can move forward from there to "real" things like a USB or PCI or even platform device and driver binding stuff.

In order to continue I propose to send out the following series:

1) minimal device and firmware abstractions only
2) v2 of all other device / driver, devres and PCI driver abstractions
3) v2 of basic DRM driver abstractions and Nova

The v2 series would contain static driver allocation (in case of DRM even const) and quite a few more simplifications around driver::Registration and device::Data.

Does that make sense?

- Danilo

Quoted 5 lines

thanks,

greg k-h

maintainer
#43 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 10 lines · Danilo Krummrich
Quoted 5 lines · Greg KH

Anyway, that's all hand-wavy right now, sorry, to get back to the point here, again, let's take this, which will allow the firmware bindings to be resubmitted and hopefully accepted, and we can move forward from there to "real" things like a USB or PCI or even platform device and driver binding stuff.

In order to continue I propose to send out the following series:

1) minimal device and firmware abstractions only

Sounds good.

But after this, I don't want to take ANY driver core rust code that is not able to live in the "normal" part of the Linux kernel tree. It's just unsustainable to have it all in one directory sorry. If this deadline makes that kbuild work actually happen faster, all the more reason to have it. If that kbuild work is somehow stalled due to other issues, please let me know what that is.

Quoted 1 line

2) v2 of all other device / driver, devres and PCI driver abstractions

I will be glad to review this.

Quoted 1 line

3) v2 of basic DRM driver abstractions and Nova

I love it how one of the most complex driver subsystems we have (drm) is attempting to be the "first real" driver use for the rust apis. Bold move :)

Quoted 5 lines

The v2 series would contain static driver allocation (in case of DRM even const) and quite a few more simplifications around driver::Registration and device::Data.

Does that make sense?

Yes, but note, I'm going to probably push back on the "driver::" stuff. But will do so with more constructive criticism as I want this to work very much and I agree that I think we are both talking past each other in different ways. Mostly probably due to my total lack of Rust experience, my apologies, thanks for your patience with me for this.

thanks,

greg k-h

#44 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 8 lines · Greg KH
Quoted 7 lines · Danilo Krummrich
Quoted 5 lines · Greg KH

Anyway, that's all hand-wavy right now, sorry, to get back to the point here, again, let's take this, which will allow the firmware bindings to be resubmitted and hopefully accepted, and we can move forward from there to "real" things like a USB or PCI or even platform device and driver binding stuff.

Quoted 5 lines
Quoted 3 lines

In order to continue I propose to send out the following series:

1) minimal device and firmware abstractions only

Sounds good.

Just a heads-up, I'll probably send this one quite a bit earlier than the other two to make sure to unblock Fujita on their PHY driver.

Quoted 11 lines

But after this, I don't want to take ANY driver core rust code that is not able to live in the "normal" part of the Linux kernel tree. It's just unsustainable to have it all in one directory sorry. If this deadline makes that kbuild work actually happen faster, all the more reason to have it. If that kbuild work is somehow stalled due to other issues, please let me know what that is.

Quoted 1 line

2) v2 of all other device / driver, devres and PCI driver abstractions

I will be glad to review this.

Glad to hear that!

Quoted 6 lines
Quoted 2 lines

3) v2 of basic DRM driver abstractions and Nova

I love it how one of the most complex driver subsystems we have (drm) is attempting to be the "first real" driver use for the rust apis. Bold move :)

I'd argue that as one of the most complex driver subsystems we have a lot of need for the advantages Rust provides to us. :)

Quoted 8 lines
Quoted 6 lines

The v2 series would contain static driver allocation (in case of DRM even const) and quite a few more simplifications around driver::Registration and device::Data.

Does that make sense?

Yes, but note, I'm going to probably push back on the "driver::" stuff.

That's OK, I'm happy to convince you of its usefulness. :)

Quoted 4 lines

But will do so with more constructive criticism as I want this to work very much and I agree that I think we are both talking past each other in different ways. Mostly probably due to my total lack of Rust experience, my apologies, thanks for your patience with me for this.

Very much appreciated! Please don't hesitate to ask for more explanation on certain things if they're unclear. I'm happy trying my best to provide useful answers.

- Danilo

Quoted 5 lines

thanks,

greg k-h

#45 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 9 lines · On Fri, 7 Jun 2024 19:55:49 +0200 Danilo Krummrich <[email protected]> wrote:
Quoted 8 lines · Greg KH
Quoted 7 lines · Danilo Krummrich
Quoted 5 lines · Greg KH

Anyway, that's all hand-wavy right now, sorry, to get back to the point here, again, let's take this, which will allow the firmware bindings to be resubmitted and hopefully accepted, and we can move forward from there to "real" things like a USB or PCI or even platform device and driver binding stuff.

Quoted 8 lines
Quoted 5 lines
Quoted 3 lines

In order to continue I propose to send out the following series:

1) minimal device and firmware abstractions only

Sounds good.

Just a heads-up, I'll probably send this one quite a bit earlier than the other two to make sure to unblock Fujita on their PHY driver.

Please. The sooner, the better. I need to send the PHY driver with these patchse to netdev.

I'm not sure what the above "minimal device" means. If you send the original patch again instead of the patch that Greg already approved and the discussion continues, then I proceed with the approved patch.

#46 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

Quoted 16 lines · FUJITA Tomonori
Quoted 13 lines · On Fri, 7 Jun 2024 19:55:49 +0200 Danilo Krummrich <[email protected]> wrote:
Quoted 12 lines · Greg KH
Quoted 10 lines · Danilo Krummrich
Quoted 5 lines · Greg KH

Anyway, that's all hand-wavy right now, sorry, to get back to the point here, again, let's take this, which will allow the firmware bindings to be resubmitted and hopefully accepted, and we can move forward from there to "real" things like a USB or PCI or even platform device and driver binding stuff.

In order to continue I propose to send out the following series:

1) minimal device and firmware abstractions only

Quoted 7 lines
Quoted 4 lines
Quoted 1 line

Sounds good.

Just a heads-up, I'll probably send this one quite a bit earlier than the other two to make sure to unblock Fujita on their PHY driver.

Please. The sooner, the better. I need to send the PHY driver with these patchse to netdev.

Why do you want to send those patches to netdev?

I think nothing prevents you from sending your PHY driver to netdev. Just add a note to your series that it depends on those two patches.

How and through which trees things are merged in the end can be figured out by the corresponding maintainers in the end.

Quoted 5 lines

I'm not sure what the above "minimal device" means. If you send the original patch again instead of the patch that Greg already approved and the discussion continues, then I proceed with the approved patch.

I'm honestly getting a bit tired of this...

1) I fundamentally disagree that it's a good thing to fork off patches that are actively discussed and reviewed on the mailing list with the objective to bypass the discussion and the review process. Especially without agreement of all involved parties.

2) It's at least questionable to claim that your forked-off patch can be considered to be "approved".

3) I really try to help and already confirmed to send out a separate series with only the patches you need as well to accelerate things for you.

If you really want to help with that, you are very welcome to get involved in the discussion and review process. If you don't want to, that is fine too. But please stop adding confusion to those series by forking off patches.

Besides that, I also don't appreciate your attitude, trying to put some kind of "ultimatum" on me.

- Danilo

#47 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

In reply to FUJITA Tomonori
Quoted 5 lines · FUJITA Tomonori

Hi,

On Fri, 31 May 2024 11:59:47 +0200
Danilo Krummrich <[email protected]> wrote:

Quoted 7 lines
Quoted 3 lines

Once we get to a conclusion I can send a series with only the device and firmare abstractions such that we can get them in outside of the scope of the reset of both series to get your driver going.

Since your discussion with Greg seems to continue for a while, let me include the following patch that Greg approved with the next version of the PHY driver patchset.

This all doesn't make a lot of sense. If that's the case, Greg approved something the he keeps arguing about in the discussion of the original patch. Please see the discussion about the NULL pointer check [1].

Besides that, I really don't think it's the correct approach to just (partially) pick up a patch from the mailing list that is actively discussed and submit versions that are slightly altered in the points that are actively discussed.

This really just complicates the situation and does not help getting to an agreement.

Quoted 6 lines

You have the new version of the firmware patch? The unused functions will not be merged so only request_firmware() and release_firmware() can be included. If not, I can include my firmware patch that I wrote before.

Please find the updated firmware patch in [2].

However, I propose to just send a new series with just the device abstraction and this firmware patch and proceed from there.

[1] https://lore.kernel.org/rust-for-linux/Zl8_bXqK-T24y1kp@cassiopeiae/
[2] https://gitlab.freedesktop.org/drm/nova/-/commit/0683e186929c4922d565e5315525925aa2d8d686

NAK for the patch below, for the reasons above.

Please also see comments inline.

Quoted 36 lines

=
From: Danilo Krummrich <[email protected]>
Date: Fri, 7 Jun 2024 20:14:59 +0900
Subject: [PATCH] add abstraction for struct device

Add abstraction for struct device. This implements only the minimum necessary functions required for the abstractions of firmware API; that is, wrapping C's pointer to a device object with Rust struct only during a caller knows the pointer is valid (e.g., the probe callback).

---
 rust/kernel/device.rs | 31 +++++++++++++++++++++++++++++++
 rust/kernel/lib.rs    |  1 +
 2 files changed, 32 insertions(+)
 create mode 100644 rust/kernel/device.rs
rust/kernel/device.rs new file +8 -0
new file mode 100644
index 000000000000..55ec4f364628
@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Generic devices that are part of the kernel's driver model.
+//!
+//! C header: [`include/linux/device.h`](srctree/include/linux/device.h)
+
+use crate::types::Opaque;
+

rust/kernel/device.rs line 18

Quoted 10 lines
rust/kernel/device.rs new file +10 -0
+/// Wraps the kernel's `struct task_struct`.
+#[repr(transparent)]
+pub struct Device(Opaque<bindings::device>);
+
+impl Device {
+    /// Creates a new [`Device`] instance from a raw pointer.
+    ///
+    /// # Safety
+    ///
+    /// For the duration of 'a, the pointer must point at a valid `device`.

The original patch says: "Callers must ensure that ptr is valid, non-null, and has a non-zero reference count for the entire duration when the returned reference exists."

This is way more precise than just saying "For the duration of 'a, the pointer must point at a valid device.", hence we should keep the original comment.

rust/kernel/device.rs line 24

Quoted 6 lines
rust/kernel/device.rs new file +6 -0
+    pub unsafe fn from_raw<'a>(ptr: *mut bindings::device) -> &'a Self {
+        // CAST: `Self` is a `repr(transparent)` wrapper around `bindings::device`.
+        let ptr = ptr.cast::<Self>();
+        // SAFETY: by the function requirements the pointer is valid and we have unique access for
+        // the duration of `'a`.
+        unsafe { &mut *ptr }

Why not just

+ // SAFETY: Guaranteed by the safety requirements of the function.
+ unsafe { &*ptr.cast() }

as in the original commit?

Quoted 22 lines
rust/kernel/device.rs new file +7 -0
+    }
+
+    /// Returns the raw pointer to the device.
+    pub(crate) fn as_raw(&self) -> *mut bindings::device {
+        self.0.get()
+    }
+}
rust/kernel/lib.rs +1 -0
index fbd91a48ff8b..dd1207f1a873 100644
@@ -28,6 +28,7 @@
 
 pub mod alloc;
 mod build_assert;
+pub mod device;
 pub mod error;
 pub mod init;
 pub mod ioctl;
Signature · 1 line
2.34.1
#48 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

In reply to Danilo Krummrich
Quoted 22 lines · On Tue, 28 May 2024 14:19:24 +0200 Danilo Krummrich <[email protected]> wrote:
Quoted 21 lines · FUJITA Tomonori
Quoted 18 lines · On Mon, 27 May 2024 21:22:47 +0200 Danilo Krummrich <[email protected]> wrote:
Quoted 17 lines
Quoted 4 lines
rust/kernel/firmware.rs new file +4 -0
+/// Abstraction around a C firmware struct.
+///
+/// This is a simple abstraction around the C firmware API. Just like with the C API, firmware can
+/// be requested. Once requested the abstraction provides direct access to the firmware buffer as

rust/kernel/firmware.rs line 22

Quoted 10 lines
rust/kernel/firmware.rs new file +10 -0
+/// `&[u8]`. Alternatively, the firmware can be copied to a new buffer using `Firmware::copy`. The
+/// firmware is released once [`Firmware`] is dropped.
+///
+/// # Examples
+///
+/// ```
+/// let fw = Firmware::request("path/to/firmware.bin", dev.as_ref())?;
+/// driver_load_firmware(fw.data());
+/// ```
+pub struct Firmware(Opaque<*const bindings::firmware>);

Wrapping a raw pointer is not the intended use of Qpaque type?

Quoted 6 lines
Quoted 4 lines
Quoted 2 lines

Indeed, will fix this in v2 and use NonNull instead. I'll also offload most of the boilerplate in the 'request' functions to some common 'request_internal' one.

You might need to add 'Invariants' comment on Firmware struct.

Which ones do you think should be documented?

Something like the comment for struct Page looks fine to me. But the Rust reviewers might have a different opinion.

/// The pointer is valid, and has ownership over the page.

#49 lore raw

Re: [RFC PATCH 7/8] rust: add firmware abstractions

In reply to Danilo Krummrich

Hi Luis and Russ,

I just noted I forgot to add you to this patch, sorry for that.

Please find the full series and previous discussions in [1].

- Danilo

[1] https://lore.kernel.org/rust-for-linux/[email protected]/

Quoted 122 lines · Danilo Krummrich

Add an abstraction around the kernels firmware API to request firmware images. The abstraction provides functions to access the firmware buffer and / or copy it to a new buffer allocated with a given allocator backend.

The firmware is released once the abstraction is dropped.

---
 rust/bindings/bindings_helper.h |  1 +
 rust/kernel/firmware.rs         | 74 +++++++++++++++++++++++++++++++++
 rust/kernel/lib.rs              |  1 +
 3 files changed, 76 insertions(+)
 create mode 100644 rust/kernel/firmware.rs
rust/bindings/bindings_helper.h +1 -0
index b245db8d5a87..e4ffc47da5ec 100644
@@ -14,6 +14,7 @@
 #include <kunit/test.h>
 #include <linux/errname.h>
 #include <linux/ethtool.h>
+#include <linux/firmware.h>
 #include <linux/jiffies.h>
 #include <linux/mdio.h>
 #include <linux/pci.h>
rust/kernel/firmware.rs new file +74 -0
new file mode 100644
index 000000000000..700504fb3c9c
@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Firmware abstraction
+//!
+//! C header: [`include/linux/firmware.h`](../../../../include/linux/firmware.h")
+
+use crate::{bindings, device::Device, error::Error, error::Result, str::CStr, types::Opaque};
+
+/// Abstraction around a C firmware struct.
+///
+/// This is a simple abstraction around the C firmware API. Just like with the C API, firmware can
+/// be requested. Once requested the abstraction provides direct access to the firmware buffer as
+/// `&[u8]`. Alternatively, the firmware can be copied to a new buffer using `Firmware::copy`. The
+/// firmware is released once [`Firmware`] is dropped.
+///
+/// # Examples
+///
+/// ```
+/// let fw = Firmware::request("path/to/firmware.bin", dev.as_ref())?;
+/// driver_load_firmware(fw.data());
+/// ```
+pub struct Firmware(Opaque<*const bindings::firmware>);
+
+impl Firmware {
+    /// Send a firmware request and wait for it. See also `bindings::request_firmware`.
+    pub fn request(name: &CStr, dev: &Device) -> Result<Self> {
+        let fw = Opaque::uninit();
+
+        let ret = unsafe { bindings::request_firmware(fw.get(), name.as_char_ptr(), dev.as_raw()) };
+        if ret != 0 {
+            return Err(Error::from_errno(ret));
+        }
+
+        Ok(Firmware(fw))
+    }
+
+    /// Send a request for an optional fw module. See also `bindings::request_firmware_nowarn`.
+    pub fn request_nowarn(name: &CStr, dev: &Device) -> Result<Self> {
+        let fw = Opaque::uninit();
+
+        let ret = unsafe {
+            bindings::firmware_request_nowarn(fw.get(), name.as_char_ptr(), dev.as_raw())
+        };
+        if ret != 0 {
+            return Err(Error::from_errno(ret));
+        }
+
+        Ok(Firmware(fw))
+    }
+
+    /// Returns the size of the requested firmware in bytes.
+    pub fn size(&self) -> usize {
+        unsafe { (*(*self.0.get())).size }
+    }
+
+    /// Returns the requested firmware as `&[u8]`.
+    pub fn data(&self) -> &[u8] {
+        unsafe { core::slice::from_raw_parts((*(*self.0.get())).data, self.size()) }
+    }
+}
+
+impl Drop for Firmware {
+    fn drop(&mut self) {
+        unsafe { bindings::release_firmware(*self.0.get()) };
+    }
+}
+
+// SAFETY: `Firmware` only holds a pointer to a C firmware struct, which is safe to be used from any
+// thread.
+unsafe impl Send for Firmware {}
+
+// SAFETY: `Firmware` only holds a pointer to a C firmware struct, references to which are safe to
+// be used from any thread.
+unsafe impl Sync for Firmware {}
rust/kernel/lib.rs +1 -0
index 6415968ee3b8..ed97d131661a 100644
@@ -35,6 +35,7 @@
 #[cfg(CONFIG_DRM = "y")]
 pub mod drm;
 pub mod error;
+pub mod firmware;
 pub mod init;
 pub mod ioctl;
 #[cfg(CONFIG_KUNIT)]
Signature · 1 line
2.45.1
#50 lore raw

RFC PATCH 8/8 nova: add initial driver stub

In reply to Danilo Krummrich

Add the initial driver stub of Nova, a Rust-based GSP-only driver for Nvidia GPUs. Nova, in the long term, is intended to serve as the successor of Nouveau for GSP-firmware-based GPUs. [1]

As a stub driver Nova's focus is to make use of the most basic device / driver infrastructure required to build a DRM driver on the PCI bus and serve as demonstration example and justification for this infrastructure.

In further consequence, the idea is to develop Nova continuously upstream, using those increments to lift further Rust abstractions and infrastructure upstream.

---
 MAINTAINERS                    |  10 ++
 drivers/gpu/drm/Kconfig        |   2 +
 drivers/gpu/drm/Makefile       |   1 +
 drivers/gpu/drm/nova/Kconfig   |  11 +++
 drivers/gpu/drm/nova/Makefile  |   3 +
 drivers/gpu/drm/nova/driver.rs | 110 +++++++++++++++++++++
 drivers/gpu/drm/nova/file.rs   |  71 ++++++++++++++
 drivers/gpu/drm/nova/gem.rs    |  50 ++++++++++
 drivers/gpu/drm/nova/gpu.rs    | 172 +++++++++++++++++++++++++++++++++
 drivers/gpu/drm/nova/nova.rs   |  20 ++++
 include/uapi/drm/nova_drm.h    | 101 +++++++++++++++++++
 rust/uapi/uapi_helper.h        |   1 +
 12 files changed, 552 insertions(+)
 create mode 100644 drivers/gpu/drm/nova/Kconfig
 create mode 100644 drivers/gpu/drm/nova/Makefile
 create mode 100644 drivers/gpu/drm/nova/driver.rs
 create mode 100644 drivers/gpu/drm/nova/file.rs
 create mode 100644 drivers/gpu/drm/nova/gem.rs
 create mode 100644 drivers/gpu/drm/nova/gpu.rs
 create mode 100644 drivers/gpu/drm/nova/nova.rs
 create mode 100644 include/uapi/drm/nova_drm.h
MAINTAINERS +10 -0
index aa3b947fb080..1ca0ea445e3f 100644
@@ -6863,6 +6863,16 @@ T:	git https://gitlab.freedesktop.org/drm/nouveau.git
 F:	drivers/gpu/drm/nouveau/
 F:	include/uapi/drm/nouveau_drm.h
 
+DRM DRIVER (STUB) FOR NVIDIA GSP GPUS [RUST]
+M:	Danilo Krummrich <[email protected]>
+L:	[email protected]
+L:	[email protected]
+S:	Supported
+C:	irc://irc.oftc.net/nouveau
+T:	git https://gitlab.freedesktop.org/drm/nova.git
+F:	drivers/gpu/drm/nova/
+F:	include/uapi/drm/nova_drm.h
+
 DRM DRIVER FOR OLIMEX LCD-OLINUXINO PANELS
 M:	Stefan Mavrodiev <[email protected]>
 S:	Maintained
drivers/gpu/drm/Kconfig +2 -0
index 5a0c476361c3..0bb0442a252e 100644
@@ -274,6 +274,8 @@ source "drivers/gpu/drm/amd/amdgpu/Kconfig"
 
 source "drivers/gpu/drm/nouveau/Kconfig"
 
+source "drivers/gpu/drm/nova/Kconfig"
+
 source "drivers/gpu/drm/i915/Kconfig"
 
 source "drivers/gpu/drm/xe/Kconfig"
drivers/gpu/drm/Makefile +1 -0
index 104b42df2e95..de6dc006cb7f 100644
@@ -143,6 +143,7 @@ obj-$(CONFIG_DRM_VMWGFX)+= vmwgfx/
 obj-$(CONFIG_DRM_VGEM)	+= vgem/
 obj-$(CONFIG_DRM_VKMS)	+= vkms/
 obj-$(CONFIG_DRM_NOUVEAU) +=nouveau/
+obj-$(CONFIG_DRM_NOVA_STUB) += nova/
 obj-$(CONFIG_DRM_EXYNOS) +=exynos/
 obj-$(CONFIG_DRM_ROCKCHIP) +=rockchip/
 obj-$(CONFIG_DRM_GMA500) += gma500/
drivers/gpu/drm/nova/Kconfig new file +11 -0
new file mode 100644
index 000000000000..1ae2d1322a92
@@ -0,0 +1,11 @@
+config DRM_NOVA_STUB
+	tristate "Nova GPU driver stub"
+	depends on DRM
+	depends on PCI
+	depends on RUST
+	default n
+	help
+	  Choose this if you want to build the Nova stub driver for Nvidia
+	  GSP-based GPUs.
+
+	  If M is selected, the module will be called nova.
drivers/gpu/drm/nova/Makefile new file +3 -0
new file mode 100644
index 000000000000..733ac5fb9f4f
@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: GPL-2.0
+
+obj-$(CONFIG_DRM_NOVA_STUB) += nova.o
drivers/gpu/drm/nova/driver.rs new file +110 -0

110 lines not on this page · raw message

drivers/gpu/drm/nova/file.rs new file +71 -0

71 lines not on this page · raw message

drivers/gpu/drm/nova/gem.rs new file +50 -0

50 lines not on this page · raw message

drivers/gpu/drm/nova/gpu.rs new file +172 -0

172 lines not on this page · raw message

drivers/gpu/drm/nova/nova.rs new file +20 -0
new file mode 100644
index 000000000000..48420267bcc1
@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Nova GPU Driver
+
+mod driver;
+mod file;
+mod gem;
+mod gpu;
+
+use kernel::prelude::module;
+
+use driver::NovaModule;
+
+module! {
+    type: NovaModule,
+    name: "Nova",
+    author: "Danilo Krummrich",
+    description: "Nova GPU driver",
+    license: "GPL v2",
+}
include/uapi/drm/nova_drm.h new file +101 -0

101 lines not on this page · raw message

rust/uapi/uapi_helper.h +1 -0
index ed42a456da2e..b9ab3406b2ce 100644
@@ -8,5 +8,6 @@
 
 #include <uapi/asm-generic/ioctl.h>
 #include <uapi/drm/drm.h>
+#include <uapi/drm/nova_drm.h>
 #include <uapi/linux/mii.h>
 #include <uapi/linux/ethtool.h>
Signature · 1 line
2.45.1