PIO - Barrel shift

[rikkenharp]

When I use out(null,2) or similar I have barrel shift in the OSR, is that a bug?
I really like it and use it for some stuff but I can't find it mentioned in the docs or somewhere else.

[robert-hh]

See RP2040 data sheet, chapter 3.2.3.1 about the OSR.

[rkompass]

I was unaware of a contradictory description until now:
In figure 40 of the datasheet the caption says:

. Data is parcelled out 1…32 bits at a time, and unused data is recycled by a bidirectional shifter.

The figure is in accordance with that. But the text at 3.2.3.1 says:

The OSR fills with zeroes as data is shifted out.

This allows the interpretation that the shift is cyclic in some cases (unused data, perhaps with null).

Also googling up the term barrel shift I find that a barrel shift is

1. immediate over several bits
2. cyclic at some references / cyclic or not cyclic at some others.

@rikkenharp did you observe a cyclic shift with e.g. out(null,2) ? This would surprise me, but, as stated above, I was not aware of such a possible interpretation.

[rikkenharp]

@rkompass Aahh...Many thanx no example needed anymore but it took me a little time to find out what was going on. I'm using it for a rgb332 to rgb565 converter now.
Many thanx again. :)

@GitHubsSilverBullet I was thinking that when I OUT(null,2) I would just kick the next two bits into Nirvana but not barrel shift them depending on what i set in threshold. But now I know better :) That would also have been nice.

Thanx to everybody now I know it's something I can rely on.

[rikkenharp]

@rkompass when I OUT(null,2) 0000_1011 will become 1100_0010 in the OSR

[rkompass]

@rkompass when I OUT(null,2) 0000_1011 will become 1100_0010 in the OSR

@rikkenharp I cannot confirm this behaviour. Do you have code that demonstrates this?

My investigation reveals that the shifted out bits with out(null, 2) are lost:

The code:

from time import sleep_ms
from rp2 import PIO, StateMachine, asm_pio

@asm_pio(push_thresh=32, in_shiftdir=PIO.SHIFT_LEFT, out_shiftdir=PIO.SHIFT_RIGHT)
def sm_gen():
    pull(block)


#  readout(sm) returns a dict containing 'rx_fifo', 'tx_fifo', 'isr, 'osr', 'x', 'y', 'pins', 'status'
#  state machine sm has to be inactive, otherwise the readout interferes with changes due to its operation
# 
def readout(sm):    
    res = {}
    res['rx_fifo'] = []                    # read and save all of rx_fifo
    for _ in range(sm.rx_fifo()):
        res['rx_fifo'].append(sm.get())
    sm.exec('push(noblock)')               # read isr
    res['isr'] = sm.get()
    sm.exec('mov(isr, osr)')               # read osr
    sm.exec('push(noblock)')
    res['osr'] = sm.get()
    sm.exec('mov(isr, x)')                 # read x
    sm.exec('push(noblock)')
    res['x'] = sm.get()
    sm.exec('mov(isr, y)')                 # read y
    sm.exec('push(noblock)')
    res['y'] = sm.get()
    sm.exec('mov(isr, pins)')              # read pins
    sm.exec('push(noblock)')
    res['pins'] = sm.get()
    sm.exec('mov(isr, status)')            # read status
    sm.exec('push(noblock)')
    res['status'] = sm.get()
    res['tx_fifo'] = []                    # read tx_fifo
    for _ in range(sm.tx_fifo()):
        sm.exec('pull(noblock)')
        sm.exec('mov(isr, osr)')
        sm.exec('push(noblock)')
        res['tx_fifo'].append(sm.get())
    for d in res['rx_fifo']:               # restore rx_fifo; uses isr, osr, tx_fifo
        sm.put(d)
        sm.exec('pull(noblock)')
        sm.exec('mov(isr, osr)')
        sm.exec('push(noblock)')
    sm.put(res['isr'])                     # restore isr; uses osr, tx_fifo
    sm.exec('pull(noblock)')
    sm.exec('mov(isr, osr)')
    sm.put(res['osr'])                     # restore osr; uses tx_fifo
    sm.exec('pull(noblock)')
    for d in res['tx_fifo']:               # restore tx_fifo
        sm.put(d)
    return res

