[PATCH v5 4/5] i3c: add i3cdev module to expose i3c dev in /dev
Frank Li
Frank.li at oss.nxp.com
Fri Sep 25 08:38:47 PDT 2026
On Mon, Sep 21, 2026 at 11:06:02PM +0000, Sam Agazaryan wrote:
> From: Vitor Soares <vitor.soares at toradex.com>
>
> Add userspace character device support for I3C transfers via /dev.
>
> The module allows userspace programs to interact directly with I3C
> targets that do not have a kernel driver bound to them, such as devices
> in ROM/bootloader recovery mode (e.g. OCP Secure Firmware Recovery v1.1
> and Caliptra Silicon Root of Trust recovery flows).
>
> Features:
> - Dynamically exposes /dev/bus/i3c/<device> character devices for I3C
> devices when unbound from kernel drivers.
> - Dynamically allocates character device minor numbers using the IDA
> allocator.
> - Implements SDR and HDR transfers via I3C_IOC_XFER ioctl with 64-bit
> aligned UAPI data structures and actual_len read reporting.
> - Supports compat_ptr_ioctl for 32-bit userspace on 64-bit kernels.
> - Uses cdev_device_add/cdev_device_del with device refcounting to ensure
> safe lifecycle management and prevent use-after-free on driver detach.
>
> Signed-off-by: Vitor Soares <vitor.soares at toradex.com>
> Co-developed-by: Oleksandr Shulzhenko <oleksandr.shulzhenko.viktorovych at intel.com>
> Signed-off-by: Oleksandr Shulzhenko <oleksandr.shulzhenko.viktorovych at intel.com>
> Co-developed-by: Sam Agazaryan <samagazaryan at google.com>
> Signed-off-by: Sam Agazaryan <samagazaryan at google.com>
> ---
> MAINTAINERS | 1 +
> drivers/i3c/Kconfig | 11 +
> drivers/i3c/Makefile | 1 +
> drivers/i3c/i3cdev.c | 491 ++++++++++++++++++++++++++++++++
> include/uapi/linux/i3c/i3cdev.h | 57 ++++
> 5 files changed, 561 insertions(+)
> create mode 100644 drivers/i3c/i3cdev.c
> create mode 100644 include/uapi/linux/i3c/i3cdev.h
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 81a9a02c919d..30a5cb12c4f0 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -12364,6 +12364,7 @@ F: Documentation/driver-api/i3c
> F: drivers/i3c/
> F: include/dt-bindings/i3c/
> F: include/linux/i3c/
> +F: include/uapi/linux/i3c/
>
> IBM Operation Panel Input Driver
> M: Eddie James <eajames at linux.ibm.com>
> diff --git a/drivers/i3c/Kconfig b/drivers/i3c/Kconfig
> index 626c54b386d5..166875837ec6 100644
> --- a/drivers/i3c/Kconfig
> +++ b/drivers/i3c/Kconfig
> @@ -20,6 +20,17 @@ menuconfig I3C
> will be called i3c.
>
> if I3C
> +
> +config I3CDEV
> + tristate "I3C device interface"
> + help
> + Say Y here to use i3c-* device files, usually found in the /dev
> + directory on your system. They make it possible to have user-space
> + programs use the I3C devices.
> +
> + This support is also available as a module. If so, the module
> + will be called i3cdev.
> +
> source "drivers/i3c/master/Kconfig"
> endif # I3C
>
> diff --git a/drivers/i3c/Makefile b/drivers/i3c/Makefile
> index 11982efbc6d9..606d422841b2 100644
> --- a/drivers/i3c/Makefile
> +++ b/drivers/i3c/Makefile
> @@ -1,4 +1,5 @@
> # SPDX-License-Identifier: GPL-2.0
> i3c-y := device.o master.o
> obj-$(CONFIG_I3C) += i3c.o
> +obj-$(CONFIG_I3CDEV) += i3cdev.o
> obj-$(CONFIG_I3C) += master/
> diff --git a/drivers/i3c/i3cdev.c b/drivers/i3c/i3cdev.c
> new file mode 100644
> index 000000000000..309ce8181209
> --- /dev/null
> +++ b/drivers/i3c/i3cdev.c
> @@ -0,0 +1,491 @@
> +// SPDX-License-Identifier: GPL-2.0
> +/*
> + * Copyright (c) 2020 Synopsys, Inc. and/or its affiliates.
> + * Copyright (c) 2026 Google LLC
> + *
> + * Author: Vitor Soares <soares at synopsys.com>
> + * Author: Sam Agazaryan <samagazaryan at google.com>
> + */
> +
> +#include <linux/cdev.h>
> +#include <linux/cleanup.h>
> +#include <linux/compat.h>
> +#include <linux/device.h>
> +#include <linux/fs.h>
> +#include <linux/init.h>
> +#include <linux/jiffies.h>
> +#include <linux/kernel.h>
> +#include <linux/list.h>
> +#include <linux/module.h>
> +#include <linux/notifier.h>
> +#include <linux/overflow.h>
> +#include <linux/slab.h>
> +#include <linux/uaccess.h>
> +
> +#include <linux/i3c/i3cdev.h>
> +
> +#include "internals.h"
> +
> +struct i3cdev_data {
> + struct list_head list;
> + struct i3c_device *i3c;
> + struct device dev;
> + struct mutex xfer_lock; /* prevent detach while transferring */
> + struct cdev cdev;
> + int id;
> +};
> +
> +static DEFINE_IDA(i3cdev_ida);
> +static LIST_HEAD(i3cdev_list);
> +static DEFINE_MUTEX(i3cdev_attach_lock);
> +static dev_t i3cdev_number;
> +#define I3C_MINORS (MINORMASK + 1)
> +
> +static void i3cdev_dev_release(struct device *dev)
> +{
> + struct i3cdev_data *i3cdev = container_of(dev, struct i3cdev_data, dev);
> +
> + ida_free(&i3cdev_ida, i3cdev->id);
> + kfree(i3cdev);
> +}
> +
> +static struct i3cdev_data *i3cdev_get_by_i3c(struct i3c_device *i3c)
> +{
> + struct i3cdev_data *i3cdev;
> +
> + list_for_each_entry(i3cdev, &i3cdev_list, list) {
> + if (i3cdev->i3c == i3c)
> + return i3cdev;
> + }
> +
> + return NULL;
> +}
> +
> +static struct i3cdev_data *get_free_i3cdev(struct i3c_device *i3c)
> +{
> + struct i3cdev_data *i3cdev;
> + int id;
> +
> + id = ida_alloc_max(&i3cdev_ida, MINORMASK, GFP_KERNEL);
> + if (id < 0) {
> + pr_err("i3cdev: no minor number available!\n");
> + return ERR_PTR(id);
> + }
> +
> + i3cdev = kzalloc_obj(*i3cdev, GFP_KERNEL);
> + if (!i3cdev) {
> + ida_free(&i3cdev_ida, id);
> + return ERR_PTR(-ENOMEM);
> + }
> +
> + i3cdev->i3c = i3c;
> + i3cdev->id = id;
> + list_add_tail(&i3cdev->list, &i3cdev_list);
> +
> + return i3cdev;
> +}
> +
> +static ssize_t
> +i3cdev_read(struct file *file, char __user *buf, size_t count, loff_t *f_pos)
> +{
> + char *tmp __free(kfree) = NULL;
> + struct i3cdev_data *i3cdev = file->private_data;
> + struct i3c_xfer xfers = {
> + .rnw = true,
> + };
> + struct i3c_device *i3c;
> + int ret;
> +
> + count = min_t(size_t, count, type_max(xfers.len));
> + xfers.len = count;
> +
> + tmp = kzalloc(count, GFP_KERNEL);
cleanup.h prefer declear tmp here
char *tmp __free(kfree) = kzalloc(count, GFP_KERNEL);
check others
> + if (!tmp)
> + return -ENOMEM;
> +
> + guard(mutex)(&i3cdev->xfer_lock);
> + i3c = i3cdev->i3c;
> + if (!i3c || i3c->dev.driver)
> + return -ENODEV;
> +
> + xfers.data.in = tmp;
> +
> + dev_dbg(&i3c->dev, "Reading %zu bytes.\n", count);
> +
> + ret = i3c_device_do_xfers(i3c, &xfers, 1, I3C_SDR);
> + if (ret)
> + return ret;
> +
> + if (copy_to_user(buf, tmp, xfers.actual_len))
> + return -EFAULT;
> +
> + return xfers.actual_len;
> +}
> +
> +static ssize_t
> +i3cdev_write(struct file *file, const char __user *buf, size_t count,
> + loff_t *f_pos)
> +{
> + void *tmp __free(kfree) = NULL;
> + struct i3cdev_data *i3cdev = file->private_data;
> + struct i3c_xfer xfers = {
> + .rnw = false,
> + };
> + struct i3c_device *i3c;
> + int ret;
> +
> + count = min_t(size_t, count, type_max(xfers.len));
> + xfers.len = count;
> +
> + tmp = memdup_user(buf, count);
> + if (IS_ERR(tmp))
> + return PTR_ERR(tmp);
> +
> + guard(mutex)(&i3cdev->xfer_lock);
> + i3c = i3cdev->i3c;
> + if (!i3c || i3c->dev.driver)
> + return -ENODEV;
> +
> + xfers.data.out = tmp;
> +
> + dev_dbg(&i3c->dev, "Writing %zu bytes.\n", count);
> +
> + ret = i3c_device_do_xfers(i3c, &xfers, 1, I3C_SDR);
> + if (ret)
> + return ret;
> +
> + return count;
> +}
> +
> +static int
> +i3cdev_do_xfer(struct i3c_device *dev, struct i3c_ioc_xfer *xfers,
> + struct i3c_ioc_xfer __user *u_xfers, unsigned int nxfers)
> +{
> + struct i3c_xfer *k_xfers __free(kfree) = NULL;
> + enum i3c_xfer_mode mode = xfers[0].mode;
> + u8 **data_ptrs;
> + int i, j, nalloc, ret = 0;
> +
> + /* Since we have nxfers we may allocate k_xfer + *data_ptrs together */
> + k_xfers = kcalloc(nxfers, sizeof(*k_xfers) + sizeof(*data_ptrs),
> + GFP_KERNEL);
> + if (!k_xfers)
> + return -ENOMEM;
> +
> + /* set data_ptrs to be after nxfers * i3c_xfer */
> + data_ptrs = (void *)k_xfers + (nxfers * sizeof(*k_xfers));
> +
> + for (i = 0; i < nxfers; i++) {
> + bool is_read;
> +
> + if (xfers[i].mode != mode) {
> + ret = -EINVAL;
> + break;
> + }
> +
> + if (memchr_inv(xfers[i].pad, 0, sizeof(xfers[i].pad))) {
> + ret = -EINVAL;
> + break;
> + }
> +
> + if (mode == I3C_SDR) {
> + if (xfers[i].rnw != I3C_DEV_DIR_WRITE &&
> + xfers[i].rnw != I3C_DEV_DIR_READ) {
> + ret = -EINVAL;
> + break;
> + }
> + is_read = xfers[i].rnw == I3C_DEV_DIR_READ;
> + } else {
> + is_read = xfers[i].cmd & 0x80;
> + }
> +
> + if (is_read) {
> + data_ptrs[i] = kzalloc(xfers[i].len, GFP_KERNEL);
> + if (!data_ptrs[i]) {
> + ret = -ENOMEM;
> + break;
> + }
> + k_xfers[i].data.in = data_ptrs[i];
> + } else {
> + data_ptrs[i] = memdup_user(u64_to_user_ptr(xfers[i].data),
> + xfers[i].len);
> + if (IS_ERR(data_ptrs[i])) {
> + ret = PTR_ERR(data_ptrs[i]);
> + break;
> + }
> + k_xfers[i].data.out = data_ptrs[i];
> + }
> +
> + k_xfers[i].cmd = xfers[i].cmd;
> + k_xfers[i].len = xfers[i].len;
> + }
> + nalloc = i;
> +
> + if (ret < 0)
> + goto err_free_mem;
> +
> + ret = i3c_device_do_xfers(dev, k_xfers, nxfers, mode);
> + if (ret)
> + goto err_free_mem;
> +
> + for (i = 0; i < nxfers; i++) {
> + bool is_read = (mode == I3C_SDR) ?
> + (xfers[i].rnw == I3C_DEV_DIR_READ) :
> + (xfers[i].cmd & 0x80);
> +
> + if (is_read) {
> + if (copy_to_user(u64_to_user_ptr(xfers[i].data),
> + data_ptrs[i], k_xfers[i].actual_len) ||
> + put_user(k_xfers[i].actual_len,
> + &u_xfers[i].actual_len)) {
> + ret = -EFAULT;
> + break;
> + }
> + }
> + }
> +
> +err_free_mem:
> + for (j = 0; j < nalloc; j++)
> + kfree(data_ptrs[j]);
> + return ret;
> +}
> +
> +static struct i3c_ioc_xfer *
> +i3cdev_get_ioc_xfer(unsigned int cmd, struct i3c_ioc_xfer __user *u_xfers,
> + unsigned int *nxfers)
> +{
> + u32 tmp = _IOC_SIZE(cmd);
> +
> + if ((tmp % sizeof(struct i3c_ioc_xfer)) != 0)
> + return ERR_PTR(-EINVAL);
> +
> + *nxfers = tmp / sizeof(struct i3c_ioc_xfer);
> + if (*nxfers == 0)
> + return ERR_PTR(-EINVAL);
> +
> + return memdup_user(u_xfers, tmp);
> +}
> +
> +static int
> +i3cdev_ioc_xfer(struct i3c_device *i3c, unsigned int cmd,
> + struct i3c_ioc_xfer __user *u_xfers)
> +{
> + struct i3c_ioc_xfer *k_xfers __free(kfree) = NULL;
> + unsigned int nxfers;
> +
> + k_xfers = i3cdev_get_ioc_xfer(cmd, u_xfers, &nxfers);
> + if (IS_ERR(k_xfers))
> + return PTR_ERR(k_xfers);
> +
> + return i3cdev_do_xfer(i3c, k_xfers, u_xfers, nxfers);
> +}
> +
> +static long
> +i3cdev_ioctl(struct file *file, unsigned int cmd, unsigned long arg)
> +{
> + struct i3cdev_data *i3cdev = file->private_data;
> + struct i3c_device *i3c;
> +
> + if (_IOC_TYPE(cmd) != I3C_DEV_IOC_MAGIC)
> + return -ENOTTY;
> +
> + /* Use the xfer_lock to prevent device detach during ioctl call */
> + guard(mutex)(&i3cdev->xfer_lock);
> + i3c = i3cdev->i3c;
> + if (!i3c || i3c->dev.driver)
> + return -ENODEV;
> +
> + dev_dbg(&i3c->dev, "ioctl, cmd=0x%02x, arg=0x%02lx\n", cmd, arg);
> +
> + /* Check command number and direction */
> + if (_IOC_NR(cmd) == _IOC_NR(I3C_IOC_XFER(0)) &&
> + _IOC_DIR(cmd) == (_IOC_READ | _IOC_WRITE))
> + return i3cdev_ioc_xfer(i3c, cmd,
> + (struct i3c_ioc_xfer __user *)arg);
> +
> + return -ENOTTY;
> +}
> +
> +static int i3cdev_open(struct inode *inode, struct file *file)
> +{
> + struct i3cdev_data *i3cdev = container_of(inode->i_cdev,
> + struct i3cdev_data,
> + cdev);
> + file->private_data = i3cdev;
> +
> + return 0;
> +}
> +
> +static int i3cdev_release(struct inode *inode, struct file *file)
> +{
> + file->private_data = NULL;
> +
> + return 0;
> +}
> +
> +static const struct file_operations i3cdev_fops = {
> + .owner = THIS_MODULE,
> + .read = i3cdev_read,
> + .write = i3cdev_write,
> + .unlocked_ioctl = i3cdev_ioctl,
> + .compat_ioctl = compat_ptr_ioctl,
> + .open = i3cdev_open,
> + .release = i3cdev_release,
> +};
> +
> +/* ------------------------------------------------------------------------- */
> +
> +static const struct class i3cdev_class = {
> + .name = "i3cdev",
> +};
> +
> +static int i3cdev_attach(struct device *dev, void *dummy)
> +{
> + struct i3cdev_data *i3cdev;
> + struct i3c_device *i3c;
> + int res;
> +
> + if (dev->type == &i3c_masterdev_type)
> + return 0;
> +
> + i3c = dev_to_i3cdev(dev);
> +
> + guard(mutex)(&i3cdev_attach_lock);
> + if (dev->driver || i3cdev_get_by_i3c(i3c))
> + return 0;
> +
> + /* Get a device */
> + i3cdev = get_free_i3cdev(i3c);
> + if (IS_ERR(i3cdev))
> + return PTR_ERR(i3cdev);
> +
> + mutex_init(&i3cdev->xfer_lock);
> + cdev_init(&i3cdev->cdev, &i3cdev_fops);
> + i3cdev->cdev.owner = THIS_MODULE;
> +
> + device_initialize(&i3cdev->dev);
> + i3cdev->dev.devt = MKDEV(MAJOR(i3cdev_number), i3cdev->id);
> + i3cdev->dev.class = &i3cdev_class;
> + i3cdev->dev.parent = &i3c->dev;
> + i3cdev->dev.release = i3cdev_dev_release;
> +
> + res = dev_set_name(&i3cdev->dev, "bus!i3c!%s", dev_name(&i3c->dev));
> + if (res)
> + goto error_put_dev;
> +
> + res = cdev_device_add(&i3cdev->cdev, &i3cdev->dev);
> + if (res)
> + goto error_put_dev;
> +
> + pr_debug("i3cdev: I3C device [%s] registered as minor %d\n",
> + dev_name(&i3c->dev), i3cdev->id);
> + return 0;
> +
> +error_put_dev:
> + list_del(&i3cdev->list);
> + put_device(&i3cdev->dev);
> + return res;
> +}
> +
> +static int i3cdev_detach(struct device *dev, void *dummy)
> +{
> + struct i3cdev_data *i3cdev;
> + struct i3c_device *i3c;
> +
> + if (dev->type == &i3c_masterdev_type)
> + return 0;
> +
> + i3c = dev_to_i3cdev(dev);
> +
> + guard(mutex)(&i3cdev_attach_lock);
> + i3cdev = i3cdev_get_by_i3c(i3c);
> + if (!i3cdev)
> + return 0;
> +
> + list_del(&i3cdev->list);
> +
> + /* Prevent transfers while cdev removal */
> + scoped_guard(mutex, &i3cdev->xfer_lock)
> + i3cdev->i3c = NULL;
> +
> + cdev_device_del(&i3cdev->cdev, &i3cdev->dev);
> + put_device(&i3cdev->dev);
> +
> + pr_debug("i3cdev: device [%s] unregistered\n", dev_name(&i3c->dev));
> +
> + return 0;
> +}
> +
> +static int i3cdev_notifier_call(struct notifier_block *nb,
> + unsigned long action,
> + void *data)
> +{
> + struct device *dev = data;
> +
> + switch (action) {
> + case BUS_NOTIFY_ADD_DEVICE:
> + case BUS_NOTIFY_UNBOUND_DRIVER:
> + case BUS_NOTIFY_DRIVER_NOT_BOUND:
> + i3cdev_attach(dev, NULL);
> + break;
> + case BUS_NOTIFY_DEL_DEVICE:
> + case BUS_NOTIFY_REMOVED_DEVICE:
> + case BUS_NOTIFY_BIND_DRIVER:
> + i3cdev_detach(dev, NULL);
> + break;
> + }
> +
> + return NOTIFY_OK;
> +}
> +
> +static struct notifier_block i3cdev_notifier = {
> + .notifier_call = i3cdev_notifier_call,
> +};
> +
> +static int __init i3cdev_init(void)
> +{
> + int res;
> +
> + /* Dynamically request unused major number */
> + res = alloc_chrdev_region(&i3cdev_number, 0, I3C_MINORS, "i3c");
> + if (res)
> + goto out;
> +
> + /* Register device class to populate sysfs entries */
> + res = class_register(&i3cdev_class);
> + if (res)
> + goto out_unreg_chrdev;
> +
> + /* Keep track of busses which have devices to add or remove later */
> + res = bus_register_notifier(&i3c_bus_type, &i3cdev_notifier);
> + if (res)
> + goto out_unreg_class;
> +
> + /* Bind to already existing device without driver right away */
> + i3c_for_each_dev(NULL, i3cdev_attach);
> +
> + return 0;
> +
> +out_unreg_class:
> + class_unregister(&i3cdev_class);
> +out_unreg_chrdev:
> + unregister_chrdev_region(i3cdev_number, I3C_MINORS);
> +out:
> + pr_err("%s: Driver Initialisation failed\n", __FILE__);
> + return res;
> +}
> +
> +static void __exit i3cdev_exit(void)
> +{
> + bus_unregister_notifier(&i3c_bus_type, &i3cdev_notifier);
> + i3c_for_each_dev(NULL, i3cdev_detach);
> + class_unregister(&i3cdev_class);
> + unregister_chrdev_region(i3cdev_number, I3C_MINORS);
> +}
> +
> +MODULE_AUTHOR("Vitor Soares <soares at synopsys.com>");
> +MODULE_DESCRIPTION("I3C /dev entries driver");
> +MODULE_LICENSE("GPL");
> +
> +module_init(i3cdev_init);
> +module_exit(i3cdev_exit);
> diff --git a/include/uapi/linux/i3c/i3cdev.h b/include/uapi/linux/i3c/i3cdev.h
> new file mode 100644
> index 000000000000..69e901017378
> --- /dev/null
> +++ b/include/uapi/linux/i3c/i3cdev.h
> @@ -0,0 +1,57 @@
> +/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
> +/*
> + * Copyright (c) 2020 Synopsys, Inc. and/or its affiliates.
> + * Copyright (c) 2026 Google LLC
> + *
> + * Author: Vitor Soares <vitor.soares at synopsys.com>
> + */
> +
> +#ifndef _UAPI_I3C_DEV_H_
> +#define _UAPI_I3C_DEV_H_
> +
> +#include <linux/types.h>
> +#include <linux/ioctl.h>
> +
> +/* IOCTL commands */
> +#define I3C_DEV_IOC_MAGIC 0x07
> +
> +#define I3C_DEV_DIR_WRITE 0
> +#define I3C_DEV_DIR_READ 1
> +
> +#define I3C_XFER_MODE_HDR_DDR 0
> +#define I3C_XFER_MODE_HDR_TSP 1
> +#define I3C_XFER_MODE_HDR_TSL 2
> +#define I3C_XFER_MODE_SDR 31
> +
> +/**
> + * struct i3c_ioc_xfer - I3C ioctl transfer
> + * @data: Holds pointer to userspace buffer with transmit/receive data.
> + * @len: Length of data buffer, in bytes.
> + * @actual_len: Actual length of data transferred on read, in bytes (output).
> + * @rnw: Transfer direction for SDR mode (I3C_DEV_DIR_WRITE or I3C_DEV_DIR_READ).
> + * @cmd: Command byte for HDR mode (0x00-0x7f write, 0x80-0xff read).
> + * @mode: Transfer mode (I3C_XFER_MODE_SDR, I3C_XFER_MODE_HDR_DDR, etc.).
> + * @pad: Reserved for future extensions; must be zeroed.
> + */
> +struct i3c_ioc_xfer {
> + __u64 data;
> + __u16 len;
> + __u16 actual_len;
> + union {
> + __u8 rnw;
> + __u8 cmd;
> + };
> + __u8 mode;
> + __u8 pad[2];
> +};
Can we share the above information include MODE* with i3c system to avoid
duplicate it?
Frank
> +
> +#define __I3C_XFER_SIZE(type) \
> + ((((sizeof(struct i3c_ioc_xfer)) * (type)) < (1 << _IOC_SIZEBITS)) \
> + ? ((sizeof(struct i3c_ioc_xfer)) * (type)) : 0)
> +
> +#define I3C_XFER_SIZE(N) __I3C_XFER_SIZE(N)
> +
> +#define I3C_IOC_XFER(N) \
> + _IOC(_IOC_READ | _IOC_WRITE, I3C_DEV_IOC_MAGIC, 30, I3C_XFER_SIZE(N))
> +
> +#endif
> --
> 2.55.0.1082.g2b9226bbc0-goog
>
More information about the linux-i3c
mailing list