rust: i2c: Add basic I2C driver abstractions

This patch series lays the groundwork for writing Linux I2C drivers in Rust by:

1. Core abstractions
Introduce i2c::I2cClient, i2c::I2cAdapter, i2c::Driver and built on the existing struct i2c_client, struct i2c_adapter and struct i2c_driver, with safe Rust wrappers around probe, transfer, and teardown logic.

2. Manual device creation
Provide an API to register an I2C device at runtime from Rust using I2cBoardInfo and I2cAdapter, including automatic cleanup when the driver unloads.

3. Sample I2C driver (legacy table, OF & ACPI)
Add rust_driver_i2c, a sample that:
- binds to an I2C client via:
- legacy I2C-ID table,
- Open Firmware (device-tree) compatible strings, or
- ACPI IDs.
4. Sample I2C client registration (OF & ACPI)
Add rust_i2c_client, a sample that:
- binds to a platform parent device using OF/ACPI table
- registers new I2C client bound to the parent platform device using i2c::Registration::new()
- destroyes the I2C client device on exit.

Together, these four patches:

- Establish the essential Rust traits and types for I2C drivers.
- Enable driver binding via legacy ID table, device-tree (OF), or ACPI
- Enable manual device creation at runtime.
- Ship a samples showing typical usage

Igor Korotin (4):
rust: i2c: add basic I2C device and driver abstractions
rust: i2c: add manual I2C device creation abstractions
samples: rust: add Rust I2C sample driver
samples: rust: add Rust I2C client registration sample

Changelog
---------
v8:
- Rebase commits on top of [1]
- Applied kernel vertical style [2]
- Replace core::mem::zeroed() with pin_init::zeroed()
- Rename I2cAdapter::get_nr to I2cAdapter::index
- fixed some minor format issues
- Link to v7: [3]

[1] https://git.kernel.org/pub/scm/linux/kernel/git/driver-core/driver-core.git/log/?h=driver-core-next
[2] https://docs.kernel.org/rust/coding-guidelines.html#imports
[3] https://lore.kernel.org/rust-for-linux/[email protected]/

v7:
- Rebase and update i2c::Driver::probe function based on patch series [1].
- use i2c::Driver::unbind instead of drop in i2c::Adapter::remove_callback
- Implement and use i2c::Driver::unbind for I2C SampleDriver instead of Drop.
- i2c::Registration::new requires a parent device to which a new I2C client will be bound.
- i2c::Registration::new returns impl PinInit<Devres<Self>, Error>
- The existing rust_driver_i2c sample has been split into two:
rust_driver_i2c, which demonstrates the implementation of an I2C driver, and rust_i2c_client, which demonstrates registering a new I2C client bound to a parent platform device.
- Link to v6: [2]

[1] https://lore.kernel.org/all/[email protected]/
[2] https://lore.kernel.org/rust-for-linux/[email protected]/

