pio.h File Reference

#include "pico.h"
#include "hardware/address_mapped.h"
#include "hardware/structs/pio.h"
#include "hardware/gpio.h"
#include "hardware/regs/dreq.h"
#include "hardware/pio_instructions.h"

Include dependency graph for pio.h:

Go to the source code of this file.

Data Structures
struct	pio_sm_config
	PIO Configuration structureThis structure is an in-memory representation of the configuration that can be applied to a PIO state machine later using pio_sm_set_config() or pio_sm_init(). More...
struct	pio_program

Macros
#define	PARAM_ASSERTIONS_ENABLED_PIO   0
#define	pio0   pio0_hw
#define	pio1   pio1_hw

Typedefs
typedef pio_hw_t *	PIO
typedef struct pio_program	pio_program_t

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	check_sm_param (__unused uint sm)
static void	check_sm_mask (__unused uint mask)
static void	check_pio_param (__unused PIO pio)
static void	sm_config_set_out_pins (pio_sm_config *c, uint out_base, uint out_count)
	Set the 'out' pins in a state machine configurationCan overlap with the 'in', 'set' and 'sideset' pins. More...
static void	sm_config_set_set_pins (pio_sm_config *c, uint set_base, uint set_count)
	Set the 'set' pins in a state machine configurationCan overlap with the 'in', 'out' and 'sideset' pins. More...
static void	sm_config_set_in_pins (pio_sm_config *c, uint in_base)
	Set the 'in' pins in a state machine configurationCan overlap with the 'out', 'set' and 'sideset' pins. More...
static void	sm_config_set_sideset_pins (pio_sm_config *c, uint sideset_base)
	Set the 'sideset' pins in a state machine configurationCan overlap with the 'in', 'out' and 'set' pins. More...
static void	sm_config_set_sideset (pio_sm_config *c, uint bit_count, bool optional, bool pindirs)
	Set the 'sideset' options in a state machine configuration. More...
static void	sm_config_set_clkdiv_int_frac (pio_sm_config *c, uint16_t div_int, uint8_t div_frac)
	Set the state machine clock divider (from integer and fractional parts - 16:8) in a state machine configurationThe clock divider can slow the state machine's execution to some rate below the system clock frequency, by enabling the state machine on some cycles but not on others, in a regular pattern. This can be used to generate e.g. a given UART baud rate. See the datasheet for further detail. More...
static void	pio_calculate_clkdiv_from_float (float div, uint16_t *div_int, uint8_t *div_frac)
static void	sm_config_set_clkdiv (pio_sm_config *c, float div)
	Set the state machine clock divider (from a floating point value) in a state machine configurationThe clock divider slows the state machine's execution by masking the system clock on some cycles, in a repeating pattern, so that the state machine does not advance. Effectively this produces a slower clock for the state machine to run from, which can be used to generate e.g. a particular UART baud rate. See the datasheet for further detail. More...
static void	sm_config_set_wrap (pio_sm_config *c, uint wrap_target, uint wrap)
	Set the wrap addresses in a state machine configuration. More...
static void	sm_config_set_jmp_pin (pio_sm_config *c, uint pin)
	Set the 'jmp' pin in a state machine configuration. More...
static void	sm_config_set_in_shift (pio_sm_config *c, bool shift_right, bool autopush, uint push_threshold)
	Setup 'in' shifting parameters in a state machine configuration. More...
static void	sm_config_set_out_shift (pio_sm_config *c, bool shift_right, bool autopull, uint pull_threshold)
	Setup 'out' shifting parameters in a state machine configuration. More...
static void	sm_config_set_fifo_join (pio_sm_config *c, enum pio_fifo_join join)
	Setup the FIFO joining in a state machine configuration. More...
static void	sm_config_set_out_special (pio_sm_config *c, bool sticky, bool has_enable_pin, uint enable_pin_index)
	Set special 'out' operations in a state machine configuration. More...
static void	sm_config_set_mov_status (pio_sm_config *c, enum pio_mov_status_type status_sel, uint status_n)
	Set source for 'mov status' in a state machine configuration. More...
static pio_sm_config	pio_get_default_sm_config (void)
	Get the default state machine configuration Setting Default Out Pins 32 starting at 0 Set Pins 0 starting at 0 In Pins (base) 0 Side Set Pins (base) 0 Side Set disabled Wrap wrap=31, wrap_to=0 In Shift shift_direction=right, autopush=false, push_threshold=32 Out Shift shift_direction=right, autopull=false, pull_threshold=32 Jmp Pin 0 Out Special sticky=false, has_enable_pin=false, enable_pin_index=0 Mov Status status_sel=STATUS_TX_LESSTHAN, n=0 More...
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 instancePIO 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. 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 itThis method: 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 machinesNote that this method just sets the enabled state of the state machine; if now enabled they continue exactly from where they left off. More...
static void	pio_sm_restart (PIO pio, uint sm)
	Restart a state machine with a known stateThis method clears the ISR, shift counters, clock divider counter pin write flags, delay counter, latched EXEC instruction, and IRQ wait condition. More...
static void	pio_restart_sm_mask (PIO pio, uint32_t mask)
	Restart multiple state machine with a known stateThis method clears the ISR, shift counters, clock divider counter pin write flags, delay counter, latched EXEC instruction, and IRQ wait condition. More...
static void	pio_sm_clkdiv_restart (PIO pio, uint sm)
	Restart a state machine's clock divider from a phase of 0Each 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. More...
static void	pio_clkdiv_restart_sm_mask (PIO pio, uint32_t mask)
	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. More...
static void	pio_enable_sm_mask_in_sync (PIO pio, uint32_t mask)
	Enable multiple PIO state machines synchronizing their clock dividersThis 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. 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 machineThis 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. 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 completeThis 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. 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 machineCan overlap with the 'in', 'set' and 'sideset' pins. 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 machineCan overlap with the 'in', 'out' and 'sideset' pins. More...
static void	pio_sm_set_in_pins (PIO pio, uint sm, uint in_base)
	Set the current 'in' pins for a state machineCan overlap with the 'out', 'set' and 'sideset' pins. More...
static void	pio_sm_set_sideset_pins (PIO pio, uint sm, uint sideset_base)
	Set the current 'sideset' pins for a state machineCan overlap with the 'in', 'out' and 'set' pins. More...
static void	pio_sm_put (PIO pio, uint sm, uint32_t data)
	Write a word of data to a state machine's TX FIFOThis 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. More...
static uint32_t	pio_sm_get (PIO pio, uint sm)
	Read a word of data from a state machine's RX FIFOThis 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. 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 FIFOThis 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. 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 instanceThis 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. 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 instanceThis 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. 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 instanceThis 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. 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 instanceThis 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. More...
void	pio_sm_claim (PIO pio, uint sm)
	Mark a state machine as usedMethod 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. More...
void	pio_claim_sm_mask (PIO pio, uint sm_mask)
	Mark multiple state machines as usedMethod 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. More...
void	pio_sm_unclaim (PIO pio, uint sm)
	Mark a state machine as no longer usedMethod for cooperative claiming of hardware. 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...