Rework the PIO API

[mgottschlag]

Rationale

The current PIO API has a number of limitations:

• As the state machines are contained in PIO, they cannot be moved around individually. Sometimes, a single PIO block implements multiple functions that are used in completely different parts of the code base.
• StateMachine is not Send, although it could be.
• Multiple state machines should be able to share code to reduce instruction space usage, yet currently they are not because PIOBuilder always allocates space. Sometimes, multiple state machines implement the same functionality (e.g., multiple SPI or I2C buses).
• Some functions must only be called in specific configurations. For example, pin directions have to be set while the state machine is stopped, as PINCTRL is modified. The current API does not reflect such restrictions, which makes it harder to use than necessary.

Also, during my work, I found a bug where used instruction space was not marked properly.

This PR also fixes #141 by providing a function to set pin directions.

Design

This PR uses different types to represent state machines in different states - UninitStateMachine<P> is not associated with any program, whereas StateMachine<P, Stopped> and StateMachine<P, Running> are. Program installation in instruction memory is separated from state machine initialization via InstalledProgram and PIO::install(). Access from state machines to shared registers is performed via atomic operations to enable Send.

Old usage example:

let pio = rp2040_hal::pio::PIO::new(pac.PIO0, &mut pac.RESETS);
let sm = &pio.state_machines()[0];
let div = 0f32; // as slow as possible (0 is interpreted as 65536)
rp2040_hal::pio::PIOBuilder::default()
    .with_program(&program)
    .set_pins(led_pin_id, 1)
    .clock_divisor(div)
    .build(&pio, sm)
    .unwrap();

New usage example:

let (mut pio, sm0, _, _, _) = pac.PIO0.split(&mut pac.RESETS);
let installed = pio.install(&program).unwrap();
let div = 0f32; // as slow as possible (0 is interpreted as 65536)
let sm = rp2040_hal::pio::PIOBuilder::from_program(installed)
    .set_pins(led_pin_id, 1)
    .clock_divisor(div)
    .build(sm0);
sm.start();

Testing

I tested that the blink examples work, and I tested with my own code that, however, does not use much more PIO functionality yet (except for sideset pins). Those programs work fine.

[mgottschlag]

The new example in this PR currently depends on rp-rs/pio-rs#9, so the two PRs should be merged together.

[henkkuli]

I like these improvements to the usability of the API. There are a couple of bugs I spotted, and probably some more I missed.

I didn't know that atomic access to peripherals was even possible. My only concern is that I don't exactly know whether using pointers like that is sound, and I also don't like manual pointer arithmetic in HAL crate. In general I think the PAC should provide us with atomic access. A quick search through svd2rust found that it is probably possible as apparently MSP430 devices have similar functionality: https://github.com/rust-embedded/svd2rust/blob/master/src/generate/generic_msp430_atomic.rs

[henkkuli]

This should use write_volatile. I'm also not sure whether this is UB or not as the pointer is increased past the end of the peripheral's regular address space.

In principle I think the atomic translation should be handled by the PAC and we should be able to use that directly here, though I'm not sure whether this can be added to PAC or not.

[mgottschlag]

I added write_volatile in all three places. This is probably still undefined behavior - the documentation talks about the bounds of allocated memory, so I am not sure. Even if it is, I do not see a problem on this hardware platform.

[henkkuli]

We should be able to use instruction encoder here. See

rp-hal/rp2040-hal/src/pio.rs

Line 168 in 833b698

instr.encode(side_set)

[mgottschlag]

The code got slightly longer - is this what you mean?

[henkkuli]

Yes, this is what I meant.

[henkkuli]

I'd like to see this be StateMachine<P, Uninit>, but when I tried to draft an example of that I realized we probably need GATs for that because InstalledProgram is generic over P. Another option we could have today is

StateMachine<Uninit<PIO0>>;
StateMachine<StoppedPIO0>>;
StateMachine<Starged<PIO0>>;

but I don't like that either.

[mgottschlag]

I tried the latter, but did not like that it made it more difficult to implement functions that can operate on Stopped and Running, but not on Uninit. There are quite some such functions that just do not make sense on an UninitStateMachine.

I do not see this as a substantial usability concern, but I can look further into it if you insist.

[henkkuli]

I see. I guess one could still have something like

trait Initialized {...}
impl Initialized for Stopped {...}
impl Initialized for Running {...}
impl<State: Initialized> StateMachine<State> {...}

if one wanted to implement something only for Stopped and Running. But I don't insist on changing this, I'm just trying to brainstorm some ideas on how to make the API more self-consistent.

[henkkuli]

Apparently there are already issues for rp2040-pac and svd2rust.

[mgottschlag]

Thanks a lot for the review. I will fix those bugs this evening.

After submitting the PR, I started to think about integrating DMA. While doing so, I noticed that the API needs some further restructuring. In particular, TX and RX FIFOs need to be managed by different objects than the state machine itself, so that the user is able to use TX and RX DMA in parallel. For example, an API such as the following may be possible:

let (sm, rx, tx) = rp2040_hal::pio::PIOBuilder::from_program(installed)
    .set_pins(led_pin_id, 1)
    .clock_divisor(div)
    .build(sm0);
let rx_dma = rx.read_with_dma(buffer);
sm.start();
// ...
let rx = rx_dma.wait().
let sm0 = sm.uninit(rx, tx);