v6:
- Add implementation of unbind for i2c::Driver trait;
- Add argument Pin<&Self> to i2c::Driver::shutdown method;
- Adjust usage of i2c::Driver::shutdown in
i2c::Adapter::shutdown_callback in i2c::Driver trait code
example and in rust_driver_i2c code;
- Remove dummy AsRef implementation for I2cAdapter. Adjust code
in rust_driver_i2c;
- Add i2c::I2cAdapter::get_nr method that returns I2cAdapter index;
- Optimize unsafe sections in inc_ref/dec_ref in AlwaysRefCounted
for I2cAdapter implementation;
- Remove unnecessary Drop implementation for I2cAdapter, because
I2cAdapter is always a reference;
- Remove unnecessary type definition Ops<T> in rust_driver_i2c
- Simplify call of i2c::I2cAdapter::get in try_pin_init! macro
for rust_driver_i2c
- Link to v5: https://lore.kernel.org/rust-for-linux/[email protected]/
v5:
- Rename missed pdev variables to idev (thanks to Daniel).
- Import crate::device_id::RawDeviceIdIndex and
crate::types::AlwaysRefCounted in i2c.rs.
- Switch dev_dbg to dev_info in the sample I2C driver messages.
- Make I2cAdapter::get() return ARef<I2cAdapter> instead of
&I2cAdapter.
- Remove TryFrom<device::Device<Ctx>> for I2cAdapter<Ctx> (unused;
to be reintroduced in a later I2C series).
- Remove AsRef<device::Device<Ctx>> for I2cAdapter<Ctx> (unused;
to be reintroduced in a later I2C series).
- Add AsRef<I2cAdapter> for I2cAdapter<Ctx>.
- Use i2c_get/put_adapter instead of get/put_device for
AlwaysRefCounted<I2cAdapter>.
- Update safety comment for unsafe impl Sync for Registration {}.
- Tweak comment for I2cBoardInfo::new.
- Adjust build-time assertion message in Adapter::register.
- Link to v4: https://lore.kernel.org/rust-for-linux/[email protected]/
v4:
- Renamed i2c::I2cAdapterRef to i2c::I2cAdapter.
- Renamed i2c::Device to i2c::I2cClient for consistency with
i2c::I2cAdapter and to avoid confusion with i2c::Adapter
- Reworked i2c::I2cAdapter to be an Opaque around i2c_adapter struct
- Implemented AlwaysRefCounted trait for i2c::I2cAdapter.
- Fixed numerous comment mistakes and typos all over the code, thanks
to Danilo and Daniel
- Got rid of all unwrap() use-cases in i2c.rs and rust_driver_i2c.rs.
This covers 0-day kernel panic <[email protected]>
- Removed unnecessary casts.
- Replaced all addr_of_mut! macros to &raw mut.
- In i2c::Adapter::register method build assert if all ID tables are
None.
- Renamed all pdrv and pdev instances to idrv and idev respectivly
- Implemented an ealry return in i2c::Adapter::i2c_id_info
- Added all missing Safety comments.
- Removed unsafe impl<Ctx: device::DeviceContext> crate::types::AlwaysRefCounted for Device<Ctx> implementation which came to v3 from v2 by mistake.
- Added more details regarding i2c-stub driver usage in rust_driver_i2c
comment.
- Changed i2c::I2cAdapter::get return type from Option<Self> to
Result<&'static Self>.
- Added Daniel Almeida as a reviewer to the "I2C Subsystem [RUST]" entry
in MAINTAINERS, per his offer.
- Link to v3: https://lore.kernel.org/rust-for-linux/[email protected]/
v3:
- removed unnecessary i2c_get_clientdata and i2c_set_clientdata rust
helpers. Using generic accessors implemented in [1] instead.
- Reimplemented i2c::DeviceId based on changes in [2].
- Using from_result in i2c::Adapter::probe_callback
- Using explicit drop() for i2c client private data in
i2c::Adapter::remove_callback
- replaced device::Device::as_ref() with device::Device::from_raw in i2c::Device::as_ref(). It is renamed in device::Device.
- Build Rust I2C only if I2C is built-in
- Reimplement overcomplicated trait i2c::DeviceOwned the same way it is
implemented in auxiliary [3].
- Merge rust_device_i2c and rust_driver_i2c samples. Resulting
rust_driver_i2c creates pined i2c_client using i2c::Registration::new
and probes newly created i2c_client.
- Created a new entry in MAINTAINERS file containing i2c.rs and
rust_driver_i2c.rs in it.
- Link to v2: [4]

[1] https://lore.kernel.org/lkml/[email protected]/
[2] https://lore.kernel.org/rust-for-linux/[email protected]/
[3] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/rust/kernel/auxiliary.rs?h=v6.16-rc4#n299
[4] https://lore.kernel.org/rust-for-linux/[email protected]/

v2:
- Merged separated ACPI support patches since ACPI-table support is
merged into driver-core-next.
- Added I2cAdapterRef and I2cBoardInfo abstractions
- Added DeviceState generic parameter which is used for i2c::Device
as a sign if the device is created manually
- Added DeviceOwned abstraction which is a safe reference to a
manually created i2c::Device<Ctx, state::Owned>.
- Added Rust manual I2C device creation sample
- Link to v1: https://lore.kernel.org/rust-for-linux/[email protected]/

 MAINTAINERS                     |   9 +
 rust/bindings/bindings_helper.h |   1 +
 rust/kernel/i2c.rs              | 589 ++++++++++++++++++++++++++++++++
 rust/kernel/lib.rs              |   2 +
 samples/rust/Kconfig            |  23 ++
 samples/rust/Makefile           |   2 +
 samples/rust/rust_driver_i2c.rs |  74 ++++
 samples/rust/rust_i2c_client.rs | 157 +++++++++
 8 files changed, 857 insertions(+)
 create mode 100644 rust/kernel/i2c.rs
 create mode 100644 samples/rust/rust_driver_i2c.rs
 create mode 100644 samples/rust/rust_i2c_client.rs

base-commit: ededb7bcdfdbcfbb7af93e3a543165a9553e1683

2.43.0