hardware_pio

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
#define	PIO_NUM(pio)
	Returns the PIO number for a PIO instance. More...
#define	PIO_INSTANCE(instance)
	Returns the PIO instance with the given PIO number. More...
#define	PIO_FUNCSEL_NUM(pio, gpio)
	Returns gpio_function_t needed to select the PIO function for the given PIO instance on the given GPIO. More...
#define	PIO_DREQ_NUM(pio, sm, is_tx)
	Returns the dreq_num_t used for pacing DMA transfers to or from a given state machine's FIFOs on this PIO instance. If is_tx is true, then it is for transfers to the PIO state machine TX FIFO else for transfers from the PIO state machine RX FIFO. More...
#define	PIO_IRQ_NUM(pio, irqn)
	Returns the irq_num_t for processor interrupts from the given PIO instance. More...

Typedefs
typedef enum pio_interrupt_source	pio_interrupt_source_t
	PIO interrupt source numbers for pio related IRQs.

Enumerations
enum	pio_fifo_join { PIO_FIFO_JOIN_NONE = 0 , PIO_FIFO_JOIN_TX = 1 , PIO_FIFO_JOIN_RX = 2 }
	FIFO join states. More...
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. More...

Functions
static uint	pio_get_gpio_base (PIO pio)
	Return the base GPIO base for the PIO instance. More...
static int	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 uint	pio_get_funcsel (PIO pio)
	Return the funcsel number of a PIO instance. More...
static PIO	pio_get_instance (uint instance)
	Convert PIO instance to hardware 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...
int	pio_set_gpio_base (PIO pio, uint gpio_base)
	Set the base GPIO base for the PIO instance. 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...
int	pio_add_program (PIO pio, const pio_program_t *program)
	Attempt to load the program. More...
int	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. 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...
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, pio_interrupt_source_t source, bool enabled)
	Enable/Disable a single source on a PIO's IRQ 0. More...
static void	pio_set_irq1_source_enabled (PIO pio, pio_interrupt_source_t 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, pio_interrupt_source_t 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_set_jmp_pin (PIO pio, uint sm, uint pin)
	Set the 'jmp' pin 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...
int	pio_sm_set_consecutive_pindirs (PIO pio, uint sm, uint pins_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...
bool	pio_claim_free_sm_and_add_program (const pio_program_t *program, PIO *pio, uint *sm, uint *offset)
	Finds a PIO and statemachine and adds a program into PIO memory. More...
bool	pio_claim_free_sm_and_add_program_for_gpio_range (const pio_program_t *program, PIO *pio, uint *sm, uint *offset, uint gpio_base, uint gpio_count, bool set_gpio_base)
	Finds a PIO and statemachine and adds a program into PIO memory. More...
void	pio_remove_program_and_unclaim_sm (const pio_program_t *program, PIO pio, uint sm, uint offset)
	Removes a program from PIO memory and unclaims the state machine. More...
static int	pio_get_irq_num (PIO pio, uint irqn)
	Return an IRQ for a PIO hardware instance. More...
static pio_interrupt_source_t	pio_get_tx_fifo_not_full_interrupt_source (uint sm)
	Return the interrupt source for a state machines TX FIFO not full interrupt. More...
static pio_interrupt_source_t	pio_get_rx_fifo_not_empty_interrupt_source (uint sm)
	Return the interrupt source for a state machines RX FIFO not empty interrupt. 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.

There are three PIO blocks in the RP2350

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 appropriate RP-series datasheet. Note that there are additional features in the RP2350 PIO implementation that mean care should be taken when writing PIO code that needs to run on both the RP2040 and the RP2350.

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)

PIO_DREQ_NUM

#define PIO_DREQ_NUM	(		pio,
			sm,
			is_tx
	)

Returns the dreq_num_t used for pacing DMA transfers to or from a given state machine's FIFOs on this PIO instance. If is_tx is true, then it is for transfers to the PIO state machine TX FIFO else for transfers from the PIO state machine RX FIFO.

Note this macro is intended to resolve at compile time, and does no parameter checking

PIO_FUNCSEL_NUM

#define PIO_FUNCSEL_NUM	(		pio,
			gpio
	)

Returns gpio_function_t needed to select the PIO function for the given PIO instance on the given GPIO.

Note this macro is intended to resolve at compile time, and does no parameter checking

PIO_INSTANCE

#define PIO_INSTANCE

(

instance

)

Returns the PIO instance with the given PIO number.

Note this macro is intended to resolve at compile time, and does no parameter checking

PIO_IRQ_NUM

#define PIO_IRQ_NUM	(		pio,
			irqn
	)

Returns the irq_num_t for processor interrupts from the given PIO instance.

Note this macro is intended to resolve at compile time, and does no parameter checking

PIO_NUM

#define PIO_NUM

(

pio

)

Returns the PIO number for a PIO instance.

Note this macro is intended to resolve at compile time, and does no parameter checking

Enumeration Type Documentation

pio_fifo_join

enum pio_fifo_join

FIFO join states.

