Programmable I/O (PIO) API. More...

Modules
	sm_config
	PIO state machine configuration.

	pio_instructions
	PIO instruction encoding.

Macros
#define	pio0 pio0_hw

#define	pio1 pio1_hw

Enumerations
enum	pio_fifo_join { PIO_FIFO_JOIN_NONE = 0, PIO_FIFO_JOIN_TX = 1, PIO_FIFO_JOIN_RX = 2 }
	FIFO join states.

enum	pio_mov_status_type { STATUS_TX_LESSTHAN = 0, STATUS_RX_LESSTHAN = 1 }
	MOV status types.

enum	pio_interrupt_source { pis_interrupt0 = PIO_INTR_SM0_LSB, pis_interrupt1 = PIO_INTR_SM1_LSB, pis_interrupt2 = PIO_INTR_SM2_LSB, pis_interrupt3 = PIO_INTR_SM3_LSB, pis_sm0_tx_fifo_not_full = PIO_INTR_SM0_TXNFULL_LSB, pis_sm1_tx_fifo_not_full = PIO_INTR_SM1_TXNFULL_LSB, pis_sm2_tx_fifo_not_full = PIO_INTR_SM2_TXNFULL_LSB, pis_sm3_tx_fifo_not_full = PIO_INTR_SM3_TXNFULL_LSB, pis_sm0_rx_fifo_not_empty = PIO_INTR_SM0_RXNEMPTY_LSB, pis_sm1_rx_fifo_not_empty = PIO_INTR_SM1_RXNEMPTY_LSB, pis_sm2_rx_fifo_not_empty = PIO_INTR_SM2_RXNEMPTY_LSB, pis_sm3_rx_fifo_not_empty = PIO_INTR_SM3_RXNEMPTY_LSB }
	PIO interrupt source numbers for pio related IRQs.

Functions
static void	pio_sm_set_config (PIO pio, uint sm, const pio_sm_config *config)
	Apply a state machine configuration to a state machine. More...

static uint	pio_get_index (PIO pio)
	Return the instance number of a PIO instance. More...

static void	pio_gpio_init (PIO pio, uint pin)
	Setup the function select for a GPIO to use output from the given PIO instance. More...

static uint	pio_get_dreq (PIO pio, uint sm, bool is_tx)
	Return the DREQ to use for pacing transfers to/from a particular state machine FIFO. More...

bool	pio_can_add_program (PIO pio, const pio_program_t *program)
	Determine whether the given program can (at the time of the call) be loaded onto the PIO instance. More...

bool	pio_can_add_program_at_offset (PIO pio, const pio_program_t *program, uint offset)
	Determine whether the given program can (at the time of the call) be loaded onto the PIO instance starting at a particular location. More...

uint	pio_add_program (PIO pio, const pio_program_t *program)
	Attempt to load the program, panicking if not possible. More...

void	pio_add_program_at_offset (PIO pio, const pio_program_t *program, uint offset)
	Attempt to load the program at the specified instruction memory offset, panicking if not possible. More...

void	pio_remove_program (PIO pio, const pio_program_t *program, uint loaded_offset)
	Remove a program from a PIO instance's instruction memory. More...

void	pio_clear_instruction_memory (PIO pio)
	Clears all of a PIO instance's instruction memory. More...

void	pio_sm_init (PIO pio, uint sm, uint initial_pc, const pio_sm_config *config)
	Resets the state machine to a consistent state, and configures it. More...

static void	pio_sm_set_enabled (PIO pio, uint sm, bool enabled)
	Enable or disable a PIO state machine. More...

static void	pio_set_sm_mask_enabled (PIO pio, uint32_t mask, bool enabled)
	Enable or disable multiple PIO state machines. More...

static void	pio_sm_restart (PIO pio, uint sm)
	Restart a state machine with a known state. More...

static void	pio_restart_sm_mask (PIO pio, uint32_t mask)
	Restart multiple state machine with a known state. More...

static void	pio_sm_clkdiv_restart (PIO pio, uint sm)
	Restart a state machine's clock divider from a phase of 0. More...

static void	pio_clkdiv_restart_sm_mask (PIO pio, uint32_t mask)
	Restart multiple state machines' clock dividers from a phase of 0. More...

static void	pio_enable_sm_mask_in_sync (PIO pio, uint32_t mask)
	Enable multiple PIO state machines synchronizing their clock dividers. More...

static void	pio_set_irq0_source_enabled (PIO pio, enum pio_interrupt_source source, bool enabled)
	Enable/Disable a single source on a PIO's IRQ 0. More...

static void	pio_set_irq1_source_enabled (PIO pio, enum pio_interrupt_source source, bool enabled)
	Enable/Disable a single source on a PIO's IRQ 1. More...

static void	pio_set_irq0_source_mask_enabled (PIO pio, uint32_t source_mask, bool enabled)
	Enable/Disable multiple sources on a PIO's IRQ 0. More...

