PIO state machine configuration. More...

Data Structures
struct	pio_sm_config
	PIO Configuration structure. More...

Functions
static void	sm_config_set_out_pin_base (pio_sm_config *c, uint out_base)
	Set the base of the 'out' pins in a state machine configuration.

static void	sm_config_set_out_pin_count (pio_sm_config *c, uint out_count)
	Set the number of 'out' pins in a state machine configuration.

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

static void	sm_config_set_set_pin_base (pio_sm_config *c, uint set_base)
	Set the base of the 'set' pins in a state machine configuration.

static void	sm_config_set_set_pin_count (pio_sm_config *c, uint set_count)
	Set the count of 'set' pins in a state machine configuration.

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

static void	sm_config_set_in_pin_base (pio_sm_config *c, uint in_base)
	Set the base of the 'in' pins in a state machine configuration.

static void	sm_config_set_in_pins (pio_sm_config *c, uint in_base)
	Set the base for the 'in' pins in a state machine configuration.

static void	sm_config_set_in_pin_count (pio_sm_config *c, uint in_count)
	Set the count of 'in' pins in a state machine configuration.

static void	sm_config_set_sideset_pin_base (pio_sm_config *c, uint sideset_base)
	Set the base of the 'sideset' pins in a state machine configuration.

static void	sm_config_set_sideset_pins (pio_sm_config *c, uint sideset_base)
	Set the 'sideset' pins in a state machine configuration.

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.

static void	sm_config_set_clkdiv_int_frac8 (pio_sm_config *c, uint32_t div_int, uint8_t div_frac8)
	Set the state machine clock divider (from integer and fractional parts - 16:8) in a state machine configuration.

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

static void	sm_config_set_wrap (pio_sm_config *c, uint wrap_target, uint wrap)
	Set the wrap addresses in a state machine configuration.

static void	sm_config_set_jmp_pin (pio_sm_config *c, uint pin)
	Set the 'jmp' pin in a state machine configuration.

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.

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.

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.

static void	sm_config_set_out_special (pio_sm_config *c, bool sticky, bool has_enable_pin, uint enable_bit_index)
	Set special 'out' operations in a state machine configuration.

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.

static pio_sm_config	pio_get_default_sm_config (void)
	Get the default state machine configuration.

Detailed Description

PIO state machine configuration.

A PIO block needs to be configured, these functions provide helpers to set up configuration structures. See pio_sm_set_config

On RP2350A, pin numbers may always be specified from 0-31.

On RP2350B, there are 48 pins but each PIO instance can only address 32 pins (the PIO instance either addresses pins 0-31 or 16-47 based on pio_set_gpio_base). The sm_config_ state machine configuration always take real pin numbers in the full range, however:

If PICO_PIO_USE_GPIO_BASE != 1 then bit 5 of the pin number is ignored. This is done so that programs compiled for boards with RP2350A do not incur the extra overhead of dealing with higher pins that don't exist. Effectively these functions behave exactly like RP2040 in this case. Note that PICO_PIO_USE_GPIO_BASE is defaulted to 0 if PICO_RP2350A is 1
If PICO_PIO_USE_GPIO_BASE == 1 then the state machine configuration stores the actual pin numbers in the range 0-47. Of course in this scenario, it is possible to make an invalid configuration (one which uses pins in both the ranges 0-15 and 32-47).

pio_sm_set_config (or pio_sm_init which calls it) attempts to apply the configuration to a particular PIO's state machine, and will return PICO_ERROR_BAD_ALIGNMENT if the configuration cannot be applied due to the above problem, or if the PIO's GPIO base (see pio_set_gpio_base) does not allow access to the required pins.

To be clear, pio_sm_set_config does not change the PIO's GPIO base for you; you must configure the PIO's GPIO base before calling the method, however you can use pio_claim_free_sm_and_add_program_for_gpio_range to find/configure a PIO instance suitable for a particular GPIO range.

