Merge pull request arduino#116 from adafruit/pb-spi

Merge Adafruit_ZeroDMA into SAMD core libraries

Author: ladyada

libraries/Adafruit_ZeroDMA/Adafruit_ZeroDMA.cpp

@@ -0,0 +1,66 @@
+#ifndef _ADAFRUIT_ZERODMA_H_
+#define _ADAFRUIT_ZERODMA_H_
+
+#include "Arduino.h"
+#include "utility/dma.h"
+
+// Status codes returned by some DMA functions and/or held in
+// a channel's jobStatus variable.
+enum ZeroDMAstatus {
+    DMA_STATUS_OK = 0,
+    DMA_STATUS_ERR_NOT_FOUND,
+    DMA_STATUS_ERR_NOT_INITIALIZED,
+    DMA_STATUS_ERR_INVALID_ARG,
+    DMA_STATUS_ERR_IO,
+    DMA_STATUS_ERR_TIMEOUT,
+    DMA_STATUS_BUSY,
+    DMA_STATUS_SUSPEND,
+    DMA_STATUS_ABORTED,
+    DMA_STATUS_JOBSTATUS = -1 // For printStatus() function
+};
+
+class Adafruit_ZeroDMA {
+ public:
+  Adafruit_ZeroDMA(void);
+
+  // DMA channel functions
+  ZeroDMAstatus   allocate(void), // Allocates DMA channel
+                  startJob(void),
+                  free(void);     // Deallocates DMA channel
+  void            trigger(void) const,
+                  setTrigger(uint8_t trigger),
+                  setAction(dma_transfer_trigger_action action),
+                  setCallback(void (*callback)(Adafruit_ZeroDMA *) = NULL,
+                    dma_callback_type type = DMA_CALLBACK_TRANSFER_DONE),
+                  loop(boolean flag),
+                  suspend(void) const,
+                  resume(void),
+                  abort(void),
+                  setPriority(dma_priority pri) const,
+                  printStatus(ZeroDMAstatus s = DMA_STATUS_JOBSTATUS) const;
+  uint8_t         getChannel(void) const { return channel; }
+
+  // DMA descriptor functions
+  DmacDescriptor *addDescriptor(void *src, void *dst, uint32_t count = 0,
+                    dma_beat_size size = DMA_BEAT_SIZE_BYTE,
+                    bool srcInc = true, bool dstInc = true, 
+                    uint32_t stepSize = DMA_ADDRESS_INCREMENT_STEP_SIZE_1, 
+                    bool stepSel = DMA_STEPSEL_DST);
+  void            changeDescriptor(DmacDescriptor *d, void *src = NULL,
+                    void *dst = NULL, uint32_t count = 0);
+  bool            isActive(void) const;
+
+  void            _IRQhandler(uint8_t flags); // DO NOT TOUCH
+
+
+ protected:  
+  uint8_t                     channel;
+  volatile enum ZeroDMAstatus jobStatus;
+  bool                        hasDescriptors;
+  bool                        loopFlag;
+  uint8_t                     peripheralTrigger;
+  dma_transfer_trigger_action triggerAction;
+  void                      (*callback[DMA_CALLBACK_N])(Adafruit_ZeroDMA *);
+};
+
+#endif // _ADAFRUIT_ZERODMA_H_

libraries/Adafruit_ZeroDMA/Adafruit_ZeroDMA.h

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Adafruit Industries
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

libraries/Adafruit_ZeroDMA/LICENSE

@@ -0,0 +1,6 @@
+# Adafruit_ZeroDMA
+DMA helper/wrapped for ATSAMD21 such as Arduino Zero & Feather M0
+
+Current version of this library no longer requires Adafruit_ASFcore as a prerequisite. However...IT BREAKS COMPATIBILITY WITH PRIOR VERSIONS. Function names, calling sequence and return types/values have changed. See examples!
+
+Item(s) in 'utility' directory are much pared-down derivatives of Atmel ASFcore 3 files. Please keep their original copyright and license intact when editing.

libraries/Adafruit_ZeroDMA/README.md

