Remove Device::from_raw() in favor of using Device::as_ref() + into().

[fbq]

First, there is an inconsistency between Device::from_raw() and ARef::from_raw() on whether the refcount gets increased or not. That means Device::from_raw() should be renamed. Moreover, as suggested here, Device::from_raw() can be avoid by using unsafe { Device::as_ref(ptr) }.into(). Things need to be done:

• Remove Device::from_raw().
• Add example usage in the documentation of Device::as_ref() and probably ARef as well

---

This requires submitting a proper patch to the LKML and the Rust for Linux mailing list. Please recall to test your changes, to use a proper title for the commit, to sign your commit under the Developer's Certificate of Origin and so on. Please see https://docs.kernel.org/process/submitting-patches.html and https://rust-for-linux.com/contributing for details.

Please take this issue only if you are new to the kernel development process and you would like to use it as a test to submit your first patch to the kernel. Please do not take it if you do not plan to make other contributions to the kernel.

[charmitro]

Perhaps @panosfol would like to take on this introductory patch for the kernel.

[panosfol]

Perhaps @panosfol would like to take on this introductory patch for the kernel.

Yes sounds good!

[GuilhermeGiacomoSimoes]

I understand this "problmen" ... The Arc::from_raw() function from standart library don't increment the refcount. But the Device::from_raw() increement your own refcount byt the line bindings::get_device(prt).

The options can be:

1. Rename the function for don't make confusing with the Arc::from_raw().
2. Remove this function and use the unsafe { Device::as_ref(ptr) }.into() when need the get pointer for device.

I like more of the first option. Because, how was will commented by @fbq , when the people wrtite the unsafe { Device::as_ref(ptr) }.into() again, again and again... inevitably anybody will create a help function for this.

Then I think that we should rename this function for Device::get_from_raw() or maybe Device::get_device() and I like more of the second option because, this will be equal the get_device() function that already exists in .c code.

Then my patch will be anything like this:

diff --git a/rust/kernel/device.rs b/rust/kernel/device.rs
index 851018eef885..5dfbe7c0824c 100644
--- a/rust/kernel/device.rs
+++ b/rust/kernel/device.rs
@@ -51,7 +51,7 @@ impl Device {
     ///
     /// It must also be ensured that `bindings::device::release` can be called from any thread.
     /// While not officially documented, this should be the case for any `struct device`.
-    pub unsafe fn from_raw(ptr: *mut bindings::device) -> ARef<Self> {
+    pub unsafe fn get_device(ptr: *mut bindings::device) -> ARef<Self> {
         // SAFETY: By the safety requirements, ptr is valid.
         // Initially increase the reference count by one to compensate for the final decrement once
         // this newly created `ARef<Device>` instance is dropped.
diff --git a/rust/kernel/firmware.rs b/rust/kernel/firmware.rs
index dee5b4b18aec..23a0a758fc72 100644
--- a/rust/kernel/firmware.rs
+++ b/rust/kernel/firmware.rs
@@ -44,7 +44,7 @@ fn request_nowarn() -> Self {
 ///
 /// # fn no_run() -> Result<(), Error> {
 /// # // SAFETY: *NOT* safe, just for the example to get an `ARef<Device>` instance
-/// # let dev = unsafe { Device::from_raw(core::ptr::null_mut()) };
+/// # let dev = unsafe { Device::get_device(core::ptr::null_mut()) };
 ///
 /// let fw = Firmware::request(c_str!("path/to/firmware.bin"), &dev)?;
 /// let blob = fw.data();

What do you think ??