Note: When PICO_PIO_USE_GPIO_BASE == 1 pio_sm_set_config ignores fields which haven't had the corresponding sm_config_ pin function called, so that you don't have to move settings for unused pin sets into the correct pin range. Therefore, it is always a best practice to explicitly configure a pin range starting at pin zero via the corresponding sm_config_ function (e.g. sm_config_set_out_pin_base(config, 0)), as the default values for pin ranges from pio_get_default_sm_config are now GPIO_BASE + 0 not 0 on RP2350B.

You can set PARAM_ASSERTIONS_ENABLED_HARDWARE_PIO = 1 to enable parameter checking to debug pin (or other) issues with hardware_pio methods.

Function Documentation

◆ pio_get_default_sm_config()

static pio_sm_config pio_get_default_sm_config ( void )

inlinestatic

Get the default state machine configuration.

Setting	Default
Clock Divider	1
Out Pins	0 starting at 0 (see note below)
Set Pins	0 starting at 0 (see note below)
In Pins	32 starting at 0 (see note below)
Side Set Pins (base)	0 (see note below)
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 (see note below)
Out Special	sticky=false, has_enable_pin=false, enable_pin_index=0
Mov Status	status_sel=STATUS_TX_LESSTHAN, n=0

Note: On RP2350B with PICO_PIO_USE_GPIO_BASE = 1, the default Out/Set/In/Side Set pin bases are actually 0 relative to the GPIO_BASE of the PIO instance the pio_sm_config is applied to, so that any pin bases which aren't explicitly specified are not included in logic related to choosing a compatible PIO instance.

Therefore, for example, if you intend to use Out pins starting at pin 0 on RP2350B, you should call sm_config_set_out_pin_base(config, 0), or sm_config_set_out_pins(config, 0, count) explicitly.

Returns: the default state machine configuration which can then be modified.

◆ sm_config_set_clkdiv()

static void sm_config_set_clkdiv	(	pio_sm_config *	c,
		float	div
	)

inlinestatic

Set the state machine clock divider (from a floating point value) in a state machine configuration.

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

Parameters

c	Pointer to the configuration structure to modify
div	The fractional divisor to be set. 1 for full speed. An integer clock divisor of n will cause the state machine to run 1 cycle in every n. Note that for small n, the jitter introduced by a fractional divider (e.g. 2.5) may be unacceptable although it will depend on the use case.

◆ sm_config_set_clkdiv_int_frac8()

static void sm_config_set_clkdiv_int_frac8	(	pio_sm_config *	c,
		uint32_t	div_int,
		uint8_t	div_frac8
	)

inlinestatic

Set the state machine clock divider (from integer and fractional parts - 16:8) in a state machine configuration.

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

Parameters

c	Pointer to the configuration structure to modify
div_int	Integer part of the divisor
div_frac8	Fractional part in 1/256ths

See also: sm_config_set_clkdiv()

◆ sm_config_set_fifo_join()

static void sm_config_set_fifo_join	(	pio_sm_config *	c,
		enum pio_fifo_join	join
	)

inlinestatic

Setup the FIFO joining in a state machine configuration.

Parameters

c	Pointer to the configuration structure to modify
join	Specifies the join type. See pio_fifo_join

◆ sm_config_set_in_pin_base()

static void sm_config_set_in_pin_base	(	pio_sm_config *	c,
		uint	in_base
	)

inlinestatic

Set the base of the 'in' pins in a state machine configuration.

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

Parameters

c	Pointer to the configuration structure to modify
in_base	First pin to use as input. See sm_config_ pins for more detail on pin arguments

◆ sm_config_set_in_pin_count()

static void sm_config_set_in_pin_count	(	pio_sm_config *	c,
		uint	in_count
	)

inlinestatic

Set the count of 'in' pins in a state machine configuration.

When reading pins using the IN pin mapping, this many (low) bits will be read, with the rest taking the value zero.

