Merge develop into master

.github/scripts/build_test_apps.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+set -e
+
+pwd
+
+wget https://raw.githubusercontent.com/xmos/xmos_cmake_toolchain/main/xs3a.cmake
+wget https://raw.githubusercontent.com/xmos/xmos_cmake_toolchain/main/xc_override.cmake
+cmake -B build.xcore -DDEV_LIB_MIC_ARRAY=1 -DCMAKE_TOOLCHAIN_FILE=./xs3a.cmake
+pushd build.xcore
+make all
+# I can't get the following two (custom) targets to build with 'all'.
+# Currently an issue with java prevents these from working in CI.
+# make tests-legacy_build
+# make tests-legacy_build_vanilla

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+# YAML schema for GitHub Actions:
+# https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions
+#
+# Helpful YAML parser to clarify YAML syntax:
+# https://yaml-online-parser.appspot.com/
+#
+# This workflow uses actions that are not certified by GitHub. They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support documentation.
+#
+# This file contains the workflows that are run prior to merging a pull request.
+
+name: CI
+
+on:
+  push:
+    branches:
+      - 'develop'
+      - 'master'
+  pull_request:
+    branches:
+      - 'develop'
+      - 'master'
+
+  # Allow manually triggering of the workflow.
+  workflow_dispatch: {}
+
+jobs:
+  build_tests_xcore:
+    name: Build Test Apps
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+        with:
+          submodules: recursive
+
+      - name: Pull builder container
+        run: |
+          docker pull ghcr.io/xmos/xcore_builder:latest 
+
+      - name: Install Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.8'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install numpy
+
+      - name: Build
+        run: |
+          docker run --rm -w /lib_mic_array -v ${{ github.workspace }}:/lib_mic_array ghcr.io/xmos/xcore_builder:latest bash -l .github/scripts/build_test_apps.sh
+

.github/workflows/docs.yml

@@ -0,0 +1,57 @@
+# YAML schema for GitHub Actions:
+# https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions
+#
+# Helpful YAML parser to clarify YAML syntax:
+# https://yaml-online-parser.appspot.com/
+#
+# This workflow uses actions that are not certified by GitHub. They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support documentation.
+#
+# This file contains the workflows that are run prior to merging a pull request.
+
+name: Docs
+
+on:
+  push:
+    branches:
+      - 'develop'
+      - 'master'
+  pull_request:
+    branches:
+      - 'develop'
+      - 'master'
+
+  # Allow manually triggering of the workflow.
+  workflow_dispatch: {}
+
+jobs:
+  build_documentation:
+    name: Build and package documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Pull doc_builder container
+        run: |
+          docker pull ghcr.io/xmos/doc_builder:v2.0.0
+
+      - name: Build documentation
+        run: |
+          docker run --rm -t -u "$(id -u):$(id -g)" -v ${{ github.workspace }}:/build -e REPO:/build -e DOXYGEN_INCLUDE=/build/doc/Doxyfile.inc  -e EXCLUDE_PATTERNS=/build/doc/doc_excludes.txt -e DOXYGEN=1 -e DOXYGEN_INCLUDE=/build/doc/Doxyfile.inc -e PDF=1 ghcr.io/xmos/doc_builder:v2.0.0
+
+      - name: Save HTML documentation artifact
+        uses: actions/upload-artifact@v2
+        with:
+          name: lib_mic_array_docs
+          path: ./doc/_build/html
+          if-no-files-found: error # 'warn' or 'ignore' are also available, defaults to `warn` 
+          retention-days: 5
+
+      - name: Save PDF documentation artifact
+        uses: actions/upload-artifact@v2
+        with:
+          name: lib_xcore_math_docs_pdf
+          path: ./doc/_build/pdf/programming_guide.pdf
+          if-no-files-found: error # 'warn' or 'ignore' are also available, defaults to `warn` 
+          retention-days: 5

.gitignore

@@ -1,6 +1,8 @@
 **/.build*/*
 bin/
 _build/
+xcore_sdk/
+.vscode/
 *.o
 *.xe
 *.vcd
@@ -31,6 +33,12 @@ tests/test_results.csv
 examples/AN00221_freq_domain_example/doc/pdf/AN00218.pdf
 examples/AN00218_app_hires_DAS_fixed/doc/pdf/AN00218.pdf
 **/.venv/**
+**/__pycache__/
+**/.ipynb_checkpoints/
+
+# Any files user wants to keep in their local clone
+**/*.local.*
+**/*.local.*/
 
 
 # Unit test runners

CHANGELOG.rst

@@ -1,16 +1,38 @@
 lib_mic_array change log
 ========================
 
-4.5.0
+5.0.2
 -----
 
-  * REMOVED: Use of Brew for CI
-  * CHANGED: XMOS Jenkins Shared Library version used in CI
+  * Documentation improvements.
 
-4.4.0
+5.0.1
 -----
