NathanY3G / rp2040-pio-emulator

RP2040 emulator for the testing and debugging of PIO programs

Emulator for the PIO Blocks within the RP2040 Microcontroller (Python Edition)

Introduction

An emulator for the Programmable Input/Output (PIO) blocks that are present within the Raspberry Pi Foundation's RP2040 Microcontroller. It is designed to assist in the analysis of PIO programs and to help you by:

• Enabling unit tests to be written.
• Answering questions such as: How many clock cycles are being consumed?
• Supporting the visualization of GPIO outputs over time.
• Providing alternatives to debugging on real hardware, which can be time consuming.

Quick Start

Below is a slight variation of the example used within the Quick Start Guide.

from pioemu import emulate

program = [0xE029, 0x0041, 0x2080]  # Count down from 9 using X register

generator = emulate(program, stop_when=lambda _, state: state.x_register < 0)

for before, after in generator:
  print(f"X register: {before.x_register} -> {after.x_register}")

Documentation

A Tour of pioemu provides a more detailed explanation than the Quick Start Guide offers. In addition, there is a FAQ available that might contain an answer to your question. However, if none of these provides you with the necessary information then please consider creating a new issue - thanks!

Additional Examples

Some additional examples are available within the rp2040-pio-emulator-examples repository, including:

1. TDD example for the Pimoroni Blinkt!

2. Tool to create Fast Signal Trace (FST) files suitable for analysis by GTKWave

3. Visualisation of square wave program using a Jupyter Notebook

Supported Instructions

Instruction	Supported	Notes
JMP	✔️
WAIT	✔️ ⚠️	IRQ variant is not supported
IN	✔️
OUT	✔️ 🚧	EXEC destination not implemented
PUSH	✔️
PULL	✔️
MOV	✔️ 🚧	Some variants and operations not implemented
IRQ	✖️
SET	✔️

Known Limitations

This software is under development and currently has limitations - the notable ones are:

1. Not all of the available instructions are supported - please refer to the table above.

2. No support for pin-sets associated with OUT, SET or IN; all pin numbers are with respect to GPIO 0.

3. Pin-sets do not wrap after GPIO 31.

4. No direct support for the concurrent running of multiple PIO programs; a single State Machine is emulated and not an entire PIO block.

Thanks To

• aaronjamt for contributing features and fixes.
• Josverl for contributing features.
• winnylourson for contributing a bug fix.