I3C Base Controller

The PxI3CBaseController class implements the functionality of an I3C Master/Controller. It provides methods to send CCCs, manage dynamic addresses, and perform private read/write transfers.

PxI3CBaseController

PxI3CBaseController(
    exerciser: AqProtocolExerciser,
    *args,
    config: I3CControllerConfig | None = None,
    **kwargs
)

An I3C basic controller device class.

This class provides a high-level interface to an I3C controller with basic I3C functionality. It does not automatically create an actual instance on the Protocol Exerciser until you call the attach_to_bus method.

Typical usage example:

i3c_bus = PxI3CBus(exerciser_session)
i3c_controller = PxI3CBaseController(exerciser_session)
i3c_controller.attach_to_bus(i3c_bus)

... # Do any operation initiated from this controller

i3c_controller.detach_from_bus()

METHOD	DESCRIPTION
init_bus	Initialize the bus with a given voltage (in mV).
do_daa	Perform a ENTDAA operation on the I3C bus.
do_rstdaa	Perform a RSTDAA operation on the I3C bus.
send_transactions	Send a sequence of I3C transactions.
i2c_write	Perform a write operation to an I2C device.
i2c_read	Perform a read operation from an I2C device.
i2c_read_addr	Perform a read operation from an I2C device with subaddresses.
private_write	Perform a private write transaction to write data to an I3C device.
private_read_addr	Read data from an I3C device with a subaddress.
private_read	Perform a private read transaction to read data from an I3C device.
broadcast_ccc_write	Perform a broadcast CCC transaction on the I3C bus.
broadcast_enec	Perform a broadcast ENEC transaction on the I3C bus.
broadcast_disec	Perform a broadcast DISEC transaction on the I3C bus.
broadcast_entas0	Perform a broadcast ENTAS0 transaction on the I3C bus.
broadcast_entas1	Perform a broadcast ENTAS1 transaction on the I3C bus.
broadcast_entas2	Perform a broadcast ENTAS2 transaction on the I3C bus.
broadcast_entas3	Perform a broadcast ENTAS3 transaction on the I3C bus.
broadcast_setmwl	Perform a broadcast SETMWL transaction on the I3C bus.
broadcast_setmrl	Perform a broadcast SETMRL transaction on the I3C bus.
broadcast_endxfer	Perform a broadcast ENDXFER transaction on the I3C bus.
broadcast_setxtime	Perform a broadcast SETXTIME transaction on the I3C bus.
broadcast_setaasa	Instruct all targets to use their static address as dynamic address.
broadcast_rstgrpa	Perform a broadcast RSTGRPA transaction on the I3C bus.
direct_ccc_write	Perform a direct CCC transaction with the data transfer direction from the controller to the targets.
direct_ccc_read	Perform a direct CCC transaction with the data transfer direction from the targets to the controller.
direct_enec	Perform a direct ENEC transaction on the I3C bus.
direct_disec	Perform a direct ENEC transaction on the I3C bus.
direct_entas0	Perform a direct ENTAS0 transaction on the I3C bus.
direct_entas1	Perform a direct ENTAS1 transaction on the I3C bus.
direct_entas2	Perform a direct ENTAS2 transaction on the I3C bus.
direct_entas3	Perform a direct ENTAS3 transaction on the I3C bus.
direct_setdasa	Perform a direct SETDASA transaction on the I3C bus.
direct_setnewda	Perform a direct SETNEWDA transaction on the I3C bus.
direct_setmwl	Perform a direct SETMWL transaction on the I3C bus.
direct_setmrl	Perform a direct SETMRL transaction on the I3C bus.
direct_getmwl	Perform a direct GETMWL transaction on the I3C bus.
direct_getmrl	Perform a direct GETMRL transaction on the I3C bus.
direct_getpid	Perform a direct GETPID transaction on the I3C bus.
direct_getbcr	Perform a direct GETBCR transaction on the I3C bus.
direct_getdcr	Perform a direct GETDCR transaction on the I3C bus.
direct_getstatus	Perform a direct GETSTATUS transaction on the I3C bus.
direct_getaccr	Perform a direct GETACCR transaction on the I3C bus.
direct_endxfer	Perform a direct ENDXFER transaction on the I3C bus.
direct_getmxds	Perform a direct GETMXDS transaction on the I3C bus.
direct_getcaps	Perform a direct GETCAPS transaction on the I3C bus.
direct_setxtime	Perform a direct SETXTIME transaction on the I3C bus.
direct_setgrpa	Perform a direct SETGRPA transaction on the I3C bus.
direct_rstgrpa	Perform a direct RSTGRPA transaction on the I3C bus.

