I2C FIFO 目標¶

PxI2CFifoTarget 模擬具有主機可存取 RX 與 TX FIFO 的 I2C 目標裝置。控制器在匯流排上寫入的資料進入 RX FIFO(以事件交給 Python);Python 將資料入列到 TX FIFO，供控制器在匯流排上讀取。

FIFO 深度固定為 4 KB，無法從 Python 設定。單次 enqueue 最多可傳送目前可用的 TX FIFO 容量。每個 receive 事件最多交付 4 KB;每個 sent 事件回報一次匯流排讀取抽走的位元組數。

資料流¶

Controller WRITE  →  RX FIFO  →  fifo_target_recv events  →  Python
Python enqueue    →  TX FIFO  →  Controller READ
Controller READ   →  (drains TX FIFO)  →  fifo_target_sent events  →  Python

快速開始¶

將目標掛載到 I2C 匯流排並入列 TX 資料:

from aqpxlib import AqProtocolExerciser
from aqpxlib.i2c import PxI2CBus, PxI2CFifoTarget

with AqProtocolExerciser.connect(port=60600) as px:
    i2c_bus = PxI2CBus(px, scl=0, sda=1)
    target = PxI2CFifoTarget(px, address=0x50)
    target.attach_to_bus(i2c_bus)

    target.enqueue([0x01, 0x02, 0x03])

    state = target.state
    print(f"TX fill: {state.tx_fill}")
    print(f"Total read: {state.total_read}")
    print(f"Total written: {state.total_written}")

    target.detach_from_bus()

入列(主機 → 匯流排)¶

使用 enqueue 載入 TX FIFO。這本身不會執行 I2C 交易。請在同一條匯流排上使用 PxI2CController 讀取已入列的位元組。

target.enqueue(b"\xde\xad\xbe\xef")

匯流排接收事件¶

當控制器寫入目標時，exerciser 會發出 fifo_target_recv 事件。每個事件帶有 data 欄位(該事件封包收到的位元組)，以及標示目前匯流排寫入交易(STOP 或 repeated-START)最後一個事件的 last 旗標。

欄位	型別	說明
`data`	`bytes`	此事件收到的位元組
`last`	`bool`	若為目前匯流排寫入的最後一個事件則為 `True`

from aqpxlib.event import PxEventMsg

@target.on_event("fifo_target_recv")
def on_recv(event: PxEventMsg):
    recv_event = event.device_event.fifo_target_recv
    print(f"Recv {recv_event.data.hex()} last={recv_event.last}")

匯流排送出事件¶

當控制器從目標讀取時，exerciser 會發出 fifo_target_sent 事件。每個事件回報該次完成的匯流排讀取從 TX FIFO 抽走多少位元組，last 標示該讀取交易結束。

欄位	型別	說明
`count`	`int`	此次讀取交易在匯流排上送出的位元組數
`last`	`bool`	若為目前匯流排讀取的最後一個事件則為 `True`

@target.on_event("fifo_target_sent")
def on_sent(event: PxEventMsg):
    sent_event = event.device_event.fifo_target_sent
    print(f"Sent {sent_event.count} bytes last={sent_event.last}")

enqueue 與狀態查詢不會發出 recv 或 sent 事件。

另見: 事件註冊與處理函式設定。

狀態¶

透過 target.state 查詢目前 FIFO 狀態: | 屬性 | 說明 | |----------|-------------| | tx_fill | TX FIFO 目前排隊中的位元組數 | | total_read | 自 configure 以來控制器讀取的累計位元組數 | | total_written | 自 configure 以來控制器寫入的累計位元組數 |

state = target.state
assert state.tx_fill >= 0
assert state.total_read >= 0
assert state.total_written >= 0

控制器存取¶

使用 PxI2CController 透過匯流排操作目標:

from aqpxlib import AqProtocolExerciser
from aqpxlib.event import PxEventMsg
from aqpxlib.i2c import PxI2CBus, PxI2CController, PxI2CFifoTarget

with AqProtocolExerciser.connect(port=60600) as px:
    i2c_bus = PxI2CBus(px, scl=0, sda=1)
    target = PxI2CFifoTarget(px, address=0x50)
    target.attach_to_bus(i2c_bus)

    controller = PxI2CController(px)
    controller.attach_to_bus(i2c_bus)

    received: list[int] = []

    @target.on_event("fifo_target_recv")
    def on_recv(event: PxEventMsg) -> None:
        recv_event = event.device_event.fifo_target_recv
        received.extend(recv_event.data)

    target.enqueue([0xAA, 0xBB, 0xCC])
    read_back = controller.i2c_read(target.address, 3)
    assert read_back == [0xAA, 0xBB, 0xCC]

    controller.i2c_write(target.address, [0x11, 0x22])
    assert received == [0x11, 0x22]

    controller.detach_from_bus()
    target.detach_from_bus()

I3C 匯流排支援¶