static void	pio_set_irq1_source_mask_enabled (PIO pio, uint32_t source_mask, bool enabled)
	Enable/Disable multiple sources on a PIO's IRQ 1. More...

static void	pio_set_irqn_source_enabled (PIO pio, uint irq_index, enum pio_interrupt_source source, bool enabled)
	Enable/Disable a single source on a PIO's specified (0/1) IRQ index. More...

static void	pio_set_irqn_source_mask_enabled (PIO pio, uint irq_index, uint32_t source_mask, bool enabled)
	Enable/Disable multiple sources on a PIO's specified (0/1) IRQ index. More...

static bool	pio_interrupt_get (PIO pio, uint pio_interrupt_num)
	Determine if a particular PIO interrupt is set. More...

static void	pio_interrupt_clear (PIO pio, uint pio_interrupt_num)
	Clear a particular PIO interrupt. More...

static uint8_t	pio_sm_get_pc (PIO pio, uint sm)
	Return the current program counter for a state machine. More...

static void	pio_sm_exec (PIO pio, uint sm, uint instr)
	Immediately execute an instruction on a state machine. More...

static bool	pio_sm_is_exec_stalled (PIO pio, uint sm)
	Determine if an instruction set by pio_sm_exec() is stalled executing. More...

static void	pio_sm_exec_wait_blocking (PIO pio, uint sm, uint instr)
	Immediately execute an instruction on a state machine and wait for it to complete. More...

static void	pio_sm_set_wrap (PIO pio, uint sm, uint wrap_target, uint wrap)
	Set the current wrap configuration for a state machine. More...

static void	pio_sm_set_out_pins (PIO pio, uint sm, uint out_base, uint out_count)
	Set the current 'out' pins for a state machine. More...

static void	pio_sm_set_set_pins (PIO pio, uint sm, uint set_base, uint set_count)
	Set the current 'set' pins for a state machine. More...

static void	pio_sm_set_in_pins (PIO pio, uint sm, uint in_base)
	Set the current 'in' pins for a state machine. More...

static void	pio_sm_set_sideset_pins (PIO pio, uint sm, uint sideset_base)
	Set the current 'sideset' pins for a state machine. More...

static void	pio_sm_put (PIO pio, uint sm, uint32_t data)
	Write a word of data to a state machine's TX FIFO. More...

static uint32_t	pio_sm_get (PIO pio, uint sm)
	Read a word of data from a state machine's RX FIFO. More...

static bool	pio_sm_is_rx_fifo_full (PIO pio, uint sm)
	Determine if a state machine's RX FIFO is full. More...

static bool	pio_sm_is_rx_fifo_empty (PIO pio, uint sm)
	Determine if a state machine's RX FIFO is empty. More...

static uint	pio_sm_get_rx_fifo_level (PIO pio, uint sm)
	Return the number of elements currently in a state machine's RX FIFO. More...

static bool	pio_sm_is_tx_fifo_full (PIO pio, uint sm)
	Determine if a state machine's TX FIFO is full. More...

static bool	pio_sm_is_tx_fifo_empty (PIO pio, uint sm)
	Determine if a state machine's TX FIFO is empty. More...

static uint	pio_sm_get_tx_fifo_level (PIO pio, uint sm)
	Return the number of elements currently in a state machine's TX FIFO. More...

static void	pio_sm_put_blocking (PIO pio, uint sm, uint32_t data)
	Write a word of data to a state machine's TX FIFO, blocking if the FIFO is full. More...

static uint32_t	pio_sm_get_blocking (PIO pio, uint sm)
	Read a word of data from a state machine's RX FIFO, blocking if the FIFO is empty. More...

void	pio_sm_drain_tx_fifo (PIO pio, uint sm)
	Empty out a state machine's TX FIFO. More...

static void	pio_sm_set_clkdiv_int_frac (PIO pio, uint sm, uint16_t div_int, uint8_t div_frac)
	set the current clock divider for a state machine using a 16:8 fraction More...

static void	pio_sm_set_clkdiv (PIO pio, uint sm, float div)
	set the current clock divider for a state machine More...

static void	pio_sm_clear_fifos (PIO pio, uint sm)
	Clear a state machine's TX and RX FIFOs. More...

void	pio_sm_set_pins (PIO pio, uint sm, uint32_t pin_values)
	Use a state machine to set a value on all pins for the PIO instance. More...

void	pio_sm_set_pins_with_mask (PIO pio, uint sm, uint32_t pin_values, uint32_t pin_mask)
	Use a state machine to set a value on multiple pins for the PIO instance. More...

void	pio_sm_set_pindirs_with_mask (PIO pio, uint sm, uint32_t pin_dirs, uint32_t pin_mask)
	Use a state machine to set the pin directions for multiple pins for the PIO instance. More...

