Additional miscdevice fops parameters
Subsystems (3)
Alice Ryhl
reviewerv3 cover Additional miscdevice fops parameters
This could not land with the base miscdevice abstractions due to the dependency on File.
The last two patches enable you to use the dev_* macros to print messages in miscdevice drivers.
---
Changes in v3:
- Fix build error in fops->open() patch.
- Improve wording of some comments in fops->open() patch.
- Update commit message with more info on why struct miscdevice is
only made available in fops->open() and not other hooks.
- Include Lee's device accessor patch, since it's a needed component to
use the dev_* printing macros with miscdevice.
- Link to v2: https://lore.kernel.org/r/[email protected]
Changes in v2:
- Access the struct miscdevice from fops->open().
- Link to v1: https://lore.kernel.org/r/[email protected]
---
Alice Ryhl (2):
rust: miscdevice: access file in fops
rust: miscdevice: access the struct miscdevice from fops->open()
Lee Jones (1):
rust: miscdevice: Provide accessor to pull out miscdevice::this_device
rust/kernel/miscdevice.rs | 66 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 55 insertions(+), 11 deletions(-)
---
base-commit: fac04efc5c793dccbd07e2d59af9f90b7fc0dca4
change-id: 20241203-miscdevice-file-param-5df7f75861da
Best regards,
Signature · 1 line
Alice Ryhl <[email protected]>
Alice Ryhl
reviewerPATCH v3 1/3 rust: miscdevice: access file in fops
This allows fops to access information about the underlying struct file for the miscdevice. For example, the Binder driver needs to inspect the O_NONBLOCK flag inside the fops->ioctl() hook.
--- rust/kernel/miscdevice.rs | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-)
rust/kernel/miscdevice.rs +25 -6
@@ -11,6 +11,7 @@use crate ::{ bindings, error::{to_result,Error ,Result ,VTABLE_DEFAULT_ERROR }, + fs::File , prelude::*, str::CStr , types::{ForeignOwnable ,Opaque },
@@ -103,10 +104,10 @@ pub trait MiscDevice {/// Called when the misc device is opened. /// /// The returned pointer will be stored as the private data for the file. -fn open () ->Result <Self ::Ptr >; +fn open (_file: &File ) ->Result <Self ::Ptr >;/// Called when the misc device is released. -fn release (device:Self ::Ptr ) { +fn release (device:Self ::Ptr , _file: &File ) {drop (device); }
@@ -117,6 +118,7 @@ fn release(device: Self::Ptr) {/// [`kernel::ioctl`]: mod@crate::ioctl fn ioctl ( _device: <Self ::Ptr as ForeignOwnable >::Borrowed <'_>, + _file: &File , _cmd:u32 , _arg:usize , ) ->Result <isize > {
@@ -133,6 +135,7 @@ fn ioctl(#[cfg( CONFIG_COMPAT )] fn compat_ioctl ( _device: <Self ::Ptr as ForeignOwnable >::Borrowed <'_>, + _file: &File , _cmd:u32 , _arg:usize , ) ->Result <isize > {
@@ -187,7 +190,10 @@ impl<T: MiscDevice> VtableHelper<T> {return ret; } -let ptr =match T ::open () { +// SAFETY: +// * The file is valid for the duration of this call. +// * There is no active fdget_pos region on the file on this thread. +let ptr =match T ::open (unsafe {File ::from_raw_file (file) }) {Ok (ptr) => ptr,Err (err) =>return err.to_errno (), };
@@ -211,7 +217,10 @@ impl<T: MiscDevice> VtableHelper<T> {// SAFETY: The release call of a file owns the private data. let ptr =unsafe { <T ::Ptr as ForeignOwnable >::from_foreign (private) }; -T ::release (ptr); +// SAFETY: +// * The file is valid for the duration of this call. +// * There is no active fdget_pos region on the file on this thread. +T ::release (ptr,unsafe {File ::from_raw_file (file) });0 }
@@ -229,7 +238,12 @@ impl<T: MiscDevice> VtableHelper<T> {// SAFETY: Ioctl calls can borrow the private data of the file. let device =unsafe { <T ::Ptr as ForeignOwnable >::borrow (private) }; -match T ::ioctl (device, cmd, argas usize ) { +// SAFETY: +// * The file is valid for the duration of this call. +// * There is no active fdget_pos region on the file on this thread. +let file =unsafe {File ::from_raw_file (file) }; + +match T ::ioctl (device, file, cmd, argas usize ) {Ok (ret) => retas c_long ,Err (err) => err.to_errno ()as c_long , }
@@ -249,7 +263,12 @@ impl<T: MiscDevice> VtableHelper<T> {// SAFETY: Ioctl calls can borrow the private data of the file. let device =unsafe { <T ::Ptr as ForeignOwnable >::borrow (private) }; -match T ::compat_ioctl (device, cmd, argas usize ) { +// SAFETY: +// * The file is valid for the duration of this call. +// * There is no active fdget_pos region on the file on this thread. +let file =unsafe {File ::from_raw_file (file) }; + +match T ::compat_ioctl (device, file, cmd, argas usize ) {Ok (ret) => retas c_long ,Err (err) => err.to_errno ()as c_long , }
Signature · 1 line
2.47.1.613.gc27f4b7a9f-goog
Re: [PATCH v3 1/3] rust: miscdevice: access file in fops
Quoted 8 lines · Alice Ryhl
This allows fops to access information about the underlying struct file for the miscdevice. For example, the Binder driver needs to inspect the
O_NONBLOCKflag inside thefops->ioctl()hook.Signed-off-by Alice Ryhl <[email protected]>--- rust/kernel/miscdevice.rs | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-)
Quoted 97 lines
rust/kernel/miscdevice.rs +25
-6@@ -11,6 +11,7 @@use crate ::{ bindings, error::{to_result,Error ,Result ,VTABLE_DEFAULT_ERROR }, + fs::File , prelude::*, str::CStr , types::{ForeignOwnable ,Opaque },@@ -103,10 +104,10 @@ pub trait MiscDevice {/// Called when the misc device is opened. /// /// The returned pointer will be stored as the private data for the file. -fn open () ->Result <Self ::Ptr >; +fn open (_file: &File ) ->Result <Self ::Ptr >;/// Called when the misc device is released. -fn release (device:Self ::Ptr ) { +fn release (device:Self ::Ptr , _file: &File ) {drop (device); }@@ -117,6 +118,7 @@ fn release(device: Self::Ptr) {/// [`kernel::ioctl`]: mod@crate::ioctl fn ioctl ( _device: <Self ::Ptr as ForeignOwnable >::Borrowed <'_>, + _file: &File , _cmd:u32 , _arg:usize , ) ->Result <isize > {@@ -133,6 +135,7 @@ fn ioctl(#[cfg( CONFIG_COMPAT )] fn compat_ioctl ( _device: <Self ::Ptr as ForeignOwnable >::Borrowed <'_>, + _file: &File , _cmd:u32 , _arg:usize , ) ->Result <isize > {@@ -187,7 +190,10 @@ impl<T: MiscDevice> VtableHelper<T> {return ret; } -let ptr =match T ::open () { +// SAFETY: +// * The file is valid for the duration of this call. +// * There is no active fdget_pos region on the file on this thread. +let ptr =match T ::open (unsafe {File ::from_raw_file (file) }) {Ok (ptr) => ptr,Err (err) =>return err.to_errno (), };@@ -211,7 +217,10 @@ impl<T: MiscDevice> VtableHelper<T> {// SAFETY: The release call of a file owns the private data. let ptr =unsafe { <T ::Ptr as ForeignOwnable >::from_foreign (private) }; -T ::release (ptr); +// SAFETY: +// * The file is valid for the duration of this call. +// * There is no active fdget_pos region on the file on this thread. +T ::release (ptr,unsafe {File ::from_raw_file (file) });0 }@@ -229,7 +238,12 @@ impl<T: MiscDevice> VtableHelper<T> {// SAFETY: Ioctl calls can borrow the private data of the file. let device =unsafe { <T ::Ptr as ForeignOwnable >::borrow (private) }; -match T ::ioctl (device, cmd, argas usize ) { +// SAFETY: +// * The file is valid for the duration of this call. +// * There is no active fdget_pos region on the file on this thread. +let file =unsafe {File ::from_raw_file (file) }; + +match T ::ioctl (device, file, cmd, argas usize ) {Ok (ret) => retas c_long ,Err (err) => err.to_errno ()as c_long , }@@ -249,7 +263,12 @@ impl<T: MiscDevice> VtableHelper<T> {// SAFETY: Ioctl calls can borrow the private data of the file. let device =unsafe { <T ::Ptr as ForeignOwnable >::borrow (private) }; -match T ::compat_ioctl (device, cmd, argas usize ) { +// SAFETY: +// * The file is valid for the duration of this call. +// * There is no active fdget_pos region on the file on this thread. +let file =unsafe {File ::from_raw_file (file) }; + +match T ::compat_ioctl (device, file, cmd, argas usize ) {Ok (ret) => retas c_long ,Err (err) => err.to_errno ()as c_long , }Signature · 2 lines
-- 2.47.1.613.gc27f4b7a9f-goog
Signature · 1 line
Lee Jones [李琼斯]
Lee Jones
Tested-byRe: [PATCH v3 1/3] rust: miscdevice: access file in fops
Quoted 6 lines · Lee Jones
Quoted 4 lines · Alice Ryhl
This allows fops to access information about the underlying struct file for the miscdevice. For example, the Binder driver needs to inspect the
O_NONBLOCKflag inside thefops->ioctl()hook.
Quoted 6 lines
Quoted 4 lines
Signed-off-by Alice Ryhl <[email protected]>--- rust/kernel/miscdevice.rs | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-)Reviewed-by Lee Jones <[email protected]>
Signature · 1 line
Lee Jones [李琼斯]
Alice Ryhl
reviewerPATCH v3 2/3 rust: miscdevice: access the `struct miscdevice` from fops->open()
In reply to Alice RyhlProviding access to the underlying struct miscdevice is useful for various reasons. For example, this allows you access the miscdevice's internal struct device for use with the dev_* printing macros.
Note that since the underlying struct miscdevice could get freed at any point after the fops->open() call (if misc_deregister is called), only the open call is given access to it. To use dev_* printing macros from other fops hooks, take a refcount on miscdevice->this_device to keep it alive. See the linked thread for further discussion on the lifetime of struct miscdevice.
--- rust/kernel/miscdevice.rs | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-)
rust/kernel/miscdevice.rs +22 -8
@@ -97,14 +97,14 @@ fn drop(self: Pin<&mut Self>) {/// Trait implemented by the private data of an open misc device. #[vtable] -pub trait MiscDevice { +pub trait MiscDevice :Sized {/// What kind of pointer should `Self` be wrapped in. type Ptr :ForeignOwnable +Send +Sync ;/// Called when the misc device is opened. /// /// The returned pointer will be stored as the private data for the file. -fn open (_file: &File ) ->Result <Self ::Ptr >; +fn open (_file: &File , _misc: &MiscDeviceRegistration <Self >) ->Result <Self ::Ptr >;/// Called when the misc device is released. fn release (device:Self ::Ptr , _file: &File ) {
@@ -182,24 +182,38 @@ impl<T: MiscDevice> VtableHelper<T> {/// The file must be associated with a `MiscDeviceRegistration<T>`. unsafe extern "C" fn fops_open <T :MiscDevice >( inode: *mut bindings::inode , - file: *mut bindings::file , + raw_file: *mut bindings::file , ) ->c_int {// SAFETY: The pointers are valid and for a file being opened. -let ret =unsafe { bindings::generic_file_open (inode, file) }; +let ret =unsafe { bindings::generic_file_open (inode, raw_file) };if ret !=0 {return ret; } +// SAFETY: The open call of a file can access the private data. +let misc_ptr =unsafe { (*raw_file).private_data }; + +// SAFETY: This is a miscdevice, so `misc_open()` set the private data to a pointer to the +// associated `struct miscdevice` before calling into this method. Furthermore, `misc_open()` +// ensures that the miscdevice can't be unregistered and freed during this call to `fops_open`. +let misc =unsafe { &*misc_ptr.cast ::<MiscDeviceRegistration <T >>() }; +// SAFETY: -// * The file is valid for the duration of this call. +// * This underlying file is valid for (much longer than) the duration of `T::open`. // * There is no active fdget_pos region on the file on this thread. -let ptr =match T ::open (unsafe {File ::from_raw_file (file) }) { +let file =unsafe {File ::from_raw_file (raw_file) }; + +let ptr =match T ::open (file, misc) {Ok (ptr) => ptr,Err (err) =>return err.to_errno (), }; -// SAFETY: The open call of a file owns the private data. -unsafe { (*file).private_data = ptr.into_foreign ().cast_mut () }; +// This overwrites the private data with the value specified by the user, changing the type of +// this file's private data. All future accesses to the private data is performed by other +// fops_* methods in this file, which all correctly cast the private data to the new type. +// +// SAFETY: The open call of a file can access the private data. +unsafe { (*raw_file).private_data = ptr.into_foreign ().cast_mut () };0 }
Signature · 1 line
2.47.1.613.gc27f4b7a9f-goog
Re: [PATCH v3 2/3] rust: miscdevice: access the `struct miscdevice` from fops->open()
Quoted 11 lines · Alice Ryhl
Providing access to the underlying
struct miscdeviceis useful for various reasons. For example, this allows you access the miscdevice's internalstruct devicefor use with thedev_*printing macros.Note that since the underlying
struct miscdevicecould get freed at any point after thefops->open()call (ifmisc_deregisteris called), only the open call is given access to it. To usedev_*printing macros from other fops hooks, take a refcount onmiscdevice->this_deviceto keep it alive. See the linked thread for further discussion on the lifetime ofstruct miscdevice.
Quoted 5 lines
Signed-off-by Alice Ryhl <[email protected]>--- rust/kernel/miscdevice.rs | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-)
Quoted 70 lines
rust/kernel/miscdevice.rs +22
-8@@ -97,14 +97,14 @@ fn drop(self: Pin<&mut Self>) {/// Trait implemented by the private data of an open misc device. #[vtable] -pub trait MiscDevice { +pub trait MiscDevice :Sized {/// What kind of pointer should `Self` be wrapped in. type Ptr :ForeignOwnable +Send +Sync ;/// Called when the misc device is opened. /// /// The returned pointer will be stored as the private data for the file. -fn open (_file: &File ) ->Result <Self ::Ptr >; +fn open (_file: &File , _misc: &MiscDeviceRegistration <Self >) ->Result <Self ::Ptr >;/// Called when the misc device is released. fn release (device:Self ::Ptr , _file: &File ) {@@ -182,24 +182,38 @@ impl<T: MiscDevice> VtableHelper<T> {/// The file must be associated with a `MiscDeviceRegistration<T>`. unsafe extern "C" fn fops_open <T :MiscDevice >( inode: *mut bindings::inode , - file: *mut bindings::file , + raw_file: *mut bindings::file , ) ->c_int {// SAFETY: The pointers are valid and for a file being opened. -let ret =unsafe { bindings::generic_file_open (inode, file) }; +let ret =unsafe { bindings::generic_file_open (inode, raw_file) };if ret !=0 {return ret; } +// SAFETY: The open call of a file can access the private data. +let misc_ptr =unsafe { (*raw_file).private_data }; + +// SAFETY: This is a miscdevice, so `misc_open()` set the private data to a pointer to the +// associated `struct miscdevice` before calling into this method. Furthermore, `misc_open()` +// ensures that the miscdevice can't be unregistered and freed during this call to `fops_open`. +let misc =unsafe { &*misc_ptr.cast ::<MiscDeviceRegistration <T >>() }; +// SAFETY: -// * The file is valid for the duration of this call. +// * This underlying file is valid for (much longer than) the duration of `T::open`. // * There is no active fdget_pos region on the file on this thread. -let ptr =match T ::open (unsafe {File ::from_raw_file (file) }) { +let file =unsafe {File ::from_raw_file (raw_file) }; + +let ptr =match T ::open (file, misc) {Ok (ptr) => ptr,Err (err) =>return err.to_errno (), }; -// SAFETY: The open call of a file owns the private data. -unsafe { (*file).private_data = ptr.into_foreign ().cast_mut () }; +// This overwrites the private data with the value specified by the user, changing the type of +// this file's private data. All future accesses to the private data is performed by other +// fops_* methods in this file, which all correctly cast the private data to the new type. +// +// SAFETY: The open call of a file can access the private data. +unsafe { (*raw_file).private_data = ptr.into_foreign ().cast_mut () };0 }Signature · 2 lines
-- 2.47.1.613.gc27f4b7a9f-goog
Signature · 1 line
Lee Jones [李琼斯]
Lee Jones
Tested-byRe: [PATCH v3 2/3] rust: miscdevice: access the `struct miscdevice` from fops->open()
Quoted 13 lines · Lee Jones
Quoted 11 lines · Alice Ryhl
Providing access to the underlying
struct miscdeviceis useful for various reasons. For example, this allows you access the miscdevice's internalstruct devicefor use with thedev_*printing macros.Note that since the underlying
struct miscdevicecould get freed at any point after thefops->open()call (ifmisc_deregisteris called), only the open call is given access to it. To usedev_*printing macros from other fops hooks, take a refcount onmiscdevice->this_deviceto keep it alive. See the linked thread for further discussion on the lifetime ofstruct miscdevice.
Quoted 7 lines
Quoted 5 lines
Signed-off-by Alice Ryhl <[email protected]>--- rust/kernel/miscdevice.rs | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-)Reviewed-by Lee Jones <[email protected]>
Signature · 1 line
Lee Jones [李琼斯]
Alice Ryhl
reviewerPATCH v3 3/3 rust: miscdevice: Provide accessor to pull out miscdevice::this_device
In reply to Alice RyhlFrom: Lee Jones <[email protected]>
There are situations where a pointer to a struct device will become necessary (e.g. for calling into dev_*() functions). This accessor allows callers to pull this out from the struct miscdevice.
--- rust/kernel/miscdevice.rs | 11 +++++++++++ 1 file changed, 11 insertions(+)
rust/kernel/miscdevice.rs +11 -0
@@ -10,6 +10,7 @@use crate ::{ bindings, + device::Device , error::{to_result,Error ,Result ,VTABLE_DEFAULT_ERROR }, fs::File , prelude::*,
@@ -85,6 +86,16 @@ pub fn register(opts: MiscDeviceOptions) -> impl PinInit<Self, Error> {pub fn as_raw (&self) -> *mut bindings::miscdevice { self.inner.get () } + +/// Access the `this_device` field. +pub fn device (&self) -> &Device { +// SAFETY: This can only be called after a successful register(), which always +// initialises `this_device` with a valid device. Furthermore, the signature of this +// function tells the borrow-checker that the `&Device` reference must not outlive the +// `&MiscDeviceRegistration<T>` used to obtain it, so the last use of the reference must be +// before the underlying `struct miscdevice` is destroyed. +unsafe {Device ::as_ref ((*self.as_raw ()).this_device) } + } }#[pinned_drop]
Signature · 1 line
2.47.1.613.gc27f4b7a9f-goog
Re: [PATCH v3 3/3] rust: miscdevice: Provide accessor to pull out miscdevice::this_device
Quoted 11 lines · Alice Ryhl
From: Lee Jones <[email protected]>
There are situations where a pointer to a
struct devicewill become necessary (e.g. for calling into dev_*() functions). This accessor allows callers to pull this out from thestruct miscdevice.Signed-off-by Lee Jones <[email protected]>Signed-off-by Alice Ryhl <[email protected]>--- rust/kernel/miscdevice.rs | 11 +++++++++++ 1 file changed, 11 insertions(+)
This might be superfluous, but:
Signature · 1 line
Lee Jones [李琼斯]
Quoted 7 lines · Alice Ryhl
This could not land with the base miscdevice abstractions due to the dependency on File.
The last two patches enable you to use the
dev_*macros to print messages in miscdevice drivers.Signed-off-by Alice Ryhl <[email protected]>
For the series,
Quoted 33 lines
---
Changes in v3:
- Fix build error infops->open()patch.
- Improve wording of some comments infops->open()patch.
- Update commit message with more info on whystruct miscdeviceis
only made available infops->open()and not other hooks.
- Include Lee's device accessor patch, since it's a needed component to
use thedev_*printing macros with miscdevice.
- Link to v2: https://lore.kernel.org/r/[email protected]Changes in v2:
- Access thestruct miscdevicefromfops->open().
- Link to v1: https://lore.kernel.org/r/[email protected]---
Alice Ryhl (2):
rust: miscdevice: access file in fops
rust: miscdevice: access thestruct miscdevicefromfops->open()Lee Jones (1):
rust: miscdevice: Provide accessor to pull outmiscdevice::this_devicerust/kernel/miscdevice.rs | 66 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 55 insertions(+), 11 deletions(-)---
base-commit:fac04efc5c793dccbd07e2d59af9f90b7fc0dca4
change-id: 20241203-miscdevice-file-param-5df7f75861daBest regards,
Signature · 1 line
Alice Ryhl <[email protected]>