Add SPISlave class (#1717)

Allows the Pico to behave as an SPI slave and allows apps to respond
with appropriate data through callbacks.

Fixes #1680

Author: earlephilhower

README.md

@@ -214,7 +214,7 @@ The installed tools include a version of OpenOCD (in the pqt-openocd directory)
 * Analog stereo audio in using DMA and the built-in ADC
 * Analog stereo audio out using PWM hardware
 * USB drive mode for data loggers (SingleFileDrive)
-* Peripherals:  SPI master, Wire(I2C) master/slave, dual UART, emulated EEPROM, I2S audio input, I2S audio output, Servo
+* Peripherals:  SPI master/slave, Wire(I2C) master/slave, dual UART, emulated EEPROM, I2S audio input/output, Servo
 * printf (i.e. debug) output over USB serial
 
 The RP2040 PIO state machines (SMs) are used to generate jitter-free:

docs/spi.rst

@@ -1,5 +1,5 @@
-SPI (Serial Peripheral Interface)
-=================================
+SPI Master (Serial Peripheral Interface)
+========================================
 
 The RP2040 has two hardware SPI interfaces, ``spi0 (SPI)`` and ``spi1 (SPI1)``.
 These interfaces are supported by the ``SPI`` library in master mode.
@@ -20,5 +20,26 @@ The Arduino `SPI documentation <https://www.arduino.cc/en/reference/SPI>`_ gives
 a detailed overview of the library, except for the following RP2040-specific
 changes:
 
-* ``SPI.begin(bool hwCS)`` can take an options ``hwCS`` parameter.  By passing in ``true`` for ``hwCS`` the sketch does not need to worry about asserting and deasserting the ``CS`` pin between transactions.  The default is ``false`` and requires the sketch to handle the CS pin itself, as is the standard way in Arduino.
-* The interrupt calls (``usingInterrupt``, ``notUsingInterrupt``, ``attachInterrupt``, and ``detachInterrpt``) are not implemented.
+* ``SPI.begin(bool hwCS)`` can take an options ``hwCS`` parameter.
+By passing in ``true`` for ``hwCS`` the sketch does not need to worry
+about asserting and deasserting the ``CS`` pin between transactions.
+The default is ``false`` and requires the sketch to handle the CS
+pin itself, as is the standard way in Arduino.
+
+* The interrupt calls (``attachInterrupt``, and ``detachInterrpt``) are not implemented.
+
+
+SPI Slave (SPISlave)
+====================
+
+Slave mode operation is also supported on either SPI interface.  Two callbacks are
+needed in your app, set through ``SPISlave.onDataRecv`` and ``SPISlave.onDataSent``,
+in order to consunme the received data and provide data to transmit.
+
+* The callbacks operate at IRQ time and may be called very frequently at high SPI frequencies.  So, make then small, fast, and with no memory allocations or locking.
+
+
+Examples
+========
+
+See the SPItoMyself example for a complete Master and Slave application.

libraries/SPI/src/SPI.h

@@ -61,7 +61,7 @@ class SPIClassRP2040 : public arduino::HardwareSPI {
     void setDataMode(uint8_t uc_mode) __attribute__((deprecated));
     void setClockDivider(uint8_t uc_div) __attribute__((deprecated));
 
-    // Unimplemented
+    // List of GPIO IRQs to disable during a transaction
     virtual void usingInterrupt(int interruptNumber) override {
         _usingIRQs.insert({interruptNumber, 0});
     }

libraries/SPISlave/examples/SPItoMyself/SPItoMyself.ino

@@ -0,0 +1,89 @@
+// Shows how to use SPISlave on a single device.
+// Core0 runs as an SPI master and initiates a transmission to the slave
+// Core1 runs the SPI Slave mode and provides a unique reply to messages from the master
+//
+// Released to the public domain 2023 by Earle F. Philhower, III <[email protected]>
+
+#include <SPI.h>
+#include <SPISlave.h>
+
+// Wiring:
+// Master RX  GP0 <-> GP11  Slave TX
+// Master CS  GP1 <-> GP9   Slave CS
+// Master CK  GP2 <-> GP10  Slave CK
+// Master TX  GP3 <-> GP8   Slave RX
+
+SPISettings spisettings(1000000, MSBFIRST, SPI_MODE0);
+
+// Core 0 will be SPI master
+void setup() {
+  SPI.setRX(0);
+  SPI.setCS(1);
+  SPI.setSCK(2);
+  SPI.setTX(3);
+  SPI.begin(true);
+
+  delay(5000);
+}
+
+int transmits = 0;
+void loop() {
+  char msg[42];
+  memset(msg, 0, sizeof(msg));
+  sprintf(msg, "What's up? This is transmission %d", transmits);
+  Serial.printf("\n\nM-SEND: '%s'\n", msg);
+  SPI.beginTransaction(spisettings);
+  SPI.transfer(msg, sizeof(msg));
+  SPI.endTransaction();
+  Serial.printf("M-RECV: '%s'\n", msg);
+  transmits++;
+  delay(5000);
+}
+
+// Core 1 will be SPI slave
+
+volatile bool recvBuffReady = false;
+char recvBuff[42] = "";
+int recvIdx = 0;
+void recvCallback(uint8_t *data, size_t len) {
+  memcpy(recvBuff + recvIdx, data, len);
+  recvIdx += len;
+  if (recvIdx == sizeof(recvBuff)) {
+    recvBuffReady = true;
+    recvIdx = 0;
+  }
+}
+
+int sendcbs = 0;
+// Note that the buffer needs to be long lived, the SPISlave doesn't copy it.  So no local stack variables, only globals or heap(malloc/new) allocations.
+char sendBuff[42];
+void sentCallback() {
+  memset(sendBuff, 0, sizeof(sendBuff));
+  sprintf(sendBuff, "Slave to Master Xmission %d", sendcbs++);
+  SPISlave1.setData((uint8_t*)sendBuff, sizeof(sendBuff));
+}
+
+// Note that we use SPISlave1 here **not** because we're running on
+// Core 1, but because SPI0 is being used already.  You can use
+// SPISlave or SPISlave1 on any core.
+void setup1() {
+  SPISlave1.setRX(8);
+  SPISlave1.setCS(9);
+  SPISlave1.setSCK(10);
+  SPISlave1.setTX(11);
+  // Ensure we start with something to send...
+  sentCallback();
+  // Hook our callbacks into the slave
+  SPISlave1.onDataRecv(recvCallback);
+  SPISlave1.onDataSent(sentCallback);
+  SPISlave1.begin(spisettings);
+  delay(3000);
+  Serial.println("S-INFO: SPISlave started");
+}
+
+void loop1() {
+  if (recvBuffReady) {
+    Serial.printf("S-RECV: '%s'\n", recvBuff);
+    recvBuffReady = false;
+  }
+}

libraries/SPISlave/keywords.txt

@@ -0,0 +1,40 @@
+#######################################
+# Syntax Coloring Map SPI
+#######################################
+
+#######################################
+# Instances (KEYWORD2)
+#######################################
+
+SPISlave	KEYWORD1
+SPISlave1	KEYWORD1
+
+#######################################
+# Methods and Functions (KEYWORD2)
+#######################################
+begin	KEYWORD2
+end	KEYWORD2
+SPISettings	KEYWORD2
+setRX	KEYWORD2
+setTX	KEYWORD2
+setSCK	KEYWORD2
+setCS	KEYWORD2
+setData	KEYWORD2
+onDataRecv	KEYWORD2
+onDataSent	KEYWORD2
+
+#######################################
+# Constants (LITERAL1)
+#######################################
+SPI_CLOCK_DIV4	LITERAL1
+SPI_CLOCK_DIV16	LITERAL1
+SPI_CLOCK_DIV64	LITERAL1
+SPI_CLOCK_DIV128	LITERAL1
+SPI_CLOCK_DIV2	LITERAL1
+SPI_CLOCK_DIV8	LITERAL1
+SPI_CLOCK_DIV32	LITERAL1
+SPI_CLOCK_DIV64	LITERAL1
+SPI_MODE0	LITERAL1
+SPI_MODE1	LITERAL1
+SPI_MODE2	LITERAL1
+SPI_MODE3	LITERAL1

libraries/SPISlave/library.properties

@@ -0,0 +1,10 @@
+name=SPISlave
+version=1.0
+author=Earle F. Philhower, III <[email protected]>
+maintainer=Earle F. Philhower, III <[email protected]>
+sentence=Enables the communication as a slave SPI devices.
+paragraph=
+category=Signal Input/Output
+url=https://github.com/earlephilhower/arduino-pico
+architectures=rp2040
+dot_a_linkage=true