Skip to contentSkip to conversation

device: rust: change the name function

PATCH In review Guilherme Giacomo Simoes 3 participants 9 messages Sep 30, 2024

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

v2 cover device: rust: change the name function

Why did I make this change?
This function "Device::from_raw()" increments the refcount by this command "bindings::get_device(prt)". This can be confused because the function Arc::from_raw() from the standard library, doesn't increment the refcount.

This discussion is in
https://rust-for-linux.zulipchat.com/#narrow/stream/291566-Library/topic/Inconsistency.20of.20.60from_raw.60.2E

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 I need the get pointer for the device.

Proposed solution
I like the first option. Because, how was will commented by Boqun Feng , when the people write 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.

How do I test this:
I create this simple file in sample/rust/device.rs """"""""
use kernel::device::Device;
use kernel::prelude::*;
use kernel::types::ARef;

module! {
type: DeviceTest,
name: "device_test",
author: "Test device",
description: "A simple module for test device",
license: "GPL",
}

struct DeviceTest;

impl kernel::Module for DeviceTest {
    fn init(_module: &'static ThisModule) -> Result<Self> {
        pr_info!("initial device test");
        let device = create_and_get_device();
        pr_info!("device created");

        Ok(DeviceTest)
    }
}
impl Drop for DeviceTest {
    fn drop(&mut self) {
        pr_info!("bye bye driver test");
    }
}
fn create_and_get_device() -> ARef<Device> {
    let device = unsafe { Device::get_device(core::ptr::null_mut()) };
    device
}

""""""""

I set this in Kconfig

samples/rust/Kconfig +5 -0
index b0f74a81c8f9..7779969e7dd6 100644
@@ -37,4 +37,9 @@ config SAMPLE_RUST_HOSTPROGS
 
          If unsure, say N.
 
+config SAMPLE_DEVICE_TEST
+       tristate "Device test"
+       help
+               This option is for device test
+
 endif # SAMPLES_RUST

and in Makefile

samples/rust/Makefile +1 -0
index 03086dabbea4..85a8b30100e7 100644
@@ -2,5 +2,6 @@
 
 obj-$(CONFIG_SAMPLE_RUST_MINIMAL)              += rust_minimal.o
 obj-$(CONFIG_SAMPLE_RUST_PRINT)                        += rust_print.o
+obj-$(CONFIG_SAMPLE_DEVICE_TEST)                       += device.o
 
 subdir-$(CONFIG_SAMPLE_RUST_HOSTPROGS)         += hostprogs

Then I enable this in menu config... compile the kernel e run this in a qemu:
qemu-system-x86_64 -kernel bzImage -initrd initramfs.img -m 2G -machine q35 -device ich9-ahci,id=sata -drive id=disk,file=rootfs.img,if=none,format=raw -device ide-hd,drive=disk,bus=sata.0 -append "root=/dev/sda console=ttyS0" -nographic -monitor telnet:127.0.0.1:5555,server,nowai

the expected print is showing

[    2.786174] device_test: initial device test
[    2.786541] device_test: device created

Guilherme Giacomo Simoes (1):
device: rust: change the name function

 rust/kernel/device.rs   | 2 +-
 rust/kernel/firmware.rs | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)
Signature · 1 line
2.46.2
#1 lore raw

PATCH v2 1/1 device: rust: change the name function

This function increment the refcount by this command "bindings::get_device(prt)".
This can be confuse becuase, the function Arc::from_raw() from standard library, don't increment the refcount. Then, this function "Device::from_raw()" will be renamed for don't make confusing in the future.

---
 rust/kernel/device.rs   | 2 +-
 rust/kernel/firmware.rs | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)
rust/kernel/device.rs +1 -1
index 851018eef885..ecffaff041e0 100644
@@ -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.
rust/kernel/firmware.rs +1 -1
index dee5b4b18aec..13a374a5cdb7 100644
@@ -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();
Signature · 1 line
2.46.2
maintainer
#2 lore raw
Quoted 3 lines · Guilherme Giacomo Simoes

This function increment the refcount by this command "bindings::get_device(prt)".
This can be confuse becuase, the function Arc::from_raw() from standard library, don't increment the refcount. Then, this function "Device::from_raw()" will be renamed for don't make confusing in the future.

