device: rust: change the name function
Subsystems (3)
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
@@ -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
@@ -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
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
@@ -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
@@ -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
Greg KH
maintainerQuoted 3 lines · Guilherme Giacomo Simoes
This function increment the refcount by this command "
bindings::get_device(prt)".
This can be confuse becuase, the functionArc::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
Signed-off-by Guilherme Giacomo Simoes <[email protected]>--- 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
Danilo Krummrich
maintainerQuoted 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
Signed-off-by Guilherme Giacomo Simoes <[email protected]>
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
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@@ -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
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_rawto avoid confusion with otherfrom_rawsemantics."Quoted 2 lines
Signed-off-by Guilherme Giacomo Simoes <[email protected]>Please make sure to run
./scripts/checkpatch.plbefore 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 functionArc::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@@ -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@@ -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
Danilo Krummrich
maintainerQuoted 15 lines · Guilherme Giácomo Simões
Quoted 5 lines · Danilo Krummrich
Quoted 5 lines
rust/kernel/device.rs +0
-0@@ -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 thefrom_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.
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@@ -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 thefrom_raw()from standard library.
Quoted 3 lines
I think you missed the
into()above. This will convert&'a DeviceintoARef<Device>, and also callinc_reffrom theAlwaysRefCountedtrait implemented forDevice, 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.
Danilo Krummrich
maintainerQuoted 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@@ -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 thefrom_raw()from standard library.
Quoted 7 lines
Quoted 3 lines
I think you missed the
into()above. This will convert&'a DeviceintoARef<Device>, and also callinc_reffrom theAlwaysRefCountedtrait implemented forDevice, and hence increase the reference count.Okay, I understand now that the .into() call, also call
inc_refthat I was don't have knowing. This body change of theget_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
Greg KH
maintainerQuoted 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 functionArc::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.2EThe options can be:
1) Rename the function for don't make confusing with theArc::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 maybeDevice::get_device()and I like more of the second option because, this will be equal theget_device()function that already exists in .c code.How do I test this:
I create this simple file insample/rust/device.rs""""""""
usekernel::device::Device;
use kernel::prelude::*;
usekernel::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
Kconfigsamples/rust/Kconfig +5
-0@@ -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_RUSTand in
Makefilesamples/rust/Makefile +1
-0@@ -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) += hostprogsThen 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,nowaithe 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 functionrust/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