void	pio_sm_set_consecutive_pindirs (PIO pio, uint sm, uint pin_base, uint pin_count, bool is_out)
	Use a state machine to set the same pin direction for multiple consecutive pins for the PIO instance. More...

void	pio_sm_claim (PIO pio, uint sm)
	Mark a state machine as used. More...

void	pio_claim_sm_mask (PIO pio, uint sm_mask)
	Mark multiple state machines as used. More...

void	pio_sm_unclaim (PIO pio, uint sm)
	Mark a state machine as no longer used. More...

int	pio_claim_unused_sm (PIO pio, bool required)
	Claim a free state machine on a PIO instance. More...

bool	pio_sm_is_claimed (PIO pio, uint sm)
	Determine if a PIO state machine is claimed. More...

Detailed Description

Programmable I/O (PIO) API.

A programmable input/output block (PIO) is a versatile hardware interface which can support a number of different IO standards. There are two PIO blocks in the RP2040.

Each PIO is programmable in the same sense as a processor: the four state machines independently execute short, sequential programs, to manipulate GPIOs and transfer data. Unlike a general purpose processor, PIO state machines are highly specialised for IO, with a focus on determinism, precise timing, and close integration with fixed-function hardware. Each state machine is equipped with:

Two 32-bit shift registers – either direction, any shift count
Two 32-bit scratch registers
4×32 bit bus FIFO in each direction (TX/RX), reconfigurable as 8×32 in a single direction
Fractional clock divider (16 integer, 8 fractional bits)
Flexible GPIO mapping
DMA interface, sustained throughput up to 1 word per clock from system DMA
IRQ flag set/clear/status

Full details of the PIO can be found in the RP2040 datasheet.

Macro Definition Documentation

◆ pio0

#define pio0 pio0_hw

Identifier for the first (PIO 0) hardware PIO instance (for use in PIO functions).

e.g. pio_gpio_init(pio0, 5)

◆ pio1

#define pio1 pio1_hw

Identifier for the second (PIO 1) hardware PIO instance (for use in PIO functions).

e.g. pio_gpio_init(pio1, 5)

Function Documentation

◆ pio_add_program()

uint pio_add_program	(	PIO	pio,
		const pio_program_t *	program
	)

Attempt to load the program, panicking if not possible.

See also: pio_can_add_program() if you need to check whether the program can be loaded

Parameters

pio	The PIO instance; either pio0 or pio1
program	the program definition

Returns: the instruction memory offset the program is loaded at

◆ pio_add_program_at_offset()

void pio_add_program_at_offset	(	PIO	pio,
		const pio_program_t *	program,
		uint	offset
	)

Attempt to load the program at the specified instruction memory offset, panicking if not possible.

See also: pio_can_add_program_at_offset() if you need to check whether the program can be loaded

Parameters

pio	The PIO instance; either pio0 or pio1
program	the program definition
offset	the instruction memory offset wanted for the start of the program

◆ pio_can_add_program()

bool pio_can_add_program	(	PIO	pio,
		const pio_program_t *	program
	)

Determine whether the given program can (at the time of the call) be loaded onto the PIO instance.

Parameters

pio	The PIO instance; either pio0 or pio1
program	the program definition

Returns: true if the program can be loaded; false if there is not suitable space in the instruction memory

◆ pio_can_add_program_at_offset()

bool pio_can_add_program_at_offset	(	PIO	pio,
		const pio_program_t *	program,
		uint	offset
	)

Determine whether the given program can (at the time of the call) be loaded onto the PIO instance starting at a particular location.

Parameters

pio	The PIO instance; either pio0 or pio1
program	the program definition
offset	the instruction memory offset wanted for the start of the program

Returns: true if the program can be loaded at that location; false if there is not space in the instruction memory

◆ pio_claim_sm_mask()

void pio_claim_sm_mask	(	PIO	pio,
		uint	sm_mask
	)

Mark multiple state machines as used.

Method for cooperative claiming of hardware. Will cause a panic if any of the state machines are already claimed. Use of this method by libraries detects accidental configurations that would fail in unpredictable ways.

Parameters

pio	The PIO instance; either pio0 or pio1
sm_mask	Mask of state machine indexes

◆ pio_claim_unused_sm()

int pio_claim_unused_sm	(	PIO	pio,
		bool	required
	)

Claim a free state machine on a PIO instance.

Parameters

pio	The PIO instance; either pio0 or pio1
required	if true the function will panic if none are available

Returns: the state machine index or -1 if required was false, and none were free

◆ pio_clear_instruction_memory()

void pio_clear_instruction_memory ( PIO pio )

Clears all of a PIO instance's instruction memory.

Parameters

pio	The PIO instance; either pio0 or pio1

◆ pio_clkdiv_restart_sm_mask()

static void pio_clkdiv_restart_sm_mask	(	PIO	pio,
		uint32_t	mask
	)

inlinestatic

