i3c_device_desc Struct Reference

Structure describing a I3C target device. More...

#include <i3c.h>

Data Fields
const struct device *const	bus
	Used to attach this node onto a linked list.
const struct device *const	dev
	Device driver instance of the I3C device.
const uint64_t	pid:48
	Device Provisioned ID.
const uint8_t	static_addr
	Static address for this target device.
const uint8_t	init_dynamic_addr
	Initial dynamic address.
uint8_t	dynamic_addr
	Dynamic Address for this target device used for communication.
uint8_t	group_addr
	Group address for this target device.
uint8_t	bcr
	Bus Characteristic Register (BCR)
uint8_t	dcr
	Device Characteristic Register (DCR)
struct {
uint8_t   maxrd
	Maximum Read Speed. More...
uint8_t   maxwr
	Maximum Write Speed. More...
uint32_t   max_read_turnaround
	Maximum Read turnaround time in microseconds. More...
}	data_speed
struct {
uint16_t   mrl
	Maximum Read Length. More...
uint16_t   mwl
	Maximum Write Length. More...
uint8_t   max_ibi
	Maximum IBI Payload Size. More...
}	data_length
struct {
union {
uint8_t   gethdrcap
	I3C v1.0 HDR Capabilities (I3C_CCC_GETCAPS1_*) More...
uint8_t   getcap1
	I3C v1.1+ GETCAPS1 (I3C_CCC_GETCAPS1_*) More...
}
uint8_t   getcap2
	GETCAPS2 (I3C_CCC_GETCAPS2_*) More...
uint8_t   getcap3
	GETCAPS3 (I3C_CCC_GETCAPS3_*) More...
uint8_t   getcap4
	GETCAPS4. More...
}	getcaps
	Describes advanced (Target) capabilities and features.
i3c_target_ibi_cb_t	ibi_cb
	Private data by the controller to aid in transactions.

Detailed Description

Structure describing a I3C target device.

Instances of this are passed to the I3C controller device APIs, for example:

• i3c_device_register() to tell the controller of a target device.
• i3c_transfers() to initiate data transfers between controller and target device.

Fields bus, pid and static_addr must be initialized by the module that implements the target device behavior prior to passing the object reference to I3C controller device APIs. static_addr can be zero if target device does not have static address.

Field node should not be initialized or modified manually.

Field Documentation

bcr

uint8_t i3c_device_desc::bcr

Bus Characteristic Register (BCR)

• BCR[7:6]: Device Role
  • 0: I3C Target
  • 1: I3C Controller capable
  • 2: Reserved
  • 3: Reserved
• BCR[5]: Advanced Capabilities
  • 0: Does not support optional advanced capabilities.
  • 1: Supports optional advanced capabilities which can be viewed via GETCAPS CCC.
• BCR[4}: Virtual Target Support
  • 0: Is not a virtual target.
  • 1: Is a virtual target.
• BCR[3]: Offline Capable
  • 0: Will always response to I3C commands.
  • 1: Will not always response to I3C commands.
• BCR[2]: IBI Payload
  • 0: No data bytes following the accepted IBI.
  • 1: One data byte (MDB, Mandatory Data Byte) follows the accepted IBI. Additional data bytes may also follows.
• BCR[1]: IBI Request Capable
  • 0: Not capable
  • 1: Capable
• BCR[0]: Max Data Speed Limitation
  • 0: No Limitation
  • 1: Limitation obtained via GETMXDS CCC.

bus

const struct device* const i3c_device_desc::bus

Used to attach this node onto a linked list.

I3C bus to which this target device is attached

[struct]

struct { ... } i3c_device_desc::data_length

[struct]

struct { ... } i3c_device_desc::data_speed

dcr

uint8_t i3c_device_desc::dcr

Device Characteristic Register (DCR)

Describes the type of device. Refer to official documentation on what this number means.

dev

const struct device* const i3c_device_desc::dev

Device driver instance of the I3C device.

dynamic_addr

uint8_t i3c_device_desc::dynamic_addr

Dynamic Address for this target device used for communication.

