RFC: A complete PIO State Machine debugger

[PaulAccisano]

Hi everyone, I've coded up a complete RP2040 PIO state machine debugger extension for Micropython. It can non-destructively read the complete state of a PIO state machine, including registers, shift counters, fifo queues, and irq status. It can step through the code line by line, and set breakpoints. It can operate in any state machine configuration, even if the fifo queues are joined. Check it out here:
https://github.com/PaulAccisano/piodebug

I'm hoping to get some feedback on the code, and maybe find out if there are other features that people would like to see added. If people find this useful, I think it would be great to make available in micropython-lib. How would I get started on that?

[rkompass]

Hey Paul,

firstly a big congratulation on your achievement.

I had intended to achieve the same but got distracted a few months ago.
My initial post of this was here.
Meanwhile I had my disassembler finished. It looks quite similar to yours. The code is here:
pio_disasm3.zip
On the very first look it could be that my readctrls() therein is more extensive and could be perhaps be helpful in displaying the PIO configuration (not sure).

The remaining hurdle for me to be taken was to Read write-only PIO instruction memory.
As I see you achieved that with the C code.

Then a decision has to be taken as for how the user interface should look like.
I appreciate that you opted for a textual display that works in an ordinary terminal /serial line.

A few questions:

• Do you have a recent binary with the C code part compiled in handy? This would make immediate testing easier.
• What do you think about the possibility to do the Read write-only PIO instruction memory in Micropython only?
  If this would be possible a purely MP package could be released and perhaps become part of the MP lib.
• If not: Do you plan / see the possibility to make an .mpy package with the C code for easy installation without extra firmware build?
• How do you deal with labels? Can the user provide a list? Or are the labels taken from the PIO assembler source?
• In debugging: Running the debugger over a number of steps/cycles: Is there a possibility to have the PIO run at the original speed and then intercept or do the single steps have to be done in a sequence of controlled single step mode?
  The latter would be sufficient for learning PIO coding and for slow interfaces. The former would allow for debugging high speed interfaces too.

Once I have tried it out I can give more feedback.

Nice greetings,
Raul

[PaulAccisano]

Hey Raul, sorry for missing your preliminary work on this.

I took a look at your code, looks like you are extracting the settings from the SHIFT/PIN/EXECCTRL registers. Including this in sm_get_state() is a thought, but I feel it's less interesting as it's fairly trivial to get this data already. In fact, SHIFTCTRL and EXECCTRL are exposed as part of the tuple returned by @rp2.asm_pio I was more interested in extracting the state machine internals, which are not exposed at all, such as the shift counters. This especially tricky when the fifo queues are joined so there is no rx to extract data from, or no tx to restore data with.

The interactive debugger and disassembler are already in Python, only sm_get_state and sm_step are in C. This is for speed reasons. sm_get_state takes between 4500 and 6000 CPU cycles depending on state machine configuration. Disassembling the the PIO program is not being done in the C code, that part is pure Python. The encoded PIO program is the first element of the tuple returned by @rp2.asm_pio. But reading the instruction memory through the INSTR register is actually brilliant, I can't believe I didn't think of that! Looking at the thread you linked, I'm not sure why you needed to mess with the clock divider? I did some quick testing, and it looks like jumping to each address while the state machine is paused is sufficient. Unfortunately, it's not a perfect solution. One thing that is definitely not accessible is the program offset, so there is no 100% accurate way of determining which of the 32 instructions are part of your PIO program and which aren't. While certainly a neat trick, I'm not sure what the practical benefit is of reading the PIO program this way instead of just relying on the list returned by @rp2.asm_pio.

Labels are not included in the disassembly right now. As you can see from the example output, I'm displaying jmp commands with relative jump target addresses, eg, jmp(not_x, +6). Unfortunately, @rp2.asm_pio does not expose the labels, and as far as I can tell there is no way to extract them. The only way would be to make a custom version of @rp2.asm_pio which would put the label dictionary as an additional tuple element. Actually, submitting a PR to change @rp2.asm_pio to have this behavior is on my todo list. But that's a separate discussion thread.

The current implementation of the debugger cannot run the state machine at full speed, but adding a full speed mode is definitely possible. Stepping a precise number of cycles at full speed would be impractical (without using another state machine), but setting breakpoints is easy: just replace the instruction at the breakpoint address with jmp(+0) and monitor the ADDR register until the breakpoint is reached. Then put the original instruction back. The obvious downside of this method is that it would interfere with other state machines if they are sharing the same code. But it's still worth having as an option.

Precompiled binaries are available in the Releases section for both Micropython v1.20/21 and v1.22+. I also added an example file with a sample PIO program to test with. Looking forward to your feedback 🙂

[fdufnews]

I decided starting to play with PIO programming and found piodebug really usefull.
It is a great tool to debug the code and understand how the staemachines are working.
On my first code, I scrached my head a long time analyzing my code for no output from my statemachine until I ran piodebug and found that it was just "out" shifting the data the wrong direction. I now have an interface to a 3 digit x 7 segment multiplexed display that consumes almost no CPU time.