Programmable IO (PIO)

Low-level PIO peripheral driver. More...

Detailed Description

Low-level PIO peripheral driver.

Programmable IO (PIO) is a cycle accurate IO control interface to emulate common IO standards like: I2C, SPI, UART or custom wire protocols as for the well known WS2812B LEDs. PIO programs are written in an MCU specific assembly language and they are saved in .pio files. The programs have to be loaded in the PIOs instruction memory. Once written to memory, a program can be executed by a state machines. A state machine can only execute one program at a time but multiple state machines can run the same program as access to instruction memory is shared. The user is responsible to allocate/deallocate instruction memory and lock/unlock state machines.

PIO programs are very versatile and execution may depend on hardware quirks, thus specific setup must be performed by the CPU PIO driver implementation and the program code itself. The CPU driver implementation provides a set of known programs for common IO standards but user written programs are also possible and should be placed in cpu//pio to make use of the processor specific PIO interface.

This API simply takes a look at PIO programs as something that resides in memory and can be executed on demand, by a state machine.

Warning

This feature is experimental!
This API is experimental and in an early state - expect changes!

Files
file	pio.h
	High-level PIO peripheral driver interface.

Data Structures
struct	pio_program_t
	Struct that models a PIO program. More...

Macros
#define	PIO_DEV(x)   (x)
	Default PIO device access macro.
#define	PIO_PROGRAM_NOT_LOADED   (-1)
	Program location that states that the program has not been loaded into instruction memory.

Typedefs
typedef unsigned	pio_t
	PIO index type.
typedef int	pio_sm_t
	PIO state machine index type.

Functions
void	pio_init (pio_t pio)
	Initialize a PIO device.
void	pio_start_programs (void)
	Start automatically configured PIO programs.
pio_sm_t	pio_sm_lock (pio_t pio)
	Get exclusive access to one of the state machines of PIO pio.
void	pio_sm_unlock (pio_t pio, pio_sm_t sm)
	Release a previously locked state machine.
void	pio_sm_start (pio_t pio, pio_sm_t sm)
	Start a state machine and execute the previously loaded program.
void	pio_sm_stop (pio_t pio, pio_sm_t sm)
	Stop the execution of a program.
int	pio_alloc_program (pio_t pio, pio_program_t *prog)
	Allocate the required instruction memory to load the given PIO program into.
int	pio_alloc_program_sm_lock_any (pio_t *pio_ptr, pio_sm_t *sm_ptr, pio_program_t *program)
	Convenience function which performs the usual PIO program resource acquisition.
void	pio_free_program (pio_t pio, pio_program_t *prog)
	Release the allocated instruction memory occupied by prog.

Macro Definition Documentation

PIO_DEV

#define PIO_DEV

(

x

)

(x)

Default PIO device access macro.

Definition at line 57 of file pio.h.

PIO_PROGRAM_NOT_LOADED

#define PIO_PROGRAM_NOT_LOADED   (-1)

Program location that states that the program has not been loaded into instruction memory.

Definition at line 64 of file pio.h.

Typedef Documentation

pio_sm_t

typedef int pio_sm_t

PIO state machine index type.

Definition at line 81 of file pio.h.

pio_t

typedef unsigned pio_t

PIO index type.

Definition at line 76 of file pio.h.

Function Documentation

pio_alloc_program()

int pio_alloc_program	(	pio_t	pio,
		pio_program_t *	prog
	)

Allocate the required instruction memory to load the given PIO program into.

Parameters

[in]	pio	PIO index
[in,out]	prog	Pointer PIO program

Returns

Success: 0 Failure: != 0

pio_alloc_program_sm_lock_any()

int pio_alloc_program_sm_lock_any	(	pio_t *	pio_ptr,
		pio_sm_t *	sm_ptr,
		pio_program_t *	program
	)

Convenience function which performs the usual PIO program resource acquisition.

pio_alloc_program pio_sm_lock

Parameters

[out]	pio_ptr	Destination to store the PIO index
[out]	sm_ptr	Destination to store the PIO state machine index
[in,out]	program	Program pointer of the program to be allocated

Returns

Success: 0 Failure: != 0

pio_free_program()

void pio_free_program	(	pio_t	pio,
		pio_program_t *	prog
	)

Release the allocated instruction memory occupied by prog.

Parameters

[in]	pio	PIO index
[in]	prog	PIO program

pio_init()

void pio_init

(

pio_t

pio

)

Initialize a PIO device.

Parameters

[in]

pio

PIO index

Note

No initialization is performed if "DISABLE_MODULE += periph_init_pio" is set.

pio_sm_lock()

pio_sm_t pio_sm_lock

(

pio_t

pio

)

Get exclusive access to one of the state machines of PIO pio.

Parameters

[in]

pio

PIO index

Returns

Success: Index of now locked state machine Failure: negative integer

pio_sm_start()

void pio_sm_start	(	pio_t	pio,
		pio_sm_t	sm
	)

Start a state machine and execute the previously loaded program.

Parameters

[in]	pio	PIO index
[in]	sm	PIO state machine index

pio_sm_stop()

void pio_sm_stop	(	pio_t	pio,
		pio_sm_t	sm
	)

Stop the execution of a program.

Parameters

[in]	pio	PIO index
[in]	sm	PIO state machine index

pio_sm_unlock()

void pio_sm_unlock	(	pio_t	pio,
		pio_sm_t	sm
	)

Release a previously locked state machine.

Parameters

[in]	pio	PIO index
[in]	sm	PIO state machine index

pio_start_programs()

void pio_start_programs

(

void

)

Start automatically configured PIO programs.

Note

No execution is automatically started if "DISABLE_MODULE += periph_init_pio" is set.