def displ_sm_data(res):
    l = len(res['tx_fifo'])
    if l > 0:
        for i in range(l):
            d = res['tx_fifo'][i]
            print('tx_fifo[{:1d}]: 0x{:08X} | 0b {:08b} {:08b} {:08b} {:08b}'.format(
                i, d, d>>24, (d>>16)&0xff, (d>>8)&0xff, d&0xff))
    else:
        print('tx_fifo   : empty')
    l = len(res['rx_fifo'])
    if l > 0:
        for i in range(l):
            d = res['rx_fifo'][i]
            print('rx_fifo[{:01d}]: 0x{:08X} | 0b {:08b} {:08b} {:08b} {:08b}'.format(
                i, d, d>>24, (d>>16)&0xff, (d>>8)&0xff, d&0xff))
    else:
        print('rx_fifo   : empty')
    for r in ('isr', 'osr', 'x', 'y', 'pins', 'status'):
        d = res[r]
        print('{: <10s}: 0x{:08X} | 0b {:08b} {:08b} {:08b} {:08b}'.format(
            r, d, d>>24, (d>>16)&0xff, (d>>8)&0xff, d&0xff))


sm = StateMachine(0, sm_gen, freq=2000)
sm.put(0b00100101000000000011000001101001)
sm.active(1)
sleep_ms(200)
sm.active(0)
res=readout(sm)
displ_sm_data(res)
sm.exec('out(null,4)')
res=readout(sm)
displ_sm_data(res)
sm.exec('out(x,4)')
res=readout(sm)
displ_sm_data(res)

Result:

MPY: soft reboot
tx_fifo   : empty
rx_fifo   : empty
isr       : 0x00000000 | 0b 00000000 00000000 00000000 00000000
osr       : 0x25003069 | 0b 00100101 00000000 00110000 01101001
x         : 0x00000000 | 0b 00000000 00000000 00000000 00000000
y         : 0x00000000 | 0b 00000000 00000000 00000000 00000000
pins      : 0x01000000 | 0b 00000001 00000000 00000000 00000000
status    : 0x00000000 | 0b 00000000 00000000 00000000 00000000
tx_fifo   : empty
rx_fifo   : empty
isr       : 0x00000000 | 0b 00000000 00000000 00000000 00000000
osr       : 0x02500306 | 0b 00000010 01010000 00000011 00000110
x         : 0x00000000 | 0b 00000000 00000000 00000000 00000000
y         : 0x00000000 | 0b 00000000 00000000 00000000 00000000
pins      : 0x01000000 | 0b 00000001 00000000 00000000 00000000
status    : 0x00000000 | 0b 00000000 00000000 00000000 00000000
tx_fifo   : empty
rx_fifo   : empty
isr       : 0x00000000 | 0b 00000000 00000000 00000000 00000000
osr       : 0x00250030 | 0b 00000000 00100101 00000000 00110000
x         : 0x00000006 | 0b 00000000 00000000 00000000 00000110
y         : 0x00000000 | 0b 00000000 00000000 00000000 00000000
pins      : 0x01000000 | 0b 00000001 00000000 00000000 00000000
status    : 0x00000000 | 0b 00000000 00000000 00000000 00000000

and I see no rotated bit left at OSR. But also with shifting out to X the bits appear at the right (LSB) of X.
Did I miss a certain setting of the PIO StateMachine?

[GitHubsSilverBullet]

My investigation reveals that the shifted out bits with out(null, 2) are lost:

I'd say that is correct.
It shifts, it does not rotate. In essence like ASL,LSR in assembler, not the rotating ROL,ROR.

[rikkenharp]

@rkompass

this is my rgb332 to rgb565 converter that i feed with the dma.
If it would not do a barrel shift i would loose my colours.

I use the PIO system instead of hardware SPI.
One PIO for SPI bit-banging and on the other PIO i have a YMZ284(ay-3-8910)) running.
Both cores are free for calculations :)
i only use the hardware SPI for setting up the display.

