This sample driver demonstrates the following basic operations:

* Register a Misc Device
* Create /dev/rust-misc-device
* Provide open call-back for the aforementioned character device
* Operate on the character device via a simple ioctl()
* Provide close call-back for the character device

Signed-off-by: Lee Jones <lee@kernel.org>
---
 samples/rust/Kconfig             | 10 ++++
 samples/rust/Makefile            |  1 +
 samples/rust/rust_misc_device.rs | 80 ++++++++++++++++++++++++++++++++
 3 files changed, 91 insertions(+)
 create mode 100644 samples/rust/rust_misc_device.rs

diff --git a/samples/rust/Kconfig b/samples/rust/Kconfig
index b0f74a81c8f9..df384e679901 100644
--- a/samples/rust/Kconfig
+++ b/samples/rust/Kconfig
@@ -20,6 +20,16 @@ config SAMPLE_RUST_MINIMAL
 
 	  If unsure, say N.
 
+config SAMPLE_RUST_MISC_DEVICE
+	tristate "Misc device"
+	help
+	  This option builds the Rust misc device.
+
+	  To compile this as a module, choose M here:
+	  the module will be called rust_misc_device.
+
+	  If unsure, say N.
+
 config SAMPLE_RUST_PRINT
 	tristate "Printing macros"
 	help
diff --git a/samples/rust/Makefile b/samples/rust/Makefile
index c1a5c1655395..ad4b97a98580 100644
--- a/samples/rust/Makefile
+++ b/samples/rust/Makefile
@@ -2,6 +2,7 @@
 ccflags-y += -I$(src)				# needed for trace events
 
 obj-$(CONFIG_SAMPLE_RUST_MINIMAL)		+= rust_minimal.o
+obj-$(CONFIG_SAMPLE_RUST_MISC_DEVICE)		+= rust_misc_device.o
 obj-$(CONFIG_SAMPLE_RUST_PRINT)			+= rust_print.o
 
 rust_print-y := rust_print_main.o rust_print_events.o
diff --git a/samples/rust/rust_misc_device.rs b/samples/rust/rust_misc_device.rs
new file mode 100644
index 000000000000..3837532d259e
--- /dev/null
+++ b/samples/rust/rust_misc_device.rs
@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: GPL-2.0
+
+// Copyright (C) 2024 Google LLC.
+
+//! Rust misc device sample.
+
+use kernel::{
+    c_str,
+    ioctl::_IO,
+    miscdevice::{MiscDevice, MiscDeviceOptions, MiscDeviceRegistration},
+    prelude::*,
+};
+
+const RUST_MISC_DEV_HELLO: u32 = _IO('|' as u32, 9);
+
+module! {
+    type: RustMiscDeviceModule,
+    name: "rust_misc_device",
+    author: "Lee Jones",
+    description: "Rust misc device sample",
+    license: "GPL",
+}
+
+struct RustMiscDeviceModule {
+    _miscdev: Pin<KBox<MiscDeviceRegistration<RustMiscDevice>>>,
+}
+
+impl kernel::Module for RustMiscDeviceModule {
+    fn init(_module: &'static ThisModule) -> Result<Self> {
+        pr_info!("Initialising Rust Misc Device Sample\n");
+
+        let options = MiscDeviceOptions {
+            name: c_str!("rust-misc-device"),
+        };
+
+        Ok(Self {
+            _miscdev: KBox::pin_init(
+                MiscDeviceRegistration::<RustMiscDevice>::register(options),
+                GFP_KERNEL,
+            )?,
+        })
+    }
+}
+
+struct RustMiscDevice;
+
+#[vtable]
+impl MiscDevice for RustMiscDevice {
+    type Ptr = KBox<Self>;
+
+    fn open() -> Result<KBox<Self>> {
+        pr_info!("Opening Rust Misc Device Sample\n");
+
+        Ok(KBox::new(RustMiscDevice, GFP_KERNEL)?)
+    }
+
+    fn ioctl(
+        _device: <Self::Ptr as kernel::types::ForeignOwnable>::Borrowed<'_>,
+        cmd: u32,
+        _arg: usize,
+    ) -> Result<isize> {
+        pr_info!("IOCTLing Rust Misc Device Sample\n");
+
+        match cmd {
+            RUST_MISC_DEV_HELLO => pr_info!("Hello from the Rust Misc Device\n"),
+            _ => {
+                pr_err!("IOCTL not recognised: {}\n", cmd);
+                return Err(ENOTTY);
+            }
+        }
+
+        Ok(0)
+    }
+}
+
+impl Drop for RustMiscDevice {
+    fn drop(&mut self) {
+        pr_info!("Exiting the Rust Misc Device Sample\n");
+    }
+}
-- 
2.47.0.338.g60cca15819-goog

