rust abstractions for interacting with sysfs
cover rust abstractions for interacting with sysfs
Hello,
For now, there are no facilities for the Rust side to tune modules written in Rust in runtime or for just simple debug output/statistics from the module. For exactly this purpose, the C has the sysfs. In this patch series, I implemented a minimal sysfs wrapper utilizing kobject API.
I would like to collect your thoughts on whether:
- Do we want something like this in the rust part of the kernel?
- Do we want to support all sysfs capabilities?
I implemented a sample to present the API I have chosen for the Rust part. It is a straightforward example that does not represent all capabilities of the sysfs. The documentation will be potentially improved, but I would like to first settle the abstractions.
Thank you
Daniel
Daniel Sedlak (3):
rust: kernel: types: add mode wrapper
rust: kernel: kobject: basic sysfs implementation
samples: rust: add kobject sample
rust/kernel/kobject.rs | 271 ++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + rust/kernel/types.rs | 17 ++ samples/rust/Kconfig | 8 + samples/rust/Makefile | 1 + samples/rust/kobject_example.rs | 66 ++++++++ 6 files changed, 365 insertions(+) create mode 100644 rust/kernel/kobject.rs create mode 100644 samples/rust/kobject_example.rs
base-commit: 40384c840ea1944d7c5a392e8975ed088ecf0b37
Signature · 1 line
2.47.1
RFC PATCH 1/3 rust: kernel: types: add mode wrapper
Add rust variant for representing file mode. This is needed in order to set file permissions.
--- rust/kernel/types.rs | 17 +++++++++++++++++ 1 file changed, 17 insertions(+)
rust/kernel/types.rs +17 -0
@@ -517,3 +517,20 @@ pub enum Either<L, R> {/// [`NotThreadSafe`]: type@NotThreadSafe #[allow(non_upper_case_globals)] pub const NotThreadSafe :NotThreadSafe =PhantomData ; + +/// Mode represents file permissions. +/// +/// TODO: add link to header files. +pub struct Mode (bindings::umode_t ); + +impl Mode { +/// Creates [`Mode`] from the number. +pub const fn from_u16 (num:u16 ) ->Self { +Self (num) + } + +/// Returns [`Mode`] as an number. +pub const fn as_u16 (&self) ->u16 { + self.0 + } +}
Signature · 1 line
2.47.1
Alice Ryhl
reviewerRe: [RFC PATCH 1/3] rust: kernel: types: add mode wrapper
rust/kernel/types.rs
Quoted 13 lines · Daniel Sedlak
Add rust variant for representing file mode. This is needed in order to set file permissions.
Signed-off-by Daniel Sedlak <[email protected]>--- rust/kernel/types.rs | 17 +++++++++++++++++ 1 file changed, 17 insertions(+)rust/kernel/types.rs +0
-0
Perhaps this should be defined in rust/kernel/fs.rs?
Alice
Re: [RFC PATCH 1/3] rust: kernel: types: add mode wrapper
Quoted 10 lines · Alice Ryhl
Quoted 9 lines · Daniel Sedlak
Add rust variant for representing file mode. This is needed in order to set file permissions.
Signed-off-by Daniel Sedlak <[email protected]>--- rust/kernel/types.rs | 17 +++++++++++++++++ 1 file changed, 17 insertions(+)
Quoted 6 lines
rust/kernel/types.rs
Quoted 4 lines
rust/kernel/types.rs +0
-0Perhaps this should be defined in
rust/kernel/fs.rs?
Yes, likely it is a better place. I was somewhat surprised, that we have dedicated kernel/fs.rs file with all that flags, but none of them regarding the permissions, so I thought that it was on purpose missing.
Daniel
RFC PATCH 2/3 rust: kernel: kobject: basic sysfs implementation
In reply to Daniel SedlakImplement initial support for interacting with sysfs via kobject API from the Rust world. Rust for now does not expose any debug interface or interface for tuning knobs of the kernel module. Sysfs is used for exporting relevant debugging metrics or it can be used for tuning module configuration in the runtime (apart from module parameters).
This patch builds on a prior work [1] by Martin RR, which is listed in the old patch registry [2]. However the [1] seems to be only focused on exposing devices to the sysfs, where this patch tries to be more broad, not only specific to the devices.
--- rust/kernel/kobject.rs | 271 +++++++++++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + 2 files changed, 273 insertions(+) create mode 100644 rust/kernel/kobject.rs
rust/kernel/kobject.rs new file +271 -0
@@ -0,0 +1,271 @@ +// SPDX-License-Identifier: GPL-2.0 +// TODO: Add unsafe doc documentation. +#![allow(clippy::undocumented_unsafe_blocks, clippy::missing_safety_doc)] + +//! KObject wrappers. +//! +//! TODO: Write more + +use bindings::PAGE_SIZE ; +use core::marker::PhantomData ; +use core::marker::PhantomPinned ; +use core::mem; +use core::ptr; +use kernel::c_str; +use kernel::container_of; +use kernel::error::code::*; +use kernel::prelude::*; +use kernel::str::{CStr ,CString }; +use kernel::types::Mode ; +use kernel::types::Opaque ; + +/// Reference to the subsystems from the non Rust world. +pub mod subsystems { +use super ::DynamicKObject ; + +macro_rules! declare_kobject { + ($name:tt, $subsystem_ptr:expr, $($doc:expr),+) => { + $( +#[doc = $doc] + )* +pub static $name:DynamicKObject =DynamicKObject { + pointer: kernel::types::Opaque ::new ( + core::ptr::addr_of!($subsystem_ptr).cast_mut (), + ), + }; + }; + } + +declare_kobject! ( +FIRMWARE_KOBJECT , + bindings::firmware_kobj, +"Firmware subsystem dynamic KObject." + ); +declare_kobject! ( +KERNEL_KOBJECT , + bindings::kernel_kobj, +"Kernel subsystem dynamic KObject." + ); +declare_kobject! ( +MM_KOBJECT , + bindings::mm_kobj, +"Memory management subsystem dynamic KObject." + ); +declare_kobject! ( +POWER_KOBJECT , + bindings::power_kobj, +"Power subsystem dynamic KObject." + ); + +// TODO: Add rests of the exported Kobjects. +} + +/// DynamicKObject is same as [`KObject`], however it does not have any state. +pub struct DynamicKObject { +// The bindings export `extern static *mut bindings::kobejct`, however +// we need to have double pointer because rustc complains with +// `could not evaluate static initializer`. + pointer:Opaque <*mut *mut bindings::kobject >, +} + +unsafe impl Send for DynamicKObject {} +unsafe impl Sync for DynamicKObject {} + +/// KObject represent wrapper structure enables interaction with +/// the sysfs, where the KObject represents directory. +/// +/// TODO: Add examples? +pub struct KObject <K > { + data:K , + pointer:Opaque <bindings::kobject >, + +// Struct must be `!Unpin`, because kobject pointer is self referential. + _m:PhantomPinned , +} + +impl <K >Drop for KObject <K > { +fn drop (&mut self) { +// SAFETY: This KObject holds a valid reference, because it was allocated +// through kobject API. +unsafe { bindings::kobject_put (self.pointer.get ()) } + } +} + +#[doc(hidden)] +struct KObjTypeVTable ; +#[doc(hidden)] +impl KObjTypeVTable { +unsafe extern "C" fn release_callback (kobj: *mut bindings::kobject ) { +unsafe { bindings::kfree (kobj.cast ()) } + } + +pub (crate )const KOBJ_TYPE : bindings::kobj_type = bindings::kobj_type { + release:Some (Self ::release_callback), + sysfs_ops: ptr::addr_of!(bindings::kobj_sysfs_ops), + ..unsafe { mem::zeroed () } + }; + +pub (crate )fn kobj_type (&self) -> &'static bindings::kobj_type { + &Self ::KOBJ_TYPE + } +} + +unsafe impl <K >Send for KObject <K >where K :Send {} +unsafe impl <K >Sync for KObject <K >where K :Sync {} + +impl <K >KObject <K > { +/// Attaches KObject to the sysfs root. +pub fn new_in_root (name:CString , data:K ) ->Result <Pin <KBox <Self >>> { +Self ::new (name, ptr::null_mut (), data) + } + +/// Attaches new KObject to the sysfs with specified KObject parent. +pub fn new_with_kobject_parent <L >( + name:CString , + parent: &KObject <L >, + data:K , + ) ->Result <Pin <KBox <Self >>> { +Self ::new (name, parent.pointer.get (), data) + } + +/// Attaches new KObject to the sysfs with specified **dynamic** KObject parent. +pub fn new_with_dynamic_kobject_parent ( + name:CString , + parent: &DynamicKObject , + data:K , + ) ->Result <Pin <KBox <Self >>> { +Self ::new (name,unsafe { **parent.pointer.get () }, data) + } + +fn new (name:CString , parent: *mut bindings::kobject , data:K ) ->Result <Pin <KBox <Self >>> { +let this =KBox ::pin ( +Self { + pointer:Opaque ::new (unsafe { mem::zeroed () }), + data, + _m:PhantomPinned , + }, +GFP_KERNEL , + )?; + +let code =unsafe { + bindings::kobject_init_and_add ( + this.pointer.get (), +KObjTypeVTable .kobj_type (), + parent, +c_str! ("%s" ).as_char_ptr (), + name.as_char_ptr (), + ) + }; +if code <0 { +return Err (Error ::from_errno (code)); + } + +// TODO: Not sure whether we must check for return code of `kobject_uevent`. +unsafe { +// We are responsible for sending uevent that kobject was added to the system. + bindings::kobject_uevent (this.pointer.get (), bindings::kobject_action_KOBJ_ADD) + }; + +Ok (this) + } + +/// Creates a file for a given KObject. +pub fn add_attribute <A :KObjectTextAttribute <K >>( + self: &mut Pin <KBox <KObject <K >>>, + attribute:A , + ) ->Result <()> { +let vtable =TextAttributeVTable ::<K ,A >::new (); +// TODO: Can we use it later? +let _ = attribute; + +let code =unsafe { + bindings::sysfs_create_file_ns ( + self.pointer.get (), + ptr::addr_of!(*vtable.attr ())as *const bindings::attribute , + ptr::null (), + ) + }; + +if code ==0 { +Ok (()) + }else { +Err (kernel::error::Error ::from_errno (code)) + } + } +} + +/// Attribute represents a file in a directory. +#[macros::vtable] +pub trait KObjectTextAttribute <K > +where +Self :Sized , +{ +/// File permissions. +const MODE :Mode =Mode ::from_u16 (0o777 ); + +/// Name of the file in the sysfs. +const NAME : &'staticCStr ; + +/// Gets called when the read is called on the file. +fn show (this: &mut K ) ->Result <CString > { +let _ = this; +Err (EIO ) + } + +/// Gets called when the write is called on the file. +fn store (this: &mut K , input: &CStr ) ->Result { +let _ = this; +let _ = input; +Err (EIO ) + } +} + +#[doc(hidden)] +struct TextAttributeVTable <K ,A :KObjectTextAttribute <K >>(PhantomData <(A ,K )>); +#[doc(hidden)] +impl <K ,A :KObjectTextAttribute <K >>TextAttributeVTable <K ,A > { +#[doc(hidden)] +const fn new () ->Self { +Self (PhantomData ) + } +unsafe extern "C" fn show_callback ( + kobj: *mut bindings::kobject , + _attr: *mut bindings::kobj_attribute , + buf: *mut core::ffi::c_char , + ) ->isize { +match A ::show ( + &mut unsafe { &mut *container_of! (kobj,KObject <K >, pointer).cast_mut () }.data, + ) { +Ok (cstring) =>unsafe { + bindings::sized_strscpy (buf.cast (), cstring.as_char_ptr (),PAGE_SIZE ) + }, +Err (error) => error.to_errno ()as isize , + } + } +unsafe extern "C" fn store_callback ( + kobj: *mut bindings::kobject , + _attr: *mut bindings::kobj_attribute , + buf: *const core::ffi::c_char , + count:usize , + ) ->isize { +match A ::store ( + &mut unsafe { &mut *container_of! (kobj,KObject <K >, pointer).cast_mut () }.data, +unsafe { kernel::str::CStr ::from_char_ptr (buf) }, + ) { +Ok (()) => countas isize , +Err (error) => error.to_errno ()as isize , + } + } +pub (crate )const ATTR : bindings::kobj_attribute = bindings::kobj_attribute { + attr: bindings::attribute { + name:A ::NAME .as_char_ptr (), + mode:A ::MODE .as_u16 (), + }, + show:Some (Self ::show_callback), + store:Some (Self ::store_callback), + }; + +const fn attr (&self) -> &'static bindings::kobj_attribute { + &TextAttributeVTable ::<K ,A >::ATTR + } +}
rust/kernel/lib.rs +2 -0
@@ -42,6 +42,8 @@pub mod init;pub mod ioctl;pub mod jump_label; +#[cfg( CONFIG_SYSFS )] +pub mod kobject;#[cfg( CONFIG_KUNIT )] pub mod kunit;pub mod list;
Signature · 1 line
2.47.1
Re: [RFC PATCH 2/3] rust: kernel: kobject: basic sysfs implementation
Quoted 7 lines · Daniel Sedlak
Implement initial support for interacting with sysfs via kobject API from the Rust world. Rust for now does not expose any debug interface or interface for tuning knobs of the kernel module. Sysfs is used for exporting relevant debugging metrics or it can be used for tuning module configuration in the runtime (apart from module parameters).
sysfs is NOT for debugging, it's for system parameters of devices or other things.
debugfs is for debugging, if you want debugging interfaces, use that please!
Quoted 69 lines
This patch builds on a prior work [1] by Martin RR, which is listed in the old patch registry [2]. However the [1] seems to be only focused on exposing devices to the sysfs, where this patch tries to be more broad, not only specific to the devices.
Signed-off-by Daniel Sedlak <[email protected]>--- rust/kernel/kobject.rs | 271 +++++++++++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + 2 files changed, 273 insertions(+) create mode 100644 rust/kernel/kobject.rsrust/kernel/kobject.rs new file +48
-0@@ -0,0 +1,271 @@ +// SPDX-License-Identifier: GPL-2.0 +// TODO: Add unsafe doc documentation. +#![allow(clippy::undocumented_unsafe_blocks, clippy::missing_safety_doc)] + +//! KObject wrappers. +//! +//! TODO: Write more + +use bindings::PAGE_SIZE ; +use core::marker::PhantomData ; +use core::marker::PhantomPinned ; +use core::mem; +use core::ptr; +use kernel::c_str; +use kernel::container_of; +use kernel::error::code::*; +use kernel::prelude::*; +use kernel::str::{CStr ,CString }; +use kernel::types::Mode ; +use kernel::types::Opaque ; + +/// Reference to the subsystems from the non Rust world. +pub mod subsystems { +use super ::DynamicKObject ; + +macro_rules! declare_kobject { + ($name:tt, $subsystem_ptr:expr, $($doc:expr),+) => { + $( +#[doc = $doc] + )* +pub static $name:DynamicKObject =DynamicKObject { + pointer: kernel::types::Opaque ::new ( + core::ptr::addr_of!($subsystem_ptr).cast_mut (), + ), + }; + }; + } + +declare_kobject! ( +FIRMWARE_KOBJECT , + bindings::firmware_kobj, +"Firmware subsystem dynamic KObject." + ); +declare_kobject! ( +KERNEL_KOBJECT , + bindings::kernel_kobj, +"Kernel subsystem dynamic KObject." + );
rust/kernel/kobject.rs line 58
Quoted 10 lines
rust/kernel/kobject.rs new file +10
-0+declare_kobject! ( +MM_KOBJECT , + bindings::mm_kobj, +"Memory management subsystem dynamic KObject." + ); +declare_kobject! ( +POWER_KOBJECT , + bindings::power_kobj, +"Power subsystem dynamic KObject." + );
Please don't export these unless you have a real user. I doubt rust code will be placing stuff in the power of mm kobjects (and if so, the maintainers of those subsystems MUST review that.) Same for the other kobjects as well.
rust/kernel/kobject.rs line 64
Quoted 6 lines
rust/kernel/kobject.rs new file +6
-0+ +// TODO: Add rests of the exported Kobjects. +} + +/// DynamicKObject is same as [`KObject`], however it does not have any state. +pub struct DynamicKObject {
Why the funny name, why not just Kobject?
rust/kernel/kobject.rs line 72
Quoted 8 lines
rust/kernel/kobject.rs new file +8
-0+// The bindings export `extern static *mut bindings::kobejct`, however +// we need to have double pointer because rustc complains with +// `could not evaluate static initializer`. + pointer: Opaque<*mut *mut bindings::kobject>, +} + +unsafe impl Send for DynamicKObject {} +unsafe impl Sync for DynamicKObject {}
All kobjects should be dynamic, so why is this needed?
Yes, a few are not, but I really really really do not want any rust code to follow the mistakes of C code where that happens if at all possible. Let's take the chance to fix the mistakes of our youth when we can.
rust/kernel/kobject.rs line 78
Quoted 5 lines
rust/kernel/kobject.rs new file +5
-0+/// KObject represent wrapper structure enables interaction with +/// the sysfs, where the KObject represents directory. +/// +/// TODO: Add examples? +pub struct KObject <K > {
Why the "O"?
rust/kernel/kobject.rs line 84
Quoted 6 lines
rust/kernel/kobject.rs new file +6
-0+ data: K, + pointer: Opaque<bindings::kobject>, + +// Struct must be `!Unpin`, because kobject pointer is self referential. + _m: PhantomPinned, +}
So that's all? Where is the kobject_get() call?
Quoted 8 lines
rust/kernel/kobject.rs new file +8
-0+impl <K >Drop for KObject <K > { +fn drop (&mut self) { +// SAFETY: This KObject holds a valid reference, because it was allocated +// through kobject API. +unsafe { bindings::kobject_put (self.pointer.get ()) } + } +} +
rust/kernel/kobject.rs line 103
Quoted 10 lines
rust/kernel/kobject.rs new file +10
-0+#[doc(hidden)] +struct KObjTypeVTable ; +#[doc(hidden)] +impl KObjTypeVTable { +unsafe extern "C" fn release_callback (kobj: *mut bindings::kobject ) { +unsafe { bindings::kfree (kobj.cast ()) } + } + +pub (crate )const KOBJ_TYPE : bindings::kobj_type = bindings::kobj_type { + release:Some (Self ::release_callback),
Note, release callbacks are REQUIRED for a kobject, can we enforce that here somehow?
rust/kernel/kobject.rs line 104
Quoted 1 line
rust/kernel/kobject.rs new file +1
-0+ sysfs_ops: ptr::addr_of!(bindings::kobj_sysfs_ops),
Why would you allow access to a kobject's sysfs_ops? What needs that?
rust/kernel/kobject.rs line 105
Quoted 1 line
rust/kernel/kobject.rs new file +1
-0+ ..unsafe { mem::zeroed () }
What does this do?
Quoted 5 lines
rust/kernel/kobject.rs new file +5
-0+ }; + +pub (crate )fn kobj_type (&self) -> &'static bindings::kobj_type { + &Self ::KOBJ_TYPE + }
rust/kernel/kobject.rs line 120
Quoted 10 lines
rust/kernel/kobject.rs new file +10
-0+} + +unsafe impl <K >Send for KObject <K >where K :Send {} +unsafe impl <K >Sync for KObject <K >where K :Sync {} + +impl <K >KObject <K > { +/// Attaches KObject to the sysfs root. +pub fn new_in_root (name:CString , data:K ) ->Result <Pin <KBox <Self >>> { +Self ::new (name, ptr::null_mut (), data) + }
Please never create a kobject in sysfs's root. Let's let C code only do that for now. If this does come up in the future, talk to me and we can reconsider it.
rust/kernel/kobject.rs line 129
Quoted 8 lines
rust/kernel/kobject.rs new file +8
-0+/// Attaches new KObject to the sysfs with specified KObject parent. +pub fn new_with_kobject_parent <L >( + name:CString , + parent: &KObject <L >, + data:K , + ) ->Result <Pin <KBox <Self >>> { +Self ::new (name, parent.pointer.get (), data) + }
Where is the parent dropped? And these function names are not matching up with the C api, why not?
rust/kernel/kobject.rs line 128
Quoted 2 lines
rust/kernel/kobject.rs new file +2
-0+ +/// Attaches new KObject to the sysfs with specified **dynamic** KObject parent.
All kobjects are dynamic. If not, please point them out to me (hint, I know a few but we really should fix them.)
rust/kernel/kobject.rs line 132
Quoted 1 line
rust/kernel/kobject.rs new file +1
-0+ pub fn new_with_dynamic_kobject_parent(
You should never know, or care, about the lifetyle/cycle of your parent kobject, so why need two different functions?
I'm going to stop here, let's see a real example please. Wrapping a kobject is only a last-resort for me, I really want to see proper users of the in-kernel apis we have already before resorting to "raw" kobjects.
Note, the one big offender right now is filesystems, and I will push to finally get a "real" filesystem kobject api created so that filesystems in rust do NOT have to deal with raw kobjects, but can instead use a correct api instead, which will prevent all of the current problems that filesystems have when dealing with raw kobjects (see the mailing list archives for loads of examples of this.)
Also, a final nit, why didn't you cc: the kobject maintainer on all of this? You're lucky I'm on the rust mailing list and happened to noice this series to hopefully save you some time :)
thanks,
greg k-h
Re: [RFC PATCH 2/3] rust: kernel: kobject: basic sysfs implementation
Quoted 9 lines · Greg KH
Quoted 7 lines · Daniel Sedlak
Implement initial support for interacting with sysfs via kobject API from the Rust world. Rust for now does not expose any debug interface or interface for tuning knobs of the kernel module. Sysfs is used for exporting relevant debugging metrics or it can be used for tuning module configuration in the runtime (apart from module parameters).
Quoted 5 lines
sysfs is NOT for debugging, it's for system parameters of devices or other things.
debugfs is for debugging, if you want debugging interfaces, use that please!
Your are right, I used wrong wording. What I meant, is statistics (for example: /sys/class/net/*/statistics).
Quoted 35 lines
Quoted 35 lines
rust/kernel/kobject.rs new file +35
-0+ +/// Reference to the subsystems from the non Rust world. +pub mod subsystems { +use super ::DynamicKObject ; + +macro_rules! declare_kobject { + ($name:tt, $subsystem_ptr:expr, $($doc:expr),+) => { + $( +#[doc = $doc] + )* +pub static $name:DynamicKObject =DynamicKObject { + pointer: kernel::types::Opaque ::new ( + core::ptr::addr_of!($subsystem_ptr).cast_mut (), + ), + }; + }; + } + +declare_kobject! ( +FIRMWARE_KOBJECT , + bindings::firmware_kobj, +"Firmware subsystem dynamic KObject." + ); +declare_kobject! ( +KERNEL_KOBJECT , + bindings::kernel_kobj, +"Kernel subsystem dynamic KObject." + ); +declare_kobject! ( +MM_KOBJECT , + bindings::mm_kobj, +"Memory management subsystem dynamic KObject." + ); +declare_kobject! ( +POWER_KOBJECT ,
Quoted 8 lines
rust/kernel/kobject.rs line 58
Quoted 3 lines
rust/kernel/kobject.rs new file +3
-0+ bindings::power_kobj, +"Power subsystem dynamic KObject." + );Please don't export these unless you have a real user. I doubt rust code will be placing stuff in the power of mm kobjects (and if so, the maintainers of those subsystems MUST review that.) Same for the other kobjects as well.
Noted.
Quoted 21 lines
rust/kernel/kobject.rs line 64
Quoted 7 lines
rust/kernel/kobject.rs new file +6
-0+ +// TODO: Add rests of the exported Kobjects. +} + +/// DynamicKObject is same as [`KObject`], however it does not have any state. +pub struct DynamicKObject {Why the funny name, why not just Kobject?
rust/kernel/kobject.rs line 72
Quoted 8 lines
rust/kernel/kobject.rs new file +8
-0+// The bindings export `extern static *mut bindings::kobejct`, however +// we need to have double pointer because rustc complains with +// `could not evaluate static initializer`. + pointer: Opaque<*mut *mut bindings::kobject>, +} + +unsafe impl Send for DynamicKObject {} +unsafe impl Sync for DynamicKObject {}All kobjects should be dynamic, so why is this needed?
Quoted 3 lines
Yes, a few are not, but I really really really do not want any rust code to follow the mistakes of C code where that happens if at all possible. Let's take the chance to fix the mistakes of our youth when we can.
I wanted to distinguish between kobjects that have a "local" state and those that have "global" state. What I mean by that is that for example samples/kobject/kobject-example.c is setting only a global variable to some "global" state, that is why it is called a dynamic kobject without generic parameter. On the other hand, samples/kobject/kset-example.c defines custom structure which represent "local" state, and that is why I called it just kobject with generic parameter representing type of that "local" state.
Quoted 8 lines
rust/kernel/kobject.rs line 78
Quoted 6 lines
rust/kernel/kobject.rs new file +5
-0+/// KObject represent wrapper structure enables interaction with +/// the sysfs, where the KObject represents directory. +/// +/// TODO: Add examples? +pub struct KObject <K > {Why the "O"?
I was reading The sysfs Filesystem [1], and there it is called Kernel Object, so I though that K(ernel)Object looks better, but I am really open to anything.
Quoted 9 lines
rust/kernel/kobject.rs line 84
Quoted 7 lines
rust/kernel/kobject.rs new file +6
-0+ data: K, + pointer: Opaque<bindings::kobject>, + +// Struct must be `!Unpin`, because kobject pointer is self referential. + _m: PhantomPinned, +}So that's all? Where is the
kobject_get()call?
For now, I did not implement cloning for the KObject. I do have only single owned "copy" for which the counter should be incremented in kobject_init_and_add so I should not need it. Or Am I overlooking something?
Quoted 14 lines
Quoted 14 lines
rust/kernel/kobject.rs new file +13
-0+impl <K >Drop for KObject <K > { +fn drop (&mut self) { +// SAFETY: This KObject holds a valid reference, because it was allocated +// through kobject API. +unsafe { bindings::kobject_put (self.pointer.get ()) } + } +} + +#[doc(hidden)] +struct KObjTypeVTable ; +#[doc(hidden)] +impl KObjTypeVTable { +unsafe extern "C" fn release_callback (kobj: *mut bindings::kobject ) {
Quoted 8 lines
rust/kernel/kobject.rs line 103
Quoted 5 lines
rust/kernel/kobject.rs new file +5
-0+unsafe { bindings::kfree (kobj.cast ()) } + } + +pub (crate )const KOBJ_TYPE : bindings::kobj_type = bindings::kobj_type { + release:Some (Self ::release_callback),Note, release callbacks are REQUIRED for a kobject, can we enforce that here somehow?
Yes, it is enforced by the trait KObjectTextAttribute, where is default implementation for show() and store(), if user does not provide them. If user does not implement the callback then the default implementation just return EIO for that callback.
Quoted 4 lines
Quoted 2 lines
+
sysfs_ops: ptr::addr_of!(bindings::kobj_sysfs_ops),Why would you allow access to a kobject's
sysfs_ops? What needs that?
I wanted to reuse already existing facilities and I did not find the need of re implementing that and duplicate that code in Rust.
Quoted 5 lines
Quoted 2 lines
+ ..unsafe {
mem::zeroed()}What does this do?
This could be implemented more gently, possibly without the unsafe, however the outcome would be the same. I am initializing the structure release and sysfs_ops pointers and initializing the rest to 0 effectively setting that to NULL pointers.
Quoted 11 lines
rust/kernel/kobject.rs line 120
Quoted 6 lines
rust/kernel/kobject.rs new file +6
-0+ +impl <K >KObject <K > { +/// Attaches KObject to the sysfs root. +pub fn new_in_root (name:CString , data:K ) ->Result <Pin <KBox <Self >>> { +Self ::new (name, ptr::null_mut (), data) + }Please never create a kobject in sysfs's root. Let's let C code only do that for now. If this does come up in the future, talk to me and we can reconsider it.
Noted.
Quoted 9 lines
rust/kernel/kobject.rs line 129
Quoted 8 lines
rust/kernel/kobject.rs new file +8
-0+/// Attaches new KObject to the sysfs with specified KObject parent. +pub fn new_with_kobject_parent <L >( + name:CString , + parent: &KObject <L >, + data:K , + ) ->Result <Pin <KBox <Self >>> { +Self ::new (name, parent.pointer.get (), data) + }
Quoted 3 lines
Where is the parent dropped? And these function names are not matching up with the C api, why not?
A module using this API has an ownership of KObject (possibly the parent as well as the returned, newly created, KObject), when the KObject is dropped by the module, then the destructor is called for that KObject releasing resources.
As for the naming. I am not sure whether we are able (or event want) to support all capabilities of the sysfs in Rust and I am unsure whether we are able to model the API capabilities **with safety guarantees**, so I am more in favor of giving it more Rust idiomatic names.
Quoted 16 lines
Review
Quoted 2 lines
(quoted diff) +2
-0+ + /// Attaches new KObject to the sysfs with specified **dynamic** KObject parent.All kobjects are dynamic. If not, please point them out to me (hint, I know a few but we really should fix them.)
Quoted 1 line
+ pub fn new_with_dynamic_kobject_parent(
You should never know, or care, about the lifetyle/cycle of your parent kobject, so why need two different functions?
I'm going to stop here, let's see a real example please. Wrapping a kobject is only a last-resort for me, I really want to see proper users of the in-kernel apis we have already before resorting to "raw" kobjects.
Quoted 6 lines
Note, the one big offender right now is filesystems, and I will push to finally get a "real" filesystem kobject api created so that filesystems in rust do NOT have to deal with raw kobjects, but can instead use a correct api instead, which will prevent all of the current problems that filesystems have when dealing with raw kobjects (see the mailing list archives for loads of examples of this.)
Thank you, for highlighting that, I will check that out.
Quoted 4 lines
Also, a final nit, why didn't you cc: the kobject maintainer on all of this? You're lucky I'm on the rust mailing list and happened to noice this series to hopefully save you some time :)
I am sorry, still getting familiar with the mailing list process, and I just forgot.
Thank you for your valuable feedback
Daniel
Re: [RFC PATCH 2/3] rust: kernel: kobject: basic sysfs implementation
In reply to Daniel SedlakSome more review after I saw your examples:
Quoted 1 line · Daniel Sedlak
+/// Attribute represents a file in a directory.
Not always, but sometimes, be careful here :)
rust/kernel/kobject.rs line 207
Quoted 10 lines
rust/kernel/kobject.rs new file +10
-0+#[macros::vtable] +pub trait KObjectTextAttribute <K > +where +Self :Sized , +{ +/// File permissions. +const MODE :Mode =Mode ::from_u16 (0o777 ); + +/// Name of the file in the sysfs. +const NAME : &'staticCStr ;
No. Well yes. Kind of. Why aren't you wrapping "struct attribute"
here instead?
rust/kernel/kobject.rs line 220
Quoted 13 lines
rust/kernel/kobject.rs new file +13
-0+ +/// Gets called when the read is called on the file. +fn show (this: &mut K ) ->Result <CString > { +let _ = this; +Err (EIO ) + } + +/// Gets called when the write is called on the file. +fn store (this: &mut K , input: &CStr ) ->Result { +let _ = this; +let _ = input; +Err (EIO ) + }
I see you called this "Text" attribute, but yet that's not what the kernel calls them in the C side. Again, let's not create multiple names for the same thing as that's going to cause nothing but headaches for decades as most of us flit from both C and Rust constantly.
Naming matters, be consistent.
Also, attributes in the kernel do NOT have show/store functions by default. The "wrapper" attribute type has them. So again, be very careful here.
sysfs/kobjects are tricky and slippery and take advantage of some crazy things in C (i.e. object structure layouts and looney casts "just because we know what we are doing".) Representing this in rust is also going to have those same types of issues, so watch out. You simplified it all here, but note that the C side is complex for real reasons (i.e. we started out simple, and then got complex to solve real problems.) Be aware of our history here first please and don't make the same mistakes we did in our youth, you have the benifit of learning from how foolish we were back then :)
Quoted 14 lines
rust/kernel/kobject.rs new file +14
-0+} + +#[doc(hidden)] +struct TextAttributeVTable <K ,A :KObjectTextAttribute <K >>(PhantomData <(A ,K )>); +#[doc(hidden)] +impl <K ,A :KObjectTextAttribute <K >>TextAttributeVTable <K ,A > { +#[doc(hidden)] +const fn new () ->Self { +Self (PhantomData ) + } +unsafe extern "C" fn show_callback ( + kobj: *mut bindings::kobject , + _attr: *mut bindings::kobj_attribute , + buf: *mut core::ffi::c_char,
rust/kernel/kobject.rs line 244
Quoted 10 lines
rust/kernel/kobject.rs new file +10
-0+ ) -> isize { +match A ::show ( + &mut unsafe { &mut *container_of! (kobj,KObject <K >, pointer).cast_mut () }.data, + ) { +Ok (cstring) =>unsafe { + bindings::sized_strscpy (buf.cast (), cstring.as_char_ptr (),PAGE_SIZE ) + }, +Err (error) => error.to_errno ()as isize , + } + }
You should ALWAYS call sysfs_emit() when printing out data (for a variety of reasons). Here you are hard-coding the PAGE_SIZE reference of the buffer that the kobject core gave you, are you SURE that is always going to work? Please just use the apis the C code gives you and don't attempt to re-write them (again, learn from our mistakes of the past...
thanks,
greg k-h
RFC PATCH 3/3 samples: rust: add kobject sample
In reply to Daniel SedlakAdd basic example using the kobject API using Rust. The example is similar to the already existing examples samples/kobject/{kobject-example.c,kset-example.c}.
--- samples/rust/Kconfig | 8 ++++ samples/rust/Makefile | 1 + samples/rust/kobject_example.rs | 66 +++++++++++++++++++++++++++++++++ 3 files changed, 75 insertions(+) create mode 100644 samples/rust/kobject_example.rs
samples/rust/Kconfig +8 -0
@@ -37,4 +37,12 @@ config SAMPLE_RUST_HOSTPROGS If unsure, say N. +config SAMPLE_RUST_KOBJECT + bool "Build kobject example in Rust" + help + This config option allows to build kobject + exampel written in Rust. + + If unsure, say N. + endif # SAMPLES_RUST
samples/rust/Makefile +1 -0
@@ -3,6 +3,7 @@ ccflags-y += -I$(src) # needed for trace events obj-$(CONFIG_SAMPLE_RUST_MINIMAL) += rust_minimal.o obj-$(CONFIG_SAMPLE_RUST_PRINT) += rust_print.o +obj-$(CONFIG_SAMPLE_RUST_KOBJECT) += kobject_example.o rust_print-y := rust_print_main.o rust_print_events.o
samples/rust/kobject_example.rs new file +66 -0
66 lines not on this page · raw message
Signature · 1 line
2.47.1
Re: [RFC PATCH 3/3] samples: rust: add kobject sample
Quoted 3 lines · Daniel Sedlak
Add basic example using the kobject API using Rust. The example is similar to the already existing examples
samples/kobject/{kobject-example.c,kset-example.c}.
No, please no. let's not have "raw kobjects in rust" even be an example of something that is a good idea to use...
samples/rust/Kconfig config SAMPLE_RUST_HOSTPROGS · line 44
Quoted 5 lines · That being
samples/rust/Kconfig +5
-0+config SAMPLE_RUST_KOBJECT + bool "Build kobject example in Rust" + help + This config option allows to build kobject + exampel written in Rust.
spelling check :)
And wrap your lines at a longer length please.
samples/rust/kobject_example.rs line 3
Quoted 7 lines
index 000000000000..90db937dea5a
samples/rust/kobject_example.rs new file +3
-0@@ -0,0 +1,66 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Rust example using kobjects.
No copyright? No authorship?
samples/rust/kobject_example.rs line 15
Quoted 11 lines
samples/rust/kobject_example.rs new file +11
-0+use kernel::{ + c_str, + kobject::{subsystems,KObject ,KObjectTextAttribute }, + prelude::*, + str::CString , +}; + +module! { +type :RustKObject , + name:"rust_kobject" , + author:"Rust for Linux Contributors" ,
No taking ownership of this? I REALLY want someone to own this if it ever happens, so that they can handle all of the fallout over time with it :)
Quoted 19 lines
samples/rust/kobject_example.rs new file +19
-0+ license: "GPL", +} + +struct RustKObject { +// This kobject may be referenced later by other parts of code to update +// the values stored within [`MyKObject`]. + _kobject:Pin <KBox <KObject <MyKObject >>>, +} + +/// Sample KObject state which creates directory in the `/sys/kernel/my_kobject`. +#[derive( Default )] +pub struct MyKObject { + text:Option <CString >, +} + +/// Attribute of the [`MyKObject`], creates file in the `/sys/kernel/my_kobject/my-text`. +/// Where `show()` is triggered when read is called and `store()` is called +/// when new data are written. +pub struct MyKObjectAttribute ;
samples/rust/kobject_example.rs line 44
Quoted 10 lines
samples/rust/kobject_example.rs new file +10
-0+#[vtable] +impl KObjectTextAttribute <MyKObject >for MyKObjectAttribute { +const NAME : &'staticCStr =c_str! ("my-text" ); + +/// Called for example by `cat /sys/kernel/my_kobject/my-text`. +fn show (this: &mut MyKObject ) ->Result <CString > { +if let Some (text) = &this.text { +CString ::try_from_fmt (fmt! ("Text that was stored: '{text:?}'\n" )) + }else { +CString ::try_from_fmt (fmt! ("No one stored anything yet, value {}.\n" , this.value))
Wouldn't this also happen if the text was ""? If not, why isn't an empty string the default to start with?
thanks,
greg k-h
Re: [RFC PATCH 3/3] samples: rust: add kobject sample
Quoted 7 lines · Greg KH
Quoted 3 lines · Daniel Sedlak
Add basic example using the kobject API using Rust. The example is similar to the already existing examples
samples/kobject/{kobject-example.c,kset-example.c}.No, please no. let's not have "raw kobjects in rust" even be an example of something that is a good idea to use...
Noted.
Quoted 13 lines
samples/rust/Kconfig config SAMPLE_RUST_HOSTPROGS · line 44
Quoted 5 lines · That being
samples/rust/Kconfig +5
-0+config SAMPLE_RUST_KOBJECT + bool "Build kobject example in Rust" + help + This config option allows to build kobject + exampel written in Rust.spelling check :)
And wrap your lines at a longer length please.
Quoted 9 lines
samples/rust/kobject_example.rs line 3
Quoted 7 lines
index 000000000000..90db937dea5a
samples/rust/kobject_example.rs new file +3
-0@@ -0,0 +1,66 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Rust example using kobjects. No copyright? No authorship?
I copied it from other rust samples, looks like collective "issue".
Quoted 10 lines
samples/rust/kobject_example.rs line 15
Quoted 5 lines
samples/rust/kobject_example.rs new file +5
-0+ +module! { +type :RustKObject , + name:"rust_kobject" , + author:"Rust for Linux Contributors" ,No taking ownership of this? I REALLY want someone to own this if it ever happens, so that they can handle all of the fallout over time with it :)
Also copied from other rust samples, it looks like even some C samples have not author specified, but that not justify not specifying one. Will remember that in the future.
Quoted 4 lines
samples/rust/kobject_example.rs line 44
Quoted 1 line
samples/rust/kobject_example.rs new file +1
-0+CString ::try_from_fmt (fmt! ("No one stored anything yet, value {}.\n" , this.value))Wouldn't this also happen if the text was ""? If not, why isn't an empty string the default to start with?
This line in the sample is result of invalid fixup and should be:
CString::try_from_fmt(fmt!("No one stored anything yet.\n"))
Thank you for your feedback
Daniel
Quoted 8 lines · Daniel Sedlak
Hello,
For now, there are no facilities for the Rust side to tune modules written in Rust in runtime or for just simple debug output/statistics from the module. For exactly this purpose, the C has the sysfs. In this patch series, I implemented a minimal sysfs wrapper utilizing kobject API.I would like to collect your thoughts on whether:
- Do we want something like this in the rust part of the kernel?
No. Module parameters are from the 1990's, please let's not perpetuate that madness into the next century if possible.
Quoted 1 line
- Do we want to support all sysfs capabilities?
For many things, yes. But let's add that when needed. I'd like to see a real user before accepting these types of things, don't just add bindings when you don't have them as it's impossible to determine if they are correct or not (see the recent miscdev sample driver for proof of that, turns out that the bindings we took weren't really right, which is fine, but it's sometimes easier to figure that out when you have a user.)
Quoted 4 lines
I implemented a sample to present the API I have chosen for the Rust part. It is a straightforward example that does not represent all capabilities of the sysfs. The documentation will be potentially improved, but I would like to first settle the abstractions.
What exactly do you want to represent in sysfs here? Start with that and we can work backwards to say what types of bindings are needed.
Almost NO kernel code should ever call "raw" kobject or sysfs calls, with some exceptions. Is your use case one of those exceptions?
thanks,
greg k-h
Quoted 7 lines · Greg KH
Quoted 4 lines
I implemented a sample to present the API I have chosen for the Rust part. It is a straightforward example that does not represent all capabilities of the sysfs. The documentation will be potentially improved, but I would like to first settle the abstractions.
What exactly do you want to represent in sysfs here? Start with that and we can work backwards to say what types of bindings are needed.
Great question, I should have started with that earlier. Lets say I wrote a module that attaches some hooks to kernel function calls and the module does some accounting on that. What is the correct way to expose the statistics from that module? From my point of view this module does not fit into any subsystem already defined in /sys/, and procfs should be abandoned. Should I use debugfs for that?
Thank you for your feedback
Daniel
Quoted 8 lines · Daniel Sedlak
Quoted 5 lines · Greg KH
Quoted 4 lines
I implemented a sample to present the API I have chosen for the Rust part. It is a straightforward example that does not represent all capabilities of the sysfs. The documentation will be potentially improved, but I would like to first settle the abstractions.
Quoted 6 lines
Quoted 2 lines
What exactly do you want to represent in sysfs here? Start with that and we can work backwards to say what types of bindings are needed.
Great question, I should have started with that earlier. Lets say I wrote a module that attaches some hooks to kernel function calls and the module does some accounting on that.
Modules do not add hooks to function calls :)
Quoted 2 lines
What is the correct way to expose the statistics
from that module?
debugfs.
Quoted 3 lines
From my point of view this module does not fit into any subsystem already defined in
/sys/, and procfs should be abandoned. Should I use debugfs for that?
As it sounds like you are attempting to be a "security module", just use securityfs instead.
And really, don't hook function calls, or if you must, just use ebpf and the functionality it provides (all the stats you could ask for!) No need to write a kernel module at all.
sysfs is for drivers and the devices they bind to (and devices that do not have drivers) and sometimes filesystems and occasionally memory stuff as well (mm is really just a driver for memory). Don't use it for things it is not designed for (i.e. module-wide things.)
thanks,
greg k-h