Parameters

c	Pointer to the configuration structure to modify
in_count	1-32 The number of pins to include when reading via the IN pin mapping

◆ sm_config_set_in_pins()

static void sm_config_set_in_pins	(	pio_sm_config *	c,
		uint	in_base
	)

inlinestatic

Set the base for the 'in' pins in a state machine configuration.

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

Parameters

c	Pointer to the configuration structure to modify
in_base	First pin to use as input. See sm_config_ pins for more detail on pin arguments

◆ sm_config_set_in_shift()

static void sm_config_set_in_shift	(	pio_sm_config *	c,
		bool	shift_right,
		bool	autopush,
		uint	push_threshold
	)

inlinestatic

Setup 'in' shifting parameters in a state machine configuration.

Parameters

c	Pointer to the configuration structure to modify
shift_right	true to shift ISR to right, false to shift ISR to left
autopush	whether autopush is enabled
push_threshold	threshold in bits to shift in before auto/conditional re-pushing of the ISR

◆ sm_config_set_jmp_pin()

static void sm_config_set_jmp_pin	(	pio_sm_config *	c,
		uint	pin
	)

inlinestatic

Set the 'jmp' pin in a state machine configuration.

Parameters

c	Pointer to the configuration structure to modify
pin	The raw GPIO pin number to use as the source for a `jmp pin` instruction. See sm_config_ pins for more detail on pin arguments

◆ sm_config_set_mov_status()

static void sm_config_set_mov_status	(	pio_sm_config *	c,
		enum pio_mov_status_type	status_sel,
		uint	status_n
	)

inlinestatic

Set source for 'mov status' in a state machine configuration.

Parameters

c	Pointer to the configuration structure to modify
status_sel	the status operation selector. See pio_mov_status_type
status_n	parameter for the mov status operation (currently a bit count)

◆ sm_config_set_out_pin_base()

static void sm_config_set_out_pin_base	(	pio_sm_config *	c,
		uint	out_base
	)

inlinestatic

Set the base of the 'out' pins in a state machine configuration.

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

Parameters

c	Pointer to the configuration structure to modify
out_base	First pin to set as output. See sm_config_ pins for more detail on pin arguments

◆ sm_config_set_out_pin_count()

static void sm_config_set_out_pin_count	(	pio_sm_config *	c,
		uint	out_count
	)

inlinestatic

Set the number of 'out' pins in a state machine configuration.

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

Parameters

c	Pointer to the configuration structure to modify
out_count	0-32 Number of pins to set.

◆ sm_config_set_out_pins()

static void sm_config_set_out_pins	(	pio_sm_config *	c,
		uint	out_base,
		uint	out_count
	)

inlinestatic

Set the 'out' pins in a state machine configuration.

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

Parameters

c	Pointer to the configuration structure to modify
out_base	First pin to set as output. See sm_config_ pins for more detail on pin arguments
out_count	0-32 Number of pins to set.

◆ sm_config_set_out_shift()

static void sm_config_set_out_shift	(	pio_sm_config *	c,
		bool	shift_right,
		bool	autopull,
		uint	pull_threshold
	)

inlinestatic

Setup 'out' shifting parameters in a state machine configuration.

Parameters

c	Pointer to the configuration structure to modify
shift_right	true to shift OSR to right, false to shift OSR to left
autopull	whether autopull is enabled
pull_threshold	threshold in bits to shift out before auto/conditional re-pulling of the OSR

◆ sm_config_set_out_special()

static void sm_config_set_out_special	(	pio_sm_config *	c,
		bool	sticky,
		bool	has_enable_pin,
		uint	enable_bit_index
	)

inlinestatic

Set special 'out' operations in a state machine configuration.

Parameters

c	Pointer to the configuration structure to modify
sticky	to enable 'sticky' output (i.e. re-asserting most recent OUT/SET pin values on subsequent cycles)
has_enable_pin	true to enable auxiliary OUT enable pin
enable_bit_index	Data bit index for auxiliary OUT enable.