On Fri, Dec 6, 2024, at 10:05, Lee Jones wrote:
> This sample driver demonstrates the following basic operations:
>
> * Register a Misc Device
> * Create /dev/rust-misc-device
> * Provide open call-back for the aforementioned character device
> * Operate on the character device via a simple ioctl()
> * Provide close call-back for the character device
>
> Signed-off-by: Lee Jones <lee@kernel.org>

Could you include a compat_ioctl() callback in the example?
I think it would be good to include it as a reminder for
authors of actual drivers that every driver implementing
ioctl should also implement compat_ioctl. In C drivers, this
can usually be done by pointing .compat_ioctl() to the
generic compat_ptr_ioctl() function, which assumes that 'arg'
is a pointer disguised as an 'unsigned long'.

      Arnd

On Fri, Dec 6, 2024 at 11:05 AM Arnd Bergmann <arnd@arndb.de> wrote:
>
> On Fri, Dec 6, 2024, at 10:05, Lee Jones wrote:
> > This sample driver demonstrates the following basic operations:
> >
> > * Register a Misc Device
> > * Create /dev/rust-misc-device
> > * Provide open call-back for the aforementioned character device
> > * Operate on the character device via a simple ioctl()
> > * Provide close call-back for the character device
> >
> > Signed-off-by: Lee Jones <lee@kernel.org>
>
> Could you include a compat_ioctl() callback in the example?
> I think it would be good to include it as a reminder for
> authors of actual drivers that every driver implementing
> ioctl should also implement compat_ioctl. In C drivers, this
> can usually be done by pointing .compat_ioctl() to the
> generic compat_ptr_ioctl() function, which assumes that 'arg'
> is a pointer disguised as an 'unsigned long'.

The current Rust logic for building the fops table will use
compat_ptr_ioctl() automatically if you specify ioctl() but don't
specify compat_ioctl(), so this already uses compat_ptr_ioctl(). But
maybe that's not what we want?

Alice