Your editor should have asked you to wrap these at 72 columns, can you please do that?

Quoted 6 lines
---
 rust/kernel/device.rs   | 2 +-
 rust/kernel/firmware.rs | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

What changed from v1? That should go under the --- line.

thanks,

greg k-h

maintainer
#3 lore raw
In reply to Guilherme Giacomo Simoes
Quoted 1 line · Guilherme Giacomo Simoes

This function increment the refcount by this command "bindings::get_device(prt)".

'increments', 'bindings::get_device(ptr)'

I'd also say 'by a call to' instead of 'by this command'.

Quoted 1 line

This can be confuse becuase, the function Arc::from_raw() from standard library, don't increment the refcount.

Neither the stdlib one, nor the kernel one.

Quoted 1 line

Then, this function "Device::from_raw()" will be renamed for don't make confusing in the future.

Prefer the imperative, e.g. "Hence, rename Device::from_raw to avoid confusion with other from_raw semantics."

Quoted 2 lines

Please make sure to run ./scripts/checkpatch.pl before submitting patches.

I see the following two warnings:

WARNING: Prefer a maximum 75 chars per line (possible unwrapped commit description?) #6:
This function increment the refcount by this command "bindings::get_device(prt)".

WARNING: 'becuase' may be misspelled - perhaps 'because'?
#7:
This can be confuse becuase, the function Arc::from_raw() from standard library, don't increment the refcount.

Please also use a more descriptive commit summary, e.g. "rust: device: rename Device::from_raw".

Quoted 10 lines
---
 rust/kernel/device.rs   | 2 +-
 rust/kernel/firmware.rs | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)
rust/kernel/device.rs +0 -0
index 851018eef885..ecffaff041e0 100644