` @rp2.asm_pio(sideset_init=[rp2.PIO.OUT_LOW], out_init=[PIO.OUT_LOW], in_shiftdir=rp2.PIO.SHIFT_LEFT, out_shiftdir=rp2.PIO.SHIFT_RIGHT, autopull=False, pull_thresh=8, autopush=False, push_thresh=8 )
def spi_cpha0():

    
    label("mainloop")
    pull(block)

CONVERTER -START- WE WORK WITH REVERSED 8bit COLOURS. RRRGGGBB are BBGGGRRR

out(null,6) # this is not sending 6 zeros to OUT, it rotates the OSR 6 bits to the right(barrel shift) 12345678 becomes 34567812
in_(null,3) # shifts in 3 zeros from the right side (left shifting) # ......._.....000
in_(osr,2)  # shifts in 2 bit from osr to isr. OSR sends out to the right, isr takes in from the right. # ........_...00021

out(null,5) # 34567812 => 67812345
in_(null,3) # ........_...00021 => ........_00021000
in_(osr,3)  # ........_00021000 => .....000_21000543

out(null,5) # 67812345 => 12345678
in_(null,2) # .....000_21000543 => ...00021_00054300
in_(osr,3)  # ...00021_00054300 => 00021000_54300876

CONVERTER -END- 10 cmds used

mov(osr,isr)    

TRANSFER 16 bits to one pin ##

set(y,15)
mov(osr,isr)

label("bitloop")
out(pins, 1)
nop()						.side(0x1)
set(pins,0)   					.side(0x0)  
jmp(y_dec,"bitloop")

set(y,15)
mov(osr,isr)

label("bitloop2")
out(pins, 1)
nop()						.side(0x1)
set(pins,0)   					.side(0x0)  
jmp(y_dec,"bitloop2")



jmp(x_dec,"mainloop")`

[rikkenharp]

this is doing pixel doubling on a ili9341.

[rkompass]

To more convincingly clarify the question of barrel shift or cyclic/rotary shift with a out(null, n) instruction I set up a simpler test program, without my PIO inspection routines:

from time import sleep_ms
from rp2 import PIO, StateMachine, asm_pio

@asm_pio(pull_thresh=32, push_thresh=32, out_init=[PIO.OUT_LOW], in_shiftdir=PIO.SHIFT_LEFT, out_shiftdir=PIO.SHIFT_RIGHT)
def sm_gen():
    pull(block)
#     out(null,4)
#     out(null,4)
#     out(null,4)
#     out(null,4)
#     out(null,4)
#     out(null,4)
#     out(null,4)
#     out(null,4)
    in_(osr,4)
    out(null,4)
    in_(osr,4)
    out(null,4)
    in_(osr,4)
    out(null,4)
    in_(osr,4)
    out(null,4)
    in_(osr,4)
    out(null,4)
    in_(osr,4)
    out(null,4)
    in_(osr,4)
    out(null,4)
    in_(osr,4)
    push(block)


sm = StateMachine(0, sm_gen, freq=2000)
x_put = 0b01111001011011010110100111101001
sm.put(x_put)
sm.active(1)
sleep_ms(50)
x_get = sm.get()
print(f'{x_put:8x}, {x_get:8x}')
sm.put(x_put)
x_get = sm.get()
print(f'{x_put:8x}, {x_get:8x}')

Running it with the 8 out(null,4) instructions commented out as in the above code I get:

796d69e9, 9e96d697
796d69e9, 9e96d697

but when de-commenting the 8 out(null,4) instructions , I get

796d69e9,        0
796d69e9,        0

so the OSR is cleared (completely shifted out to nirvana:-) ) by those instructions.
@rikkenharp feel invited to show us a setup where with those 8 out(null,4) instructions included, one after the other, as in the above code, the OSR or parts of it is preserved, as would be expected with a cyclic (barrel) shift.

Given this is not possible then it remains an interesting question why your rgb332 to rgb565 converter still works as expected.
I had a look at it but could not find an explanation. Your code is not complete though, so I could not just copy and paste it to try and explore it's results.

