Advanced PIO equipment – Dmitry.GR

Utilizing RP2040 PIO to drive a poorly-designed show

Desk of Contents

1. The givens
   1. Initially…
   2. The issues
   3. PIO
2. Towards a solution
   1. The math
   2. The 16bpp mode
   3. Touch
   4. The 4bpp mode
   5. 1bpp and 2bpp modes
   6. The 8bpp indexed-colour mode
3. Some more details
   1. DMA chaining woes
   2. Why no nPENIRQ
   3. SD card access
   4. Clock speeds
   5. Setup & use
4. Comments…

I used to be trying to find a show with not less than 160×160 decision and a resistive contact display screen that will mate simply to RaspberryPi pico for my rePalm venture? There weren’t many, really. However I did come throughout this display at Waveshare – a 2.8inch 320×240 full-colour LCD. With out a lot additional trying, I ordered a couple of and began planning the code to drive it. The aim was to have a framebuffer supporting 1, 2, and 4 bits per pixel greyscale, 8 bits per pixel listed color, and 16 bits per pixel full color modes, whereas getting contact knowledge in realtime. As this show doesn’t help listed color or greyscale, that will have to be regionally synthesized in some way. Moreover, I noticed a couple of totally different articles on the market about how individuals drive this show, and so they had been all atrociously inefficient, so I figured I might publish a approach to do it proper and save everybody else the difficulty and ache. Offered here’s a very quick driver for this show supporting 1, 2, and 4 bpp greyscale, 8-bit listed color, and 16-bit fullcolour modes on the entire show or any rectangular subset of it. Contact knowledge is copied to a reminiscence location on your perusal at your leisure mechanically, and if you want, you possibly can even do tear-free web page flipping and get VSync interrupts. No CPU cycles are used in any respect! An actual, correct driver. So, why is driving this show correctly a ache? Nicely…

The 16bpp mode is the only, for the reason that show natively helps RGB565 fullcolour mode, so it made sense to begin there. Issues are fairly simple right here. State machine 0 (SM0) right here will ingest knowledge, 16 bits at a time, and shift it out MSB first SPI-like to the show. However, keep in mind, we have to pattern contact. New plan. We set the X register to some worth, say 2560. We then decrease the show’s nCS, and ship it knowledge. We ship pixels till we’ve despatched X of them (that is approx 1/30 of a display screen’s price of pixels). After this we increase the show’s nCS and sign an irq to State machine 2 (SM2). We then anticipate an irq again from it. SM2 was ready all alongside. It lowers the contact controller’s nCS, gathers a pattern, raises contact controler’s nCS, and alerts an irq to SM0, which continues sending knowledge to the display screen. This could work and it does.

We’ll want some DMA channels to help this. Channel 0 will ship uncooked display screen knowledge to SM0, when carried out, it is going to set off channel 1, whose solely job will likely be to re-start and re-trigger channel 0. Thus the show is continually refreshing from our framebuffer. Contact is a little more complicated. To collect our samples we have to ship three instructions to the chip, and get three 12-bit responses. DMA channel 3 will program channel 2, in sequence, to first ship the three instructions to SM2’s TX buffer, then obtain the three knowledge factors from SM2’s RX buffer, then reprogram channel 3 in order that we will do that once more in a loop. Surely we’ll be receiving 4 knowledge factors, not three. Extra on why later. In any case, with these 4 DMA channels and two state machines, the 16 bit mode works. We get contact knowledge DMAed to RAM and show picture DMAed from RAM, all with no CPU involvement in any respect. Channel 2’s completion interrupt can be utilized to inform us when a brand new pattern has arrived, if desired.

