refactor SPI3w; better PIO docs; add more functionality

Author: soypat

rp2-pio/pio.go

@@ -225,8 +225,19 @@ func (pio *PIO) GetIRQ() uint8 {
 }
 
 // ClearIRQ clears IRQ flags when 1 is written to bit flag.
-func (pio *PIO) ClearIRQ(irqmsk uint8) {
-	pio.hw.SetIRQ(uint32(irqmsk))
+func (pio *PIO) ClearIRQ(irqMask uint8) {
+	pio.hw.SetIRQ(uint32(irqMask))
+}
+
+// SetInputSyncBypassMasked sets the pinMask bits of the INPUT_SYNC_BYPASS register
+// with the values in the corresponding bypassMask bits.
+//
+// There is a 2-flipflop synchronizer on each GPIO input, which protects
+// PIO logic from metastabilities. This increases input delay, and for
+// fast synchronous IO (e.g. SPI) these synchronizers may need to be bypassed.
+// If bit set the corresponding synchronizer is bypassed. If in doubt leave as zeros.
+func (pio *PIO) SetInputSyncBypassMasked(bypassMask, pinMask uint32) {
+	pio.hw.INPUT_SYNC_BYPASS.ReplaceBits(bypassMask, pinMask, 0)
 }
 
 // HW returns a pointer to the PIO's hardware registers.

rp2-pio/piolib/spi.go

@@ -69,14 +69,15 @@ func NewSPI(sm pio.StateMachine, spicfg machine.SPIConfig) (*SPI, error) {
 
 	// MOSI, SCK output are low, MISO is input.
 	outMask := uint32((1 << spicfg.SCK) | (1 << spicfg.SDO))
+	inMask := uint32(1 << spicfg.SDI)
 	sm.SetPinsMasked(0, outMask)
-	sm.SetPindirsMasked(outMask, outMask|(1<<spicfg.SDI))
+	sm.SetPindirsMasked(outMask, outMask|inMask)
 
 	pincfg := machine.PinConfig{Mode: Pio.PinMode()}
 	spicfg.SCK.Configure(pincfg)
 	spicfg.SDO.Configure(pincfg)
 	spicfg.SDI.Configure(pincfg)
-	Pio.HW().INPUT_SYNC_BYPASS.SetBits(1 << spicfg.SDI)
+	Pio.SetInputSyncBypassMasked(inMask, inMask)
 
 	sm.Init(offset, cfg)
 	sm.SetEnabled(true)

rp2-pio/piolib/spi3w.go

@@ -3,8 +3,11 @@
 package piolib
 
 import (
+	"device/rp"
 	"machine"
+	"runtime/volatile"
 	"time"
+	"unsafe"
 
 	pio "github.com/tinygo-org/pio/rp2-pio"
 )
@@ -50,21 +53,36 @@ func NewSPI3w(sm pio.StateMachine, dio, clk machine.Pin, baud uint32) (*SPI3w, e
 	pinCfg := machine.PinConfig{Mode: Pio.PinMode()}
 	dio.Configure(pinCfg)
 	clk.Configure(pinCfg)
-	Pio.HW().INPUT_SYNC_BYPASS.SetBits(1 << dio)
+	Pio.SetInputSyncBypassMasked(1<<dio, 1<<dio)
+
+	dioPad := pinPadCtrl(dio)
+	// Disable pull up and pull down.
+	dioPad.ReplaceBits(0, 1, rp.PADS_BANK0_GPIO0_PUE_Pos)
+	dioPad.ReplaceBits(0, 1, rp.PADS_BANK0_GPIO0_PDE_Pos)
+
+	dioPad.ReplaceBits(1, 1, rp.PADS_BANK0_GPIO0_SCHMITT_Pos) // Enable Schmitt trigger.
+
+	// 12mA drive strength for both clock and output.
+	const drive = rp.PADS_BANK0_GPIO0_DRIVE_12mA
+	const driveMsk = rp.PADS_BANK0_GPIO0_DRIVE_Msk >> rp.PADS_BANK0_GPIO0_DRIVE_Pos
+	dioPad.ReplaceBits(drive, driveMsk, rp.PADS_BANK0_GPIO0_DRIVE_Pos)
+
+	dioPad.ReplaceBits(1, 1, rp.PADS_BANK0_GPIO0_SLEWFAST_Pos) // Enable fast slewrate.
+
+	clkPad := pinPadCtrl(clk)
+	clkPad.ReplaceBits(drive, driveMsk, rp.PADS_BANK0_GPIO0_DRIVE_Pos)
+	clkPad.ReplaceBits(1, 1, rp.PADS_BANK0_GPIO0_SLEWFAST_Pos) // Enable fast slewrate.
 
 	// Initialize state machine.
 	sm.Init(offset, cfg)
 	pinMask := uint32(1<<dio | 1<<clk)
 	sm.SetPindirsMasked(pinMask, pinMask)
 	sm.SetPinsMasked(0, pinMask)
 
-	sm.SetEnabled(true)
-
 	spiw := &SPI3w{
-		sm:       sm,
-		offset:   offset,
-		pinMask:  pinMask,
-		statusEn: true,
+		sm:      sm,
+		offset:  offset,
+		pinMask: pinMask,
 	}
 	return spiw, nil
 }
@@ -163,8 +181,8 @@ func (spi *SPI3w) LastStatus() uint32 {
 	return spi.lastStatus
 }
 
-// enableStatus enables the reading of the last status word after a CmdRead/CmdWrite.
-func (spi *SPI3w) enableStatus(enabled bool) {
+// EnableStatus enables the reading of the last status word after a CmdRead/CmdWrite.
+func (spi *SPI3w) EnableStatus(enabled bool) {
 	spi.statusEn = enabled
 }
 
@@ -250,3 +268,7 @@ func (spi *SPI3w) writeDMA(w []uint32) error {
 func (spi *SPI3w) IsDMAEnabled() bool {
 	return spi.dma.IsValid()
 }
+
+func pinPadCtrl(pin machine.Pin) *volatile.Register32 {
+	return (*volatile.Register32)(unsafe.Pointer(uintptr(unsafe.Pointer(&rp.PADS_BANK0.GPIO0)) + uintptr(4*pin)))
+}

rp2-pio/piolib/spi3w.pio

@@ -6,22 +6,23 @@
 .wrap_target
 
 ; write out x-1 bits
-lp: 
-    out pins, 1   side 0
-    jmp x-- lp    side 1
-    
-    ; Switch directions
-    
+lp:
+    out pins, 1    side 0
+    jmp x-- lp     side 1
+
+    jmp !y end     side 0  ; If y (readbits) is 0 then run to end of program.
+
+    ; Prepare for read, Switch directions
     set pindirs, 0 side 0
     nop            side 0
-    
+
 ; read in y-1 bits
 lp2:
     in pins, 1     side 1
     jmp y--  lp2   side 0
 
-    ; wait for event and irq host
-
+; wait for event and irq host
+end:
     wait 1 pin 0   side 0
     irq  0         side 0
 

rp2-pio/piolib/spi3w_pio.go

@@ -96,12 +96,12 @@ func (sm StateMachine) IsEnabled() bool {
 	return sm.pio.hw.CTRL.HasBits(1 << (rp.PIO0_CTRL_SM_ENABLE_Pos + sm.index))
 }
 
-// Restart restarts the state machine
+// Restart clears internal StateMachine state which may otherwise be difficult to access, e.g. shift counters.
 func (sm StateMachine) Restart() {
 	sm.pio.hw.CTRL.SetBits(1 << (rp.PIO0_CTRL_SM_RESTART_Pos + sm.index))
 }
 
-// Restart a state machine clock divider with a phase of 0
+// ClkDivRestart forces clock dividers to restart their count and clear fractional accumulators (phase is zeroed).
 func (sm StateMachine) ClkDivRestart() {
 	sm.pio.hw.CTRL.SetBits(1 << (rp.PIO0_CTRL_CLKDIV_RESTART_Pos + sm.index))
 }
@@ -146,16 +146,16 @@ func (sm StateMachine) RxGet() uint32 {
 
 // TxReg gets a pointer to the TX FIFO register for this state machine.
 func (sm StateMachine) TxReg() *volatile.Register32 {
-	start := unsafe.Pointer(&sm.pio.hw.TXF0) // 0x10
+	start := uintptr(unsafe.Pointer(&sm.pio.hw.TXF0)) // 0x10
 	offset := uintptr(sm.index) * 4
-	return (*volatile.Register32)(unsafe.Pointer(uintptr(start) + offset))
+	return (*volatile.Register32)(unsafe.Pointer(start + offset))
 }
 
 // RxReg gets a pointer to the RX FIFO register for this state machine.
 func (sm StateMachine) RxReg() *volatile.Register32 {
-	start := unsafe.Pointer(&sm.pio.hw.RXF0) // 0x20
+	start := uintptr(unsafe.Pointer(&sm.pio.hw.RXF0)) // 0x20
 	offset := uintptr(sm.index) * 4
-	return (*volatile.Register32)(unsafe.Pointer(uintptr(start) + offset))
+	return (*volatile.Register32)(unsafe.Pointer(start + offset))
 }
 
 // RxFIFOLevel returns the number of elements currently in a state machine's RX FIFO.
@@ -238,6 +238,9 @@ func (sm StateMachine) SetPinsMasked(valueMask, pinMask uint32) {
 	sm.setPinExec(SrcDestPins, valueMask, pinMask)
 }
 
+// SetPindirsMasked sets the pin directions (input/output) on multiple pins for
+// the PIO instance. This method repeatedly reconfigures the state machines pins.
+// Use this method as convenience to set initial pin states BEFORE running state machine.
 func (sm StateMachine) SetPindirsMasked(dirMask, pinMask uint32) {
 	sm.setPinExec(SrcDestPinDirs, dirMask, pinMask)
 }
@@ -337,10 +340,10 @@ func (sm StateMachine) Jmp(toAddr uint8, cond JmpCond) {
 }
 
 const (
-	_REG_ALIAS_RW_BITS  = 0x0 << 12
-	_REG_ALIAS_XOR_BITS = 0x1 << 12
-	_REG_ALIAS_SET_BITS = 0x2 << 12
-	_REG_ALIAS_CLR_BITS = 0x3 << 12
+	// regAliasRW  = 0x0 << 12
+	regAliasXOR = 0x1 << 12
+	regAliasSET = 0x2 << 12
+	regAliasCLR = 0x3 << 12
 )
 
 // Gets the 'XOR' alias for a register
@@ -354,10 +357,13 @@ const (
 //   - Addr + 0x1000 : atomic XOR on write
 //   - Addr + 0x2000 : atomic bitmask set on write
 //   - Addr + 0x3000 : atomic bitmask clear on write
-func xorRegister(reg *volatile.Register32) *volatile.Register32 {
-	return (*volatile.Register32)(unsafe.Pointer(uintptr(unsafe.Pointer(reg)) | _REG_ALIAS_XOR_BITS))
+//
+//go:inline
+func aliasReg(alias uintptr, reg *volatile.Register32) *volatile.Register32 {
+	alias = uintptr(unsafe.Pointer(reg)) | alias
+	return (*volatile.Register32)(unsafe.Pointer(alias))
 }
 
 func xorBits(reg *volatile.Register32, bits uint32) {
-	xorRegister(reg).Set(bits)
+	aliasReg(regAliasXOR, reg).Set(bits)
 }