I3C device driver API¶

enum i3c_error_code¶: I3C error codes

Constants

I3C_ERROR_UNKNOWN: unknown error, usually means the error is not I3C related
I3C_ERROR_M0: M0 error
I3C_ERROR_M1: M1 error
I3C_ERROR_M2: M2 error

Description

These are the standard error codes as defined by the I3C specification. When -EIO is returned by the i3c_device_do_priv_xfers() or i3c_device_send_hdr_cmds() one can check the error code in struct_i3c_priv_xfer.err or struct i3c_hdr_cmd.err to get a better idea of what went wrong.

enum i3c_hdr_mode¶: HDR mode ids

Constants

I3C_HDR_DDR: DDR mode
I3C_HDR_TSP: TSP mode
I3C_HDR_TSL: TSL mode

struct i3c_priv_xfer¶: I3C SDR private transfer

Definition:

struct i3c_priv_xfer {
    u8 rnw;
    u16 len;
    u16 actual_len;
    union {
        void *in;
        const void *out;
    } data;
    enum i3c_error_code err;
};

Members

rnw: encodes the transfer direction. true for a read, false for a write
len: transfer length in bytes of the transfer
actual_len: actual length in bytes are transferred by the controller
data: input/output buffer
data.in: input buffer. Must point to a DMA-able buffer
data.out: output buffer. Must point to a DMA-able buffer
err: I3C error code

enum i3c_dcr¶: I3C DCR values

Constants

I3C_DCR_GENERIC_DEVICE: generic I3C device

struct i3c_device_info¶: I3C device information

Definition:

struct i3c_device_info {
    u64 pid;
    u8 bcr;
    u8 dcr;
    u8 static_addr;
    u8 dyn_addr;
    u8 hdr_cap;
    u8 max_read_ds;
    u8 max_write_ds;
    u8 max_ibi_len;
    u32 max_read_turnaround;
    u16 max_read_len;
    u16 max_write_len;
};

Members

pid: Provisioned ID
bcr: Bus Characteristic Register
dcr: Device Characteristic Register
static_addr: static/I2C address
dyn_addr: dynamic address
hdr_cap: supported HDR modes
max_read_ds: max read speed information
max_write_ds: max write speed information
max_ibi_len: max IBI payload length
max_read_turnaround: max read turn-around time in micro-seconds
max_read_len: max private SDR read length in bytes
max_write_len: max private SDR write length in bytes

Description

These are all basic information that should be advertised by an I3C device. Some of them are optional depending on the device type and device capabilities. For each I3C slave attached to a master with i3c_master_add_i3c_dev_locked(), the core will send the relevant CCC command to retrieve these data.

struct i3c_driver¶: I3C device driver

Definition:

struct i3c_driver {
    struct device_driver driver;
    int (*probe)(struct i3c_device *dev);
    void (*remove)(struct i3c_device *dev);
    const struct i3c_device_id *id_table;
};

Members

driver: inherit from device_driver
probe: I3C device probe method
remove: I3C device remove method
id_table: I3C device match table. Will be used by the framework to decide which device to bind to this driver

dev_to_i3cdev¶

dev_to_i3cdev (__dev)

Returns the I3C device containing dev

Parameters

__dev: device object

Return

a pointer to an I3C device object.

module_i3c_driver¶

module_i3c_driver (__drv)

Register a module providing an I3C driver

Parameters

__drv: the I3C driver to register

Description

Provide generic init/exit functions that simply register/unregister an I3C driver. Should be used by any driver that does not require extra init/cleanup steps.

int i3c_i2c_driver_register(struct i3c_driver *i3cdrv, struct i2c_driver *i2cdrv)¶: Register an i2c and an i3c driver

Parameters

struct i3c_driver *i3cdrv: the I3C driver to register
struct i2c_driver *i2cdrv: the I2C driver to register

Description

This function registers both i2cdev and i3cdev, and fails if one of these registrations fails. This is mainly useful for devices that support both I2C and I3C modes. Note that when CONFIG_I3C is not enabled, this function only registers the I2C driver.

Return

0 if both registrations succeeds, a negative error code otherwise.

void i3c_i2c_driver_unregister(struct i3c_driver *i3cdrv, struct i2c_driver *i2cdrv)¶: Unregister an i2c and an i3c driver

Parameters

struct i3c_driver *i3cdrv: the I3C driver to register
struct i2c_driver *i2cdrv: the I2C driver to register

Description

This function unregisters both i3cdrv and i2cdrv. Note that when CONFIG_I3C is not enabled, this function only unregisters the i2cdrv.

module_i3c_i2c_driver¶

module_i3c_i2c_driver (__i3cdrv, __i2cdrv)

Register a module providing an I3C and an I2C driver

Parameters

__i3cdrv: the I3C driver to register
__i2cdrv: the I3C driver to register

Description

Provide generic init/exit functions that simply register/unregister an I3C and an I2C driver. This macro can be used even if CONFIG_I3C is disabled, in this case, only the I2C driver will be registered. Should be used by any driver that does not require extra init/cleanup steps.