The contact controller, in the most effective case, can produce a brand new pattern each 15 cycles. We’ll attempt to go for that mode. This doesn’t imply that we will get three samples in 45 cycles. It signifies that in an infinite stream of samples being carried out, a brand new one is prepared each 15. In actuality to collect three samples, 51 cycles are wanted. A brand new command begins each 15 cycles, and after a delay of 9 cycles, a 12-bit reply (pattern) could also be learn, the following will likely be 15 cycles after that one, and so forth. All this counting is getting slightly complicated, although. This could waste loads of PIO directions. However there’s a higher manner. 51 = 17 * 3, so if I put together the command bitstream, slice it into three 17-bit phrases, and allow auto-pull, the PIO code needn’t do any counting within the TX path, simply OUT a bit at a time. This won’t work for obtain, since every pattern would find yourself shifted by a variable quantity. As a substitute, we actually need to pattern 15 bits at a time. So we notice that 51 = 15 * 4 – 9. Thus, we will configure our PIO code to auto-push each 15 bits, pre-load ISR with 9 bits of zeros up entrance, and IN a bit at a time. It will produce 4 15-bit samples, the primary containing all zeroes, and the following three containing the info we wished (X, Y, Z). Since every PIO SM has a 4-word FIFO for TX and identical for RX, we will first load the TX fifo with our instructions, then anticipate RX utilizing the identical DMA channel, as described above. Superior! Right here on the proper you possibly can see the way it seems when zoomed out – the show knowledge is sometimes interrupted to pattern contact, however many of the SPI time is used to ship the info to the show, as supposed.

This show doesn’t help any greyscale modes. The bottom bits-per-pixel that it will probably help is 12, in RGB444 format. That mode is exactly what we’ll have to make use of to create our 1bpp (B&W), 2bpp (4 greys), and 4bpp (16 greys) modes. We might, in fact, simply do that by taking our framebuffer, fetching each 4 bits sequentially, calculating the right 12-bit color, and sending that by way of SPI. Nonetheless, the aim is to do all this with no CPU involvement. Fortunately, we will. Here’s what we’ll do.

SM0 will likely be fed (by DMA) the 4bpp knowledge from RAM, 32 bits at a time. It would shift off 4 bits from the low finish into a brief variable. Shift that variable in 3 instances, and output these twelve bits. Thus, SM0 merely expands the incoming pixel knowledge into 12-bit show knowledge. We will then arrange a DMA channel to feed SM0’s output to SM1, which is able to shift out 12-bit phrases to the show. After some numbers of pixels it’s going to give the contact controller a while to pattern contact, and repeat ceaselessly. There may be a few points to think about right here. To start with, regardless of every pixel being 12 bits in dimension, the show won’t settle for non-integer-number-of-bytes-long writes, so the variety of pixels we ship between contact samples should be even. OK. Straightforward sufficient.

The final challenge is pushback. DMA will be triggered by one occasion (knowledge request, aka DREQ). For instance, the DMA that feeds SM0 with our uncooked pixel knowledge is triggered by SM0 having house in its enter FIFO. So how will we correctly set off the DMA that feeds SM0’s output to SM1’s enter? If we set off it primarily based on SM0’s output having knowledge, we’d overflow SM1’s enter FIFO. If we set off it primarily based on SM1’s enter having house, we’d learn rubbish from SM0 because it has not but produced knowledge. You could possibly try to resolve this by claiming that SM0 will at all times be sooner to supply knowledge than SM1 can devour it. That is usually true, however what if there’s a delay on the enter knowledge to SM0? Actually we wish a DMA channel that we will set off primarily based on each SM0’s non-empty output and SM1’s non-full enter. Sadly, such DMA set off mechanisms don’t exist on RP2040 (or every other chip i’ve ever seen). The answer I settled on was this: the DMA will likely be triggered by SM1 having house within the enter buffer. However to stop it overflowing when SM0 is simply too quick, SM1 will sign an IRQ to SM0, and SM0 will anticipate IRQ earlier than producing one other output pattern. To prime this technique, we’ll force-issue one IRQ at first. This works!

One tiny very last thing to recollect – most monochrome screens deal with zero as white and all ones as black, for the reason that pure relaxed state of an LCD is evident. However for our color show all ones is white and all zeroes is black. Thus, SM0, on enter, will invert its knowledge to offer for the right color mapping.