Restart multiple state machines' clock dividers from a phase of 0.

Each state machine's clock divider is a free-running piece of hardware, that generates a pattern of clock enable pulses for the state machine, based only on the configured integer/fractional divisor. The pattern of running/halted cycles slows the state machine's execution to some controlled rate.

This function simultaneously clears the integer and fractional phase accumulators of multiple state machines' clock dividers. If these state machines all have the same integer and fractional divisors configured, their clock dividers will run in precise deterministic lockstep from this point.

With their execution clocks synchronised in this way, it is then safe to e.g. have multiple state machines performing a 'wait irq' on the same flag, and all clear it on the same cycle.

Also note that this function can be called whilst state machines are running (e.g. if you have just changed the clock divisors of some state machines and wish to resynchronise them), and that disabling a state machine does not halt its clock divider: that is, if multiple state machines have their clocks synchronised, you can safely disable and reenable one of the state machines without losing synchronisation.

Parameters

pio	The PIO instance; either pio0 or pio1
mask	bit mask of state machine indexes to modify the enabled state of

◆ pio_enable_sm_mask_in_sync()

static void pio_enable_sm_mask_in_sync	(	PIO	pio,
		uint32_t	mask
	)

inlinestatic

Enable multiple PIO state machines synchronizing their clock dividers.

This is equivalent to calling both pio_set_sm_mask_enabled() and pio_clkdiv_restart_sm_mask() on the same clock cycle. All state machines specified by 'mask' are started simultaneously and, assuming they have the same clock divisors, their divided clocks will stay precisely synchronised.

Parameters

pio	The PIO instance; either pio0 or pio1
mask	bit mask of state machine indexes to modify the enabled state of

◆ pio_get_dreq()

static uint pio_get_dreq	(	PIO	pio,
		uint	sm,
		bool	is_tx
	)

inlinestatic

Return the DREQ to use for pacing transfers to/from a particular state machine FIFO.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)
is_tx	true for sending data to the state machine, false for receiving data from the state machine

◆ pio_get_index()

static uint pio_get_index ( PIO pio )

inlinestatic

Return the instance number of a PIO instance.

Parameters

pio	The PIO instance; either pio0 or pio1

Returns: the PIO instance number (either 0 or 1)

◆ pio_gpio_init()

static void pio_gpio_init	(	PIO	pio,
		uint	pin
	)

inlinestatic

Setup the function select for a GPIO to use output from the given PIO instance.

PIO appears as an alternate function in the GPIO muxing, just like an SPI or UART. This function configures that multiplexing to connect a given PIO instance to a GPIO. Note that this is not necessary for a state machine to be able to read the input value from a GPIO, but only for it to set the output value or output enable.

Parameters

pio	The PIO instance; either pio0 or pio1
pin	the GPIO pin whose function select to set

◆ pio_interrupt_clear()

static void pio_interrupt_clear	(	PIO	pio,
		uint	pio_interrupt_num
	)

inlinestatic

Clear a particular PIO interrupt.

Parameters

pio	The PIO instance; either pio0 or pio1
pio_interrupt_num	the PIO interrupt number 0-7

◆ pio_interrupt_get()

static bool pio_interrupt_get	(	PIO	pio,
		uint	pio_interrupt_num
	)

inlinestatic

Determine if a particular PIO interrupt is set.

Parameters

pio	The PIO instance; either pio0 or pio1
pio_interrupt_num	the PIO interrupt number 0-7

Returns: true if corresponding PIO interrupt is currently set

◆ pio_remove_program()

void pio_remove_program	(	PIO	pio,
		const pio_program_t *	program,
		uint	loaded_offset
	)

Remove a program from a PIO instance's instruction memory.

Parameters

pio	The PIO instance; either pio0 or pio1
program	the program definition
loaded_offset	the loaded offset returned when the program was added

◆ pio_restart_sm_mask()

static void pio_restart_sm_mask	(	PIO	pio,
		uint32_t	mask
	)

inlinestatic

Restart multiple state machine with a known state.

This method clears the ISR, shift counters, clock divider counter pin write flags, delay counter, latched EXEC instruction, and IRQ wait condition.

Parameters

pio	The PIO instance; either pio0 or pio1
mask	bit mask of state machine indexes to modify the enabled state of

◆ pio_set_irq0_source_enabled()

static void pio_set_irq0_source_enabled	(	PIO	pio,
		enum pio_interrupt_source	source,
		bool	enabled
	)

inlinestatic

Enable/Disable a single source on a PIO's IRQ 0.

Parameters

pio	The PIO instance; either pio0 or pio1
source	the source number (see pio_interrupt_source)
enabled	true to enable IRQ 0 for the source, false to disable.

◆ pio_set_irq0_source_mask_enabled()

static void pio_set_irq0_source_mask_enabled	(	PIO	pio,
		uint32_t	source_mask,
		bool	enabled
	)

