https://github.com/rp-rs/pio-rs
Support crate for Raspberry Pi's PIO architecture.
https://github.com/rp-rs/pio-rs
assembler raspberry-pi-pico rust
Last synced: about 1 year ago
JSON representation
Support crate for Raspberry Pi's PIO architecture.
- Host: GitHub
- URL: https://github.com/rp-rs/pio-rs
- Owner: rp-rs
- License: mit
- Created: 2021-01-25T18:29:28.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-03-03T18:40:48.000Z (about 1 year ago)
- Last Synced: 2025-05-15T07:03:44.811Z (about 1 year ago)
- Topics: assembler, raspberry-pi-pico, rust
- Language: Rust
- Homepage:
- Size: 182 KB
- Stars: 164
- Watchers: 9
- Forks: 25
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# pio-rs
Support for the Raspberry Silicon RP2040's *PIO* State Machines.
## What is PIO?
See https://www.raspberrypi.com/news/what-is-pio/. You can also read the PIO
section in the (very well written) RP2040 datasheet:
https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf.
## What is pio-rs?
PIO programs must be compiled from PIO Assembly Language into a special PIO
machine code. This machine code is then stored in your C or Rust program, and
program is copied to the PIO hardware at the relevant point in time.
Raspberry Pi provide a PIO assembler called pioasm, and it lives at
https://github.com/raspberrypi/pico-sdk/tree/master/tools/pioasm. This is an
excellent choice if you want use the Raspberry Pi Pico SDK
(https://github.com/raspberrypi/pico-sdk) to write C or C++ programs for your
RP2040.
The pio-rs project provides an alternative implementation of pioasm. The main
benefits are:
* It's easier to integrate into an Embedded Rust program for the RP2040 than
`pioasm`
* It provides a `pio_asm!` macro that can assemble PIO at compile-time.
* The compiler itself can be included in your Embedded Rust program as a library,
so you can compile PIO code on the RP2040, at run-time!
* Writing an assembler was a good way to test our understanding of the
specification.
* It's written in Rust :)
## How do I use pio-rs?
If you want to write a program in Rust that uses the RP2040's PIO block, there
are three ways to use pio-rs:
### pio!
There is a macro called `pio!` which allows you to place PIO assembly language
source into your Rust program. This source code is assembled into a PIO program
at compile time.
Your `Cargo.toml` file should include:
```toml
[dependencies]
pio = "0.2"
```
Your Rust program should contain your PIO program, as follows with PIO asm directly in the file:
```rust
let program_with_defines = pio::pio_asm!(
"set pindirs, 1",
".wrap_target",
"set pins, 0 [31]",
"set pins, 1 [31]",
".wrap",
options(max_program_size = 32) // Optional, defaults to 32
);
let program = program_with_defines.program;
```
Or you can assemble a stand-alone PIO file from disk:
```rust
let program_with_defines = pio::pio_file!(
"./tests/test.pio",
select_program("test"), // Optional if only one program in the file
options(max_program_size = 32) // Optional, defaults to 32
);
let program = program_with_defines.program;
```
The syntax should be the same as supported by the official pioasm tool.
### pio::Assembler::new()
You can call `pio::Assembler::new()` and construct a PIO program using
the 'builder pattern' - effectively you are compiling a PIO program at
run-time on the RP2040 itself!
```rust
// Define some simple PIO program.
const MAX_DELAY: u8 = 31;
let mut assembler = pio::Assembler::<32>::new();
let mut wrap_target = assembler.label();
let mut wrap_source = assembler.label();
// Set pin as Out
assembler.set(pio::SetDestination::PINDIRS, 1);
// Define begin of program loop
assembler.bind(&mut wrap_target);
// Set pin low
assembler.set_with_delay(pio::SetDestination::PINS, 0, MAX_DELAY);
// Set pin high
assembler.set_with_delay(pio::SetDestination::PINS, 1, MAX_DELAY);
// Define end of program loop
assembler.bind(&mut wrap_source);
// The labels wrap_target and wrap_source, as set above,
// define a loop which is executed repeatedly by the PIO
// state machine.
let program = assembler.assemble_with_wrap(wrap_source, wrap_target);
```
Each line starting `assembler.` adds a new line to the program. The completed
program can be passed to the PIO driver in the Rust-language [RP2040
HAL](https://docs.rs/rp2040-hal/).
## PIO Examples
This crate is just the PIO assembler. If you want to see some fully-featured
PIO examples integrated with Embedded Rust on the RP2040, check out the
[rp-hal examples](https://github.com/rp-rs/rp-hal/tree/main/rp2040-hal/examples).
## Roadmap
NOTE This tool is under active development. As such, it is likely to remain
volatile until a 1.0.0 release.
See the [open issues](https://github.com/rp-rs/pio-rs/issues) for a list of
proposed features (and known issues).
## Contributing
Contributions are what make the open source community such an amazing place to
be learn, inspire, and create. Any contributions you make are **greatly
appreciated**.
1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
Distributed under the MIT License. See `LICENSE` for more information.
## Contact
Project Link: [https://github.com/rp-rs/pio-rs/issues](https://github.com/rp-rs/pio-rs/issues)
Matrix: [#rp-rs:matrix.org](https://matrix.to/#/#rp-rs:matrix.org)
## Acknowledgements
* [pioasm](https://github.com/raspberrypi/pico-sdk/tree/master/tools/pioasm)