This is to be set by the controller driver in one of the following situations:

• During Dynamic Address Assignment (during ENTDAA)
• Reset Dynamic Address Assignment (RSTDAA)
• Set All Addresses to Static Addresses (SETAASA)
• Set New Dynamic Address (SETNEWDA)
• Set Dynamic Address from Static Address (SETDASA)

0 if address has not been assigned.

getcap1

uint8_t i3c_device_desc::getcap1

I3C v1.1+ GETCAPS1 (I3C_CCC_GETCAPS1_*)

• Bit[0]: HDR-DDR
• Bit[1]: HDR-TSP
• Bit[2]: HDR-TSL
• Bit[3]: HDR-BT
• Bit[7:4]: Reserved

getcap2

uint8_t i3c_device_desc::getcap2

GETCAPS2 (I3C_CCC_GETCAPS2_*)

• Bit[3:0]: I3C 1.x Specification Version
• Bit[5:4]: Group Address Capabilities
• Bit[6]: HDR-DDR Write Abort
• Bit[7]: HDR-DDR Abort CRC

getcap3

uint8_t i3c_device_desc::getcap3

GETCAPS3 (I3C_CCC_GETCAPS3_*)

• Bit[0]: Multi-Lane (ML) Data Transfer Support
• Bit[1]: Device to Device Transfer (D2DXFER) Support
• Bit[2]: Device to Device Transfer (D2DXFER) IBI Capable
• Bit[3]: Defining Byte Support in GETCAPS
• Bit[4]: Defining Byte Support in GETSTATUS
• Bit[5]: HDR-BT CRC-32 Support
• Bit[6]: IBI MDB Support for Pending Read Notification
• Bit[7]: Reserved

getcap4

uint8_t i3c_device_desc::getcap4

GETCAPS4.

• Bit[7:0]: Reserved

[struct]

struct { ... } i3c_device_desc::getcaps

Describes advanced (Target) capabilities and features.

gethdrcap

uint8_t i3c_device_desc::gethdrcap

I3C v1.0 HDR Capabilities (I3C_CCC_GETCAPS1_*)

• Bit[0]: HDR-DDR
• Bit[1]: HDR-TSP
• Bit[2]: HDR-TSL
• Bit[7:3]: Reserved

group_addr

uint8_t i3c_device_desc::group_addr

Group address for this target device.

Set during:

• Reset Group Address(es) (RSTGRPA)
• Set Group Address (SETGRPA)

0 if group address has not been assigned.

ibi_cb

i3c_target_ibi_cb_t i3c_device_desc::ibi_cb

Private data by the controller to aid in transactions.

Do not modify. In-Band Interrupt (IBI) callback.

init_dynamic_addr

const uint8_t i3c_device_desc::init_dynamic_addr

Initial dynamic address.

This is specified in the device tree property "assigned-address" to indicate the desired dynamic address during address assignment (SETDASA and ENTDAA).

0 if there is no preference.

max_ibi

uint8_t i3c_device_desc::max_ibi

Maximum IBI Payload Size.

Valid only if BCR[2] is 1.

max_read_turnaround

uint32_t i3c_device_desc::max_read_turnaround

Maximum Read turnaround time in microseconds.

maxrd

uint8_t i3c_device_desc::maxrd

Maximum Read Speed.

maxwr

uint8_t i3c_device_desc::maxwr

Maximum Write Speed.

mrl

uint16_t i3c_device_desc::mrl

Maximum Read Length.

mwl

uint16_t i3c_device_desc::mwl

Maximum Write Length.

pid

const uint64_t i3c_device_desc::pid

Device Provisioned ID.

static_addr

const uint8_t i3c_device_desc::static_addr

Static address for this target device.

0 if static address is not being used, and only dynamic address is used. This means that the target device must go through ENTDAA (Dynamic Address Assignment) to get a dynamic address before it can communicate with the controller. This means SETAASA and SETDASA CCC cannot be used to set dynamic address on the target device (as both are to tell target device to use static address as dynamic address).

---

The documentation for this struct was generated from the following file:

• include/zephyr/drivers/i3c.h