[PATCH v2 0/1] device: rust: change the name function

[PATCH v2 0/1] device: rust: change the name function

[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
diff --git a/samples/rust/Kconfig b/samples/rust/Kconfig
index b0f74a81c8f9..7779969e7dd6 100644
--- a/samples/rust/Kconfig
+++ b/samples/rust/Kconfig
@@ -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
diff --git a/samples/rust/Makefile b/samples/rust/Makefile
index 03086dabbea4..85a8b30100e7 100644
--- a/samples/rust/Makefile
+++ b/samples/rust/Makefile
@@ -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(-)

-- 
2.46.2

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

[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.

Signed-off-by: Guilherme Giacomo Simoes <trintaeoitogc@gmail.com>
---
 rust/kernel/device.rs   | 2 +-
 rust/kernel/firmware.rs | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/rust/kernel/device.rs b/rust/kernel/device.rs
index 851018eef885..ecffaff041e0 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..13a374a5cdb7 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();
-- 
2.46.2

Re: [PATCH v2 1/1] device: rust: change the name function

[Greg KH]

On Mon, Sep 30, 2024 at 09:39:56AM -0300, Guilherme Giacomo Simoes wrote:
> 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?

> 
> Signed-off-by: Guilherme Giacomo Simoes <trintaeoitogc@gmail.com>
> ---
>  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

Re: [PATCH v2 1/1] device: rust: change the name function

[Danilo Krummrich]

On Mon, Sep 30, 2024 at 09:39:56AM -0300, Guilherme Giacomo Simoes wrote:
> 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'.

> 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.

> 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."

> 
> Signed-off-by: Guilherme Giacomo Simoes <trintaeoitogc@gmail.com>

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`".

> ---
>  rust/kernel/device.rs   | 2 +-
>  rust/kernel/firmware.rs | 2 +-
>  2 files changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/rust/kernel/device.rs b/rust/kernel/device.rs
> index 851018eef885..ecffaff041e0 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> {

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

>          // 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..13a374a5cdb7 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();
> -- 
> 2.46.2
> 

Re: [PATCH v2 1/1] device: rust: change the name function

[Guilherme Giácomo Simões]

Danilo Krummrich <dakr@kernel.org> writes:
>
> On Mon, Sep 30, 2024 at 09:39:56AM -0300, Guilherme Giacomo Simoes wrote:
> > 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'.
>
> > 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.
>
> > 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."
>
> >
> > Signed-off-by: Guilherme Giacomo Simoes <trintaeoitogc@gmail.com>
>
> 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`".
>

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

> > ---
> >  rust/kernel/device.rs   | 2 +-
> >  rust/kernel/firmware.rs | 2 +-
> >  2 files changed, 2 insertions(+), 2 deletions(-)
> >
> > diff --git a/rust/kernel/device.rs b/rust/kernel/device.rs
> > index 851018eef885..ecffaff041e0 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> {
>
> 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.

>
> >          // 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..13a374a5cdb7 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();
> > --
> > 2.46.2
> >

Re: [PATCH v2 1/1] device: rust: change the name function

[Danilo Krummrich]

On Mon, Sep 30, 2024 at 10:52:27AM -0300, Guilherme Giácomo Simões wrote:
> Danilo Krummrich <dakr@kernel.org> writes:
> > > diff --git a/rust/kernel/device.rs b/rust/kernel/device.rs
> > > index 851018eef885..ecffaff041e0 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> {
> >
> > 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.

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.

Re: [PATCH v2 1/1] device: rust: change the name function

[Guilherme Giácomo Simões]

Danilo Krummrich <dakr@kernel.org> wrote:
>
> On Mon, Sep 30, 2024 at 10:52:27AM -0300, Guilherme Giácomo Simões wrote:
> > Danilo Krummrich <dakr@kernel.org> writes:
> > > > diff --git a/rust/kernel/device.rs b/rust/kernel/device.rs
> > > > index 851018eef885..ecffaff041e0 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> {
> > >
> > > 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.
>
> 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.

Re: [PATCH v2 1/1] device: rust: change the name function

[Danilo Krummrich]

On Mon, Sep 30, 2024 at 01:53:20PM -0300, Guilherme Giácomo Simões wrote:
> Danilo Krummrich <dakr@kernel.org> wrote:
> >
> > On Mon, Sep 30, 2024 at 10:52:27AM -0300, Guilherme Giácomo Simões wrote:
> > > Danilo Krummrich <dakr@kernel.org> writes:
> > > > > diff --git a/rust/kernel/device.rs b/rust/kernel/device.rs
> > > > > index 851018eef885..ecffaff041e0 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> {
> > > >
> > > > 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.
> >
> > 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.

> 
> Thanks for this Mr. Krummrich.

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

> 

Re: [PATCH v2 0/1] device: rust: change the name function

[Greg KH]

On Mon, Sep 30, 2024 at 09:39:55AM -0300, Guilherme Giacomo Simoes wrote:
> 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
> diff --git a/samples/rust/Kconfig b/samples/rust/Kconfig
> index b0f74a81c8f9..7779969e7dd6 100644
> --- a/samples/rust/Kconfig
> +++ b/samples/rust/Kconfig
> @@ -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
> diff --git a/samples/rust/Makefile b/samples/rust/Makefile
> index 03086dabbea4..85a8b30100e7 100644
> --- a/samples/rust/Makefile
> +++ b/samples/rust/Makefile
> @@ -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(-)
> 
> -- 
> 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