Enumerator
PIO_FIFO_JOIN_NONE	TX FIFO length=4 is used for transmit, RX FIFO length=4 is used for receive.
PIO_FIFO_JOIN_TX	TX FIFO length=8 is used for transmit, RX FIFO is disabled.
PIO_FIFO_JOIN_RX	RX FIFO length=8 is used for receive, TX FIFO is disabled.

pio_interrupt_source

enum pio_interrupt_source

PIO interrupt source numbers for pio related IRQs.

Enumerator
pis_interrupt0	PIO interrupt 0 is raised.
pis_interrupt1	PIO interrupt 1 is raised.
pis_interrupt2	PIO interrupt 2 is raised.
pis_interrupt3	PIO interrupt 3 is raised.
pis_sm0_tx_fifo_not_full	State machine 0 TX FIFO is not full.
pis_sm1_tx_fifo_not_full	State machine 1 TX FIFO is not full.
pis_sm2_tx_fifo_not_full	State machine 2 TX FIFO is not full.
pis_sm3_tx_fifo_not_full	State machine 3 TX FIFO is not full.
pis_sm0_rx_fifo_not_empty	State machine 0 RX FIFO is not empty.
pis_sm1_rx_fifo_not_empty	State machine 1 RX FIFO is not empty.
pis_sm2_rx_fifo_not_empty	State machine 2 RX FIFO is not empty.
pis_sm3_rx_fifo_not_empty	State machine 3 RX FIFO is not empty.

Function Documentation

pio_add_program()

int pio_add_program	(	PIO	pio,
		const pio_program_t *	program
	)

Attempt to load the program.

See also

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

Parameters

pio	The PIO instance; e.g. pio0 or pio1
program	the program definition

Returns

the instruction memory offset the program is loaded at, or negative for error (for backwards compatibility with prior SDK the error value is -1 i.e. PICO_ERROR_GENERIC)

pio_add_program_at_offset()

int 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.

See also

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

Parameters

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

Returns

the instruction memory offset the program is loaded at, or negative for error (for backwards compatibility with prior SDK the error value is -1 i.e. PICO_ERROR_GENERIC)

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; e.g. 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; e.g. 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_free_sm_and_add_program()

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

Finds a PIO and statemachine and adds a program into PIO memory.

Parameters

program	PIO program to add
pio	Returns the PIO hardware instance or NULL if no PIO is available
sm	Returns the index of the PIO state machine that was claimed
offset	Returns the instruction memory offset of the start of the program

Returns

true on success, false otherwise

See also

pio_remove_program_unclaim_sm

pio_claim_free_sm_and_add_program_for_gpio_range()

bool pio_claim_free_sm_and_add_program_for_gpio_range	(	const pio_program_t *	program,
		PIO *	pio,
		uint *	sm,
		uint *	offset,
		uint	gpio_base,
		uint	gpio_count,
		bool	set_gpio_base
	)

Finds a PIO and statemachine and adds a program into PIO memory.

This variation of pio_claim_free_sm_and_add_program is useful on RP2350 QFN80 where the "GPIO Base" must be set per PIO instance to either address the 32 GPIOs (0->31) or the 32 GPIOS (16-47). No single PIO instance can interact with both pins 0->15 or 32->47 at the same time.

This method takes additional information about the GPIO pins needed (via gpi_base and gpio_count), and optionally will set the GPIO base (

See also

pio_set_gpio_base) of an unused PIO instance if necessary

Parameters

program	PIO program to add
pio	Returns the PIO hardware instance or NULL if no PIO is available
sm	Returns the index of the PIO state machine that was claimed
offset	Returns the instruction memory offset of the start of the program
gpio_base	the lowest GPIO number required
gpio_count	the count of GPIOs required
set_gpio_base	if there is no free SM on a PIO instance with the right GPIO base, and there IS an unused PIO instance, then that PIO will be reconfigured so that this method can succeed

Returns

true on success, false otherwise

See also

pio_remove_program_unclaim_sm

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; e.g. 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; e.g. pio0 or pio1
required	if true the function will panic if none are available

Returns

the state machine index or negative if required was false, and none were free (for backwards compatibility with prior SDK the error value is -1 i.e. PICO_ERROR_GENERIC)

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; e.g. 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 re-enable one of the state machines without losing synchronisation.

Parameters

pio	The PIO instance; e.g. 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; e.g. 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; e.g. 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_funcsel()

static uint pio_get_funcsel ( PIO  pio )

inlinestatic

Return the funcsel number of a PIO instance.

Parameters

pio	The PIO instance; e.g. pio0 or pio1

Returns

the PIO instance number (0, 1, ...)

See also

gpio_function

pio_get_gpio_base()

static uint pio_get_gpio_base ( PIO  pio )

inlinestatic

Return the base GPIO base for the PIO instance.

This method always return 0 in RP2040

Parameters

pio	The PIO instance; e.g. pio0 or pio1

Returns

the current GPIO base for the PIO instance

pio_get_index()

static uint pio_get_index ( PIO  pio )

inlinestatic

Return the instance number of a PIO instance.

Parameters

pio	The PIO instance; e.g. pio0 or pio1

Returns

the PIO instance number (0, 1, ...)