rust/kernel/device.rs impl Device { · line 54

Quoted 5 lines
rust/kernel/device.rs +1 -1
@@ -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> {

As a follow-up, it probably makes sense to also change the function body to
just: unsafe { Self::as_ref(ptr) }.into().

Quoted 19 lines
rust/kernel/device.rs +0 -0
         // 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.
rust/kernel/firmware.rs +1 -1
index dee5b4b18aec..13a374a5cdb7 100644
@@ -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();
Signature · 1 line
2.46.2
#4 lore raw
Quoted 28 lines · Danilo Krummrich
Quoted 1 line · Guilherme Giacomo Simoes

This function increment the refcount by this command "bindings::get_device(prt)".

'increments', 'bindings::get_device(ptr)'

I'd also say 'by a call to' instead of 'by this command'.

Quoted 1 line

This can be confuse becuase, the function Arc::from_raw() from standard library, don't increment the refcount.

Neither the stdlib one, nor the kernel one.

Quoted 1 line

Then, this function "Device::from_raw()" will be renamed for don't make confusing in the future.

Prefer the imperative, e.g. "Hence, rename Device::from_raw to avoid confusion with other from_raw semantics."

Quoted 2 lines

Please make sure to run ./scripts/checkpatch.pl before submitting patches.

I see the following two warnings:

WARNING: Prefer a maximum 75 chars per line (possible unwrapped commit description?) #6:
This function increment the refcount by this command "bindings::get_device(prt)".

Quoted 7 lines

WARNING: 'becuase' may be misspelled - perhaps 'because'?
#7:
This can be confuse becuase, the function Arc::from_raw() from standard library, don't increment the refcount.

Please also use a more descriptive commit summary, e.g. "rust: device: rename Device::from_raw".

Thanks for your suggestions... I will make this changes.

Quoted 5 lines
Quoted 5 lines
---
 rust/kernel/device.rs   | 2 +-
 rust/kernel/firmware.rs | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)
Quoted 13 lines

rust/kernel/device.rs impl Device { · line 54

Quoted 10 lines
rust/kernel/device.rs +1 -1
index 851018eef885..ecffaff041e0 100644
@@ -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> {

As a follow-up, it probably makes sense to also change the function body to
just: unsafe { Self::as_ref(ptr) }.into().

But if we change the function body that is suggested for you, the function will not have your own refcount. If I don't wrong, the Device::as_ref() expects the caller to have its own reference counter. And if we change the behavior of function, your name don't need to be changed, because your behavior will be equal the from_raw() from standard library.

Quoted 20 lines
Quoted 20 lines
rust/kernel/device.rs +0 -0
         // 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.
rust/kernel/firmware.rs +1 -2
index dee5b4b18aec..13a374a5cdb7 100644
@@ -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();
--

2.46.2

maintainer
#5 lore raw
Quoted 15 lines · Guilherme Giácomo Simões
Quoted 5 lines · Danilo Krummrich
Quoted 5 lines
rust/kernel/device.rs +0 -0
index 851018eef885..ecffaff041e0 100644
@@ -51,7 +51,7 @@ impl Device {
Quoted 8 lines

rust/kernel/device.rs impl Device { · line 54

Quoted 5 lines
rust/kernel/device.rs +1 -1
     ///
     /// 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> {

As a follow-up, it probably makes sense to also change the function body to
just: unsafe { Self::as_ref(ptr) }.into().

Quoted 6 lines

But if we change the function body that is suggested for you, the function will not have your own refcount. If I don't wrong, the Device::as_ref() expects the caller to have its own reference counter. And if we change the behavior of function, your name don't need to be changed, because your behavior will be equal the from_raw() from standard library.

I think you missed the into() above. This will convert &'a Device into ARef<Device>, and also call inc_ref from the AlwaysRefCounted trait implemented for Device, and hence increase the reference count.

#6 lore raw
Quoted 24 lines · Danilo Krummrich
Quoted 15 lines · Guilherme Giácomo Simões
Quoted 5 lines · Danilo Krummrich
Quoted 5 lines
rust/kernel/device.rs +0 -0
index 851018eef885..ecffaff041e0 100644
@@ -51,7 +51,7 @@ impl Device {
Quoted 8 lines

rust/kernel/device.rs impl Device { · line 54

Quoted 5 lines
rust/kernel/device.rs +1 -1
     ///
     /// 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> {

As a follow-up, it probably makes sense to also change the function body to
just: unsafe { Self::as_ref(ptr) }.into().

Quoted 6 lines

But if we change the function body that is suggested for you, the function will not have your own refcount. If I don't wrong, the Device::as_ref() expects the caller to have its own reference counter. And if we change the behavior of function, your name don't need to be changed, because your behavior will be equal the from_raw() from standard library.

Quoted 3 lines

I think you missed the into() above. This will convert &'a Device into ARef<Device>, and also call inc_ref from the AlwaysRefCounted trait implemented for Device, and hence increase the reference count.

Okay, I understand now that the .into() call, also call inc_ref that I was don't have knowing. This body change of the get_device() really make sense, and I will send a v4 patch.

Thanks for this Mr. Krummrich.

maintainer
#7 lore raw
Quoted 25 lines · Guilherme Giácomo Simões
Quoted 24 lines · Danilo Krummrich
Quoted 21 lines · Guilherme Giácomo Simões
Quoted 5 lines · Danilo Krummrich
Quoted 5 lines
rust/kernel/device.rs +0 -0
index 851018eef885..ecffaff041e0 100644
@@ -51,7 +51,7 @@ impl Device {
Quoted 8 lines

rust/kernel/device.rs impl Device { · line 54

Quoted 5 lines
rust/kernel/device.rs +1 -1
     ///
     /// 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> {

As a follow-up, it probably makes sense to also change the function body to
just: unsafe { Self::as_ref(ptr) }.into().

But if we change the function body that is suggested for you, the function will not have your own refcount. If I don't wrong, the Device::as_ref() expects the caller to have its own reference counter. And if we change the behavior of function, your name don't need to be changed, because your behavior will be equal the from_raw() from standard library.

Quoted 7 lines
Quoted 3 lines

I think you missed the into() above. This will convert &'a Device into ARef<Device>, and also call inc_ref from the AlwaysRefCounted trait implemented for Device, and hence increase the reference count.

Okay, I understand now that the .into() call, also call inc_ref that I was don't have knowing. This body change of the get_device() really make sense, and I will send a v4 patch.

No need to send a v4, please just send a separate patch for this.

Quoted 2 lines

Thanks for this Mr. Krummrich.

Danilo is just fine, we call people by their first name.

Quoted 1 line
maintainer
#8 lore raw
In reply to Guilherme Giacomo Simoes
Quoted 94 lines · Guilherme Giacomo Simoes

Why did I make this change?
This function "Device::from_raw()" increments the refcount by this command "bindings::get_device(prt)". This can be confused because the function Arc::from_raw() from the standard library, doesn't increment the refcount.

This discussion is in
https://rust-for-linux.zulipchat.com/#narrow/stream/291566-Library/topic/Inconsistency.20of.20.60from_raw.60.2E

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 I need the get pointer for the device.

Proposed solution
I like the first option. Because, how was will commented by Boqun Feng , when the people write 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.

How do I test this:
I create this simple file in sample/rust/device.rs """"""""
use kernel::device::Device;
use kernel::prelude::*;
use kernel::types::ARef;

module! {
type: DeviceTest,
name: "device_test",
author: "Test device",
description: "A simple module for test device",
license: "GPL",
}

struct DeviceTest;

impl kernel::Module for DeviceTest {
    fn init(_module: &'static ThisModule) -> Result<Self> {
        pr_info!("initial device test");
        let device = create_and_get_device();
        pr_info!("device created");

        Ok(DeviceTest)
    }
}
impl Drop for DeviceTest {
    fn drop(&mut self) {
        pr_info!("bye bye driver test");
    }
}
fn create_and_get_device() -> ARef<Device> {
    let device = unsafe { Device::get_device(core::ptr::null_mut()) };
    device
}

""""""""

I set this in Kconfig

samples/rust/Kconfig +5 -0
index b0f74a81c8f9..7779969e7dd6 100644
@@ -37,4 +37,9 @@ config SAMPLE_RUST_HOSTPROGS
 
          If unsure, say N.
 
+config SAMPLE_DEVICE_TEST
+       tristate "Device test"
+       help
+               This option is for device test
+
 endif # SAMPLES_RUST

and in Makefile

samples/rust/Makefile +1 -0
index 03086dabbea4..85a8b30100e7 100644
@@ -2,5 +2,6 @@
 
 obj-$(CONFIG_SAMPLE_RUST_MINIMAL)              += rust_minimal.o
 obj-$(CONFIG_SAMPLE_RUST_PRINT)                        += rust_print.o
+obj-$(CONFIG_SAMPLE_DEVICE_TEST)                       += device.o
 
 subdir-$(CONFIG_SAMPLE_RUST_HOSTPROGS)         += hostprogs

Then I enable this in menu config... compile the kernel e run this in a qemu:
qemu-system-x86_64 -kernel bzImage -initrd initramfs.img -m 2G -machine q35 -device ich9-ahci,id=sata -drive id=disk,file=rootfs.img,if=none,format=raw -device ide-hd,drive=disk,bus=sata.0 -append "root=/dev/sda console=ttyS0" -nographic -monitor telnet:127.0.0.1:5555,server,nowai

the expected print is showing

[    2.786174] device_test: initial device test
[    2.786541] device_test: device created
Quoted 10 lines

Guilherme Giacomo Simoes (1):
device: rust: change the name function

 rust/kernel/device.rs   | 2 +-
 rust/kernel/firmware.rs | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)
Signature · 1 line
2.46.2

Hi,

This is the friendly patch-bot of Greg Kroah-Hartman. You have sent him a patch that has triggered this response. He used to manually respond to these common problems, but in order to save his sanity (he kept writing the same thing over and over, yet to different people), I was created. Hopefully you will not take offence and will fix the problem in your patch and resubmit it so that it can be accepted into the Linux kernel tree.

You are receiving this message because of the following common error(s) as indicated below:

- This looks like a new version of a previously submitted patch, but you did not list below the --- line any changes from the previous version. Please read the section entitled "The canonical patch format" in the kernel file, Documentation/process/submitting-patches.rst for what needs to be done here to properly describe this.

If you wish to discuss this problem further, or you have questions about how to resolve this issue, please feel free to respond to this email and Greg will reply once he has dug out from the pending patches received from other developers.

thanks,

greg k-h's patch email bot