PxI2CFifoTarget 可掛載到 I3C 匯流排(valid_buses 包含 "i3c" 與 "i2c")。裝置在 I3C SDA 線上以 I2C 風格目標運作。

API 參考¶

PxI2CFifoTarget ¶

PxI2CFifoTarget(
    exerciser: AqProtocolExerciser,
    address: int = 0,
    config: I2CFifoTargetConfig | None = None,
    *args,
    **kwargs
)

Bases: PxAbstractTarget

I2C FIFO target.

Emulates an I2C target with host-accessible RX and TX FIFOs. Bytes written by a controller on the bus are delivered to Python as packeted fifo_target_recv events. Bytes enqueued from Python are presented on subsequent bus reads; completed bus reads are reported as fifo_target_sent events with the byte count drained in each transaction.

Use enqueue to load the TX FIFO. Use self.state for the current device state snapshot (tx_fill, total_read, total_written).

METHOD	DESCRIPTION
`add_event_handler`	Add an event handler to the current device instance.
`remove_event_handler`	Remove an event handler.
`get_event_handlers`	Retreive handlers registerd on this device.
`on_event`	Add an event handler to the instance by decorator.
`set_config`	Set the config of the target.
`detach_from_bus`	Detach the device from the bus.
`perform_operation`	Send an operation.
`attach_to_bus`	Attach the target to a bus.
`enqueue`	Enqueue bytes into the host-side TX FIFO.

ATTRIBUTE	DESCRIPTION
`available_events_map`	A reverse mapping of `field_name_by_number`, which uses field name as key. TYPE: `dict[str, str]`
`is_attached`	Check if the device is attached to a bus. TYPE: `bool`
`state`	Get the state of the device. TYPE: `Message \| None`
`name`	Get the name of the device. TYPE: `str`
`additional_data`	Get the opaque additional data blob associated with this device. TYPE: `bytes`
`config`	Get the config of the device. TYPE: `Message \| None`
`cts_op_name`	Get the name of CTS operation. Currently not available now. TYPE: `str \| None`
`address`	Static 7-bit I2C address of the target. TYPE: `int`
`tx_fill`	Number of bytes currently in the TX FIFO. TYPE: `int`
`total_read`	Total bytes read by the controller from the target since configuration. TYPE: `int`
`total_written`	Total bytes written by the controller to the target since configuration. TYPE: `int`

available_events_map ¶

available_events_map: dict[str, str]

A reverse mapping of field_name_by_number, which uses field name as key.

is_attached ¶

is_attached: bool

Check if the device is attached to a bus.

state ¶

state: Message | None

Get the state of the device.

name ¶

name: str

Get the name of the device.

additional_data ¶

additional_data: bytes

Get the opaque additional data blob associated with this device.

config ¶

config: Message | None

Get the config of the device.

cts_op_name ¶

cts_op_name: str | None

Get the name of CTS operation. Currently not available now.

address ¶

address: int

Static 7-bit I2C address of the target.

tx_fill ¶

tx_fill: int

Number of bytes currently in the TX FIFO.

total_read ¶

total_read: int

Total bytes read by the controller from the target since configuration.

total_written ¶

total_written: int

Total bytes written by the controller to the target since configuration.

add_event_handler ¶

add_event_handler(event: str, handler: Callable[[Any], Any]) -> None

Add an event handler to the current device instance.

remove_event_handler ¶

remove_event_handler(event: str) -> None

Remove an event handler.

get_event_handlers ¶

get_event_handlers() -> dict[str, Callable]

Retreive handlers registerd on this device.

on_event ¶

on_event(event_type: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]

Add an event handler to the instance by decorator.

set_config ¶

set_config(config: Message) -> None

Set the config of the target.

detach_from_bus ¶

detach_from_bus() -> None

Detach the device from the bus.

The opposite of the attach_to_bus method.

perform_operation ¶

perform_operation(operation: PxDeviceOperation) -> PxDeviceOperation

Send an operation.

attach_to_bus ¶

attach_to_bus(bus: PxAbstractBus) -> None

Attach the target to a bus.

This method is used to make the device aware of the bus it is connected to. It is used to set the bus attribute of the device.

Note

This method will not automatically create an actual instance on the Protocol Exerciser until user call the attach_to_bus method.

PARAMETER	DESCRIPTION
`bus` ¶	The bus to attach the device to TYPE: `PxAbstractBus`

RAISES	DESCRIPTION
`ValueError`	If the device is already attached to a bus

enqueue ¶

enqueue(data: list[int] | bytes) -> None

Enqueue bytes into the host-side TX FIFO.

This does not perform an I2C bus transaction. Enqueued bytes are returned to a controller on subsequent bus read transfers.

PARAMETER	DESCRIPTION
`data` ¶	Bytes to enqueue (`0`-`255` per byte). May exceed 4 KB in a single call; size is limited only by available TX FIFO space. TYPE: `list[int] \| bytes`