@@ -0,0 +1,94 @@
+// Simple ZeroDMA example -- an equivalent to the memcpy() function.
+// Decause it uses DMA, unlike memcpy(), your code could be doing other
+// things simultaneously while the copy operation runs.
+
+#include <Adafruit_ZeroDMA.h>
+#include "utility/dma.h"
+
+Adafruit_ZeroDMA myDMA;
+ZeroDMAstatus    stat; // DMA status codes returned by some functions
+
+// The memory we'll be moving:
+#define DATA_LENGTH 1024
+uint8_t source_memory[DATA_LENGTH],
+        destination_memory[DATA_LENGTH];
+
+volatile bool transfer_is_done = false; // Done yet?
+
+// Callback for end-of-DMA-transfer
+void dma_callback(Adafruit_ZeroDMA *dma) {
+  transfer_is_done = true;
+}
+
+void setup() {
+  uint32_t t;
+  pinMode(LED_BUILTIN, OUTPUT);   // Onboard LED can be used for precise
+  digitalWrite(LED_BUILTIN, LOW); // benchmarking with an oscilloscope
+  Serial.begin(115200);
+  while(!Serial);                 // Wait for Serial monitor before continuing
+
+  Serial.println("DMA test: memory copy");
+
+  Serial.print("Allocating DMA channel...");
+  stat = myDMA.allocate();
+  myDMA.printStatus(stat);
+
+  Serial.println("Setting up transfer");
+  myDMA.addDescriptor(source_memory, destination_memory, DATA_LENGTH);
+
+  Serial.println("Adding callback");
+  // register_callback() can optionally take a second argument
+  // (callback type), default is DMA_CALLBACK_TRANSFER_DONE
+  myDMA.setCallback(dma_callback);
+
+  // Fill the source buffer with incrementing bytes, dest buf with 0's
+  for(uint32_t i=0; i<DATA_LENGTH; i++) source_memory[i] = i;
+  memset(destination_memory, 0, DATA_LENGTH);
+
+  // Show the destination buffer is empty before transfer
+  Serial.println("Destination buffer before transfer:");
+  dump();
+
+  Serial.println("Starting transfer job");
+  stat = myDMA.startJob();
+  myDMA.printStatus(stat);
+
+  Serial.println("Triggering DMA transfer...");
+  t = micros();
+  digitalWrite(LED_BUILTIN, HIGH);
+  myDMA.trigger();
+
+  // Your code could do other things here while copy happens!
+
+  while(!transfer_is_done); // Chill until DMA transfer completes
+
+  digitalWrite(LED_BUILTIN, LOW);
+  t = micros() - t; // Elapsed time
+
+  Serial.print("Done! ");
+  Serial.print(t);
+  Serial.println(" microseconds");
+
+  Serial.println("Destination buffer after transfer:");
+  dump();
+
+  // Now repeat the same operation, but 'manually' using memcpy() (not DMA):
+  t = micros();
+  digitalWrite(LED_BUILTIN, HIGH);
+  memcpy(destination_memory, source_memory,  DATA_LENGTH);
+  digitalWrite(LED_BUILTIN, LOW);
+  t = micros() - t; // Elapsed time
+  Serial.print("Same operation without DMA: ");
+  Serial.print(t);
+  Serial.println(" microseconds");
+}
+
+// Show contents of destination_memory[] array
+void dump() {
+  for(uint32_t i=0; i<DATA_LENGTH; i++) {
+    Serial.print(destination_memory[i], HEX); Serial.print(' ');
+    if ((i & 15) == 15) Serial.println();
+  }
+}
+
+void loop() { }

libraries/Adafruit_ZeroDMA/examples/zerodma_memcpy/zerodma_memcpy.ino

