Functions for creating and updating an epio instance from apio state. More...

Functions
EPIO_EXPORT epio_t *	epio_from_apio (void)
	Create an epio instance configured from the current apio state.

EPIO_EXPORT void	epio_update_from_apio (epio_t *epio)
	Update a live epio instance from the current accumulated apio state.

EPIO_EXPORT int	epio_disassemble_sm (epio_t epio, uint8_t block, uint8_t sm, char buffer, size_t buffer_size)
	Disassemble the instructions of a state machine.

Detailed Description

Functions for creating and updating an epio instance from apio state.

Function Documentation

◆ epio_disassemble_sm()

EPIO_EXPORT int epio_disassemble_sm	(	epio_t *	epio,
		uint8_t	block,
		uint8_t	sm,
		char *	buffer,
		size_t	buffer_size
	)

Disassemble the instructions of a state machine.

Parameters

epio	The epio instance.
block	PIO block number.
sm	State machine number.
buffer	Buffer to store the disassembled instructions.
buffer_size	Size of the buffer.

Returns: Number of characters written to the buffer. 0 indicates a failure, for example no debug information available for the specified SM. -1 indicates the buffer was too small to hold the full disassembly.

◆ epio_from_apio()

EPIO_EXPORT epio_t * epio_from_apio ( void )

Create an epio instance configured from the current apio state.

Reads the PIO program, SM configuration, and GPIO state assembled by apio and uses it to initialise and return a fully configured epio instance. This is the recommended entry point when using epio with apio.

After applying all apio state, the accumulated pre_instr_count, tx_fifo_count, and rx_fifo_count in the apio global state are reset to zero. This marks those items as consumed, so that a subsequent call to epio_update_from_apio() sees only the delta accumulated since this call.

Only available when APIO_EMULATION is defined (i.e. on non-RP2350 hosts).

Returns: Pointer to the configured epio instance, or NULL on failure.

See also: epio_init(), epio_free(), epio_update_from_apio()

◆ epio_update_from_apio()

EPIO_EXPORT void epio_update_from_apio ( epio_t * epio )

Update a live epio instance from the current accumulated apio state.

Applies any apio configuration or state accumulated since the last call to epio_from_apio() or epio_update_from_apio() to the running epio instance, without disturbing the live runtime state of already-enabled SMs.

Specifically:

PIO instruction memory is updated for all blocks (safe: instructions are append-only once written; existing slots are never modified in place).
SM configuration registers and debug info are applied only to SMs not yet enabled in epio, preserving the runtime state (PC, X, Y, ISR, OSR, FIFOs, stall, delay) of already-running SMs.
Pre-instructions, TX FIFO entries, and RX FIFO entries are applied to all SMs regardless of enabled state, as these are intentional modifications to live SM state (e.g. the PULL/MOV X OSR pair emitted by pio_switch_rom_region to atomically update the address SM's X register).
Newly enabled SMs (those enabled in apio but not yet enabled in epio) are started; already-enabled SMs are left alone.
GPIO configuration is re-applied from the accumulated apio GPIO state.

After applying, the accumulated pre_instr_count, tx_fifo_count, and rx_fifo_count in the apio global state are reset to zero so that the next call sees only the delta.

Must be called after any firmware function that uses APIO_ASM_CONTINUE() to extend the PIO configuration of a live epio instance:

pio_switch_rom_region() — updates the address SM's X register via PULL/MOV X OSR pre-instructions.
pio_setup_address_monitor_pios() — appends two new SMs for CS monitoring and address capture.

Parameters

epio	The live epio instance to update. Must not be NULL.

See also: epio_from_apio()