Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/devsnek/pio-rs

Support crate for Raspberry Pi's PIO architecture.
https://github.com/devsnek/pio-rs

assembler raspberry-pi-pico rust

Last synced: about 2 months ago
JSON representation

Support crate for Raspberry Pi's PIO architecture.

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`

* The compiler itself can be included in your Embedded Rust program, 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-proc = "0.2"

pio = "0.2"

```



Your Rust program should contain your PIO program, as follows with PIO asm directly in the file:



```rust

use pio_proc::pio_asm;



let program_with_defines = pio_proc::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

use pio_proc::pio_file;



let program_with_defines = pio_proc::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)