@@ -0,0 +1,97 @@
+// DMA-based SPI buffer write.  This is transmit-only as written, i.e.
+// not equivalent to Arduino's SPI.transfer() which both sends and
+// receives a single byte or word.  Also, this is single-buffered to
+// demonstrate a simple SPI write case.  See zerodma_spi2.ino for an
+// example using double buffering (2 buffers alternating fill & transmit).
+
+#include <SPI.h>
+#include <Adafruit_ZeroDMA.h>
+#include "utility/dma.h"
+
+Adafruit_ZeroDMA myDMA;
+ZeroDMAstatus    stat; // DMA status codes returned by some functions
+
+// The memory we'll be issuing to SPI:
+#define DATA_LENGTH 2048
+uint8_t source_memory[DATA_LENGTH];
+
+volatile bool transfer_is_done = false; // Done yet?
+
+// Callback for end-of-DMA-transfer
+void dma_callback(Adafruit_ZeroDMA *dma) {
+  transfer_is_done = true;
+}
+
+void setup() {
+  uint32_t t;
+  pinMode(LED_BUILTIN, OUTPUT);   // Onboard LED can be used for precise
+  digitalWrite(LED_BUILTIN, LOW); // benchmarking with an oscilloscope
+  Serial.begin(115200);
+  while(!Serial);                 // Wait for Serial monitor before continuing
+
+  Serial.println("DMA test: SPI data out");
+
+  SPI.begin();
+
+  Serial.println("Configuring DMA trigger");
+#ifdef __SAMD51__
+  // SERCOM2 is the 'native' SPI SERCOM on Metro M4
+  myDMA.setTrigger(SERCOM2_DMAC_ID_TX);
+#else
+  // SERCOM4 is the 'native' SPI SERCOM on most M0 boards
+  myDMA.setTrigger(SERCOM4_DMAC_ID_TX);
+#endif
+  myDMA.setAction(DMA_TRIGGER_ACTON_BEAT);
+
+  Serial.print("Allocating DMA channel...");
+  stat = myDMA.allocate();
+  myDMA.printStatus(stat);
+
+  Serial.println("Setting up transfer");
+  myDMA.addDescriptor(
+    source_memory,                    // move data from here
+#ifdef __SAMD51__
+    (void *)(&SERCOM2->SPI.DATA.reg), // to here (M4)
+#else
+    (void *)(&SERCOM4->SPI.DATA.reg), // to here (M0)
+#endif
+    DATA_LENGTH,                      // this many...
+    DMA_BEAT_SIZE_BYTE,               // bytes/hword/words
+    true,                             // increment source addr?
+    false);                           // increment dest addr?
+
+  Serial.println("Adding callback");
+  // register_callback() can optionally take a second argument
+  // (callback type), default is DMA_CALLBACK_TRANSFER_DONE
+  myDMA.setCallback(dma_callback);
+
+  // Fill the source buffer with incrementing bytes
+  for(uint32_t i=0; i<DATA_LENGTH; i++) source_memory[i] = i;
+
+  // Start SPI transaction at 12 MHz
+  SPI.beginTransaction(SPISettings(12000000, MSBFIRST, SPI_MODE0));
+
+  Serial.println("Starting transfer job");
+  t = micros();
+  digitalWrite(LED_BUILTIN, HIGH);
+
+  // Because we've configured a peripheral trigger (SPI), there's
+  // no need to manually trigger transfer, it starts up on its own.
+  stat = myDMA.startJob();
+
+  // Your code could do other things here while SPI write happens!
+
+  while(!transfer_is_done); // Chill until DMA transfer completes
+
+  digitalWrite(LED_BUILTIN, LOW);
+  t = micros() - t; // Elapsed time
+
+  SPI.endTransaction();
+  myDMA.printStatus(stat); // Results of start_transfer_job()
+
+  Serial.print("Done! ");
+  Serial.print(t);
+  Serial.println(" microseconds");
+}
+
+void loop() { }

libraries/Adafruit_ZeroDMA/examples/zerodma_spi1/zerodma_spi1.ino

