Adding a PIOProgram class

[nludban]

I've been looking at adding a PIOProgram class as a wrapper around the opaque array returned by asm_pio to make it much easier to implement a number of open tickets. There's a proof of concept PR here.

Adding new features to the existing API didn't work out well IMHO - it would be cleaner and probably smaller to prefer implementation in Python vs C. My proposal is to create several PRs with a slightly different approach:

• fix the memory leak and bug around _pio_funcs
• add a PIOProgram class as an alternative to asm_pio (no new features yet)
• refactor asm_pio to be a wrapper around PIOProgram
• rp2.StateMachine() should accept 'Freq' as 'Float' (currently 'Int'). #11593 but implemented in Python this time, updating StateMachine constructor (in C) to accept divisors
• rp2 PIO StateMachine jump table to produce instructions #13439 as seen in the PoC PR
• rp2 PIO state machine pin config enhancements #13248
• RP2: Make PIO EXECCTRL_STATUS_SEL settable through API #10210

Looking for some good idea / bad idea type of discussion here before doing the work.

[Josverl]

Can you provide an example how this works from a python perspective?

Also I'm interessed to understand if and how this may help IDEs, linters or type checkers handle the Python form of the PIO code better than the current implementation

[nludban]

Can you provide an example how this works from a python perspective?

https://github.com/micropython/micropython/blob/master/examples/rp2/pio_1hz.py would be updated to look something like:

# @rp2.asm_pio(set_init=rp2.PIO.OUT_LOW)
def blink_1hz():
    # No change to the program

prog = rp2.PIOProgram(blink_1hz)
sm = prog.init_state_machine(0, freq=2000, set_init=rp2.PIO.OUT_LOW, set_base=Pin(25))
sm.irq(lambda p: print(time.ticks_ms()))
sm.active(1)

Also I'm interessed to understand if and how this may help IDEs, linters or type checkers handle the Python form of the PIO code better than the current implementation

No help directly, but by separating the assembler phase from the deployment phase, it would be easier (less code) to substitute just the assembler part with an improved syntax or support for 2350 opcodes.

[Josverl]

That's nice for the assembler/compiler,
For me as a human (n=1) I will have lost the explicit cue that a function is written in a different language, which I'm used to from other similar @asm decorators.

Is there a way to achieve your goals, without removing that context?

[nludban]

Is the current @rp2.asm_pio decorator sufficient to switch your IDE into a PIO mode? I was assuming it would need something like import * from asm_pio to see the magic namespace.

🤔 @rp2.asm(pio=RP2040) would be explicit and allow substitution of the assembler.

[Josverl]

I would prefer a syntax where a decorator indicates the fact that PIO assembly is used, and

Is the current @rp2.asm_pio decorator sufficient to switch your IDE into a PIO mode ?

No unfortunately not. I've not found a way for Type Checkers to use a externally defined context based on a decorator. (I have tried more than a few ways )
The best, still a bit clunky, method is to manually do that for the remainder of the module under evaluation.

if TYPE_CHECKING:
    from rp2.asm_pio import *

PIO_ASM_typing

for your proposal this could be adapted to something like:

• rp2040 : from rp2.asm.rp2040 import *
• rp2040 : from rp2.asm.rp2350 import *

and the stubs could re-use the common syntax.