However, in the last line, the API should ensure that only the right rx and tx objects can be used. This could, for example, be done by adding another generic parameter, where there would be the following types and sm.id would be removed:

UninitStateMachine<PIO, SM0>
StateMachine<PIO0, SM0, Running>
PIOTx<PIO0, SM0>

etc.

That, however, means that any function/type that receives a state machine object needs to be parametrized for the specific state machine index. I do not think that this would be a large problem, as we already have similar behavior for objects/functions operating on GPIO pins, where they need to be written as generics which take a specific GPIO pin type.

What do you think?

[mgottschlag]

Oh, and with regards to MSP430 atomics: The scenario is somewhat different as MSP430, if I understand it correctly, uses atomic instructions to operate at the same addresses, which is probably much easier to implement in svd2rust. This kind of atomic register access (register aliases) would probably have to be implemented in rp2040-pac, but I have no idea how that would be done.

[henkkuli]

I think having everything be generic over the state machine won't be a problem. As you said, similar API is used elsewhere. Maybe one way to make it little easier to use would be to have types PIO0SM0, PIO0SM1, etc. and be generic over those instead. This way a function taking a state machine could have signature

fn foo<SM: ValidStateMachine>(_: StateMachine<SM, Running>) {}

instead of

fn foo<PIO: ValidPIO, SM: ValidStateMachine>(_: StateMachine<PIO, SM, Running>) {}

Regarding the atomics, I think I managed to hack something together already, though it is currently still a hack. Basically I just copied https://github.com/rust-embedded/svd2rust/blob/master/src/generate/generic_msp430_atomic.rs, changed the writes to something like

self.register
    .as_ptr()
    .add(0x2000 / core::mem::size_of::<REG::Ux>())
    .write_volatile(bits);

and force-added the file to every compiled crate. This has a couple of problems I haven't resolved yet: The most obvious one is that not every PAC crate should have this added, so a new flag or target needs to be added. More subtle problem is that the RP2040 documentation states that SIO device doesn't support atomic access (as it already is atomic by design), so this API shouldn't be exposed for SIO device.

[mgottschlag]

I added parametrization for the state machines. I have to admit that my type design skills are not really great, so someone might want to check whether that's really the most elegant way to specify state machine indices.

Currently, the state machines still carry references around to the registers:

block: *const rp2040_pac::pio0::RegisterBlock,
sm: *const rp2040_pac::pio0::SM,

These fields have basically become unnecessary now, I will remove them in the next commit.

[9names]

If you need atomics, what you'll want is the atomic- polyfill crate. It's not multi-core safe, but we are planning on making a fork that is.
[edit]
Oh, you want access to the atomic_set register alias. Yeah, that's something that should go in the PAC.
How many registers do you need to add this for? Adding a few isn't a big deal.

[9names]

and force-added the file to every compiled crate. This has a couple of problems I haven't resolved yet: The most obvious one is that not every PAC crate should have this added, so a new flag or target needs to be added. More subtle problem is that the RP2040 documentation states that SIO device doesn't support atomic access (as it already is atomic by design), so this API shouldn't be exposed for SIO device.

Definitely sounds like something that should be opt-in.
I was thinking more along the lines of using svdtools to copy the peripheral, add a suffix _or, and change the peripheral offset. That would work with current svd2rust, won't break any existing uses but might make the interface a little less nice to deal with.

[mgottschlag]

How many registers do you need to add this for? Adding a few isn't a big deal.

Currently, the code only needs atomic access to the CTRL register.

[henkkuli]

I'm thinking whether having a transceiver type would be helpful or not, the idea being that it would provide convenient methods read and write, and split to create separate Rx and Tx channels.

[henkkuli]

Definitely sounds like something that should be opt-in.

Exactly. My implementation was just a quick POC to just check whether adding atomic methods to PAC is possible or not.

I was thinking more along the lines of using svdtools to copy the peripheral, add a suffix _or, and change the peripheral offset. That would work with current svd2rust, won't break any existing uses but might make the interface a little less nice to deal with.

I don't think copying the peripheral should be the first solution. Especially as then the Peripherals struct would have both PIO0 and PIO0_or fields, and both would need to be given to HAL, degrading the UX of the HAL greatly. Otherwise the user could use PIO0_or and PIO0_nand to modify the registers even if they had given access to PIO0 away.

Instead I suggest that the SVD file should contain an attribute for every register telling whether the register has atomic counterparts or not. This would then instruct the codegen to implement AtomicAccess trait on the register, allowing us to gate the access to the atomic methods by this trait. I'm just not familiar enough with SVD to know whether this is possible, or how difficult that would be to implement.

[9names]

@mgottschlag Could you add an entry to the changelog for this?
I want CI to run with the latest pio-rs now that rp-rs/pio-rs#9 is merged, after that I think this PR is good merge.

[mgottschlag]

I added a changelog entry.

[mgottschlag]

I will have a look at the failures this evening.

[mgottschlag]

I fixed all clippy warnings, except for two warnings about very complex types that I somehow can't see in the CI output. I also marked most doc comment code examples as ignore, except for one which I extended with use statements and a simple PIO program and marked as no-run.

I told clippy to ignore the return types of split() and build(), as those tuples are too complex for clippy. We could also package those into structs, but I do not think that it would help make the code more readable. GPIOs are placed into a struct instead of a tuple, for example, but there is no free() method for GPIOs. Here, there is, and that method simply expects the variables as returned by split() at the moment, and I think this symmetry is good.

[9names]

LGTM