struct i3c_ibi_setup¶: IBI setup object

Definition:

struct i3c_ibi_setup {
    unsigned int max_payload_len;
    unsigned int num_slots;
    void (*handler)(struct i3c_device *dev, const struct i3c_ibi_payload *payload);
};

Members

max_payload_len: maximum length of the payload associated to an IBI. If one IBI appears to have a payload that is bigger than this number, the IBI will be rejected.
num_slots: number of pre-allocated IBI slots. This should be chosen so that the system never runs out of IBI slots, otherwise you’ll lose IBIs.
handler: IBI handler, every time an IBI is received. This handler is called in a workqueue context. It is allowed to sleep and send new messages on the bus, though it’s recommended to keep the processing done there as fast as possible to avoid delaying processing of other queued on the same workqueue.

Description

Temporary structure used to pass information to i3c_device_request_ibi(). This object can be allocated on the stack since i3c_device_request_ibi() copies every bit of information and do not use it after i3c_device_request_ibi() has returned.

int i3c_device_do_priv_xfers(struct i3c_device *dev, struct i3c_priv_xfer *xfers, int nxfers)¶: do I3C SDR private transfers directed to a specific device

Parameters

struct i3c_device *dev: device with which the transfers should be done
struct i3c_priv_xfer *xfers: array of transfers
int nxfers: number of transfers

Description

Initiate one or several private SDR transfers with dev.

This function can sleep and thus cannot be called in atomic context.

Return

0 in case of success, a negative error core otherwise.

-EAGAIN: controller lost address arbitration. Target: (IBI, HJ or controller role request) win the bus. Client driver needs to resend the ‘xfers’ some time later. See I3C spec ver 1.1.1 09-Jun-2021. Section: 5.1.2.2.3.

int i3c_device_do_setdasa(struct i3c_device *dev)¶: do I3C dynamic address assignement with static address

Parameters

struct i3c_device *dev: device with which the DAA should be done

Return

0 in case of success, a negative error core otherwise.

void i3c_device_get_info(const struct i3c_device *dev, struct i3c_device_info *info)¶: get I3C device information

Parameters

const struct i3c_device *dev: device we want information on
struct i3c_device_info *info: the information object to fill in

Description

Retrieve I3C dev info.

int i3c_device_disable_ibi(struct i3c_device *dev)¶: Disable IBIs coming from a specific device

Parameters

struct i3c_device *dev: device on which IBIs should be disabled

Description

This function disable IBIs coming from a specific device and wait for all pending IBIs to be processed.

Return

0 in case of success, a negative error core otherwise.

int i3c_device_enable_ibi(struct i3c_device *dev)¶: Enable IBIs coming from a specific device

Parameters

struct i3c_device *dev: device on which IBIs should be enabled

Description

This function enable IBIs coming from a specific device and wait for all pending IBIs to be processed. This should be called on a device where i3c_device_request_ibi() has succeeded.

Note that IBIs from this device might be received before this function returns to its caller.

Return

0 in case of success, a negative error core otherwise.

int i3c_device_request_ibi(struct i3c_device *dev, const struct i3c_ibi_setup *req)¶: Request an IBI

Parameters

struct i3c_device *dev: device for which we should enable IBIs
const struct i3c_ibi_setup *req: setup requested for this IBI

Description

This function is responsible for pre-allocating all resources needed to process IBIs coming from dev. When this function returns, the IBI is not enabled until i3c_device_enable_ibi() is called.

Return

0 in case of success, a negative error core otherwise.

void i3c_device_free_ibi(struct i3c_device *dev)¶: Free all resources needed for IBI handling

Parameters

struct i3c_device *dev: device on which you want to release IBI resources

Description

This function is responsible for de-allocating resources previously allocated by i3c_device_request_ibi(). It should be called after disabling IBIs with i3c_device_disable_ibi().

struct device *i3cdev_to_dev(struct i3c_device *i3cdev)¶: Returns the device embedded in i3cdev

Parameters

struct i3c_device *i3cdev: I3C device

Return

a pointer to a device object.

const struct i3c_device_id *i3c_device_match_id(struct i3c_device *i3cdev, const struct i3c_device_id *id_table)¶: Returns the i3c_device_id entry matching i3cdev

Parameters

struct i3c_device *i3cdev: I3C device
const struct i3c_device_id *id_table: I3C device match table

Return

a pointer to an i3c_device_id object or NULL if there’s no match.

int i3c_driver_register_with_owner(struct i3c_driver *drv, struct module *owner)¶: register an I3C device driver

Parameters

struct i3c_driver *drv: driver to register
struct module *owner: module that owns this driver

Description

Register drv to the core.

Return

0 in case of success, a negative error core otherwise.

void i3c_driver_unregister(struct i3c_driver *drv)¶: unregister an I3C device driver

Parameters

struct i3c_driver *drv: driver to unregister

Description

Unregister drv.

The Linux Kernel

Contents

This Page

I3C device driver API¶