I left the indexed-colour mode for final, as it’s the hardest. Ideally, the best way it really works is that there’s a color lookup desk (CLUT) someplace, with 256 entries, every representing a full RGB565 color. The framebuffer is one byte per pixel, represending an index into the colourtable. This mode was generally used on outdated PCs, however can also be nice for UIs that need to be colored however dont need to waste the framebuffer house on 2 bytes per pixel. This show controller doesn’t help listed color mode and has no reminiscence for a CLUT, so it’s going to must dwell in RAM, in some way.

PIO equipment can’t do math effectively, nor can the DMA models. However PIO can concatenate bit strings. An concept begins to kind. For instance that our CLUT will comprise 16-bit RGB565 entries and dwell in RAM at an deal with divisible by 512. Which means to get an deal with of the Nth entry we don’t want so as to add. We will simply insert “N” shifted left by 1 into the deal with, since its decrease 9 bits are assured to be zero. This we CAN do in PIO. So SM0 will enter pixel knowledge, 8 bits at a time. Certainly one of its registers will likely be pre-programmed with the deal with of the CLUT, proper shifted by 9. It would shift that into the ISR, shift within the pixel worth, and shift in a single zero bit. Now it will probably output this 32-bit worth, which is an deal with, in RAM, of the CLUT entry with the precise RGB565 color of this pixel.

Cool, however we can’t feed a RAM deal with to our show – it has no concept what our RAM incorporates. We will, nonetheless use one DMA channel to program one other… Sure, we’ll DMA out each output from SM0 into the “learn deal with” register of one other DMA channel. That channel will likely be programmed to switch a single 16-bit worth from there to SM1’s enter. Thus it’s going to copy the precise RGB565 worth to SM1’s enter. SM1 then merely sends it, because it did for 16bpp mode. We apply the identical form of bidirectional pushback mechanism right here as we do for 1/2/4 bpp mode, and the contact sampling works the identical right here as in all different instances. It’s fairly convoluted, but it surely works! The color desk will be up to date any time and takes impact instantly, as a result of how it’s used. And sure, I’m utilizing a PIO state machine to … add. Cool, eh?

With some minor work, this mode will be modified to make use of RGB666 mode for barely higher color accuracy, however as a result of needing to ship extra bits over the SPI bus (24 bits despatched per pixel vs 16 for RGB565), the framerate will endure by an element of 33%. That is why I compromised on RGB565 for this mode – it’s simply not price it for two extra bits.

See Also

Ask HN: Anybody left software program to review non-STEM topics?

Some extra particulars

Whereas engaged on this venture I bumped into a problem whereby issues would work effectively, till the CPU’s inside AHBlite bus was very loaded, at which level issues would break down and a DMA channel would find yourself misconfigured in some way. After breaking my head over it for a couple of days and discovering no manner through which my code was incorrect, I filed bug 321. It seems that RP2040’s DMA chaining, in some instances, might set off the chained channel earlier than the final write has accomplished. Appears the chain sign is fired when the final write is issued, not when it’s accomplished. Generally this is able to be completely tremendous, since virtually actually no one depends upon cycle-exact DMA chaining, and doing it this manner makes the sign seem sooner. In my case, when one channel reconfigures one other, after which chains to it, it mattered, since generally the second channel would get triggered to begin earlier than the final configuration phrase had been written. Fortunately, the repair is easy. Apart from chaining, one might triger a channel by writing to sure register addresses. I modified my DMA configuration to at all times set off utilizing such writes and now the entire thing is rock secure. All-in-all, this driver wants six DMA channels and utterly takes over PIO0, because it makes use of 30/32 of its instruction slots and three/4 of its state machines.

Obtain: [HERE]. License is BSD 2-clause. I’m too lazy (and disgusted) to show this into some type of an arduino or a micropython library, however I’m positive another person will. My supplied code will construct standalone with no dependency on something. License is BSD-2 clause. Take pleasure in