[rikkenharp]

I think I have found the cause. I use a second dma to restart my first with funny settings. The first is 8bit the second is 32bit. The second is also using the same buffer but in my understanding it should only cause a bit doubling that I use as a barrel shift once per 240*240 bit. Hmmmm. Have to investigate further. When I have found something or not I'll give you an update. Thanx for sending me down the rabbit hole :)

[rikkenharp]

@rkompass

Hii, here's a clean code doing the barrel shifting.
I transfer 00001111 via DMA to the PIO.
Without NULL i will get 00001111 like expected, with OUT(NULL,2) i get 11000011, like i also expected :)
On this Pico board i have a MicroPython v1.20.0 running.

from micropython import mem_info
from machine import Pin, PWM, mem32,Timer
from time import sleep
from rp2 import PIO, StateMachine, asm_pio
from array import array
from uctypes import addressof
import gc

gc.collect()
mem_info()

DMA_BASE=0x50000000

CH1_READ_ADDR  =DMA_BASE+0x040
CH1_WRITE_ADDR =DMA_BASE+0x044
CH1_TRANS_COUNT=DMA_BASE+0x048
CH1_CTRL_TRIG  =DMA_BASE+0x04c
CH1_AL1_CTRL   =DMA_BASE+0x050

PIO0_BASE      =0x50200000
PIO0_TXF0      =PIO0_BASE+0x10
PIO0_SM0_CLKDIV=PIO0_BASE+0xc8

@asm_pio(sideset_init=[rp2.PIO.OUT_LOW],out_init=[PIO.OUT_LOW]*8, out_shiftdir=PIO.SHIFT_RIGHT, autopull=False, pull_thresh=8)
def stream_YM_music():

    pull(block)

    out(null,2) # 
    
    out(pins,8)

    label("loopofdeath")
    jmp("loopofdeath")    
    

sm1 = StateMachine(0, stream_YM_music, freq=2000, sideset_base=Pin(13),out_base=Pin(0))
sm1.active(1)

def startDMA(array,count):

    mem32[CH1_READ_ADDR]=addressof(array)
    mem32[CH1_WRITE_ADDR]=PIO0_TXF0
    mem32[CH1_TRANS_COUNT]=count
    IRQ_QUIET=0x1 #no interrupt
    TREQ_SEL=0x00 #wait pio
    CHAIN_TO=1    #
    RING_SEL=0
    RING_SIZE=0   #
    INCR_WRITE=0  #
    INCR_READ=1   #
    DATA_SIZE=0   #8-bit word transfer
    HIGH_PRIORITY=1
    EN=1
    CTRL1=(IRQ_QUIET<<21)|(TREQ_SEL<<15)|(CHAIN_TO<<11)|(RING_SEL<<10)|(RING_SIZE<<9)|(INCR_WRITE<<5)|(INCR_READ<<4)|(DATA_SIZE<<2)|(HIGH_PRIORITY<<1)|(EN<<0)
    mem32[CH1_CTRL_TRIG]=CTRL1


test=array('B',[0B00001111,0B00000000])
startDMA(test,1)

[GitHubsSilverBullet]

It still isn't rotating. And it will never rotate because it isn't designed to rotate!
Your single-byte DMA transfer somehow replicates itself to bit positions [31: 24] [23,16] [15:8] [7:0]
Thus you're seeing a (previously unnoticed) side-effect. (data shifting to the right from [15:8]).

Will check the reference manual whether this is intended or not.

EDIT:
Already found it. Page 92.
The DMA performs standard byte lane replication on narrow writes, so byte data
is available in all 4 bytes of the databus, and halfword data in both halfwords.

[rikkenharp]

@GitHubsSilverBullet

Thank You.
At least I got an answer.
And I now know that I still can use it as an 8 or 16bit barrel shift.
Good enough for me :)
I wish a lazy Sunday and thank you for the crarification.

[rkompass]

@GitHubsSilverBullet
Nice finding.
Do we need a demonstration of this by a readout of the OSR? I think not.