Executable example programs

Run from the repository after installing the package:

python examples/v2/run.py --output build/examples-new

Each scenario emits assembly (.asm), an assembled raw image (.bin), a 40 ns cycle-domain trace (.trace.json), and an entry in results.json with word count, image checksum, ownership/open-drain masks, and checked results. The command exits nonzero on a mismatch. Generation calls the existing firmware functions and assembles with capacity=64; no alternate protocol implementation is introduced. Reassemble a generated source with assemble(Path(path).read_text(), capacity=64) from protocol_emulator.v2.isa. The toolchain page shows decoding, image writing and loading.

Protocol matrix

All protocol pin numbers below are uio bits. Dedicated host pins remain ui0=SCK, ui1=CS_n, ui2=MOSI and uo0=MISO.

Protocol	Role/rate	Generated program or scenario	Pins and expected transaction	Executable verification
UART	TX and RX, 115200 baud	uart_tx_115200, uart_rx_115200, uart_duplex_115200	TX=0, RX=1; transmit 00 55 a5 ff, receive 81 5a 01 fe; metadata zero	tests/v2/test_uart.py, test_v2_full_duplex_host_budget
UART	TX and RX, 1 Mbaud	uart_tx_1000000, uart_rx_1000000, uart_duplex_1000000	Same four-byte duplex trace	tests/v2/test_uart.py, test_v2_uart_megabaud_buffered_duplex
SPI	Controller, mode 0	spi_controller_mode0	MOSI=0, SCK=1, CS_n=2, MISO=3; transmit a5, receive ff	tests/v2/test_spi.py, V2 pin controller suite
SPI	Target, mode 0	spi_target_mode0	Same pins; controller sends ff and receives a5	tests/v2/test_spi.py, V2 pin target suite
SPI	Controller, mode 1	spi_controller_mode1	Same a5/ff trace	Controller mode parametrization and pin suite
SPI	Target, mode 1	spi_target_mode1	Same ff/a5 trace	Target mode parametrization and pin suite
SPI	Controller, mode 2	spi_controller_mode2	Same a5/ff trace	Controller mode parametrization and pin suite
SPI	Target, mode 2	spi_target_mode2	Same ff/a5 trace	Target mode parametrization and pin suite
SPI	Controller, mode 3	spi_controller_mode3	Same a5/ff trace	Controller mode parametrization and pin suite
SPI	Target, mode 3	spi_target_mode3	Same ff/a5 trace	Target mode parametrization and pin suite
I2C	Controller, 100 kHz	i2c_controller_100000	SDA=0, SCL=1; address 42; write 55 a5, repeated START, read 81 5a, STOP	tests/v2/test_i2c.py, V2 pin I2C controller suite
I2C	Target, 100 kHz	i2c_target_100000	Same transaction from external controller	Target write/read tests and pin suite
I2C	Controller, 400 kHz	i2c_controller_400000	Same combined transaction	Controller timing/combined tests and pin suite
I2C	Target, 400 kHz	i2c_target_400000	Same combined transaction	Target write/read tests and pin suite

Source links: UART tests, SPI tests, I2C tests, RTL pin scenarios. The branch links aid navigation; acceptance uses immutable source identities.

Configuration and limits

UART uses 217 cycles per bit (approximately 115207 baud) or exactly 25 cycles (1 Mbaud). The examples run TX and RX concurrently on separate engines with four queued bytes, within each 16-entry queue. They do not simulate host refill. The RTL 115200-baud budget test services 145 TX and 128 RX bytes at 500 us intervals, with maximum service time 492 us. This is a measured simulation budget, not a Linux scheduling guarantee. At 1 Mbaud, the 1 MHz SPI host cannot sustain arbitrary continuous duplex traffic; preloaded/bounded bursts are the supported example. Overflow and starvation remain meaningful limits.

SPI examples use 1 MHz SCK (25 system clocks per period). Modes 0/1 have idle SCK low; modes 2/3 high. Even modes sample the leading edge and odd modes the trailing edge. Controller ownership is 0x07; target ownership is 0x08. Targets configure watcher 0 (mask=4, value=4, edges=4) and abort mask 1 for CS release. The model driver includes a three-cycle input pipeline for targets. The existing controller tests additionally cover 100 kHz.

I2C examples configure owner and open-drain masks 0x03. Pull-ups resolve released SDA/SCL high in the digital peer. Targets use START/STOP watchers (3,2,1) and (3,3,1) with abort mask 3. The generated combined controller occupies all 64 words; the target uses 62. They use the bypass input path; filtered controller firmware must be generated with filtered=True and mask 3 configured consistently. Existing pin tests cover the filtered path. Bus stretching and instruction boundaries may reduce transaction throughput below the nominal clock ceiling. These digital examples do not establish analog rise times or hardware operation.