On Fri, Dec 06, 2024 at 09:05:06AM +0000, Lee Jones wrote:
> This sample driver demonstrates the following basic operations:
> 
> * Register a Misc Device
> * Create /dev/rust-misc-device
> * Provide open call-back for the aforementioned character device
> * Operate on the character device via a simple ioctl()
> * Provide close call-back for the character device
> 
> Signed-off-by: Lee Jones <lee@kernel.org>
> ---
>  samples/rust/Kconfig             | 10 ++++
>  samples/rust/Makefile            |  1 +
>  samples/rust/rust_misc_device.rs | 80 ++++++++++++++++++++++++++++++++
>  3 files changed, 91 insertions(+)
>  create mode 100644 samples/rust/rust_misc_device.rs
> 
> diff --git a/samples/rust/Kconfig b/samples/rust/Kconfig
> index b0f74a81c8f9..df384e679901 100644
> --- a/samples/rust/Kconfig
> +++ b/samples/rust/Kconfig
> @@ -20,6 +20,16 @@ config SAMPLE_RUST_MINIMAL
>  
>  	  If unsure, say N.
>  
> +config SAMPLE_RUST_MISC_DEVICE
> +	tristate "Misc device"
> +	help
> +	  This option builds the Rust misc device.
> +
> +	  To compile this as a module, choose M here:
> +	  the module will be called rust_misc_device.
> +
> +	  If unsure, say N.
> +
>  config SAMPLE_RUST_PRINT
>  	tristate "Printing macros"
>  	help
> diff --git a/samples/rust/Makefile b/samples/rust/Makefile
> index c1a5c1655395..ad4b97a98580 100644
> --- a/samples/rust/Makefile
> +++ b/samples/rust/Makefile
> @@ -2,6 +2,7 @@
>  ccflags-y += -I$(src)				# needed for trace events
>  
>  obj-$(CONFIG_SAMPLE_RUST_MINIMAL)		+= rust_minimal.o
> +obj-$(CONFIG_SAMPLE_RUST_MISC_DEVICE)		+= rust_misc_device.o
>  obj-$(CONFIG_SAMPLE_RUST_PRINT)			+= rust_print.o
>  
>  rust_print-y := rust_print_main.o rust_print_events.o
> diff --git a/samples/rust/rust_misc_device.rs b/samples/rust/rust_misc_device.rs
> new file mode 100644
> index 000000000000..3837532d259e
> --- /dev/null
> +++ b/samples/rust/rust_misc_device.rs
> @@ -0,0 +1,80 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +// Copyright (C) 2024 Google LLC.
> +
> +//! Rust misc device sample.
> +
> +use kernel::{
> +    c_str,
> +    ioctl::_IO,
> +    miscdevice::{MiscDevice, MiscDeviceOptions, MiscDeviceRegistration},
> +    prelude::*,
> +};
> +
> +const RUST_MISC_DEV_HELLO: u32 = _IO('|' as u32, 9);
> +
> +module! {
> +    type: RustMiscDeviceModule,
> +    name: "rust_misc_device",
> +    author: "Lee Jones",
> +    description: "Rust misc device sample",
> +    license: "GPL",
> +}
> +
> +struct RustMiscDeviceModule {
> +    _miscdev: Pin<KBox<MiscDeviceRegistration<RustMiscDevice>>>,
> +}
> +
> +impl kernel::Module for RustMiscDeviceModule {
> +    fn init(_module: &'static ThisModule) -> Result<Self> {
> +        pr_info!("Initialising Rust Misc Device Sample\n");
> +
> +        let options = MiscDeviceOptions {
> +            name: c_str!("rust-misc-device"),
> +        };
> +
> +        Ok(Self {
> +            _miscdev: KBox::pin_init(
> +                MiscDeviceRegistration::<RustMiscDevice>::register(options),
> +                GFP_KERNEL,
> +            )?,
> +        })

Since this v4 was sent just when I was commenting on v3:

Why do we add examples where we ask people to allocate those structures with
kmalloc()?

`MiscDevice` should switch to the generic `Registration` type in [1] and use
`InPlaceModule`, such that those structures land in the .data section of the
binary.

[1] https://lore.kernel.org/rust-for-linux/20241205141533.111830-3-dakr@kernel.org/

> +    }
> +}
> +
> +struct RustMiscDevice;
> +
> +#[vtable]
> +impl MiscDevice for RustMiscDevice {
> +    type Ptr = KBox<Self>;
> +
> +    fn open() -> Result<KBox<Self>> {
> +        pr_info!("Opening Rust Misc Device Sample\n");

This should be `dev_info!`, but I see why you don't have access to the device
structure here...

@Greg: How do miscdev drivers do this in C? I looked at a couple of them, but
all of those seem to use pr_* macros. They can't get the device pointer from
the inode or file pointer.

However, C drivers could refer to the struct miscdevice directly since it's
almost always a static variable in the file scope.

In Rust we do the static allocation part with `InPlaceModule` as mentioned
above. However, this still doesn't let us refer to the underlying struct
miscdevice.

This all would be much cleaner if there'd be a "fake" probe() callback for a
struct miscdevice. This way we could perfectly align the miscdevice abstraction
with the abstractions for all other drivers, such as PCI, platform, etc.

- Danilo

> +
> +        Ok(KBox::new(RustMiscDevice, GFP_KERNEL)?)
> +    }
> +
> +    fn ioctl(
> +        _device: <Self::Ptr as kernel::types::ForeignOwnable>::Borrowed<'_>,
> +        cmd: u32,
> +        _arg: usize,
> +    ) -> Result<isize> {
> +        pr_info!("IOCTLing Rust Misc Device Sample\n");
> +
> +        match cmd {
> +            RUST_MISC_DEV_HELLO => pr_info!("Hello from the Rust Misc Device\n"),
> +            _ => {
> +                pr_err!("IOCTL not recognised: {}\n", cmd);
> +                return Err(ENOTTY);
> +            }
> +        }
> +
> +        Ok(0)
> +    }
> +}
> +
> +impl Drop for RustMiscDevice {
> +    fn drop(&mut self) {
> +        pr_info!("Exiting the Rust Misc Device Sample\n");
> +    }
> +}
> -- 
> 2.47.0.338.g60cca15819-goog
> 
>