@@ -0,0 +1,103 @@
+// Double-buffered DMA on auxiliary SPI peripheral on pins 11/12/13.
+// Continuously alternates between two data buffers...one is filled
+// with new data as the other is being transmitted.
+
+#include <SPI.h>
+#include <Adafruit_ZeroDMA.h>
+#include "utility/dma.h"
+#include "wiring_private.h" // pinPeripheral() function
+
+// Declare our own SPI peripheral 'mySPI' on pins 11/12/13:
+// (Do not call this SPI1; Arduino Zero and Metro M0 already
+// have an SPI1 (the EDBG interface) and it won't compile.)
+SPIClass mySPI(
+  &sercom1,         // -> Sercom peripheral
+  34,               // MISO pin (also digital pin 12)
+  37,               // SCK pin  (also digital pin 13)
+  35,               // MOSI pin (also digital pin 11)
+  SPI_PAD_0_SCK_1,  // TX pad (MOSI, SCK pads)
+  SERCOM_RX_PAD_3); // RX pad (MISO pad)
+
+Adafruit_ZeroDMA myDMA;
+ZeroDMAstatus    stat; // DMA status codes returned by some functions
+
+// Data we'll issue to mySPI.  There are TWO buffers; one being
+// filled with new data while the other's being transmitted in
+// the background.
+#define DATA_LENGTH 512
+uint8_t source_memory[2][DATA_LENGTH],
+        buffer_being_filled = 0, // Index of 'filling' buffer
+        buffer_value        = 0; // Value of fill
+
+volatile bool transfer_is_done = true; // Done yet?
+
+// Callback for end-of-DMA-transfer
+void dma_callback(Adafruit_ZeroDMA *dma) {
+  transfer_is_done = true;
+}
+
+DmacDescriptor *desc; // DMA descriptor address (so we can change contents)
+
+void setup() {
+  Serial.begin(115200);
+  while(!Serial); // Wait for Serial monitor before continuing
+
+  Serial.println("DMA test: SPI data out");
+
+  mySPI.begin();
+  // Assign pins 11, 12, 13 to SERCOM functionality
+  pinPeripheral(11, PIO_SERCOM);
+  pinPeripheral(12, PIO_SERCOM);
+  pinPeripheral(13, PIO_SERCOM);
+
+  // Configure DMA for SERCOM1 (our 'mySPI' port on 11/12/13)
+  Serial.println("Configuring DMA trigger");
+  myDMA.setTrigger(SERCOM1_DMAC_ID_TX);
+  myDMA.setAction(DMA_TRIGGER_ACTON_BEAT);
+
+  Serial.print("Allocating DMA channel...");
+  stat = myDMA.allocate();
+  myDMA.printStatus(stat);
+
+  desc = myDMA.addDescriptor(
+    source_memory[buffer_being_filled], // move data from here
+    (void *)(&SERCOM1->SPI.DATA.reg),   // to here
+    DATA_LENGTH,                        // this many...
+    DMA_BEAT_SIZE_BYTE,                 // bytes/hword/words
+    true,                               // increment source addr?
+    false);                             // increment dest addr?
+
+  Serial.println("Adding callback");
+  // register_callback() can optionally take a second argument
+  // (callback type), default is DMA_CALLBACK_TRANSFER_DONE
+  myDMA.setCallback(dma_callback);
+}
+
+void loop() {
+  // Fill buffer with new data.  The other buffer might
+  // still be transmitting in the background via DMA.
+  memset(source_memory[buffer_being_filled], buffer_value, DATA_LENGTH);
+
+  // Wait for prior transfer to complete before starting new one...
+  Serial.print("Waiting on prior transfer...");
+  while(!transfer_is_done) Serial.write('.');
+  mySPI.endTransaction();
+  Serial.println("Done!");
+
+  // Modify the DMA descriptor using the newly-filled buffer as source...
+  myDMA.changeDescriptor(desc,           // DMA descriptor address
+    source_memory[buffer_being_filled]); // New src; dst & count don't change
+
+  // Begin new transfer...
+  Serial.println("Starting new transfer job");
+  mySPI.beginTransaction(SPISettings(12000000, MSBFIRST, SPI_MODE0));
+  transfer_is_done = false;            // Reset 'done' flag
+  stat             = myDMA.startJob(); // Go!
+  myDMA.printStatus(stat);
+
+  // Switch buffer indices so the alternate buffer is filled/xfer'd
+  // on the next pass.
+  buffer_being_filled = 1 - buffer_being_filled;
+  buffer_value++;
+}
+