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;
  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

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

Provisional 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);
  int (*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

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(__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.

void i3c_device_get_info(struct i3c_device *dev, struct i3c_device_info *info)

get I3C device information

Parameters

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.

struct i3c_device * dev_to_i3cdev(struct device *dev)

Returns the I3C device containing dev

Parameters

struct device *dev

device object

Return

a pointer to an I3C 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.