pio_get_instance()

static PIO pio_get_instance ( uint  instance )

inlinestatic

Convert PIO instance to hardware instance.

Parameters

instance

Instance of PIO, 0 or 1

Returns

the PIO hardware instance

pio_get_irq_num()

static int pio_get_irq_num ( PIO  pio, uint  irqn  )

inlinestatic

Return an IRQ for a PIO hardware instance.

Parameters

pio	PIO hardware instance
irqn	0 for PIOx_IRQ_0 or 1 for PIOx_IRQ_1 etc where x is the PIO number

Returns

The IRQ number to use for the PIO

pio_get_rx_fifo_not_empty_interrupt_source()

static pio_interrupt_source_t pio_get_rx_fifo_not_empty_interrupt_source ( uint  sm )

inlinestatic

Return the interrupt source for a state machines RX FIFO not empty interrupt.

Parameters

sm	State machine index (0..3)

Returns

The interrupt source number for use in pio_set_irqn_source_enabled or similar functions

pio_get_tx_fifo_not_full_interrupt_source()

static pio_interrupt_source_t pio_get_tx_fifo_not_full_interrupt_source ( uint  sm )

inlinestatic

Return the interrupt source for a state machines TX FIFO not full interrupt.

Parameters

sm	State machine index (0..3)

Returns

The interrupt source number for use in pio_set_irqn_source_enabled or similar functions

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; e.g. 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; e.g. 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; e.g. 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; e.g. pio0 or pio1
program	the program definition
loaded_offset	the loaded offset returned when the program was added

pio_remove_program_and_unclaim_sm()

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

Removes a program from PIO memory and unclaims the state machine.

Parameters

program	PIO program to remove from memory
pio	PIO hardware instance being used
sm	PIO state machine that was claimed
offset	offset of the program in PIO memory

See also

pio_claim_free_sm_and_add_program

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; e.g. pio0 or pio1
mask	bit mask of state machine indexes to modify the enabled state of

pio_set_gpio_base()

int pio_set_gpio_base	(	PIO	pio,
		uint	gpio_base
	)

Set the base GPIO base for the PIO instance.

Since an individual PIO accesses only 32 pins, to be able to access more pins, the PIO instance must specify a base GPIO where the instance's "pin 0" maps. For RP2350 the valid values are 0 and 16, indicating the PIO instance has access to pins 0-31, or 16-47 respectively.

Parameters

pio	The PIO instance; e.g. pio0 or pio1
gpio_base	the GPIO base (either 0 or 16)

Returns

PICO_OK (0) on success, error code otherwise

pio_set_irq0_source_enabled()

static void pio_set_irq0_source_enabled ( PIO  pio, pio_interrupt_source_t  source, bool  enabled  )

inlinestatic

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

Parameters

pio	The PIO instance; e.g. 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; e.g. 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, pio_interrupt_source_t  source, bool  enabled  )

inlinestatic

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

Parameters

pio	The PIO instance; e.g. 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; e.g. 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, pio_interrupt_source_t  source, bool  enabled  )

inlinestatic

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

Parameters

pio	The PIO instance; e.g. 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; e.g. 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; e.g. 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; e.g. 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; e.g. 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; e.g. 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; e.g. 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; e.g. 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; e.g. 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; e.g. 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; e.g. 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; e.g. 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; e.g. 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; e.g. pio0 or pio1
sm	State machine index (0..3)

Returns

the number of elements in the TX FIFO

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; e.g. 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; e.g. 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; e.g. 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; e.g. 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; e.g. 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; e.g. 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; e.g. 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; e.g. 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; e.g. 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; e.g. 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; e.g. 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 int 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; e.g. pio0 or pio1
sm	State machine index (0..3)
config	the configuration to apply

Returns

PICO_OK (0) on success, negative error code otherwise

pio_sm_set_consecutive_pindirs()

int pio_sm_set_consecutive_pindirs	(	PIO	pio,
		uint	sm,
		uint	pins_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; e.g. pio0 or pio1
sm	State machine index (0..3) to use
pins_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

Returns

PICO_OK (0) on success, error code otherwise

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; e.g. 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.

'in' pins can overlap with the 'out', 'set' and 'sideset' pins

Parameters

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

pio_sm_set_jmp_pin()

static void pio_sm_set_jmp_pin ( PIO  pio, uint  sm, uint  pin  )

inlinestatic

Set the 'jmp' pin for a state machine.

Parameters

pio	The PIO instance; e.g. pio0 or pio1
sm	State machine index (0..3)
pin	The raw GPIO pin number to use as the source for a jmp pin instruction

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.

'out' pins can overlap with the 'in', 'set' and 'sideset' pins

Parameters

pio	The PIO instance; e.g. 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; e.g. 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; e.g. 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; e.g. 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.

'set' pins can overlap with the 'in', 'out' and 'sideset' pins

Parameters

pio	The PIO instance; e.g. 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.

'sideset' pins can overlap with the 'in', 'out' and 'set' pins

Parameters

pio	The PIO instance; e.g. 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; e.g. 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; e.g. pio0 or pio1
sm	State machine index (0..3)