inlinestatic

Enable/Disable multiple sources on a PIO's IRQ 0.

Parameters

pio	The PIO instance; either pio0 or pio1
source_mask	Mask of bits, one for each source number (see pio_interrupt_source) to affect
enabled	true to enable all the sources specified in the mask on IRQ 0, false to disable all the sources specified in the mask on IRQ 0

◆ pio_set_irq1_source_enabled()

static void pio_set_irq1_source_enabled	(	PIO	pio,
		enum pio_interrupt_source	source,
		bool	enabled
	)

inlinestatic

Enable/Disable a single source on a PIO's IRQ 1.

Parameters

pio	The PIO instance; either pio0 or pio1
source	the source number (see pio_interrupt_source)
enabled	true to enable IRQ 0 for the source, false to disable.

◆ pio_set_irq1_source_mask_enabled()

static void pio_set_irq1_source_mask_enabled	(	PIO	pio,
		uint32_t	source_mask,
		bool	enabled
	)

inlinestatic

Enable/Disable multiple sources on a PIO's IRQ 1.

Parameters

pio	The PIO instance; either pio0 or pio1
source_mask	Mask of bits, one for each source number (see pio_interrupt_source) to affect
enabled	true to enable all the sources specified in the mask on IRQ 1, false to disable all the source specified in the mask on IRQ 1

◆ pio_set_irqn_source_enabled()

static void pio_set_irqn_source_enabled	(	PIO	pio,
		uint	irq_index,
		enum pio_interrupt_source	source,
		bool	enabled
	)

inlinestatic

Enable/Disable a single source on a PIO's specified (0/1) IRQ index.

Parameters

pio	The PIO instance; either pio0 or pio1
irq_index	the IRQ index; either 0 or 1
source	the source number (see pio_interrupt_source)
enabled	true to enable the source on the specified IRQ, false to disable.

◆ pio_set_irqn_source_mask_enabled()

static void pio_set_irqn_source_mask_enabled	(	PIO	pio,
		uint	irq_index,
		uint32_t	source_mask,
		bool	enabled
	)

inlinestatic

Enable/Disable multiple sources on a PIO's specified (0/1) IRQ index.

Parameters

pio	The PIO instance; either pio0 or pio1
irq_index	the IRQ index; either 0 or 1
source_mask	Mask of bits, one for each source number (see pio_interrupt_source) to affect
enabled	true to enable all the sources specified in the mask on the specified IRQ, false to disable all the sources specified in the mask on the specified IRQ

◆ pio_set_sm_mask_enabled()

static void pio_set_sm_mask_enabled	(	PIO	pio,
		uint32_t	mask,
		bool	enabled
	)

inlinestatic

Enable or disable multiple PIO state machines.

Note that this method just sets the enabled state of the state machine; if now enabled they continue exactly from where they left off.

See also: pio_enable_sm_mask_in_sync() if you wish to enable multiple state machines and ensure their clock dividers are in sync.

Parameters

pio	The PIO instance; either pio0 or pio1
mask	bit mask of state machine indexes to modify the enabled state of
enabled	true to enable the state machines; false to disable

◆ pio_sm_claim()

void pio_sm_claim	(	PIO	pio,
		uint	sm
	)

Mark a state machine as used.

Method for cooperative claiming of hardware. Will cause a panic if the state machine is already claimed. Use of this method by libraries detects accidental configurations that would fail in unpredictable ways.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)

◆ pio_sm_clear_fifos()

static void pio_sm_clear_fifos	(	PIO	pio,
		uint	sm
	)

inlinestatic

Clear a state machine's TX and RX FIFOs.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)

◆ pio_sm_clkdiv_restart()

static void pio_sm_clkdiv_restart	(	PIO	pio,
		uint	sm
	)

inlinestatic

Restart a state machine's clock divider from a phase of 0.

Each state machine's clock divider is a free-running piece of hardware, that generates a pattern of clock enable pulses for the state machine, based only on the configured integer/fractional divisor. The pattern of running/halted cycles slows the state machine's execution to some controlled rate.

This function clears the divider's integer and fractional phase accumulators so that it restarts this pattern from the beginning. It is called automatically by pio_sm_init() but can also be called at a later time, when you enable the state machine, to ensure precisely consistent timing each time you load and run a given PIO program.

More commonly this hardware mechanism is used to synchronise the execution clocks of multiple state machines – see pio_clkdiv_restart_sm_mask().

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)

◆ pio_sm_drain_tx_fifo()

void pio_sm_drain_tx_fifo	(	PIO	pio,
		uint	sm
	)

Empty out a state machine's TX FIFO.

This method executes pull instructions on the state machine until the TX FIFO is empty. This disturbs the contents of the OSR, so see also pio_sm_clear_fifos() which clears both FIFOs but leaves the state machine's internal state undisturbed.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)