◆ sm_config_set_set_pin_base()

static void sm_config_set_set_pin_base	(	pio_sm_config *	c,
		uint	set_base
	)

inlinestatic

Set the base of the 'set' pins in a state machine configuration.

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

Parameters

c	Pointer to the configuration structure to modify
set_base	First pin to use as 'set'. See sm_config_ pins for more detail on pin arguments

◆ sm_config_set_set_pin_count()

static void sm_config_set_set_pin_count	(	pio_sm_config *	c,
		uint	set_count
	)

inlinestatic

Set the count of 'set' pins in a state machine configuration.

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

Parameters

c	Pointer to the configuration structure to modify
set_count	0-5 Number of pins to set.

◆ sm_config_set_set_pins()

static void sm_config_set_set_pins	(	pio_sm_config *	c,
		uint	set_base,
		uint	set_count
	)

inlinestatic

Set the 'set' pins in a state machine configuration.

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

Parameters

c	Pointer to the configuration structure to modify
set_base	First pin to use as 'set'. See sm_config_ pins for more detail on pin arguments
set_count	0-5 Number of pins to set.

◆ sm_config_set_sideset()

static void sm_config_set_sideset	(	pio_sm_config *	c,
		uint	bit_count,
		bool	optional,
		bool	pindirs
	)

inlinestatic

Set the 'sideset' options in a state machine configuration.

Parameters

c	Pointer to the configuration structure to modify
bit_count	Number of bits to steal from delay field in the instruction for use of side set (max 5)
optional	True if the topmost side set bit is used as a flag for whether to apply side set on that instruction
pindirs	True if the side set affects pin directions rather than values

◆ sm_config_set_sideset_pin_base()

static void sm_config_set_sideset_pin_base	(	pio_sm_config *	c,
		uint	sideset_base
	)

inlinestatic

Set the base of the 'sideset' pins in a state machine configuration.

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

Parameters

c	Pointer to the configuration structure to modify
sideset_base	First pin to use for 'side set'. See sm_config_ pins for more detail on pin arguments

◆ sm_config_set_sideset_pins()

static void sm_config_set_sideset_pins	(	pio_sm_config *	c,
		uint	sideset_base
	)

inlinestatic

Set the 'sideset' pins in a state machine configuration.

This method is identical to sm_config_set_sideset_pin_base, and is provided for backwards compatibility

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

Parameters

c	Pointer to the configuration structure to modify
sideset_base	First pin to use for 'side set'. See sm_config_ pins for more detail on pin arguments

◆ sm_config_set_wrap()

static void sm_config_set_wrap	(	pio_sm_config *	c,
		uint	wrap_target,
		uint	wrap
	)

inlinestatic

Set the wrap addresses in a state machine configuration.

Parameters

c	Pointer to the configuration structure to modify
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

Data Structures

Functions

Detailed Description

Function Documentation

◆ pio_get_default_sm_config()

◆ sm_config_set_clkdiv()

◆ sm_config_set_clkdiv_int_frac8()

◆ sm_config_set_fifo_join()

◆ sm_config_set_in_pin_base()

◆ sm_config_set_in_pin_count()

◆ sm_config_set_in_pins()

◆ sm_config_set_in_shift()

◆ sm_config_set_jmp_pin()

◆ sm_config_set_mov_status()

◆ sm_config_set_out_pin_base()

◆ sm_config_set_out_pin_count()

◆ sm_config_set_out_pins()

◆ sm_config_set_out_shift()

◆ sm_config_set_out_special()

◆ sm_config_set_set_pin_base()

◆ sm_config_set_set_pin_count()

◆ sm_config_set_set_pins()

◆ sm_config_set_sideset()

◆ sm_config_set_sideset_pin_base()

◆ sm_config_set_sideset_pins()

◆ sm_config_set_wrap()