hardware_pio

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

Modules

 sm_config
 PIO state machine configuration.
 

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 a particular state machine. 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_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...
 
#define pio0   pio0_hw
 
#define pio1   pio1_hw
 

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:

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
pioThe PIO instance; either pio0 or pio1
programthe 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
pioThe PIO instance; either pio0 or pio1
programthe program definition
offsetthe 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
pioThe PIO instance; either pio0 or pio1
programthe 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
pioThe PIO instance; either pio0 or pio1
programthe program definition
offsetthe 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
pioThe PIO instance; either pio0 or pio1
sm_maskMask 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
pioThe PIO instance; either pio0 or pio1
requiredif 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
pioThe 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
pioThe PIO instance; either pio0 or pio1
maskbit 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
pioThe PIO instance; either pio0 or pio1
maskbit 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 a particular state machine.

Parameters
pioThe PIO instance; either pio0 or pio1
smState machine index (0..3)
is_txtrue for sending data to the state machine, false for received 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
pioThe 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
pioThe PIO instance; either pio0 or pio1
pinthe 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
pioThe PIO instance; either pio0 or pio1
pio_interrupt_numthe 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
pioThe PIO instance; either pio0 or pio1
pio_interrupt_numthe 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
pioThe PIO instance; either pio0 or pio1
programthe program definition
loaded_offsetthe 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
pioThe PIO instance; either pio0 or pio1
maskbit 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
pioThe PIO instance; either pio0 or pio1
sourcethe source number (see pio_interrupt_source)
enabledtrue 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
pioThe PIO instance; either pio0 or pio1
source_maskMask of bits, one for each source number (see pio_interrupt_source) to affect
enabledtrue 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
pioThe PIO instance; either pio0 or pio1
sourcethe source number (see pio_interrupt_source)
enabledtrue 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
pioThe PIO instance; either pio0 or pio1
source_maskMask of bits, one for each source number (see pio_interrupt_source) to affect
enabledtrue 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
pioThe PIO instance; either pio0 or pio1
irq_indexthe IRQ index; either 0 or 1
sourcethe source number (see pio_interrupt_source)
enabledtrue 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
pioThe PIO instance; either pio0 or pio1
irq_indexthe IRQ index; either 0 or 1
source_maskMask of bits, one for each source number (see pio_interrupt_source) to affect
enabledtrue 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
pioThe PIO instance; either pio0 or pio1
maskbit mask of state machine indexes to modify the enabled state of
enabledtrue 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
pioThe PIO instance; either pio0 or pio1
smState 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
pioThe PIO instance; either pio0 or pio1
smState 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
pioThe PIO instance; either pio0 or pio1
smState 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
pioThe PIO instance; either pio0 or pio1
smState 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
pioThe PIO instance; either pio0 or pio1
smState machine index (0..3)
instrthe 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
pioThe PIO instance; either pio0 or pio1
smState machine index (0..3)
instrthe 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
pioThe PIO instance; either pio0 or pio1
smState 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
pioThe PIO instance; either pio0 or pio1
smState 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
pioThe PIO instance; either pio0 or pio1
smState 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
pioThe PIO instance; either pio0 or pio1
smState 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
pioThe PIO instance; either pio0 or pio1
smState 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
pioThe PIO instance; either pio0 or pio1
smState machine index (0..3)
initial_pcthe initial program memory offset to run from
configthe 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
pioThe PIO instance; either pio0 or pio1
smState 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
pioThe PIO instance; either pio0 or pio1
smState 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
pioThe PIO instance; either pio0 or pio1
smState 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
pioThe PIO instance; either pio0 or pio1
smState 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
pioThe PIO instance; either pio0 or pio1
smState 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
pioThe PIO instance; either pio0 or pio1
smState 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
pioThe PIO instance; either pio0 or pio1
smState machine index (0..3)
datathe 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
pioThe PIO instance; either pio0 or pio1
smState machine index (0..3)
datathe 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
pioThe PIO instance; either pio0 or pio1
smState 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
pioThe PIO instance; either pio0 or pio1
smState machine index (0..3)
divthe 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
pioThe PIO instance; either pio0 or pio1
smState machine index (0..3)
div_intthe integer part of the clock divider
div_fracthe 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
pioHandle to PIO instance; either pio0 or pio1
smState machine index (0..3)
configthe 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
pioThe PIO instance; either pio0 or pio1
smState machine index (0..3) to use
pin_basethe first pin to set a direction for
pin_countthe count of consecutive pins to set the direction for
is_outthe 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
pioThe PIO instance; either pio0 or pio1
smState machine index (0..3)
enabledtrue to enable the state machine; false to disable

◆ 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
pioThe PIO instance; either pio0 or pio1
smState machine index (0..3) to use
pin_dirsthe pin directions to set - 1 = out, 0 = in (if the corresponding bit in pin_mask is set)
pin_maska 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
pioThe PIO instance; either pio0 or pio1
smState machine index (0..3) to use
pin_valuesthe 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
pioThe PIO instance; either pio0 or pio1
smState machine index (0..3) to use
pin_valuesthe pin values to set (if the corresponding bit in pin_mask is set)
pin_maska bit for each pin to indicate whether the corresponding pin_value for that pin should be applied.

◆ 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
pioThe PIO instance; either pio0 or pio1
smState machine index (0..3)
wrap_targetthe instruction memory address to wrap to
wrapthe 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
pioThe PIO instance; either pio0 or pio1
smState machine index (0..3)