See also: pio_sm_clear_fifos()

◆ pio_sm_exec()

static void pio_sm_exec	(	PIO	pio,
		uint	sm,
		uint	instr
	)

inlinestatic

Immediately execute an instruction on a state machine.

This instruction is executed instead of the next instruction in the normal control flow on the state machine. Subsequent calls to this method replace the previous executed instruction if it is still running.

See also: pio_sm_is_exec_stalled() to see if an executed instruction is still running (i.e. it is stalled on some condition)

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)
instr	the encoded PIO instruction

◆ pio_sm_exec_wait_blocking()

static void pio_sm_exec_wait_blocking	(	PIO	pio,
		uint	sm,
		uint	instr
	)

inlinestatic

Immediately execute an instruction on a state machine and wait for it to complete.

This instruction is executed instead of the next instruction in the normal control flow on the state machine. Subsequent calls to this method replace the previous executed instruction if it is still running.

See also: pio_sm_is_exec_stalled() to see if an executed instruction is still running (i.e. it is stalled on some condition)

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)
instr	the encoded PIO instruction

◆ pio_sm_get()

static uint32_t pio_sm_get	(	PIO	pio,
		uint	sm
	)

inlinestatic

Read a word of data from a state machine's RX FIFO.

This is a raw FIFO access that does not check for emptiness. If the FIFO is empty, the hardware ignores the attempt to read from the FIFO (the FIFO remains in an empty state following the read) and the sticky RXUNDER flag for this FIFO is set in FDEBUG to indicate that the system tried to read from this FIFO when empty. The data returned by this function is undefined when the FIFO is empty.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)

See also: pio_sm_get_blocking()

◆ pio_sm_get_blocking()

static uint32_t pio_sm_get_blocking	(	PIO	pio,
		uint	sm
	)

inlinestatic

Read a word of data from a state machine's RX FIFO, blocking if the FIFO is empty.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)

◆ pio_sm_get_pc()

static uint8_t pio_sm_get_pc	(	PIO	pio,
		uint	sm
	)

inlinestatic

Return the current program counter for a state machine.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)

Returns: the program counter

◆ pio_sm_get_rx_fifo_level()

static uint pio_sm_get_rx_fifo_level	(	PIO	pio,
		uint	sm
	)

inlinestatic

Return the number of elements currently in a state machine's RX FIFO.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)

Returns: the number of elements in the RX FIFO

◆ pio_sm_get_tx_fifo_level()

static uint pio_sm_get_tx_fifo_level	(	PIO	pio,
		uint	sm
	)

inlinestatic

Return the number of elements currently in a state machine's TX FIFO.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)

Returns: the number of elements in the TX FIFO

◆ pio_sm_init()

void pio_sm_init	(	PIO	pio,
		uint	sm,
		uint	initial_pc,
		const pio_sm_config *	config
	)

Resets the state machine to a consistent state, and configures it.

This method:

Disables the state machine (if running)
Clears the FIFOs
Applies the configuration specified by 'config'
Resets any internal state e.g. shift counters
Jumps to the initial program location given by 'initial_pc'

The state machine is left disabled on return from this call.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)
initial_pc	the initial program memory offset to run from
config	the configuration to apply (or NULL to apply defaults)

◆ pio_sm_is_claimed()

bool pio_sm_is_claimed	(	PIO	pio,
		uint	sm
	)

Determine if a PIO state machine is claimed.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)

Returns: true if claimed, false otherwise

See also: pio_sm_claim; pio_claim_sm_mask

◆ pio_sm_is_exec_stalled()

static bool pio_sm_is_exec_stalled	(	PIO	pio,
		uint	sm
	)

inlinestatic

Determine if an instruction set by pio_sm_exec() is stalled executing.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)

Returns: true if the executed instruction is still running (stalled)

◆ pio_sm_is_rx_fifo_empty()

static bool pio_sm_is_rx_fifo_empty	(	PIO	pio,
		uint	sm
	)

inlinestatic

Determine if a state machine's RX FIFO is empty.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)

Returns: true if the RX FIFO is empty

◆ pio_sm_is_rx_fifo_full()

static bool pio_sm_is_rx_fifo_full	(	PIO	pio,
		uint	sm
	)

inlinestatic

Determine if a state machine's RX FIFO is full.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)

Returns: true if the RX FIFO is full

◆ pio_sm_is_tx_fifo_empty()

static bool pio_sm_is_tx_fifo_empty	(	PIO	pio,
		uint	sm
	)

inlinestatic

Determine if a state machine's TX FIFO is empty.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)

Returns: true if the TX FIFO is empty

◆ pio_sm_is_tx_fifo_full()

static bool pio_sm_is_tx_fifo_full	(	PIO	pio,
		uint	sm
	)

inlinestatic

Determine if a state machine's TX FIFO is full.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)

Returns: true if the TX FIFO is full

◆ pio_sm_put()