init_bus

init_bus(voltage: int | None = None) -> bool

Initialize the bus with a given voltage (in mV).

PARAMETER	DESCRIPTION
voltage	The voltage to initialize the bus with (in mV). If not provided, the controller will try to initiate the initialization procedure with the voltage previously set on the bus. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
bool	True if the bus is initialized successfully. Otherwise, return False.

do_daa

do_daa() -> bool

Perform a ENTDAA operation on the I3C bus.

This function start initiating Dynamic Address Assignment on the I3C devices. All device information are automatically retrieved after the operation is completed.

RETURNS	DESCRIPTION
bool	True if the operation is successful. Otherwise, return False.

do_rstdaa

do_rstdaa() -> bool

Perform a RSTDAA operation on the I3C bus.

This method initiates a Reset Dynamic Address Assignment process on all devices on the I3C bus. This shall remove all assigned dynamic addresses from all the devices on the bus.

RETURNS	DESCRIPTION
bool	True if the operation is successful. Otherwise, return False.

send_transactions

send_transactions(
    transactions: list[I3CTransaction],
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> list[I3CTransaction]

Send a sequence of I3C transactions.

This method enqueues a sequence of I3C transactions to be sent to the I3C bus, starting from a START pattern end with one of the supported stop types determined by the stop_type parameter. Each element in transactions is an I3CTransaction object, which contains one of the supported transaction types listed below:

• I2CWriteTransaction
• I2CReadTransaction
• I3CBroadcastCccTransaction
• I3CDirectCccTransaction
• I3CPrivateWriteTransaction
• I3CPrivateReadTransaction

The transactions are sent in the order they are provided.

PARAMETER	DESCRIPTION
transactions	A list of I3CTransaction objects to be sent. TYPE: list[I3CTransaction]
header_policy	enumerated value of TransactionHeaderPolicy TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	enumerated value of TransactionStopType TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
list[I3CTransaction]	A list of I3CTransaction objects, which contains the responses of the transactions sent. If any transaction responds with any data, it will be carried along with the I3CTransaction object.

RAISES	DESCRIPTION
PxError	If the transaction fails.

i2c_write

i2c_write(address: int, data: list[int]) -> int | None

Perform a write operation to an I2C device.

This method sends data to an I2C device with a given address.

PARAMETER	DESCRIPTION
address	The address of the I2C device to write to. TYPE: int
data	The data to be written to the I2C device. TYPE: list[int]

RETURNS	DESCRIPTION
int | None	The number of bytes written. Returns None if the target NACKs.

RAISES	DESCRIPTION
ValueError	data must be a list of integers within (0, 256).

i2c_read

i2c_read(address: int, count: int) -> list[int]

Perform a read operation from an I2C device.

This method tries to read data from an I2C device with a given address. If may return less than count bytes if the abort the read operation early.

PARAMETER	DESCRIPTION
address	The address of the I2C device to read from. TYPE: int
count	The number of bytes to read from the I2C device. TYPE: int

RETURNS	DESCRIPTION
list[int]	The data read from the I2C device. Returns an empty list if the target NACKs.

RAISES	DESCRIPTION
ValueError	If the count is 0.

i2c_read_addr

i2c_read_addr(i2c_address: int, sub_address: int, count: int) -> list[int]

Perform a read operation from an I2C device with subaddresses.

This method tries to read data from an I2C device with a given address. If may return less than count bytes if the abort the read operation early.

PARAMETER	DESCRIPTION
i2c_address	The address of the I2C device to read from. TYPE: int
sub_address	The subaddress of the I2C device to read from. TYPE: int
count	The number of bytes to read from the I2C device. TYPE: int

RETURNS	DESCRIPTION
list[int]	The data read from the I2C device. Returns an empty list if the target NACKs.

RAISES	DESCRIPTION
OverflowError	If the sub_address is not within (0, 256).
ValueError	If the count is 0.

private_write

private_write(
    address: int,
    data: list[int],
    parity: list[int] | None = None,
    parity_mode: ParityMode = ALL_CORRECT,
    with_broadcast_hdr: bool = True,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> int

Perform a private write transaction to write data to an I3C device.

This method sends data to an I3C device with a given address. It includes various options to specify how the operation is performed, such as the parity value or with/without broadcast header. One can choose to send an invalid parity by manually setting incorrect parity bit value.

Parity mode options are:

Parity Modes	Value for parity	Description
ParityMode.RAW	Required	Raw parity provided by the caller.
ParityMode.FLAG	Bitmask for parity of each data byte.	1 for incorrect parity, 0 for correct parity.
ParityMode.ALL_CORRECT	-	All correct parity calculated internally
ParityMode.ALL_INCORRECT	-	All incorrect parity calculated internally

PARAMETER	DESCRIPTION
address	The address of the I3C device to write to. TYPE: int
data	The data to be written to the I3C device. TYPE: list[int]
parity	The parity to use for the operation. This parameter is required when parity_mode is either ParityMode.RAW or ParityMode.FLAG. Otherwise, it will be ignored. TYPE: list[int] | None DEFAULT: None
parity_mode	The parity mode to use for the operation. TYPE: ParityMode DEFAULT: ALL_CORRECT
with_broadcast_hdr	Whether to use the broadcast 7'7Eh header. TYPE: bool DEFAULT: True
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
int	1 if the target at address acknowledges the command. Otherwise, return 0.

private_read_addr

private_read_addr(
    address: int,
    sub_address: int,
    count: int,
    parity: list[int] | None = None,
    parity_mode: ParityMode = ALL_CORRECT,
    with_broadcast_hdr: bool = True,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> list[int]

Read data from an I3C device with a subaddress.

private_read

private_read(
    address: int,
    count: int,
    with_broadcast_hdr: bool = True,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> bytes | None

Perform a private read transaction to read data from an I3C device.

This method tries to read data from an I3C device with a given address. It includes options to include broadcast header or not.

PARAMETER	DESCRIPTION
address	The address of the I3C device to read from. TYPE: int
count	The number of bytes to read from the I3C device. TYPE: int
with_broadcast_hdr	Whether to include the broadcast 7'7Eh header. TYPE: bool DEFAULT: True
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
bytes | None	The data read from the I3C device. Returns None if the target NACKs.

RAISES	DESCRIPTION
ValueError	If the count is 0.

broadcast_ccc_write

broadcast_ccc_write(
    ccc: int | PxI3CCommonCommandCode,
    data: list[int],
    defining_byte: int | None = None,
    ccc_parity_mode: ParityMode = ALL_CORRECT,
    parity_mode: ParityMode = ALL_CORRECT,
    parity: list[int] | None = None,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> bool

Perform a broadcast CCC transaction on the I3C bus.

This method sends a broadcast CCC command, followed by target addresses and the data to be written, to all targets on the I3C bus.

Parity mode options for ccc_parity_mode and parity_mode are:

Parity Modes	Value for parity	Description
ParityMode.RAW	Required	Raw parity provided by the caller.
ParityMode.FLAG	Bitmask for parity of each data byte.	1 for incorrect parity, 0 for correct parity.
ParityMode.ALL_CORRECT	-	All correct parity calculated internally
ParityMode.ALL_INCORRECT	-	All incorrect parity calculated internally

PARAMETER	DESCRIPTION
ccc	The broadcast CCC command to write. TYPE: int | PxI3CCommonCommandCode
ccc_parity_mode	The parity mode to use for the broadcast CCC command. TYPE: ParityMode DEFAULT: ALL_CORRECT
data	A list of tuples with a format of (address, list[data]) to write to the I3C device. TYPE: list[int]
defining_byte	The defining byte to use for this broadcast CCC transaction. TYPE: int | None DEFAULT: None
parity_mode	The parity mode to use for this broadcast CCC transaction. TYPE: ParityMode DEFAULT: ALL_CORRECT
parity	The parity to use for this broadcast CCC transaction. TYPE: list[int] | None DEFAULT: None
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
bool	True if the transaction is successful. Otherwise, return False.

RAISES	DESCRIPTION
ValueError	If the data or parity is not a list of integers within (0, 256).

broadcast_enec

broadcast_enec(
    event: int,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> bool

Perform a broadcast ENEC transaction on the I3C bus.

This allow controllers to enable Target-initiated events on the I3C bus. It always includes a 1-byte event byte in the data payload as shown below.

Bit 7	Bit 6	Bit 5	Bit 4	Bit 3	Bit 2	Bit 1	Bit 0
RESV	RESV	RESV	RESV	ENHJ	RESV	ENCR	ENINT

PARAMETER	DESCRIPTION
event	The events to enable. TYPE: int
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
bool	True if the events are enabled successfully. Otherwise, return False.

broadcast_disec

broadcast_disec(
    event: int,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> bool

Perform a broadcast DISEC transaction on the I3C bus.

This allow controllers to disable Target-initiated events on the I3C bus, the opposite operation of ENEC. It always includes a 1-byte event byte in the data payload as shown below.

Bit 7	Bit 6	Bit 5	Bit 4	Bit 3	Bit 2	Bit 1	Bit 0
RESV	RESV	RESV	RESV	ENHJ	RESV	ENCR	ENINT

PARAMETER	DESCRIPTION
event	The events to disable. TYPE: int
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
bool	True if the events are disabled successfully. Otherwise, return False.

broadcast_entas0

broadcast_entas0(
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> bool

Perform a broadcast ENTAS0 transaction on the I3C bus.

ENTAS0 is used when the controller is ready to enter Activity State 0, which informs all targets that it will not be active on the I3C Bus for approximately 1 us.

PARAMETER	DESCRIPTION
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
bool	True if the tranasction is sent successfully. Otherwise, return False.

broadcast_entas1

broadcast_entas1(
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> bool

Perform a broadcast ENTAS1 transaction on the I3C bus.

ENTAS1 is used when the controller is ready to enter Activity State 1, which informs all targets that it will not be active on the I3C Bus for approximately 100 us.

PARAMETER	DESCRIPTION
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
bool	True if the tranasction is sent successfully. Otherwise, return False.

broadcast_entas2

broadcast_entas2(
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> bool

Perform a broadcast ENTAS2 transaction on the I3C bus.

ENTAS2 is used when the controller is ready to enter Activity State 2, which informs all targets that it will not be active on the I3C Bus for approximately 2 ms.

PARAMETER	DESCRIPTION
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
bool	True if the tranasction is sent successfully. Otherwise, return False.

broadcast_entas3

broadcast_entas3(
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> bool

Perform a broadcast ENTAS3 transaction on the I3C bus.

ENTAS3 is used when the controller is ready to enter Activity State 3, which informs all targets that it will not be active on the I3C Bus for approximately 50 ms.

PARAMETER	DESCRIPTION
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
bool	True if the tranasction is sent successfully. Otherwise, return False.

broadcast_setmwl

broadcast_setmwl(
    max_write_length: int,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> bool

Perform a broadcast SETMWL transaction on the I3C bus.

The controller sets all targets' maximum write length to the given value. However, it does not affect data write length for CCCs, since their data payloads are defined by each CCC.

PARAMETER	DESCRIPTION
max_write_length	The maximum data write length for all targets. TYPE: int
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
bool	True if the maximum data write length for all targets is set successfully.
bool	Otherwise, return False.

RAISES	DESCRIPTION
ValueError	If the max_write_length is not within (0, 65536).

broadcast_setmrl

broadcast_setmrl(
    max_read_length: int,
    ibi_payload_size: int | None = None,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> bool

Perform a broadcast SETMRL transaction on the I3C bus.

The controller sets all targets' maximum read length to the given value. For devices that its BCR[2] = 1, the maximum IBI payload size value as a third byte, where a value of 0 indicates an unlimited payload size.

PARAMETER	DESCRIPTION
max_read_length	The maximum data read length for all targets. TYPE: int
ibi_payload_size	The maximum IBI payload size set to all targets. TYPE: int | None DEFAULT: None
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
bool	True if the maximum data read length for all targets is set successfully.
bool	Otherwise, return False.

RAISES	DESCRIPTION
ValueError	If the max_read_length is not within (0, 65536).
ValueError	If the ibi_payload_size is not within (0, 256).

broadcast_endxfer

broadcast_endxfer(
    data: list[int],
    defining_byte: int,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> bool

Perform a broadcast ENDXFER transaction on the I3C bus.

ENDXFER is used when Controllers and Targets exchange setup parameters for ending data transfers in HDR modes. It always requires an 1-byte defining byte in the data payload, which acts as a sub-command identifier defining the specific function.

PARAMETER	DESCRIPTION
data	Additional data bytes to be sent to the target, which are defined by the defining byte. TYPE: list[int]
defining_byte	The defining byte to use for the transaction. TYPE: int
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
bool	True if the transaction is successful. Otherwise, return False.

broadcast_setxtime

broadcast_setxtime(
    exchange_time_info: int,
    additional_data: list[int] | None = None,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> bool

Perform a broadcast SETXTIME transaction on the I3C bus.

SETXTIME is used when Controllers and Targets exchange event timing information. It always includes a 1-byte sub-command byte (exchange_time_info) in the data payload.

PARAMETER	DESCRIPTION
exchange_time_info	The exchange time parameters to set. TYPE: int
additional_data	The additional data to set. TYPE: list[int] | None DEFAULT: None
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
bool	True if the exchange time parameters are set successfully. Otherwise, return False.

broadcast_setaasa

broadcast_setaasa(
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> bool

Instruct all targets to use their static address as dynamic address.

Controller tells all targets to use their static address as dynamic address. This is a faster method to assign dynamic addresses to targets.

PARAMETER	DESCRIPTION
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
bool	True if the static address is used as dynamic address successfully.
bool	Otherwise, return False.

broadcast_rstgrpa

broadcast_rstgrpa(
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> bool

Perform a broadcast RSTGRPA transaction on the I3C bus.

Controller reset the all targets' group addresses.

PARAMETER	DESCRIPTION
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
bool	True if the all targets' group addresses are reset successfully.
bool	Otherwise, return False.

direct_ccc_write

direct_ccc_write(
    ccc: int | PxI3CCommonCommandCode,
    data: list[tuple[int, list[int]]],
    defining_byte: int | None = None,
    ccc_parity_mode: ParityMode = ALL_CORRECT,
    defining_byte_parity_mode: ParityMode = ALL_CORRECT,
    parity_mode: ParityMode = ALL_CORRECT,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> list[int]

Perform a direct CCC transaction with the data transfer direction from the controller to the targets.

This method sends a direct CCC command, followed by target addresses and the amount of data to be written to each target, from a list of I3C target devices.

PARAMETER	DESCRIPTION
ccc	The direct CCC command to write. TYPE: int | PxI3CCommonCommandCode
ccc_parity_mode	The parity mode to use for the direct CCC command. TYPE: ParityMode DEFAULT: ALL_CORRECT
data	A list of tuples with a format of (address, list[data]) to write to the I3C device. TYPE: list[tuple[int, list[int]]]
defining_byte	The defining byte to use for this direct CCC transaction. TYPE: int | None DEFAULT: None
defining_byte_parity_mode	The parity mode to use for the defining byte. TYPE: ParityMode DEFAULT: ALL_CORRECT
parity_mode	The parity mode to use for the data. TYPE: ParityMode DEFAULT: ALL_CORRECT
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
list[int]	The list of ACK that response to each address.

RAISES	DESCRIPTION
ValueError	If the data is not a list of integers within (0, 256).

direct_ccc_read

direct_ccc_read(
    ccc: int | PxI3CCommonCommandCode,
    addresses: list[int],
    count: int,
    ccc_parity_mode: ParityMode = ALL_CORRECT,
    defining_byte: int | None = None,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> list[list[int] | None]

Perform a direct CCC transaction with the data transfer direction from the targets to the controller.

This method sends a direct CCC command, followed by target addresses and the amount of data to be read, from a list of I3C target devices.

PARAMETER	DESCRIPTION
ccc	The direct CCC command to read. TYPE: int | PxI3CCommonCommandCode
ccc_parity_mode	The parity mode to use for the direct CCC command. TYPE: ParityMode DEFAULT: ALL_CORRECT
addresses	A list of target addresses to read from. TYPE: list[int]
count	The number of bytes to read from each target address. TYPE: int
defining_byte	The defining byte to use for this direct CCC transaction. TYPE: int | None DEFAULT: None
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
list[list[int] | None]	A list of bytes read from each corresponding I3C target device, or None if the target NAK'd. Return an empty list if the transaction fails.

direct_enec

direct_enec(
    addresses: list[int],
    event: int,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> list[int]

Perform a direct ENEC transaction on the I3C bus.

This allow controllers to enable Target-initiated events to individual targets on the I3C bus. It always includes a 1-byte event byte in the data payload as shown below.

Bit 7	Bit 6	Bit 5	Bit 4	Bit 3	Bit 2	Bit 1	Bit 0
RESV	RESV	RESV	RESV	ENHJ	RESV	ENCR	ENINT

PARAMETER	DESCRIPTION
addresses	The addresses of the I3C devices within the transaction. TYPE: list[int]
event	The events to enable. TYPE: int
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
list[int]	The list of ACKs (1 for ACK, 0 for NAK) that each address responded.

direct_disec

direct_disec(
    addresses: list[int],
    event: int,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> list[int]

Perform a direct ENEC transaction on the I3C bus.

This allow controllers to disable Target-initiated events to individual targets on the I3C bus. It always includes a 1-byte event byte in the data payload as shown below.

Bit 7	Bit 6	Bit 5	Bit 4	Bit 3	Bit 2	Bit 1	Bit 0
RESV	RESV	RESV	RESV	ENHJ	RESV	ENCR	ENINT

PARAMETER	DESCRIPTION
addresses	The addresses of the I3C devices within the transaction. TYPE: list[int]
event	The events to disable. TYPE: int
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
list[int]	The list of ACKs (1 for ACK, 0 for NAK) that each address responded.

direct_entas0

direct_entas0(
    addresses: list[int],
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> list[int]

Perform a direct ENTAS0 transaction on the I3C bus.

ENTAS0 is used when the controller is ready to enter Activity State 0. This tells the targets listed in addresses that it will not be active on the I3C Bus for approximately 1 us.

PARAMETER	DESCRIPTION
addresses	The addresses of the I3C devices within the transaction. TYPE: list[int]
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
list[int]	The list of ACKs (1 for ACK, 0 for NAK) that each address responded.

direct_entas1

direct_entas1(
    addresses: list[int], header_policy: TransactionHeaderPolicy = OPTIMIZED
) -> list[int]

Perform a direct ENTAS1 transaction on the I3C bus.

ENTAS1 is used when the controller is ready to enter Activity State 0. This tells the targets listed in addresses that it will not be active on the I3C Bus for approximately 100 us.

PARAMETER	DESCRIPTION
addresses	The addresses of the I3C devices within the transaction. TYPE: list[int]
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED

RETURNS	DESCRIPTION
list[int]	The list of ACKs (1 for ACK, 0 for NAK) that each address responded.

direct_entas2

direct_entas2(
    addresses: list[int], header_policy: TransactionHeaderPolicy = OPTIMIZED
) -> list[int]

Perform a direct ENTAS2 transaction on the I3C bus.

ENTAS2 is used when the controller is ready to enter Activity State 2. This tells the targets listed in addresses that it will not be active on the I3C Bus for approximately 2 ms.

PARAMETER	DESCRIPTION
addresses	The addresses of the I3C devices within the transaction. TYPE: list[int]
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED

RETURNS	DESCRIPTION
list[int]	The list of ACKs (1 for ACK, 0 for NAK) that each address responded.

direct_entas3

direct_entas3(
    addresses: list[int], header_policy: TransactionHeaderPolicy = OPTIMIZED
) -> list[int]

Perform a direct ENTAS3 transaction on the I3C bus.

ENTAS3 is used when the controller is ready to enter Activity State 3. This tells the targets listed in addresses that it will not be active on the I3C Bus for approximately 50 ms.

PARAMETER	DESCRIPTION
addresses	The addresses of the I3C devices within the transaction. TYPE: list[int]
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED

RETURNS	DESCRIPTION
list[int]	The list of ACKs (1 for ACK, 0 for NAK) that each address responded.

direct_setdasa

direct_setdasa(
    static_addresses: list[int],
    dynamic_addresses: list[int],
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
) -> list[int]

Perform a direct SETDASA transaction on the I3C bus.

Controller assigns a dynamic address to a target using the target's static address. It is generally faster than ENTDAA Dynamic Address Assignment procedure. SETDASA shall be used before the ENTDAA is used.

PARAMETER	DESCRIPTION
static_addresses	The list of static addresses of the I3C devices. TYPE: list[int]
dynamic_addresses	The list of dynamic addresses to be assigned to the target devices. TYPE: list[int]
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED

RETURNS	DESCRIPTION
list[int]	The list of ACKs (1 for ACK, 0 for NAK) that each address responded.

direct_setnewda

direct_setnewda(
    addresses: list[tuple[int, int]], header_policy: TransactionHeaderPolicy = OPTIMIZED
) -> list[int]

Perform a direct SETNEWDA transaction on the I3C bus.

Controller assigns a dynamic address to a target or a secondary controller listed in addresses. If the target supports this CCC and acceptes the new address, then the target device shall change its current dynamic address.

PARAMETER	DESCRIPTION
addresses	The list of current addresses of the I3C devices. TYPE: list[tuple[int, int]]
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED

RETURNS	DESCRIPTION
list[int]	The list of ACKs (1 for ACK, 0 for NAK) that each address responded.

direct_setmwl

direct_setmwl(
    addresses: list[int],
    max_write_length: int,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
) -> list[int]

Perform a direct SETMWL transaction on the I3C bus.

The controller maximum data write length to the targets listed in addresses.

PARAMETER	DESCRIPTION
addresses	The addresses of the I3C devices within the transaction. TYPE: list[int]
max_write_length	The maximum data write length to set. TYPE: int
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED

RETURNS	DESCRIPTION
list[int]	The list of ACKs (1 for ACK, 0 for NAK) that each address responded.

RAISES	DESCRIPTION
ValueError	If the max_write_length is not within (0, 65536).

direct_setmrl

direct_setmrl(
    addresses: list[int],
    max_read_length: int,
    ibi_payload_size: int | None = None,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
) -> list[int]

Perform a direct SETMRL transaction on the I3C bus.

The controller maximum data read length to the targets listed in addresses. For devices that its BCR[2] = 1, the maximum IBI payload size value as a third byte, where a value of 0 indicates an unlimited payload size.

PARAMETER	DESCRIPTION
addresses	The addresses of the I3C devices within the transaction. TYPE: list[int]
max_read_length	The maximum data read length to set. TYPE: int
ibi_payload_size	The maximum IBI payload size to set. TYPE: int | None DEFAULT: None
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED

RETURNS	DESCRIPTION
list[int]	The list of ACKs (1 for ACK, 0 for NAK) that each address responded.

RAISES	DESCRIPTION
ValueError	If the max_read_length is not within (0, 65536).
ValueError	If the ibi_payload_size is not within (0, 256).

direct_getmwl

direct_getmwl(
    addresses: list[int], header_policy: TransactionHeaderPolicy = OPTIMIZED
) -> list[list[int] | None]

Perform a direct GETMWL transaction on the I3C bus.

The controller gets the maximum data write length from the targets listed in addresses.

PARAMETER	DESCRIPTION
addresses	The addresses of the I3C devices within the transaction. TYPE: list[int]
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED

RETURNS	DESCRIPTION
list[list[int] | None]	A list of maximum data write length values read from each corresponding I3C target device, or None if target devices NACKed the transaction. The returned list is expected to have the same length as the addresses list.

direct_getmrl

direct_getmrl(
    addresses: list[int], header_policy: TransactionHeaderPolicy = OPTIMIZED
) -> list[list[int] | None]

Perform a direct GETMRL transaction on the I3C bus.

The controller gets the maximum data read length from the targets listed in addresses.

PARAMETER	DESCRIPTION
addresses	The addresses of the I3C devices within the transaction. TYPE: list[int]
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED

RETURNS	DESCRIPTION
list[list[int] | None]	A list of maximum data read length values read from each corresponding I3C target device, or None if target devices NACKed the transaction. The returned list is expected to have the same length as the addresses list.

direct_getpid

direct_getpid(
    addresses: list[int], header_policy: TransactionHeaderPolicy = OPTIMIZED
) -> list[list[int] | None]

Perform a direct GETPID transaction on the I3C bus.

Fetch the Provisioned ID (PID) for a list of I3C targets.

PARAMETER	DESCRIPTION
addresses	The addresses of the I3C devices within the transaction. TYPE: list[int]
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED

RETURNS	DESCRIPTION
list[list[int] | None]	A list of PID values read from each corresponding I3C target device, or None if target devices NACKed the transaction. The returned list is expected to have the same length as the addresses list.

direct_getbcr

direct_getbcr(
    addresses: list[int],
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> list[list[int] | None]

Perform a direct GETBCR transaction on the I3C bus.

Fetch the Bus Characteristics Register (BCR) for a list of I3C targets.

PARAMETER	DESCRIPTION
addresses	The addresses of the I3C devices within the transaction. TYPE: list[int]
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
list[list[int] | None]	A list of BCR values read from each corresponding I3C target device, or None if target devices NACKed the transaction. The returned list is expected to have the same length as the addresses list.

direct_getdcr

direct_getdcr(
    addresses: list[int],
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> list[list[int] | None]

Perform a direct GETDCR transaction on the I3C bus.

Fetch the Device Characteristics Register (DCR) for a list of I3C targets.

PARAMETER	DESCRIPTION
addresses	The addresses of the I3C devices within the transaction. TYPE: list[int]
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
list[list[int] | None]	A list of DCR values read from each corresponding I3C target device, or None if target devices NACKed the transaction. The returned list is expected to have the same length as the addresses list.

direct_getstatus

direct_getstatus(
    addresses: list[int],
    defining_byte: int | None = None,
    count: int = 2,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> list[list[int] | None]

Perform a direct GETSTATUS transaction on the I3C bus.

Fetch the current operating status for a list of I3C targets. The returned status' formats are defined by the defining byte.

PARAMETER	DESCRIPTION
addresses	The addresses of the I3C devices within the transaction. TYPE: list[int]
defining_byte	The defining byte used within the transaction. This affects the data returned by the transaction. TYPE: int | None DEFAULT: None
count	The number of bytes to read from each target device. TYPE: int DEFAULT: 2
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
list[list[int] | None]	A list of status values read from each corresponding I3C target device, or None if target devices NACKed the transaction. The returned list is expected to have the same length as the addresses list.

direct_getaccr

direct_getaccr(
    address: int,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> list[int] | None

Perform a direct GETACCR transaction on the I3C bus.

Controller gets the Access Control Register from a target Args: address: The address of the I3C device from which the Access Control Register is read. header_policy: policy that used to transfer the first byte after START. stop_type: the stop type to use for the operation.

RETURNS	DESCRIPTION
list[int] | None	A list of bytes read from each corresponding I3C target device, which contains the capabilities, or None if NAK

direct_endxfer

direct_endxfer(
    addresses: list[int],
    data: list[int],
    defining_byte: int,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> list[int]

Perform a direct ENDXFER transaction on the I3C bus.

ENDXFERS is used when controller and targets exchange set-up parameters for ending data transfers in HDR Modes, and for Monitoring Devices to request early termination of running transactions. It always requires an 1-byte defining byte in the data payload, which acts as a sub-command identifier defining the specific function.

PARAMETER	DESCRIPTION
addresses	The addresses of the I3C devices within the transaction. TYPE: list[int]
data	Additional data bytes to be sent to the target, which are defined by the defining byte. TYPE: list[int]
defining_byte	The defining byte to use for the transaction. TYPE: int
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
list[int]	The list of ACKs (1 for ACK, 0 for NAK) that each address responded.

direct_getmxds

direct_getmxds(
    addresses: list[int],
    defining_byte: int | None = None,
    count: int = 2,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> list[list[int] | None]

Perform a direct GETMXDS transaction on the I3C bus.

The controller gets the maximum data speed from the targets listed in addresses. The maximum data speed is defined by the defining byte.

PARAMETER	DESCRIPTION
addresses	The list of addresses of the I3C devices from which the target's maximum data speed is read. TYPE: list[int]
defining_byte	The defining byte to use for the transaction. TYPE: int | None DEFAULT: None
count	The number of read back bytes. TYPE: int DEFAULT: 2
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
list[list[int] | None]	A list of maximum data speed values read from each corresponding I3C target device, or None if target devices NACKed the transaction. The returned list is expected to have the same length as the addresses list.

direct_getcaps

direct_getcaps(
    addresses: list[int],
    defining_byte: int | None = None,
    count: int = 4,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> list[list[int] | None]

Perform a direct GETCAPS transaction on the I3C bus.

The controller gets the capabilities from the targets listed in addresses. The returned capabilities formats are defined by the defining byte.

PARAMETER	DESCRIPTION
addresses	The list of addresses of the I3C devices from which the target's capabilities are read. TYPE: list[int]
defining_byte	The defining byte to use for the transaction. TYPE: int | None DEFAULT: None
count	The number of read back bytes. TYPE: int DEFAULT: 4
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
list[list[int] | None]	A list of capabilities values read from each corresponding I3C target device, or None if target devices NACKed the transaction. The returned list is expected to have the same length as the addresses list.

direct_setxtime

direct_setxtime(
    addresses: list[int],
    exchange_time_info: int,
    additional_data: list[int] | None = None,
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> list[int]

Perform a direct SETXTIME transaction on the I3C bus.

SETXTIME is used when Controllers and Targets exchange event timing information. It always includes a 1-byte sub-command byte (exchange_time_info) in the data payload.

PARAMETER	DESCRIPTION
addresses	The list of addresses of the I3C devices to which the target's exchange time parameters are set. TYPE: list[int]
exchange_time_info	The exchange time information to set. (Subcommand byte) TYPE: int
additional_data	Additional data bytes to be sent to the target, which are defined by the exchange_time_info. TYPE: list[int] | None DEFAULT: None
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
list[int]	The list of ACKs (1 for ACK, 0 for NAK) that each address responded.

direct_setgrpa

direct_setgrpa(
    addresses: list[int],
    assigned_group_addresses: list[int],
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> list[int]

Perform a direct SETGRPA transaction on the I3C bus.

SETGRPA is used when the controller wants to set the group address to a target.

PARAMETER	DESCRIPTION
addresses	The list of the target that is going to be assigned group address. TYPE: list[int]
assigned_group_addresses	The list of group address that is going to be assigned to targets. TYPE: list[int]
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
list[int]	The list of ACK that response to each address.

direct_rstgrpa

direct_rstgrpa(
    addresses: list[int],
    header_policy: TransactionHeaderPolicy = OPTIMIZED,
    stop_type: TransactionStopType = PUSH_PULL,
) -> list[int]

Perform a direct RSTGRPA transaction on the I3C bus.

RSTGRPA is used when the controller wants to reset the group address of a target.

PARAMETER	DESCRIPTION
addresses	The list of the target address or group address that want to remove TYPE: list[int]
header_policy	policy that used to transfer the first byte after START. TYPE: TransactionHeaderPolicy DEFAULT: OPTIMIZED
stop_type	the stop type to use for the operation. TYPE: TransactionStopType DEFAULT: PUSH_PULL

RETURNS	DESCRIPTION
list[int]	The list of ACK that response to each address.