rust: add basic serial device bus abstractions
Subsystems (7)
Markus Probst
maintainerv2 cover rust: add basic serial device bus abstractions
This patch series adds the serdev device bus rust abstraction into the kernel.
This abstraction will be used by a driver, which targets the MCU devices in Synology devices.
Kari Argillander also messaged me, stating that he wants to write a watchdog driver with this abstraction (needing initial device data).
@Rob: Are you willing to maintain these rust abstractions yourself, as you are the expert on this subsystem, otherwise I would take care of it with a "SERIAL DEVICE BUS [RUST]" section in the MAINTAINERS file. In the second case, I assume you are going to pick those patches as-is into your tree, after they have been reviewed?
---
Changes in v2:
- fix documentation in serdev::Driver::write and serdev::Driver::write_all
- remove use of dev_info in probe from the sample
- remove properties_parse from the sample
- add optional baudrate property to the sample
- remove 1. patch
- remove TryFrom<&device::Device<Ctx>> for &serdev::Device<Ctx> implementation
- fix import style
- add patch to return reference in devres::register to fix safety
issue
- add patch to add private data to serdev_device, to fix Device.drvdata() from failing
- simplify abstraction by removing ability to receive the initial transmission. It may be added later in a separate patch series if needed.
- Link to v1: https://lore.kernel.org/r/[email protected]
---
Markus Probst (4):
rust: devres: return reference in devres::register
serdev: add private data to serdev_device
rust: add basic serial device bus abstractions
samples: rust: add Rust serial device bus sample device driver
include/linux/serdev.h | 14 +- rust/bindings/bindings_helper.h | 1 + rust/helpers/helpers.c | 1 + rust/helpers/serdev.c | 22 ++ rust/kernel/cpufreq.rs | 3 +- rust/kernel/devres.rs | 15 +- rust/kernel/drm/driver.rs | 3 +- rust/kernel/lib.rs | 2 + rust/kernel/serdev.rs | 533 +++++++++++++++++++++++++++++++++++++ samples/rust/Kconfig | 11 + samples/rust/Makefile | 1 + samples/rust/rust_driver_serdev.rs | 86 ++++++ 12 files changed, 682 insertions(+), 10 deletions(-)
---
base-commit: 11439c4635edd669ae435eec308f4ab8a0804808
change-id: 20251217-rust_serdev-ee5481e9085c
Markus Probst
maintainerPATCH v2 1/4 rust: devres: return reference in `devres::register`
Return the reference to the initialized data in the devres::register function.
This is needed in a following commit (rust: add basic serial device bus abstractions).
--- rust/kernel/cpufreq.rs | 3 ++- rust/kernel/devres.rs | 15 +++++++++++++-- rust/kernel/drm/driver.rs | 3 ++- 3 files changed, 17 insertions(+), 4 deletions(-)
rust/kernel/cpufreq.rs +2 -1
@@ -1051,7 +1051,8 @@ pub fn new_foreign_owned(dev: &Device<Bound>) -> Result where T: 'static, { - devres::register(dev, Self::new()?, GFP_KERNEL) + devres::register(dev, Self::new()?, GFP_KERNEL)?; +Ok (()) } }
rust/kernel/devres.rs +13 -2
@@ -326,15 +326,26 @@ fn register_foreign<P>(dev: &Device<Bound>, data: P) -> Result/// } /// /// fn from_bound_context(dev: &Device<Bound>) -> Result { -/// devres::register(dev, Registration::new(), GFP_KERNEL) +/// devres::register(dev, Registration::new(), GFP_KERNEL)?; +/// Ok(()) /// } /// ``` -pub fn register <T ,E >(dev: &Device <Bound >, data:impl PinInit <T ,E >, flags:Flags ) ->Result +pub fn register <'a,T ,E >( + dev: &'aDevice <Bound >, + data:impl PinInit <T ,E >, + flags:Flags , +) ->Result <&'aT >where T :Send + 'static,Error :From <E >, {let data =KBox ::pin_init (data, flags)?; +let data_ptr = &raw const *data; +register_foreign (dev, data) +// SAFETY: `dev` is valid for the lifetime of 'a. As long as there is a reference to +// `Device<Bound>`, it is guaranteed that the device is not unbound and data has not been +// dropped. Thus `data_ptr` is also valid for the lifetime of 'a. + .map (|()|unsafe { &*data_ptr }) }
rust/kernel/drm/driver.rs +2 -1
@@ -145,7 +145,8 @@ pub fn new_foreign_owned(let reg =Registration ::<T >::new (drm, flags)?; - devres::register (dev, reg,GFP_KERNEL ) + devres::register (dev, reg,GFP_KERNEL )?; +Ok (()) }/// Returns a reference to the `Device` instance for this registration.
Signature · 1 line
2.52.0
Markus Probst
maintainerPATCH v2 2/4 serdev: add private data to serdev_device
In reply to Markus ProbstAdd private data to struct serdev_device, as it is required by the rust abstraction added in the following commit
(rust: add basic serial device bus abstractions).
--- include/linux/serdev.h | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-)
include/linux/serdev.h +8 -6
@@ -33,12 +33,13 @@ struct serdev_device_ops {/** * struct serdev_device - Basic representation of an serdev device -* @dev: Driver model representation of the device. -* @nr: Device number on serdev bus. -* @ctrl: serdev controller managing this device. -* @ops: Device operations. -* @write_comp Completion used by serdev_device_write() internally -* @write_lock Lock to serialize access when writing data +* @dev: Driver model representation of the device. +* @nr: Device number on serdev bus. +* @ctrl: serdev controller managing this device. +* @ops: Device operations. +* @write_comp Completion used by serdev_device_write() internally +* @write_lock Lock to serialize access when writing data +* @private_data Private data for the device driver. */ struct serdev_device {struct device dev;
@@ -47,6 +48,7 @@ struct serdev_device {const struct serdev_device_ops *ops;struct completion write_comp;struct mutex write_lock; +void *private_data; };static inline struct serdev_device *to_serdev_device (struct device *d)
Signature · 1 line
2.52.0
Markus Probst
maintainerPATCH v2 3/4 rust: add basic serial device bus abstractions
In reply to Markus ProbstImplement the basic serial device bus abstractions required to write a serial device bus device driver with or without the need for initial device data. This includes the following data structures:
The serdev::Driver trait represents the interface to the driver.
The serdev::Device abstraction represents a struct serdev_device.
In order to provide the Serdev specific parts to a generic driver::Registration the driver::RegistrationOps trait is implemented by serdev::Adapter.
--- rust/bindings/bindings_helper.h | 1 + rust/helpers/helpers.c | 1 + rust/helpers/serdev.c | 22 ++ rust/kernel/lib.rs | 2 + rust/kernel/serdev.rs | 533 ++++++++++++++++++++++++++++++++++++++++ 5 files changed, 559 insertions(+)
rust/bindings/bindings_helper.h +1 -0
@@ -80,6 +80,7 @@#include <linux/regulator/consumer.h> #include <linux/sched.h> #include <linux/security.h> +#include <linux/serdev.h> #include <linux/slab.h> #include <linux/sys_soc.h> #include <linux/task_work.h>
rust/helpers/helpers.c +1 -0
@@ -53,6 +53,7 @@#include "regulator.c" #include "scatterlist.c" #include "security.c" +#include "serdev.c" #include "signal.c" #include "slab.c" #include "spinlock.c"
rust/helpers/serdev.c new file +22 -0
@@ -0,0 +1,22 @@ +// SPDX-License-Identifier: GPL-2.0 + +#include <linux/serdev.h> + +__rust_helper +void rust_helper_serdev_device_driver_unregister(struct serdev_device_driver *sdrv) +{ +serdev_device_driver_unregister (sdrv); +} + +__rust_helper +void rust_helper_serdev_device_put(struct serdev_device *serdev) +{ +serdev_device_put (serdev); +} + +__rust_helper +void rust_helper_serdev_device_set_client_ops(struct serdev_device *serdev, +const struct serdev_device_ops *ops) +{ +serdev_device_set_client_ops (serdev, ops); +}
rust/kernel/lib.rs +2 -0
@@ -140,6 +140,8 @@pub mod scatterlist;pub mod security;pub mod seq_file; +#[cfg( CONFIG_SERIAL_DEV_BUS )] +pub mod serdev;pub mod sizes;pub mod slice;#[cfg( CONFIG_SOC_BUS )]
rust/kernel/serdev.rs new file +533 -0
533 lines not on this page · raw message
Signature · 1 line
2.52.0
Markus Probst
maintainerPATCH v2 4/4 samples: rust: add Rust serial device bus sample device driver
In reply to Markus ProbstAdd a sample Rust serial device bus device driver illustrating the usage of the serial device bus abstractions.
This drivers probes through either a match of device / driver name or a match within the OF ID table.
--- samples/rust/Kconfig | 11 +++++ samples/rust/Makefile | 1 + samples/rust/rust_driver_serdev.rs | 86 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 98 insertions(+)
samples/rust/Kconfig +11 -0
@@ -161,6 +161,17 @@ config SAMPLE_RUST_DRIVER_AUXILIARY If unsure, say N. +config SAMPLE_RUST_DRIVER_SERDEV + tristate "Serial Device Bus Device Driver" + depends on SERIAL_DEV_BUS + help + This option builds the Rust serial device bus driver sample. + + To compile this as a module, choose M here: + the module will be called rust_driver_serdev. + + If unsure, say N. + config SAMPLE_RUST_SOC tristate "SoC Driver" select SOC_BUS
samples/rust/Makefile +1 -0
@@ -14,6 +14,7 @@ obj-$(CONFIG_SAMPLE_RUST_DRIVER_PLATFORM) += rust_driver_platform.o obj-$(CONFIG_SAMPLE_RUST_DRIVER_USB) += rust_driver_usb.o obj-$(CONFIG_SAMPLE_RUST_DRIVER_FAUX) += rust_driver_faux.o obj-$(CONFIG_SAMPLE_RUST_DRIVER_AUXILIARY) += rust_driver_auxiliary.o +obj-$(CONFIG_SAMPLE_RUST_DRIVER_SERDEV) += rust_driver_serdev.o obj-$(CONFIG_SAMPLE_RUST_CONFIGFS) += rust_configfs.o obj-$(CONFIG_SAMPLE_RUST_SOC) += rust_soc.o
samples/rust/rust_driver_serdev.rs new file +86 -0
86 lines not on this page · raw message
Signature · 1 line
2.52.0
Re: [PATCH v2 2/4] serdev: add private data to serdev_device
In reply to Markus ProbstHi--
Quoted 21 lines · Markus Probst
Add private data to
struct serdev_device, as it is required by the rust abstraction added in the following commit
(rust: add basic serial device bus abstractions).Signed-off-by Markus Probst <[email protected]>--- include/linux/serdev.h | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-)include/linux/serdev.h +0
-4@@ -33,12 +33,13 @@ struct serdev_device_ops {/** * struct serdev_device - Basic representation of an serdev device -* @dev: Driver model representation of the device. -* @nr: Device number on serdev bus. -* @ctrl: serdev controller managing this device. -* @ops: Device operations.
include/linux/serdev.h struct serdev_device_ops { · line 43
Quoted 10 lines
include/linux/serdev.h +7
-2-* @write_comp Completion used by serdev_device_write() internally -* @write_lock Lock to serialize access when writing data +* @dev: Driver model representation of the device. +* @nr: Device number on serdev bus. +* @ctrl: serdev controller managing this device. +* @ops: Device operations. +* @write_comp Completion used by serdev_device_write() internally +* @write_lock Lock to serialize access when writing data +* @private_data Private data for the device driver. */
I don't quite get why each changed line has an extra tab added to it. ? Also, struct member names in kernel-doc should with a colon (':'), e.g.,
* @private_data: Private data for the device driver.
Please correct that and the 2 lines above it also. And maybe test it to check for warnings.
include/linux/serdev.h struct serdev_device { · line 54
Quoted 11 lines
include/linux/serdev.h +1
-0struct serdev_device {struct device dev;@@ -47,6 +48,7 @@ struct serdev_device {const struct serdev_device_ops *ops;struct completion write_comp;struct mutex write_lock; +void *private_data; };static inline struct serdev_device *to_serdev_device (struct device *d)
thanks.
Signature · 1 line
~Randy
Markus Probst
maintainerRe: [PATCH v2 2/4] serdev: add private data to serdev_device
Quoted 28 lines · Randy Dunlap
Hi--
Quoted 25 lines · Markus Probst
Add private data to
struct serdev_device, as it is required by the rust abstraction added in the following commit
(rust: add basic serial device bus abstractions).Signed-off-by Markus Probst <[email protected]>--- include/linux/serdev.h | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-)include/linux/serdev.h +2
-6@@ -33,12 +33,13 @@ struct serdev_device_ops {/** * struct serdev_device - Basic representation of an serdev device -* @dev: Driver model representation of the device. -* @nr: Device number on serdev bus. -* @ctrl: serdev controller managing this device. -* @ops: Device operations. -* @write_comp Completion used by serdev_device_write() internally -* @write_lock Lock to serialize access when writing data +* @dev: Driver model representation of the device. +* @nr: Device number on serdev bus.
Quoted 8 lines
include/linux/serdev.h struct serdev_device_ops { · line 43
Quoted 6 lines
include/linux/serdev.h +5
-0+* @ctrl: serdev controller managing this device. +* @ops: Device operations. +* @write_comp Completion used by serdev_device_write() internally +* @write_lock Lock to serialize access when writing data +* @private_data Private data for the device driver. */ I don't quite get why each changed line has an extra tab added to it. ?
So all the fields have the same indentation.
Otherwise the description of private_data, because of its length, would be 1 character more to the right.
Quoted 6 lines
Also, struct member names in kernel-doc should with a colon (':'), e.g.,
* @private_data: Private data for the device driver.
Please correct that and the 2 lines above it also. And maybe test it to check for warnings.
I can do that.
Quoted 10 lines
Quoted 10 lines
include/linux/serdev.h +1
-0struct serdev_device {struct device dev;@@ -47,6 +48,7 @@ struct serdev_device {const struct serdev_device_ops *ops;struct completion write_comp;struct mutex write_lock; +void *private_data; };
Quoted 4 lines
include/linux/serdev.h struct serdev_device { · line 54
Quoted 2 lines
include/linux/serdev.h +0
-0static inline struct serdev_device *to_serdev_device (struct device *d)thanks.
Thanks
- Markus Probst
Danilo Krummrich
maintainerRe: [PATCH v2 2/4] serdev: add private data to serdev_device
In reply to Markus ProbstQuoted 20 lines · Markus Probst
Add private data to
struct serdev_device, as it is required by the rust abstraction added in the following commit
(rust: add basic serial device bus abstractions).Signed-off-by Markus Probst <[email protected]>--- include/linux/serdev.h | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-)include/linux/serdev.h +0
-3@@ -33,12 +33,13 @@ struct serdev_device_ops {/** * struct serdev_device - Basic representation of an serdev device -* @dev: Driver model representation of the device. -* @nr: Device number on serdev bus. -* @ctrl: serdev controller managing this device.
include/linux/serdev.h struct serdev_device_ops { · line 42
Quoted 10 lines
include/linux/serdev.h +7
-3-* @ops: Device operations. -* @write_comp Completion used by serdev_device_write() internally -* @write_lock Lock to serialize access when writing data +* @dev: Driver model representation of the device. +* @nr: Device number on serdev bus. +* @ctrl: serdev controller managing this device. +* @ops: Device operations. +* @write_comp Completion used by serdev_device_write() internally +* @write_lock Lock to serialize access when writing data +* @private_data Private data for the device driver.
I think this is a bit misleading, as the driver's device private data is stored in the embedded struct device. This seems to be more about having a place to store private data of the Rust abstraction.
So, you may want to name this something along the lines of rust_private_data. Additionally, you should make it very clear that this field must not be used by drivers directly (i.e. C drivers could easily be tempted to abuse this).
Quoted 14 lines
include/linux/serdev.h +1
-0*/ struct serdev_device {struct device dev;@@ -47,6 +48,7 @@ struct serdev_device {const struct serdev_device_ops *ops;struct completion write_comp;struct mutex write_lock; +void *private_data; };static inline struct serdev_device *to_serdev_device (struct device *d)Signature · 2 lines
-- 2.52.0
Markus Probst
maintainerQuoted 278 lines · Markus Probst
Implement the basic serial device bus abstractions required to write a serial device bus device driver with or without the need for initial device data. This includes the following data structures:
The
serdev::Drivertrait represents the interface to the driver.The
serdev::Deviceabstraction represents astruct serdev_device.In order to provide the Serdev specific parts to a generic
driver::Registrationthedriver::RegistrationOpstrait is implemented byserdev::Adapter.Signed-off-by Markus Probst <[email protected]>--- rust/bindings/bindings_helper.h | 1 + rust/helpers/helpers.c | 1 + rust/helpers/serdev.c | 22 ++ rust/kernel/lib.rs | 2 + rust/kernel/serdev.rs | 533 ++++++++++++++++++++++++++++++++++++++++ 5 files changed, 559 insertions(+)rust/bindings/bindings_helper.h +1
-0@@ -80,6 +80,7 @@#include <linux/regulator/consumer.h> #include <linux/sched.h> #include <linux/security.h> +#include <linux/serdev.h> #include <linux/slab.h> #include <linux/sys_soc.h> #include <linux/task_work.h> rust/helpers/helpers.c +1
-0@@ -53,6 +53,7 @@#include "regulator.c" #include "scatterlist.c" #include "security.c" +#include "serdev.c" #include "signal.c" #include "slab.c" #include "spinlock.c" rust/helpers/serdev.c new file +22
-0@@ -0,0 +1,22 @@ +// SPDX-License-Identifier: GPL-2.0 + +#include <linux/serdev.h> + +__rust_helper +void rust_helper_serdev_device_driver_unregister(struct serdev_device_driver *sdrv) +{ +serdev_device_driver_unregister (sdrv); +} + +__rust_helper +void rust_helper_serdev_device_put(struct serdev_device *serdev) +{ +serdev_device_put (serdev); +} + +__rust_helper +void rust_helper_serdev_device_set_client_ops(struct serdev_device *serdev, +const struct serdev_device_ops *ops) +{ +serdev_device_set_client_ops (serdev, ops); +}rust/kernel/lib.rs +2
-0@@ -140,6 +140,8 @@pub mod scatterlist;pub mod security;pub mod seq_file; +#[cfg( CONFIG_SERIAL_DEV_BUS )] +pub mod serdev;pub mod sizes;pub mod slice;#[cfg( CONFIG_SOC_BUS )] rust/kernel/serdev.rs new file +186
-0@@ -0,0 +1,533 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Abstractions for the serial device bus. +//! +//! C header: [`include/linux/serdev.h`](srctree/include/linux/serdev.h) + +use crate ::{ + acpi, + device, + devres, + driver, + error::{from_result, to_result,VTABLE_DEFAULT_ERROR }, + of, + prelude::*, + sync::Completion , + time::{msecs_to_jiffies,Jiffies ,Msecs }, + types::{AlwaysRefCounted ,ForeignOwnable ,Opaque },// +}; + +use core::{ + cell::UnsafeCell , + marker::PhantomData , + mem::offset_of, + num::NonZero , + ptr::NonNull ,// +}; + +/// Parity bit to use with a serial device. +#[repr( u32 )] +pub enum Parity { +/// No parity bit. +None = bindings::serdev_parity_SERDEV_PARITY_NONE, +/// Even partiy. +Even = bindings::serdev_parity_SERDEV_PARITY_EVEN, +/// Odd parity. +Odd = bindings::serdev_parity_SERDEV_PARITY_ODD, +} + +/// Timeout in Jiffies. +pub enum Timeout { +/// Wait for a specific amount of [`Jiffies`]. +Jiffies (NonZero <Jiffies >), +/// Wait for a specific amount of [`Msecs`]. +Milliseconds (NonZero <Msecs >), +/// Wait as long as possible. +/// +/// This is equivalent to [`kernel::task::MAX_SCHEDULE_TIMEOUT`]. +Max , +} + +impl Timeout { +fn into_jiffies (self) ->isize { +match self { +Self ::Jiffies (value) => value.get ().try_into ().unwrap_or_default (), +Self ::Milliseconds (value) => { +msecs_to_jiffies (value.get ()).try_into ().unwrap_or_default () + } +Self ::Max =>0 , + } + } +} + +/// An adapter for the registration of serial device bus device drivers. +pub struct Adapter <T :Driver >(T ); + +// SAFETY: +// - `bindings::serdev_device_driver` is a C type declared as `repr(C)`. +// - `Drvdata<T>` is the type of the driver's device private data. +// - `struct serdev_device_driver` embeds a `struct device_driver`. +// - `DEVICE_DRIVER_OFFSET` is the correct byte offset to the embedded `struct device_driver`. +unsafe impl <T :Driver + 'static> driver::DriverLayout for Adapter <T > { +type DriverType = bindings::serdev_device_driver ; +type DriverData =T ; +const DEVICE_DRIVER_OFFSET :usize = core::mem::offset_of!(Self ::DriverType , driver); +} + +// SAFETY: A call to `unregister` for a given instance of `DriverType` is guaranteed to be valid if +// a preceding call to `register` has been successful. +unsafe impl <T :Driver + 'static> driver::RegistrationOps for Adapter <T > { +unsafe fn register ( + sdrv: &Opaque <Self ::DriverType >, + name: &'staticCStr , + module: &'staticThisModule , + ) ->Result { +let of_table =match T ::OF_ID_TABLE { +Some (table) => table.as_ptr (), +None => core::ptr::null (), + }; + +let acpi_table =match T ::ACPI_ID_TABLE { +Some (table) => table.as_ptr (), +None => core::ptr::null (), + }; + +// SAFETY: It's safe to set the fields of `struct serdev_device_driver` on initialization. +unsafe { + (*sdrv.get ()).driver.name = name.as_char_ptr (); + (*sdrv.get ()).probe =Some (Self ::probe_callback); + (*sdrv.get ()).remove =Some (Self ::remove_callback); + (*sdrv.get ()).driver.of_match_table = of_table; + (*sdrv.get ()).driver.acpi_match_table = acpi_table; + } + +// SAFETY: `sdrv` is guaranteed to be a valid `DriverType`. +to_result (unsafe { bindings::__serdev_device_driver_register (sdrv.get (), module.0 ) }) + } + +unsafe fn unregister (sdrv: &Opaque <Self ::DriverType >) { +// SAFETY: `sdrv` is guaranteed to be a valid `DriverType`. +unsafe { bindings::serdev_device_driver_unregister (sdrv.get ()) }; + } +} + +#[pin_data] +struct PrivateData { +#[pin] + probe_complete:Completion , + error:UnsafeCell <bool >, +} + +impl <T :Driver + 'static>Adapter <T > { +const OPS : &'static bindings::serdev_device_ops = &bindings::serdev_device_ops { + receive_buf:if T ::HAS_RECEIVE { +Some (Self ::receive_buf_callback) + }else { +None + }, + write_wakeup:Some (bindings::serdev_device_write_wakeup), + }; + +extern "C" fn probe_callback (sdev: *mut bindings::serdev_device ) -> kernel::ffi::c_int { +// SAFETY: The serial device bus only ever calls the probe callback with a valid pointer to +// a `struct serdev_device`. +// +// INVARIANT: `sdev` is valid for the duration of `probe_callback()`. +let sdev =unsafe { &*sdev.cast ::<Device <device::CoreInternal >>() }; +let id_info = <Self as driver::Adapter >::id_info (sdev.as_ref ()); + +from_result (|| { +let private_data = devres::register ( + sdev.as_ref (), +try_pin_init! (PrivateData { + probe_complete <-Completion ::new (), + error:false .into (), + }), +GFP_KERNEL , + )?; + +// SAFETY: `sdev.as_raw()` is guaranteed to be a valid pointer to `serdev_device`. +unsafe { + (*sdev.as_raw ()).private_data = + (&raw const *private_data).cast ::<c_void >().cast_mut () + }; + +// SAFETY: `sdev.as_raw()` is guaranteed to be a valid pointer to `serdev_device`. +unsafe { bindings::serdev_device_set_client_ops (sdev.as_raw (),Self ::OPS ) }; + +// SAFETY: The serial device bus only ever calls the probe callback with a valid pointer +// to a `serdev_device`. +to_result (unsafe { + bindings::devm_serdev_device_open (sdev.as_ref ().as_raw (), sdev.as_raw ()) + })?; + +let data =T ::probe (sdev, id_info); +let result = sdev.as_ref ().set_drvdata (data); + +// SAFETY: We have exclusive access to `private_data.error`. +unsafe { *private_data.error.get () = result.is_err () }; + + private_data.probe_complete.complete_all (); + + result.map (|()|0 ) + }) + } + +extern "C" fn remove_callback (sdev: *mut bindings::serdev_device ) { +// SAFETY: The serial device bus only ever calls the remove callback with a valid pointer +// to a `struct serdev_device`. +// +// INVARIANT: `sdev` is valid for the duration of `remove_callback()`. +let sdev =unsafe { &*sdev.cast ::<Device <device::CoreInternal >>() }; + +// SAFETY: `remove_callback` is only ever called after a successful call to +// `probe_callback`, hence it's guaranteed that `Device::set_drvdata()` has been called +// and stored a `Pin<KBox<T>>`. +let data =unsafe { sdev.as_ref ().drvdata_borrow ::<T >() };
rust/kernel/serdev.rs line 196
Quoted 10 lines
rust/kernel/serdev.rs new file +10
-0+ +T ::unbind (sdev, data); + +// SAFETY: +// - `sdev.as_raw()` is guaranteed to be a pointer to a valid `serdev_device`. +// - `remove_callback` is only ever called after a successful call to +// `probe_callback`, hence it's guaranteed that `private_data` is a valid pointer to +// `PrivateData` and is stored in a `Pin<KBox<PrivateData>>`. +// - `private_data` will not be accessed after this function. +drop (unsafe { <Pin <KBox <PrivateData >>>::from_foreign ((*sdev.as_raw ()).private_data) });
It seems I forgot to remove this drop statement. Please ignore it.
Thanks
- Markus Probst
Quoted 337 lines
rust/kernel/serdev.rs new file +337
-0+ } + +extern "C" fn receive_buf_callback ( + sdev: *mut bindings::serdev_device , + buf: *const u8 , + length:usize , + ) ->usize { +// SAFETY: The serial device bus only ever calls the receive buf callback with a valid +// pointer to a `struct serdev_device`. +// +// INVARIANT: `sdev` is valid for the duration of `receive_buf_callback()`. +let sdev =unsafe { &*sdev.cast ::<Device <device::CoreInternal >>() }; + +// SAFETY: `receive_buf_callback` is only ever called after a successful call to +// `probe_callback`, hence it's guaranteed that `Device::set_drvdata()` has been called +// and stored a `Pin<KBox<T>>`. +let data =unsafe { sdev.as_ref ().drvdata_borrow ::<T >() }; + +// SAFETY: +// - The serial device bus only ever calls the receive buf callback with a valid pointer to +// a `struct serdev_device`. +// - `receive_buf_callback` is only ever called after a successful call to +// `probe_callback`, hence it's guaranteed that `sdev.private_data` is a pointer +// to a valid `PrivateData`. +let private_data =unsafe { &*(*sdev.as_raw ()).private_data.cast ::<PrivateData >() }; + + private_data.probe_complete.complete_all (); + +// SAFETY: No one has exclusive access to `private_data.error`. +if unsafe { *private_data.error.get () } { +return length; + } + +// SAFETY: `buf` is guaranteed to be non-null and has the size of `length`. +let buf =unsafe { core::slice::from_raw_parts (buf, length) }; + +T ::receive (sdev, data, buf) + } +} + +impl <T :Driver + 'static> driver::Adapter for Adapter <T > { +type IdInfo =T ::IdInfo ; + +fn of_id_table () ->Option <of::IdTable <Self ::IdInfo >> { +T ::OF_ID_TABLE + } + +fn acpi_id_table () ->Option <acpi::IdTable <Self ::IdInfo >> { +T ::ACPI_ID_TABLE + } +} + +/// Declares a kernel module that exposes a single serial device bus device driver. +/// +/// # Examples +/// +/// ```ignore +/// kernel::module_serdev_device_driver! { +/// type: MyDriver, +/// name: "Module name", +/// authors: ["Author name"], +/// description: "Description", +/// license: "GPL v2", +/// } +/// ``` +#[macro_export] +macro_rules! module_serdev_device_driver { + ($($f:tt)*) => { + $crate::module_driver!(<T >, $crate ::serdev::Adapter <T >, { $($f)* }); + }; +} + +/// The serial device bus device driver trait. +/// +/// Drivers must implement this trait in order to get a serial device bus device driver registered. +/// +/// # Examples +/// +///``` +/// # use kernel::{ +/// acpi, +/// bindings, +/// device::{ +/// Bound, +/// Core, // +/// }, +/// of, +/// serdev, // +/// }; +/// +/// struct MyDriver; +/// +/// kernel::of_device_table!( +/// OF_TABLE, +/// MODULE_OF_TABLE, +/// <MyDriver as serdev::Driver>::IdInfo, +/// [ +/// (of::DeviceId::new(c"test,device"), ()) +/// ] +/// ); +/// +/// kernel::acpi_device_table!( +/// ACPI_TABLE, +/// MODULE_ACPI_TABLE, +/// <MyDriver as serdev::Driver>::IdInfo, +/// [ +/// (acpi::DeviceId::new(c"LNUXBEEF"), ()) +/// ] +/// ); +/// +/// #[vtable] +/// impl serdev::Driver for MyDriver { +/// type IdInfo = (); +/// const OF_ID_TABLE: Option<of::IdTable<Self::IdInfo>> = Some(&OF_TABLE); +/// const ACPI_ID_TABLE: Option<acpi::IdTable<Self::IdInfo>> = Some(&ACPI_TABLE); +/// +/// fn probe( +/// sdev: &serdev::Device<Core>, +/// _id_info: Option<&Self::IdInfo>, +/// ) -> impl PinInit<Self, Error> { +/// sdev.set_baudrate(115200); +/// sdev.write_all(b"Hello\n", serdev::Timeout::Max)?; +/// Ok(MyDriver) +/// } +/// } +///``` +#[vtable] +pub trait Driver :Send { +/// The type holding driver private data about each device id supported by the driver. +// TODO: Use associated_type_defaults once stabilized: +// +// ``` +// type IdInfo: 'static = (); +// ``` +type IdInfo : 'static; + +/// The table of OF device ids supported by the driver. +const OF_ID_TABLE :Option <of::IdTable <Self ::IdInfo >> =None ; + +/// The table of ACPI device ids supported by the driver. +const ACPI_ID_TABLE :Option <acpi::IdTable <Self ::IdInfo >> =None ; + +/// Serial device bus device driver probe. +/// +/// Called when a new serial device bus device is added or discovered. +/// Implementers should attempt to initialize the device here. +fn probe ( + sdev: &Device <device::Core >, + id_info:Option <&Self ::IdInfo >, + ) ->impl PinInit <Self ,Error >; + +/// Serial device bus device driver unbind. +/// +/// Called when a [`Device`] is unbound from its bound [`Driver`]. Implementing this callback +/// is optional. +/// +/// This callback serves as a place for drivers to perform teardown operations that require a +/// `&Device<Core>` or `&Device<Bound>` reference. For instance. +/// +/// Otherwise, release operations for driver resources should be performed in `Self::drop`. +fn unbind (sdev: &Device <device::Core >, this:Pin <&Self >) { +let _ = (sdev, this); + } + +/// Serial device bus device data receive callback. +/// +/// Called when data got received from device. +/// +/// Returns the number of bytes accepted. +fn receive (sdev: &Device <device::Bound >, this:Pin <&Self >, data: &[u8 ]) ->usize { +let _ = (sdev, this, data); +build_error! (VTABLE_DEFAULT_ERROR ) + } +} + +/// The serial device bus device representation. +/// +/// This structure represents the Rust abstraction for a C `struct serdev_device`. The +/// implementation abstracts the usage of an already existing C `struct serdev_device` within Rust +/// code that we get passed from the C side. +/// +/// # Invariants +/// +/// A [`Device`] instance represents a valid `struct serdev_device` created by the C portion of +/// the kernel. +#[repr(transparent)] +pub struct Device <Ctx : device::DeviceContext = device::Normal >( +Opaque <bindings::serdev_device >, +PhantomData <Ctx >, +); + +impl <Ctx : device::DeviceContext >Device <Ctx > { +fn as_raw (&self) -> *mut bindings::serdev_device { + self.0 .get () + } +} + +impl Device <device::Bound > { +/// Set the baudrate in bits per second. +/// +/// Common baudrates are 115200, 9600, 19200, 57600, 4800. +/// +/// Use [`Device::write_flush`] before calling this if you have written data prior to this call. +pub fn set_baudrate (&self, speed:u32 ) ->Result <(),u32 > { +// SAFETY: `self.as_raw()` is guaranteed to be a pointer to a valid `serdev_device`. +let ret =unsafe { bindings::serdev_device_set_baudrate (self.as_raw (), speed) }; +if ret == speed { +Ok (()) + }else { +Err (ret) + } + } + +/// Set if flow control should be enabled. +/// +/// Use [`Device::write_flush`] before calling this if you have written data prior to this call. +pub fn set_flow_control (&self, enable:bool ) { +// SAFETY: `self.as_raw()` is guaranteed to be a pointer to a valid `serdev_device`. +unsafe { bindings::serdev_device_set_flow_control (self.as_raw (), enable) }; + } + +/// Set parity to use. +/// +/// Use [`Device::write_flush`] before calling this if you have written data prior to this call. +pub fn set_parity (&self, parity:Parity ) ->Result { +// SAFETY: `self.as_raw()` is guaranteed to be a pointer to a valid `serdev_device`. +to_result (unsafe { bindings::serdev_device_set_parity (self.as_raw (), parityas u32 ) }) + } + +/// Write data to the serial device until the controller has accepted all the data or has +/// been interrupted by a timeout or signal. +/// +/// Note that any accepted data has only been buffered by the controller. Use +/// [ Device::wait_until_sent`] to make sure the controller write buffer has actually been +/// emptied. +/// +/// Returns the number of bytes written (less than `data.len()` if interrupted). +/// [`kernel::error::code::ETIMEDOUT`] or [`kernel::error::code::ERESTARTSYS`] if interrupted +/// before any bytes were written. +pub fn write_all (&self, data: &[u8 ], timeout:Timeout ) ->Result <usize > { +// SAFETY: +// - `self.as_raw()` is guaranteed to be a pointer to a valid `serdev_device`. +// - `data.as_ptr()` is guaranteed to be a valid array pointer with the size of +// `data.len()`. +let ret =unsafe { + bindings::serdev_device_write ( + self.as_raw (), + data.as_ptr (), + data.len (), + timeout.into_jiffies (), + ) + }; +// CAST: negative return values are guaranteed to be between `-MAX_ERRNO` and `-1`, +// which always fit into a `i32`. +to_result (retas i32 ).map (|()| ret.unsigned_abs ()) + } + +/// Write data to the serial device. +/// +/// If you want to write until the controller has accepted all the data, use +/// [`Device::write_all`]. +/// +/// Note that any accepted data has only been buffered by the controller. Use +/// [ Device::wait_until_sent`] to make sure the controller write buffer has actually been +/// emptied. +/// +/// Returns the number of bytes written (less than `data.len()` if not enough room in the +/// write buffer). +pub fn write (&self, data: &[u8 ]) ->Result <u32 > { +// SAFETY: +// - `self.as_raw()` is guaranteed to be a pointer to a valid `serdev_device`. +// - `data.as_ptr()` is guaranteed to be a valid array pointer with the size of +// `data.len()`. +let ret = +unsafe { bindings::serdev_device_write_buf (self.as_raw (), data.as_ptr (), data.len ()) }; + +to_result (retas i32 ).map (|()| ret.unsigned_abs ()) + } + +/// Send data to the serial device immediately. +/// +/// Note that this doesn't guarantee that the data has been transmitted. +/// Use [`Device::wait_until_sent`] for this purpose. +pub fn write_flush (&self) { +// SAFETY: `self.as_raw()` is guaranteed to be a pointer to a valid `serdev_device`. +unsafe { bindings::serdev_device_write_flush (self.as_raw ()) }; + } + +/// Wait for the data to be sent. +/// +/// After this function, the write buffer of the controller should be empty. +pub fn wait_until_sent (&self, timeout:Timeout ) { +// SAFETY: `self.as_raw()` is guaranteed to be a pointer to a valid `serdev_device`. +unsafe { bindings::serdev_device_wait_until_sent (self.as_raw (), timeout.into_jiffies ()) }; + } +} + +// SAFETY: `serdev::Device` is a transparent wrapper of `struct serdev_device`. +// The offset is guaranteed to point to a valid device field inside `serdev::Device`. +unsafe impl <Ctx : device::DeviceContext > device::AsBusDevice <Ctx >for Device <Ctx > { +const OFFSET :usize =offset_of! (bindings::serdev_device, dev); +} + +// SAFETY: `Device` is a transparent wrapper of a type that doesn't depend on `Device`'s generic +// argument. +kernel::impl_device_context_deref!(unsafe {Device }); +kernel::impl_device_context_into_aref!(Device ); + +// SAFETY: Instances of `Device` are always reference-counted. +unsafe impl AlwaysRefCounted for Device { +fn inc_ref (&self) { + self.as_ref ().inc_ref (); + } + +unsafe fn dec_ref (obj:NonNull <Self >) { +// SAFETY: The safety requirements guarantee that the refcount is non-zero. +unsafe { bindings::serdev_device_put (obj.cast ().as_ptr ()) } + } +} + +impl <Ctx : device::DeviceContext >AsRef <device::Device <Ctx >>for Device <Ctx > { +fn as_ref (&self) -> &device::Device <Ctx > { +// SAFETY: By the type invariant of `Self`, `self.as_raw()` is a pointer to a valid +// `struct serdev_device`. +let dev =unsafe { &raw mut (*self.as_raw ()).dev }; + +// SAFETY: `dev` points to a valid `struct device`. +unsafe { device::Device ::from_raw (dev) } + } +} + +// SAFETY: A `Device` is always reference-counted and can be released from any thread. +unsafe impl Send for Device {} + +// SAFETY: `Device` can be shared among threads because all methods of `Device` +// (i.e. `Device<Normal>) are thread safe. +unsafe impl Sync for Device {}
Danilo Krummrich
maintainerQuoted 15 lines · Markus Probst
rust/kernel/serdev.rs new file +15
-0+extern "C" fn receive_buf_callback ( + sdev: *mut bindings::serdev_device , + buf: *const u8 , + length:usize , + ) ->usize { +// SAFETY: The serial device bus only ever calls the receive buf callback with a valid +// pointer to a `struct serdev_device`. +// +// INVARIANT: `sdev` is valid for the duration of `receive_buf_callback()`. +let sdev =unsafe { &*sdev.cast ::<Device <device::CoreInternal >>() }; + +// SAFETY: `receive_buf_callback` is only ever called after a successful call to +// `probe_callback`, hence it's guaranteed that `Device::set_drvdata()` has been called +// and stored a `Pin<KBox<T>>`. +let data =unsafe { sdev.as_ref ().drvdata_borrow ::<T >() };
rust/kernel/serdev.rs line 223
Quoted 10 lines
rust/kernel/serdev.rs new file +10
-0+ +// SAFETY: +// - The serial device bus only ever calls the receive buf callback with a valid pointer to +// a `struct serdev_device`. +// - `receive_buf_callback` is only ever called after a successful call to +// `probe_callback`, hence it's guaranteed that `sdev.private_data` is a pointer +// to a valid `PrivateData`. +let private_data =unsafe { &*(*sdev.as_raw ()).private_data.cast ::<PrivateData >() }; + + private_data.probe_complete.complete_all ();
Will do a full review pass later on, but one quick question in advance:
What is this used for? It is completed here and in probe(), but I don't see it ever being used to actually wait.
Quoted 12 lines
rust/kernel/serdev.rs new file +12
-0+ +// SAFETY: No one has exclusive access to `private_data.error`. +if unsafe { *private_data.error.get () } { +return length; + } + +// SAFETY: `buf` is guaranteed to be non-null and has the size of `length`. +let buf =unsafe { core::slice::from_raw_parts (buf, length) }; + +T ::receive (sdev, data, buf) + } +}
Markus Probst
maintainerQuoted 29 lines · Danilo Krummrich
Quoted 15 lines · Markus Probst
rust/kernel/serdev.rs new file +15
-0+extern "C" fn receive_buf_callback ( + sdev: *mut bindings::serdev_device , + buf: *const u8 , + length:usize , + ) ->usize { +// SAFETY: The serial device bus only ever calls the receive buf callback with a valid +// pointer to a `struct serdev_device`. +// +// INVARIANT: `sdev` is valid for the duration of `receive_buf_callback()`. +let sdev =unsafe { &*sdev.cast ::<Device <device::CoreInternal >>() }; + +// SAFETY: `receive_buf_callback` is only ever called after a successful call to +// `probe_callback`, hence it's guaranteed that `Device::set_drvdata()` has been called +// and stored a `Pin<KBox<T>>`. +let data =unsafe { sdev.as_ref ().drvdata_borrow ::<T >() };rust/kernel/serdev.rs line 223
Quoted 10 lines
rust/kernel/serdev.rs new file +10
-0+ +// SAFETY: +// - The serial device bus only ever calls the receive buf callback with a valid pointer to +// a `struct serdev_device`. +// - `receive_buf_callback` is only ever called after a successful call to +// `probe_callback`, hence it's guaranteed that `sdev.private_data` is a pointer +// to a valid `PrivateData`. +let private_data =unsafe { &*(*sdev.as_raw ()).private_data.cast ::<PrivateData >() }; + + private_data.probe_complete.complete_all ();Will do a full review pass later on, but one quick question in advance:
Quoted 2 lines
What is this used for? It is completed here and in
probe(), but I don't see it ever being used to actually wait.
Uh, thats a typo. It is supposed to wait here in receive_buf_callback.
Thanks
- Markus Probst
Quoted 13 lines
Quoted 13 lines
rust/kernel/serdev.rs new file +12
-0+ +// SAFETY: No one has exclusive access to `private_data.error`. +if unsafe { *private_data.error.get () } { +return length; + } + +// SAFETY: `buf` is guaranteed to be non-null and has the size of `length`. +let buf =unsafe { core::slice::from_raw_parts (buf, length) }; + +T ::receive (sdev, data, buf) + } +}