static void pio_sm_put	(	PIO	pio,
		uint	sm,
		uint32_t	data
	)

inlinestatic

Write a word of data to a state machine's TX FIFO.

This is a raw FIFO access that does not check for fullness. If the FIFO is full, the FIFO contents and state are not affected by the write attempt. Hardware sets the TXOVER sticky flag for this FIFO in FDEBUG, to indicate that the system attempted to write to a full FIFO.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)
data	the 32 bit data value

See also: pio_sm_put_blocking()

◆ pio_sm_put_blocking()

static void pio_sm_put_blocking	(	PIO	pio,
		uint	sm,
		uint32_t	data
	)

inlinestatic

Write a word of data to a state machine's TX FIFO, blocking if the FIFO is full.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)
data	the 32 bit data value

◆ pio_sm_restart()

static void pio_sm_restart	(	PIO	pio,
		uint	sm
	)

inlinestatic

Restart a state machine with a known state.

This method clears the ISR, shift counters, clock divider counter pin write flags, delay counter, latched EXEC instruction, and IRQ wait condition.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)

◆ pio_sm_set_clkdiv()

static void pio_sm_set_clkdiv	(	PIO	pio,
		uint	sm,
		float	div
	)

inlinestatic

set the current clock divider for a state machine

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)
div	the floating point clock divider

◆ pio_sm_set_clkdiv_int_frac()

static void pio_sm_set_clkdiv_int_frac	(	PIO	pio,
		uint	sm,
		uint16_t	div_int,
		uint8_t	div_frac
	)

inlinestatic

set the current clock divider for a state machine using a 16:8 fraction

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)
div_int	the integer part of the clock divider
div_frac	the fractional part of the clock divider in 1/256s

◆ pio_sm_set_config()

static void pio_sm_set_config	(	PIO	pio,
		uint	sm,
		const pio_sm_config *	config
	)

inlinestatic

Apply a state machine configuration to a state machine.

Parameters

pio	Handle to PIO instance; either pio0 or pio1
sm	State machine index (0..3)
config	the configuration to apply

◆ pio_sm_set_consecutive_pindirs()

void pio_sm_set_consecutive_pindirs	(	PIO	pio,
		uint	sm,
		uint	pin_base,
		uint	pin_count,
		bool	is_out
	)

Use a state machine to set the same pin direction for multiple consecutive pins for the PIO instance.

This method repeatedly reconfigures the target state machine's pin configuration and executes 'set' instructions to set the pin direction on consecutive pins, before restoring the state machine's pin configuration to what it was.

This method is provided as a convenience to set initial pin directions, and should not be used against a state machine that is enabled.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3) to use
pin_base	the first pin to set a direction for
pin_count	the count of consecutive pins to set the direction for
is_out	the direction to set; true = out, false = in

◆ pio_sm_set_enabled()

static void pio_sm_set_enabled	(	PIO	pio,
		uint	sm,
		bool	enabled
	)

inlinestatic

Enable or disable a PIO state machine.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)
enabled	true to enable the state machine; false to disable

◆ pio_sm_set_in_pins()

static void pio_sm_set_in_pins	(	PIO	pio,
		uint	sm,
		uint	in_base
	)

inlinestatic

Set the current 'in' pins for a state machine.

Can overlap with the 'out', 'set' and 'sideset' pins

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)
in_base	0-31 First pin to use as input

◆ pio_sm_set_out_pins()

static void pio_sm_set_out_pins	(	PIO	pio,
		uint	sm,
		uint	out_base,
		uint	out_count
	)

inlinestatic

Set the current 'out' pins for a state machine.

Can overlap with the 'in', 'set' and 'sideset' pins

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)
out_base	0-31 First pin to set as output
out_count	0-32 Number of pins to set.

◆ pio_sm_set_pindirs_with_mask()

void pio_sm_set_pindirs_with_mask	(	PIO	pio,
		uint	sm,
		uint32_t	pin_dirs,
		uint32_t	pin_mask
	)

Use a state machine to set the pin directions for multiple pins for the PIO instance.

This method repeatedly reconfigures the target state machine's pin configuration and executes 'set' instructions to set pin directions on up to 32 pins, before restoring the state machine's pin configuration to what it was.

This method is provided as a convenience to set initial pin directions, and should not be used against a state machine that is enabled.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3) to use
pin_dirs	the pin directions to set - 1 = out, 0 = in (if the corresponding bit in pin_mask is set)
pin_mask	a bit for each pin to indicate whether the corresponding pin_value for that pin should be applied.

◆ pio_sm_set_pins()

void pio_sm_set_pins	(	PIO	pio,
		uint	sm,
		uint32_t	pin_values
	)

Use a state machine to set a value on all pins for the PIO instance.

This method repeatedly reconfigures the target state machine's pin configuration and executes 'set' instructions to set values on all 32 pins, before restoring the state machine's pin configuration to what it was.