On Fri, Dec 6, 2024 at 10:29 AM Danilo Krummrich <dakr@kernel.org> wrote:
>
> On Fri, Dec 06, 2024 at 09:05:06AM +0000, Lee Jones wrote:
> > This sample driver demonstrates the following basic operations:
> >
> > * Register a Misc Device
> > * Create /dev/rust-misc-device
> > * Provide open call-back for the aforementioned character device
> > * Operate on the character device via a simple ioctl()
> > * Provide close call-back for the character device
> >
> > Signed-off-by: Lee Jones <lee@kernel.org>
> > ---
> >  samples/rust/Kconfig             | 10 ++++
> >  samples/rust/Makefile            |  1 +
> >  samples/rust/rust_misc_device.rs | 80 ++++++++++++++++++++++++++++++++
> >  3 files changed, 91 insertions(+)
> >  create mode 100644 samples/rust/rust_misc_device.rs
> >
> > diff --git a/samples/rust/Kconfig b/samples/rust/Kconfig
> > index b0f74a81c8f9..df384e679901 100644
> > --- a/samples/rust/Kconfig
> > +++ b/samples/rust/Kconfig
> > @@ -20,6 +20,16 @@ config SAMPLE_RUST_MINIMAL
> >
> >         If unsure, say N.
> >
> > +config SAMPLE_RUST_MISC_DEVICE
> > +     tristate "Misc device"
> > +     help
> > +       This option builds the Rust misc device.
> > +
> > +       To compile this as a module, choose M here:
> > +       the module will be called rust_misc_device.
> > +
> > +       If unsure, say N.
> > +
> >  config SAMPLE_RUST_PRINT
> >       tristate "Printing macros"
> >       help
> > diff --git a/samples/rust/Makefile b/samples/rust/Makefile
> > index c1a5c1655395..ad4b97a98580 100644
> > --- a/samples/rust/Makefile
> > +++ b/samples/rust/Makefile
> > @@ -2,6 +2,7 @@
> >  ccflags-y += -I$(src)                                # needed for trace events
> >
> >  obj-$(CONFIG_SAMPLE_RUST_MINIMAL)            += rust_minimal.o
> > +obj-$(CONFIG_SAMPLE_RUST_MISC_DEVICE)                += rust_misc_device.o
> >  obj-$(CONFIG_SAMPLE_RUST_PRINT)                      += rust_print.o
> >
> >  rust_print-y := rust_print_main.o rust_print_events.o
> > diff --git a/samples/rust/rust_misc_device.rs b/samples/rust/rust_misc_device.rs
> > new file mode 100644
> > index 000000000000..3837532d259e
> > --- /dev/null
> > +++ b/samples/rust/rust_misc_device.rs
> > @@ -0,0 +1,80 @@
> > +// SPDX-License-Identifier: GPL-2.0
> > +
> > +// Copyright (C) 2024 Google LLC.
> > +
> > +//! Rust misc device sample.
> > +
> > +use kernel::{
> > +    c_str,
> > +    ioctl::_IO,
> > +    miscdevice::{MiscDevice, MiscDeviceOptions, MiscDeviceRegistration},
> > +    prelude::*,
> > +};
> > +
> > +const RUST_MISC_DEV_HELLO: u32 = _IO('|' as u32, 9);
> > +
> > +module! {
> > +    type: RustMiscDeviceModule,
> > +    name: "rust_misc_device",
> > +    author: "Lee Jones",
> > +    description: "Rust misc device sample",
> > +    license: "GPL",
> > +}
> > +
> > +struct RustMiscDeviceModule {
> > +    _miscdev: Pin<KBox<MiscDeviceRegistration<RustMiscDevice>>>,
> > +}
> > +
> > +impl kernel::Module for RustMiscDeviceModule {
> > +    fn init(_module: &'static ThisModule) -> Result<Self> {
> > +        pr_info!("Initialising Rust Misc Device Sample\n");
> > +
> > +        let options = MiscDeviceOptions {
> > +            name: c_str!("rust-misc-device"),
> > +        };
> > +
> > +        Ok(Self {
> > +            _miscdev: KBox::pin_init(
> > +                MiscDeviceRegistration::<RustMiscDevice>::register(options),
> > +                GFP_KERNEL,
> > +            )?,
> > +        })
>
> Since this v4 was sent just when I was commenting on v3:
>
> Why do we add examples where we ask people to allocate those structures with
> kmalloc()?
>
> `MiscDevice` should switch to the generic `Registration` type in [1] and use
> `InPlaceModule`, such that those structures land in the .data section of the
> binary.
>
> [1] https://lore.kernel.org/rust-for-linux/20241205141533.111830-3-dakr@kernel.org/
>
> > +    }
> > +}
> > +
> > +struct RustMiscDevice;
> > +
> > +#[vtable]
> > +impl MiscDevice for RustMiscDevice {
> > +    type Ptr = KBox<Self>;
> > +
> > +    fn open() -> Result<KBox<Self>> {
> > +        pr_info!("Opening Rust Misc Device Sample\n");
>
> This should be `dev_info!`, but I see why you don't have access to the device
> structure here...
>
> @Greg: How do miscdev drivers do this in C? I looked at a couple of them, but
> all of those seem to use pr_* macros. They can't get the device pointer from
> the inode or file pointer.
>
> However, C drivers could refer to the struct miscdevice directly since it's
> almost always a static variable in the file scope.
>
> In Rust we do the static allocation part with `InPlaceModule` as mentioned
> above. However, this still doesn't let us refer to the underlying struct
> miscdevice.
>
> This all would be much cleaner if there'd be a "fake" probe() callback for a
> struct miscdevice. This way we could perfectly align the miscdevice abstraction
> with the abstractions for all other drivers, such as PCI, platform, etc.

It turns out that the file private data is a pointer to the `struct
miscdevice` in fops->open(), so we can access it in open. To access it
in other fops hooks, we need to take a refcount on the device in open
and stash it.

Alice

On Fri, Dec 06, 2024 at 10:40:23AM +0100, Alice Ryhl wrote:
> On Fri, Dec 6, 2024 at 10:29 AM Danilo Krummrich <dakr@kernel.org> wrote:
> >
> > On Fri, Dec 06, 2024 at 09:05:06AM +0000, Lee Jones wrote:
> > > This sample driver demonstrates the following basic operations:
> > >
> > > * Register a Misc Device
> > > * Create /dev/rust-misc-device
> > > * Provide open call-back for the aforementioned character device
> > > * Operate on the character device via a simple ioctl()
> > > * Provide close call-back for the character device
> > >
> > > Signed-off-by: Lee Jones <lee@kernel.org>
> > > ---
> > >  samples/rust/Kconfig             | 10 ++++
> > >  samples/rust/Makefile            |  1 +
> > >  samples/rust/rust_misc_device.rs | 80 ++++++++++++++++++++++++++++++++
> > >  3 files changed, 91 insertions(+)
> > >  create mode 100644 samples/rust/rust_misc_device.rs
> > >
> > > diff --git a/samples/rust/Kconfig b/samples/rust/Kconfig
> > > index b0f74a81c8f9..df384e679901 100644
> > > --- a/samples/rust/Kconfig
> > > +++ b/samples/rust/Kconfig
> > > @@ -20,6 +20,16 @@ config SAMPLE_RUST_MINIMAL
> > >
> > >         If unsure, say N.
> > >
> > > +config SAMPLE_RUST_MISC_DEVICE
> > > +     tristate "Misc device"
> > > +     help
> > > +       This option builds the Rust misc device.
> > > +
> > > +       To compile this as a module, choose M here:
> > > +       the module will be called rust_misc_device.
> > > +
> > > +       If unsure, say N.
> > > +
> > >  config SAMPLE_RUST_PRINT
> > >       tristate "Printing macros"
> > >       help
> > > diff --git a/samples/rust/Makefile b/samples/rust/Makefile
> > > index c1a5c1655395..ad4b97a98580 100644
> > > --- a/samples/rust/Makefile
> > > +++ b/samples/rust/Makefile
> > > @@ -2,6 +2,7 @@
> > >  ccflags-y += -I$(src)                                # needed for trace events
> > >
> > >  obj-$(CONFIG_SAMPLE_RUST_MINIMAL)            += rust_minimal.o
> > > +obj-$(CONFIG_SAMPLE_RUST_MISC_DEVICE)                += rust_misc_device.o
> > >  obj-$(CONFIG_SAMPLE_RUST_PRINT)                      += rust_print.o
> > >
> > >  rust_print-y := rust_print_main.o rust_print_events.o
> > > diff --git a/samples/rust/rust_misc_device.rs b/samples/rust/rust_misc_device.rs
> > > new file mode 100644
> > > index 000000000000..3837532d259e
> > > --- /dev/null
> > > +++ b/samples/rust/rust_misc_device.rs
> > > @@ -0,0 +1,80 @@
> > > +// SPDX-License-Identifier: GPL-2.0
> > > +
> > > +// Copyright (C) 2024 Google LLC.
> > > +
> > > +//! Rust misc device sample.
> > > +
> > > +use kernel::{
> > > +    c_str,
> > > +    ioctl::_IO,
> > > +    miscdevice::{MiscDevice, MiscDeviceOptions, MiscDeviceRegistration},
> > > +    prelude::*,
> > > +};
> > > +
> > > +const RUST_MISC_DEV_HELLO: u32 = _IO('|' as u32, 9);
> > > +
> > > +module! {
> > > +    type: RustMiscDeviceModule,
> > > +    name: "rust_misc_device",
> > > +    author: "Lee Jones",
> > > +    description: "Rust misc device sample",
> > > +    license: "GPL",
> > > +}
> > > +
> > > +struct RustMiscDeviceModule {
> > > +    _miscdev: Pin<KBox<MiscDeviceRegistration<RustMiscDevice>>>,
> > > +}
> > > +
> > > +impl kernel::Module for RustMiscDeviceModule {
> > > +    fn init(_module: &'static ThisModule) -> Result<Self> {
> > > +        pr_info!("Initialising Rust Misc Device Sample\n");
> > > +
> > > +        let options = MiscDeviceOptions {
> > > +            name: c_str!("rust-misc-device"),
> > > +        };
> > > +
> > > +        Ok(Self {
> > > +            _miscdev: KBox::pin_init(
> > > +                MiscDeviceRegistration::<RustMiscDevice>::register(options),
> > > +                GFP_KERNEL,
> > > +            )?,
> > > +        })
> >
> > Since this v4 was sent just when I was commenting on v3:
> >
> > Why do we add examples where we ask people to allocate those structures with
> > kmalloc()?
> >
> > `MiscDevice` should switch to the generic `Registration` type in [1] and use
> > `InPlaceModule`, such that those structures land in the .data section of the
> > binary.
> >
> > [1] https://lore.kernel.org/rust-for-linux/20241205141533.111830-3-dakr@kernel.org/
> >
> > > +    }
> > > +}
> > > +
> > > +struct RustMiscDevice;
> > > +
> > > +#[vtable]
> > > +impl MiscDevice for RustMiscDevice {
> > > +    type Ptr = KBox<Self>;
> > > +
> > > +    fn open() -> Result<KBox<Self>> {
> > > +        pr_info!("Opening Rust Misc Device Sample\n");
> >
> > This should be `dev_info!`, but I see why you don't have access to the device
> > structure here...
> >
> > @Greg: How do miscdev drivers do this in C? I looked at a couple of them, but
> > all of those seem to use pr_* macros. They can't get the device pointer from
> > the inode or file pointer.
> >
> > However, C drivers could refer to the struct miscdevice directly since it's
> > almost always a static variable in the file scope.
> >
> > In Rust we do the static allocation part with `InPlaceModule` as mentioned
> > above. However, this still doesn't let us refer to the underlying struct
> > miscdevice.
> >
> > This all would be much cleaner if there'd be a "fake" probe() callback for a
> > struct miscdevice. This way we could perfectly align the miscdevice abstraction
> > with the abstractions for all other drivers, such as PCI, platform, etc.
> 
> It turns out that the file private data is a pointer to the `struct
> miscdevice` in fops->open(), so we can access it in open. To access it
> in other fops hooks, we need to take a refcount on the device in open
> and stash it.

Even better! I suggest to represent it as `misc::Device` and align it with
`platform::Device`, `pci::Device`, etc.

> 
> Alice
>