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.