This method is provided as a convenience to set initial pin states, and should not be used against a state machine that is enabled.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3) to use
pin_values	the pin values to set

◆ pio_sm_set_pins_with_mask()

void pio_sm_set_pins_with_mask	(	PIO	pio,
		uint	sm,
		uint32_t	pin_values,
		uint32_t	pin_mask
	)

Use a state machine to set a value on multiple pins for the PIO instance.

This method repeatedly reconfigures the target state machine's pin configuration and executes 'set' instructions to set values on up to 32 pins, before restoring the state machine's pin configuration to what it was.

This method is provided as a convenience to set initial pin states, and should not be used against a state machine that is enabled.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3) to use
pin_values	the pin values to set (if the corresponding bit in pin_mask is set)
pin_mask	a bit for each pin to indicate whether the corresponding pin_value for that pin should be applied.

◆ pio_sm_set_set_pins()

static void pio_sm_set_set_pins	(	PIO	pio,
		uint	sm,
		uint	set_base,
		uint	set_count
	)

inlinestatic

Set the current 'set' pins for a state machine.

Can overlap with the 'in', 'out' and 'sideset' pins

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)
set_base	0-31 First pin to set as
set_count	0-5 Number of pins to set.

◆ pio_sm_set_sideset_pins()

static void pio_sm_set_sideset_pins	(	PIO	pio,
		uint	sm,
		uint	sideset_base
	)

inlinestatic

Set the current 'sideset' pins for a state machine.

Can overlap with the 'in', 'out' and 'set' pins

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)
sideset_base	0-31 base pin for 'side set'

◆ pio_sm_set_wrap()

static void pio_sm_set_wrap	(	PIO	pio,
		uint	sm,
		uint	wrap_target,
		uint	wrap
	)

inlinestatic

Set the current wrap configuration for a state machine.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)
wrap_target	the instruction memory address to wrap to
wrap	the instruction memory address after which to set the program counter to wrap_target if the instruction does not itself update the program_counter

◆ pio_sm_unclaim()

void pio_sm_unclaim	(	PIO	pio,
		uint	sm
	)

Mark a state machine as no longer used.

Method for cooperative claiming of hardware.

Parameters

pio	The PIO instance; either pio0 or pio1
sm	State machine index (0..3)

Modules

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ pio0

◆ pio1

Function Documentation

◆ pio_add_program()

◆ pio_add_program_at_offset()

◆ pio_can_add_program()

◆ pio_can_add_program_at_offset()

◆ pio_claim_sm_mask()

◆ pio_claim_unused_sm()

◆ pio_clear_instruction_memory()

◆ pio_clkdiv_restart_sm_mask()

◆ pio_enable_sm_mask_in_sync()

◆ pio_get_dreq()

◆ pio_get_index()

◆ pio_gpio_init()

◆ pio_interrupt_clear()

◆ pio_interrupt_get()

◆ pio_remove_program()

◆ pio_restart_sm_mask()

◆ pio_set_irq0_source_enabled()

◆ pio_set_irq0_source_mask_enabled()

◆ pio_set_irq1_source_enabled()

◆ pio_set_irq1_source_mask_enabled()

◆ pio_set_irqn_source_enabled()

◆ pio_set_irqn_source_mask_enabled()

◆ pio_set_sm_mask_enabled()

◆ pio_sm_claim()

◆ pio_sm_clear_fifos()

◆ pio_sm_clkdiv_restart()

◆ pio_sm_drain_tx_fifo()

◆ pio_sm_exec()

◆ pio_sm_exec_wait_blocking()

◆ pio_sm_get()

◆ pio_sm_get_blocking()

◆ pio_sm_get_pc()

◆ pio_sm_get_rx_fifo_level()

◆ pio_sm_get_tx_fifo_level()

◆ pio_sm_init()

◆ pio_sm_is_claimed()

◆ pio_sm_is_exec_stalled()

◆ pio_sm_is_rx_fifo_empty()

◆ pio_sm_is_rx_fifo_full()

◆ pio_sm_is_tx_fifo_empty()

◆ pio_sm_is_tx_fifo_full()

◆ pio_sm_put()

◆ pio_sm_put_blocking()

◆ pio_sm_restart()

◆ pio_sm_set_clkdiv()

◆ pio_sm_set_clkdiv_int_frac()

◆ pio_sm_set_config()

◆ pio_sm_set_consecutive_pindirs()

◆ pio_sm_set_enabled()

◆ pio_sm_set_in_pins()

◆ pio_sm_set_out_pins()

◆ pio_sm_set_pindirs_with_mask()

◆ pio_sm_set_pins()

◆ pio_sm_set_pins_with_mask()

◆ pio_sm_set_set_pins()

◆ pio_sm_set_sideset_pins()

◆ pio_sm_set_wrap()

◆ pio_sm_unclaim()