Add buffer read to AudioBufferManager and I2S (#2777)

* Added buffer read to `AudioBufferManager` and `I2S`. Example and documentation included.
* Update type of words to unsigned in example.
* Improve buffered loopback example.
* Remove const from read buffer.

docs/i2s.rst

@@ -164,7 +164,7 @@ size_t write(const uint8_t \*buffer, size_t size)
 Transfers number of bytes from an application buffer to the I2S output buffer.
 Be aware that ``size`` is in *bytes** and not samples.  Size must be a multiple
 of **4 bytes**.  Will not block, so check the return value to find out how
-many bytes were actually written.
+many 32-bit words were actually written.
 
 int availableForWrite()
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -181,6 +181,13 @@ int peek()
 Returns the next sample to be read from the I2S buffer (without actually
 removing it).
 
+size_t read(uint8_t \*buffer, size_t size)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Transfers number of bytes from the I2S input buffer to an application buffer.
+Be aware that ``size`` is in *bytes** and not samples.  Size must be a multiple
+of **4 bytes**.  Will not block, so check the return value to find out how
+many 32-bit words were actually read.
+
 void onTransmit(void (\*fn)(void))
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Sets a callback to be called when an I2S DMA buffer is fully transmitted.

libraries/AudioBufferManager/src/AudioBufferManager.cpp

@@ -204,7 +204,6 @@ size_t AudioBufferManager::write(const uint32_t *v, size_t words, bool sync) {
                     /* noop busy wait */
                 }
             }
-
         }
         size_t availToWriteThisBuff = _wordsPerBuffer - _userOff;
         size_t toWrite = std::min(availToWriteThisBuff, words);
@@ -245,6 +244,38 @@ bool AudioBufferManager::read(uint32_t *v, bool sync) {
     return true;
 }
 
+size_t AudioBufferManager::read(uint32_t *v, size_t words, bool sync) {
+    size_t read = 0;
+
+    if (!_running || _isOutput) {
+        return 0;
+    }
+    while (words) {
+        AudioBuffer ** volatile p = (AudioBuffer ** volatile)&_filled;
+        if (!*p) {
+            if (!sync) {
+                return read;
+            } else {
+                while (!*p) {
+                    /* noop busy wait */
+                }
+            }
+        }
+        size_t availToReadThisBuff = _wordsPerBuffer - _userOff;
+        size_t toRead = std::min(availToReadThisBuff, words);
+        memcpy((void *)v, &((*p)->buff[_userOff]), toRead * sizeof(uint32_t));
+        v += toRead;
+        read += toRead;
+        _userOff += toRead;
+        words -= toRead;
+        if (_userOff == _wordsPerBuffer) {
+            _addToList(&_empty, _takeFromList(p));
+            _userOff = 0;
+        }
+    }
+    return read;
+}
+
 bool AudioBufferManager::getOverUnderflow() {
     bool hold = _overunderflow;
     _overunderflow = false;

libraries/AudioBufferManager/src/AudioBufferManager.h

@@ -36,6 +36,7 @@ class AudioBufferManager {
     bool write(uint32_t v, bool sync = true);
     size_t write(const uint32_t *v, size_t words, bool sync = true);
     bool read(uint32_t *v, bool sync = true);
+    size_t read(uint32_t *v, size_t words, bool sync = true);
     void flush();
 
     bool getOverUnderflow();

libraries/I2S/examples/I2SLoopback_Buffer/I2SLoopback_Buffer.ino

@@ -0,0 +1,39 @@
+/*
+   I2S bi-directional input and output buffered loopback example
+   Released to the Public Domain by Cooper Dalrymple
+*/
+
+#include <I2S.h>
+
+I2S i2s(INPUT_PULLUP);
+
+#define SIZE 256
+int16_t buffer[SIZE];
+
+void setup() {
+  Serial.begin(115200);
+
+  i2s.setDOUT(0);
+  i2s.setDIN(1);
+  i2s.setBCLK(2); // Note: LRCLK = BCLK + 1
+  i2s.setBitsPerSample(16);
+  i2s.setFrequency(22050);
+  i2s.setBuffers(6, SIZE * sizeof(int16_t) / sizeof(uint32_t));
+  i2s.begin();
+
+  size_t count, index;
+  while (1) {
+    count = i2s.read((uint8_t *)&buffer, SIZE * sizeof(int16_t)) * sizeof(uint32_t) / sizeof(int16_t);
+    index = 0;
+    while (index < count) {
+      // Reduce volume by half
+      buffer[index++] >>= 1; // right
+      buffer[index++] >>= 1; // left
+    }
+    i2s.write((const uint8_t *)&buffer, count * sizeof(int16_t));
+  }
+}
+
+void loop() {
+  /* Nothing here */
+}

libraries/I2S/src/I2S.cpp

@@ -559,6 +559,14 @@ bool I2S::read32(int32_t *l, int32_t *r) {
     return true;
 }
 
+size_t I2S::read(uint8_t *buffer, size_t size) {
+    // We can only read 32-bit chunks here
+    if (size & 0x3 || !_running || !_isInput) {
+        return 0;
+    }
+    return _arbInput->read((uint32_t *)buffer, size / sizeof(uint32_t), false);
+}
+
 size_t I2S::write(const uint8_t *buffer, size_t size) {
     // We can only write 32-bit chunks here
     if (size & 0x3 || !_running || !_isOutput) {

libraries/I2S/src/I2S.h

@@ -127,6 +127,9 @@ class I2S : public Stream, public AudioOutputBase {
     bool read24(int32_t *l, int32_t *r); // Note that 24b reads will be left-aligned (see above)
     bool read32(int32_t *l, int32_t *r);
 
+    // Read samples into buffer
+    size_t read(uint8_t *buffer, size_t size);
+
     // Note that these callback are called from **INTERRUPT CONTEXT** and hence
     // should be in RAM, not FLASH, and should be quick to execute.
     void onTransmit(void(*)(void));