+  * Updates lib_mic_array to use lib_xcore_math (formerly lib_xs3_math) version 2.0.2
+  * Updates CMake project to use CPM to obtain dependencies (when top level project)
+  * [issue #171] Changes behavior when mic array consumer gets backed up from a quiet deadlock to an ECALL exception
+    * Also adds a way to allow blocks of PDM to be quietly dropped instead  (see AssertOnDroppedBlock())
+
+5.0.0
+-----
+
+  * Mic Array library redesigned from scratch to make efficient use of XMOS XS3 architecture
+  * Many unused features from previous versions have been dropped
+  * Initial v5.0 features:
+
+    * Supports 1-, 4-, and 8-bit ports
+    * Supports both SDR and DDR microphone configurations
+    * Use 1-16 PDM microphones
+    * Configurable PDM clock frequency
+    * Configurable two-stage decimating FIR
+
+      * Reference filter with total decimation factor of 192 provided
+
+    * Optional DC offset elimination filter
+    * Configurable frame size (down to single sample)
+    * Extensible C++ design
+
 
-  * CHANGED: XN files to support 15.x.x tools
 
 4.3.0
 -----

CMakeLists.txt

@@ -0,0 +1,58 @@
+cmake_minimum_required(VERSION 3.14)
+
+
+# Disable in-source build.
+if("${CMAKE_SOURCE_DIR}" STREQUAL "${CMAKE_BINARY_DIR}")
+    message(FATAL_ERROR "In-source build is not allowed! Please specify a build folder.\n\tex:cmake -B build")
+endif()
+
+include(cmake/CPM.cmake)
+
+# if( PROJECT_IS_TOP_LEVEL )
+#   message(STATUS "Configuring as top-level project")
+#   set( DEV_LIB_MIC_ARRAY 1 )
+# endif()
+
+# If DEV_LIB_MIC_ARRAY is not defined, set it to true iff the root 
+# build dir (CMAKE_BINARY_DIR) is a child of the current source dir.
+# This will tell us whether to include the demos and tests.
+if(NOT DEFINED DEV_LIB_MIC_ARRAY)
+  set(DEV_LIB_MIC_ARRAY 0)
+  get_filename_component(BIN_PARENT ${CMAKE_BINARY_DIR} DIRECTORY)
+  if("${CMAKE_CURRENT_SOURCE_DIR}" STREQUAL "${BIN_PARENT}")
+      set(DEV_LIB_MIC_ARRAY 1)
+  endif()
+endif()
+
+project(lib_mic_array 
+    VERSION 5.0.1
+    LANGUAGES CXX C ASM)
+
+if( PROJECT_IS_TOP_LEVEL OR ${DEV_LIB_MIC_ARRAY} )
+  # Fixes issue where .xc files always recompile on Windows
+  string(REPLACE "-MD" "-MMD" CMAKE_DEPFILE_FLAGS_C ${CMAKE_DEPFILE_FLAGS_C})
+endif()
+
+# Add lib_mic_array
+add_subdirectory(lib_mic_array)
+
+if( PROJECT_IS_TOP_LEVEL )
+  set(CMAKE_INSTALL_PREFIX ${CMAKE_BINARY_DIR})
+endif()
+
+# Make vanilla API macro available
+include( etc/vanilla/vanilla.cmake )
+
+#**********************
+# Demos/Tests
+#**********************
+
+if(${DEV_LIB_MIC_ARRAY})
+  CPMAddPackage(
+    NAME lib_xcore_math
+    GIT_REPOSITORY https://github.com/xmos/lib_xcore_math
+    GIT_TAG        v2.1.0
+  )
+  add_subdirectory( demos )
+  add_subdirectory( tests )
+endif()

README.rst

@@ -1,47 +1,31 @@
-Microphone array library
+Microphone Array Library
 ========================
 
 Summary
 -------
 
 The XMOS microphone array library is designed to allow interfacing to PDM 
-microphones coupled with efficient decimation to user selectable output
-sample rates. Additionally, a high resolution delay can be introduced to 
-each of the individual PDM microphones allowing for individual time shifts.
-This library is only available for XS2 devices.
+microphones coupled with efficient decimation to user configurable output
+sample rates. This library is only available for XS3 devices.
 
 Features
 ........
 
 The microphone array library has the following features:
 
-  - 48kHz, 24kHz, 16kHz, 12kHz and 8kHz output sample rate by default (3.072MHz PDM clock), 
-  - 44.1kHz, 22.05kHz, 14.7kHz, 11.025kHz and 7.35kHz output sample rate by default (2.8224MHz PDM clock), 
-  - 4, 8, 12 or 16 PDM interfaces per tile,
-  - No less than 70dB of stop band attenuation for all output sample frequencies,
-  - Configurable latency, ripple and bandwidth,
-  - Framing, configurable frame size from 1 sample to 8192 samples plus 50% overlapping frames option,
-  - Windowing and sample index bit reversal within a frame,
-  - Individual microphone gain compensation,
-  - DC offset removal,
-  - Up to 3.072MHz input sample rate,
-  - High resolution (2.63 microsecond) microphone specific delay lines,
-  - Every task requires only a 62.5 MIPS core to run,
-  - Group delay of a maximum of 18 output clock cycles,
-  - No less than 140dB of dynamic range.
-
-Components
-...........
-
- * PDM interface,
- * Four channel decimators,
- * High resolution delay block.
+  - 48kHz, 24kHz, 16kHz, 12kHz and 8kHz output sample rate by default (3.072MHz PDM clock)
+  - Configurable PDM clock divider
+  - Use the provided reference decimation filter or supply your own
+  - 1 to 16 PDM microphones
+  - Supports both SDR and DDR microphone configurations
+  - Framing with configurable frame size
+  - DC offset removal
+  - Extensible C++ design
 
 Software version and dependencies
 .................................
 
 The CHANGELOG contains information about the current and previous versions.
-For a list of direct dependencies, look for DEPENDENT_MODULES in lib_mic_array/module_build_info.
 
 Related application notes
 .........................