init

lib_mic_array/CHANGELOG.rst

@@ -0,0 +1,260 @@
+lib_mic_array change log
+========================
+
+5.5.0
+-----
+
+  * CHANGED: Documentation updated
+  * CHANGED: Renamed examples to app_
+  * CHANGED: Renamed the scripts/ directory to python/
+
+  * Changes to dependencies:
+
+    - lib_xcore_math: 2.3.0 -> 2.4.0
+
+5.4.0
+-----
+
+  * CHANGED: All examples now build under XCommon CMake build system
+  * ADDED:   Will build without errors for XS2 targets but no API available
+  * DEPRECATED: Previously used custom CMake build support. This will be removed
+    in future versions. Please use XCommon CMake build system as provided in XTC
+    15.3.0 onwards for new projects.
+
+  * Changes to dependencies:
+
+    - lib_xcore_math: 2.0.0 -> 2.3.0
+
+5.3.0
+-----
+
+  * FIXED:   Vanilla configuration now compiles correctly under XTC 15.3.0
+  * ADDED:   Support for XCommon CMake build system
+
+5.2.0
+-----
+
+  * Added 48 kHz decimator design script
+  * Added documentation to cover 32 kHz and 48 kHz deciamtors
+
+5.1.0
+-----
+
+  * Added 16ch de-interleave to support 16 DDR mics on a single 8b port
+  * Added parallel decimation use example
+  * Fixed documentation generation issues
+
+5.0.3
+-----
+
+  * Improved default audio filter. Reduces noise floor and improves alias
+    attentuation
+  * Changed DCOE filter to increase attenuation below 20 Hz
+
+5.0.2
+-----
+
+  * Documentation improvements.
+
+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
+
+  * Changes to dependencies:
+
+    - lib_dsp: Removed dependency
+
+    - lib_logging: Removed dependency
+
+    - lib_xassert: Removed dependency
+
+    - lib_xcore_math: Added dependency 2.0.0
+
+4.3.0
+-----
+
+  * CHANGED: Use XMOS Public Licence Version 1
+  * FIXED: Compiler warnings when MIC_DUAL_ENABLED is not defined
+
+4.2.2
+-----
+
+  * CHANGED: Pin Python package versions
+  * REMOVED: not necessary cpanfile
+
+4.2.1
+-----
+
+  * CHANGED: Jenkinsfile pinned to Jenkins shared library 0.10.0
+  * CHANGED: Updated the minimum version of libraries this library depends upon.
+
+4.2.0
+-----
+
+  * ADDED support for global define to set single/dual output buffer for
+    mic_dual
+
+4.1.0
+-----
+
+  * Added mic_dual, an optimised single core, 16kHz, two channel version (not
+    compatible with async interface)
+
+4.0.0
+-----
+
+  * ADDED: Support for arbitrary frame sizes
+  * ADDED: #defines for mic muting
+  * ADDED: Non-blocking interface to decimators for 2 mic setup
+  * CHANGED: Build files updated to support new "xcommon" behaviour in xwaf.
+
+3.2.0
+-----
+
+  * Added xwaf build system support
+  * Cleaned up some of the code in the FIR designer.
+  * Removed fixed gain in examples
+  * Update VU meter example
+  * Fix port types in examples
+  * Set and inherit XCC_FLAGS rather than XCC_XC_FLAGS when building library
+
+3.1.1
+-----
+
+  * Updated lib_dsp dependancy from 3.0.0 to 4.0.0
+
+3.1.0
+-----
+
+  * Modified the FIR designer to increase the first stage stopband attenuation.
+  * Cleaned up some of the code in the FIR designer.
+  * Updated docs to reflect the above.
+
+3.0.2
+-----
+
+  * Update DAC settings to work for mic array base board as well.
+
+3.0.1
+-----
+
+  * Filter design script update for usability.
+  * Documentation improvement.
+  * Changed DEBUG_UNIT to XASSERT_UNIT to work with lib_xassert.
+  * Added upgrade advisory.
+  * Added dynamic range subsection to documentation.
+
+3.0.0
+-----
+
+  * Added ability to route internal channels of the output rate of the mic_array
+    to the mic_array so that they can benefit from the post processing of the
+    mic_array.
+  * Enabled the metadata which delivers the frame counter.
+  * Small fix to the filter generator to allow the use of fewer taps in the
+    final stage FIR.
+  * Added significant bits collection to the metadata.
+  * Added fixed gain control through define MIC_ARRAY_FIXED_GAIN.
+  * Tested and enabled the debug mode for detecting frame dropping. Enabled by
+    adding DEBUG_MIC_ARRAY to the Makefile.
+  * Moved to using types from lib_dsp.
+  * Bug fix in python FIR generator script resulting in excessive output ripple.
+  * Default FIR coefficients now optimised for 16kHz output sample rate.
+  * Added ability to remap port pins to channels.
+  * MIC_ARRAY_NUM_MICS is now forced to a multiple of 4 with a warning if it
+    changed.
+  * Corrected MIC_ARRAY_DC_OFFSET_LOG2 default value reporting in documentation.
+
+  * Changes to dependencies:
+
+    - lib_dsp: Added dependency 3.0.0
+
+2.0.1
+-----
+
+  * Updated AN00221 to use new lib_dsp API for FFTs
+  * Updates required for latest lib_mic_array_board_support API
+
+2.0.0
+-----
+
+  * Renamed all functions to match library structure
+  * Decimator interface functions now take the array of
+    mic_array_decimator_config structure rather than
+    mic_array_decimator_config_common
+  * All defines renames to match library naming policy
+  * DC offset simplified
+  * Added optional MIC_ARRAY_NUM_MICS define to save memory when using less than
+    16 microphones
+
+1.0.1
+-----
+
+  * Added dynamic DC offset removal at startup to eliminate slow convergance
+  * Mute first 32 samples to allow DC offset to adapt before outputting signal
+  * Fixed XTA scripte to ensure timing is being met
+  * Now use a 64-bit accumulator for DC offset removal
+  * Consolidated generators into a single python generator
+  * Produced output frequency response graphs
+  * Added 16 bit output mode
+
+1.0.0
+-----
+
+  * Major refactor
+  * FRAME_SIZE_LOG2 renamed MAX_FRAME_SIZE_LOG2
+  * Decimator interface now takes arrays of streaming channels
+  * Decimators now take channel count as a parameter
+  * Added filter designer script
+  * Documentation updates
+  * First stage now uses a FIR decimator
+  * Changed decimation flow
+  * Removed high res delay module
+  * Added generator for FIR coefficients
+  * Added ability to reduce number of channels active in a decimator
+  * Increased number of FIR taps
+  * Increased output dynamic range
+
+0.0.2
+-----
+
+  * Documentation fixes
+  * Fixed frame number fix
+  * Added frame metadata
+
+0.0.1
+-----
+
+  * Initial Release
+
+  * Changes to dependencies:
+
+    - lib_logging: Added dependency 2.0.0
+
+    - lib_xassert: Added dependency 2.0.0
+

lib_mic_array/LICENSE.rst

@@ -0,0 +1,84 @@
+*******************************
+XMOS PUBLIC LICENCE: Version 1
+*******************************
+
+Subject to the conditions and limitations below, permission is hereby granted by XMOS LIMITED (“XMOS”), free of charge, to any person or entity obtaining a copy of the XMOS Software.
+
+**1. Definitions**
+
+**“Applicable Patent Rights”** means: (a) where XMOS is the grantor of the rights, (i) claims of patents that are now or in future owned by or assigned to XMOS and (ii) that cover subject matter contained in the Software, but only to the extent it is necessary to use, reproduce or distribute the Software without infringement; and (b) where you are the grantor of the rights, (i) claims of patents that are now or in future owned by or assigned to you and (ii) that cover the subject matter contained in your Derivatives, taken alone or in combination with the Software.
+
+**“Compiled Code”** means any compiled, binary, machine readable or executable version of the Source Code.
+
+**“Contributor”** means any person or entity that creates or contributes to the creation of Derivatives.
+
+**“Derivatives”** means any addition to, deletion from and/or change to the substance, structure of the Software, any previous Derivatives, the combination of the Derivatives and the Software and/or any respective portions thereof.
+
+**“Source Code”** means the human readable code that is suitable for making modifications but excluding any Compiled Code.
+
+**“Software”** means the software and associated documentation files which XMOS makes available and which contain a notice identifying the software as original XMOS software and referring to the software being subject to the terms of this XMOS Public Licence.
+
+This Licence refers to XMOS Software and does not relate to any XMOS hardware or devices which are protected by intellectual property rights (including patent and trade marks) which may be sold to you under a separate agreement.
+
+
+**2. Licence**
+
+**Permitted Uses, Conditions and Restrictions.**  Subject to the conditions below, XMOS grants you a worldwide, royalty free, non-exclusive licence, to the extent of any Patent Rights to do the following:
+
+2.1 **Unmodified Software.** You may use, copy, display, publish, distribute and make available unmodified copies of the Software:
+
+2.1.1 for personal or academic, non-commercial purposes; or
+
+2.1.2 for commercial purposes provided the Software is at all times used on a device designed, licensed or developed by XMOS and, provided that in each instance (2.1.1 and 2.1.2):
+
+(a) you must retain and reproduce in all copies of the Software the copyright and proprietary notices and disclaimers of XMOS as they appear in the Software, and keep intact all notices and disclaimers in the Software files that refer to this Licence; and
+
+(b) you must include a copy of this Licence with every copy of the Software and documentation you publish, distribute and make available and you may not offer or impose any terms on such Software that alter or restrict this Licence or the intent of such Licence, except as permitted below (Additional Terms).
+
+The licence above does not include any Compiled Code which XMOS may make available under a separate support and licence agreement.
+
+2.2 **Derivatives.** You may create and modify Derivatives and use, copy, display, publish, distribute and make available Derivatives:
+
+2.2.1 for personal or academic, non-commercial purposes; or
+
+2.2.2 for commercial purposes, provided the Derivatives are at all times used on a device designed, licensed or developed by XMOS and, provided that in each instance (2.2.1 and 2.2.2):
+
+(a) you must comply with the terms of clause 2.1 with respect to the Derivatives;
+
+(b) you must copy (to the extent it doesn’t already exist) the notice below in each file of the Derivatives, and ensure all the modified files carry prominent notices stating that you have changed the files and the date of any change; and
+
+(c) if you sublicence, distribute or otherwise make the Software and/or the Derivatives available for commercial purposes, you must provide that the Software and Derivatives are at all times used on a device designed, licensed or developed by XMOS.
+
+Without limitation to these terms and clause 3 below, the Source Code and Compiled Code to your Derivatives may at your discretion (but without obligation) be released, copied, displayed, published, distributed and made available; and if you elect to do so, it must be under the terms of this Licence including the terms of the licence at clauses 2.2.1, 2.2.2 and clause 3 below.
+
+2.3 **Distribution of Executable Versions.**  If you distribute or make available Derivatives, you must include a prominent notice in the code itself as well as in all related documentation, stating that the Source Code of the Software from which the Derivatives are based is available under the terms of this Licence, with information on how and where to obtain such Source Code.
+
+**3. Your Grant of Rights.**  In consideration and as a condition to this Licence, you grant to any person or entity receiving or distributing any Derivatives, a non-exclusive, royalty free, perpetual, irrevocable license under your Applicable Patent Rights and all other intellectual property rights owned or controlled by you, to use, copy, display, publish, distribute and make available your Derivatives of the same scope and extent as XMOS’s licence under clause 2.2 above.
+
+**4. Combined Products.**  You may create a combined product by combining Software, Derivatives and other code not covered by this Licence as a single application or product. In such instance, you must comply with the requirements of this Licence for any portion of the Software and/or Derivatives.
+
+**5. Additional Terms.**  You may choose to offer, and to charge a fee for, warranty, support, indemnity or liability obligations and/or other rights consistent with the term of this Licence (“Additional Terms”) to any legitimate recipients of the Software and/or Derivatives.  The terms on which you provide such Additional Terms are on your sole responsibility and you shall indemnify, defend and hold XMOS harmless against any claims asserted against XMOS.
+
+**6. New Versions.**  XMOS may publish revised and/or new versions of this Licence from time to time to accommodate changes to the Licence terms, new versions, updates and bug fixes of the Software.  Each version will be given a distinguishing version number.  Once Software has been published under a particular version of this Licence, you may continue to use it under the terms of that version.  You may also choose to use the latest version of the Software under any subsequent version published by XMOS.  Only XMOS shall have the right to modify these terms.
+
+**7. IPR and Ownership**
+Any rights, including all intellectual property rights and all trademarks not expressly granted herein are reserved in full by the authors or copyright holders. Any requests for additional permissions by XMOS including any rights to use XMOS trademarks, should be made (without obligation) to XMOS at **support@xmos.com**
+
+Nothing herein shall limit any rights that XMOS is otherwise entitled to under the doctrines of patent exhaustion, implied license, or legal estoppel.  Neither the name of the authors, the copyright holders or any contributors may be used to endorse or promote any Derivatives from this Software without specific written permission.  Any attempt to deal with the Software which does not comply with this Licence shall be void and shall automatically terminate any rights granted under this licence (including any licence of any intellectual property rights granted herein).
+Subject to the licences granted under this Licence any Contributor retains all rights, title and interest in and to any Derivatives made by Contributor subject to the underlying rights of XMOS in the Software.  XMOS shall retain all rights, title and interest in the Software and any Derivatives made by XMOS (“XMOS Derivatives”).  XMOS Derivatives will not automatically be subject to this Licence and XMOS shall be entitled to licence such rights on any terms (without obligation) as it sees fit.
+
+**8. Termination**
+
+8.1 This Licence will automatically terminate immediately, without notice to you, if:
+
+(a) you fail to comply with the terms of this Licence; and/or
+
+(b) you directly or indirectly commence any action for patent or intellectual property right infringement against XMOS, or any parent, group, affiliate or subsidiary of XMOS; provided XMOS did not first commence an action or patent infringement against you in that instance; and/or
+
+(c) the terms of this Licence are held by any court of competent jurisdiction to be unenforceable in whole or in part.
+
+**9. Critical Applications.**  Unless XMOS has agreed in writing with you an agreement specifically governing use of the Goods in military, aerospace, automotive or medically related functions (collectively and individually hereinafter referred to as "Special Use"), any permitted use of the Software excludes Special Use. Notwithstanding any agreement between XMOS and you for Special Use, Special Use shall be at your own risk, and you shall fully indemnify XMOS against any damages, losses, costs and claims (direct and indirect) arising out of any Special Use.
+
+**10. NO WARRANTY OR SUPPORT.**  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 XMOS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, WARRANTY, CIVIL TORT (INCLUDING NEGLIGENCE), PRODUCTS LIABILITY OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE INCLUDING GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES EVEN IF SUCH PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES AND NOT WITHSTANDING THE FAILURE OF ESSENTIAL PURPOSE.  IN SOME JURISDICTIONS PARTIES ARE UNABLE TO LIMIT LIABILTY IN THIS WAY, IF THIS APPLIES TO YOUR JURISDICTION THIS LIABILITY CLAUSE ABOVE MAY NOT APPLY.  NOTWITHSTANDING THE ABOVE, IN NO EVENT SHALL XMOS’s TOTAL LIABILITY TO YOU FOR ALL DAMAGES, LOSS OR OTHERWISE EXCEED $50.
+
+**11. Governing Law and Jurisdiction.**  This Licence constitutes the entire agreement between the parties with respect to the subject matter hereof. The Licence shall be governed by the laws of England and the conflict of laws and UN Convention on Contracts for the International Sale of Goods, shall not apply.

lib_mic_array/README.rst

@@ -0,0 +1,82 @@
+
+:orphan:
+
+###########################################
+lib_mic_array: PDM microphone array library
+###########################################
+
+:vendor: XMOS
+:version: 5.5.0
+:scope: General Use
+:description: PDM microphone array library
+:category: General Purpose
+:keywords: PDM, microphone
+:devices: xcore.ai
+
+*******
+Summary
+*******
+
+The XMOS microphone array library is designed to allow interfacing to PDM microphones coupled with efficient decimation to user configurable output
+sample rates.
+
+This library is only available for XS3 devices due to requiring the XS3 vector unit. It will build without errors for XS2 targets however no mic_array APIs will be available.
+Please see versions prior to v5.0.0 for XS2 support.
+
+********
+Features
+********
+
+The microphone array library has the following features:
+
+  - 48, 32, 16 kHz output sample rates by default (3.072 MHz PDM clock)
+  - 44.1, 29.4, 14.7 kHz output samples using 2.8224 MHz PDM clock
+  - Other sample rates possible using custom decimation filter
+  - 1 to 16 PDM microphones
+  - Supports up to 8 microphones using only a single thread
+  - Configurable MCLK to PDM clock divider
+  - Supports both SDR and DDR microphone configurations
+  - Framing with configurable frame size
+  - DC offset removal
+  - Extensible C++ design
+
+
+************
+Known issues
+************
+
+  * PDM receive can lock-up in ISR mode when ma_frame_rx is not called isochronously after first transfer.
+
+Also see https://github.com/xmos/lib_mic_array/issues.
+
+****************
+Development repo
+****************
+
+  * `lib_mic_array <https://www.github.com/xmos/lib_mic_array>`_
+
+**************
+Required tools
+**************
+
+  * XMOS XTC Tools: 15.3.0
+
+*********************************
+Required libraries (dependencies)
+*********************************
+
+  * `lib_xcore_math <https://www.xmos.com/file/lib_xcore_math>`_
+
+*************************
+Related application notes
+*************************
+
+The following application notes use this library:
+
+  * AN000248 - Using lib_xua with lib_mic_array
+
+*******
+Support
+*******
+
+This package is supported by XMOS Ltd. Issues can be raised against the software at: http://www.xmos.com/support

lib_mic_array/lib_mic_array/api/mic_array.h

@@ -0,0 +1,21 @@
+// Copyright 2015-2024 XMOS LIMITED.
+// This Software is subject to the terms of the XMOS Public Licence: Version 1.
+#pragma once
+
+#ifdef __XS3A__ // Only available for xcore.ai
+#include "mic_array/api.h"  
+#endif // __XS3A__
+#include "mic_array/pdm_resources.h"
+#include "mic_array/dc_elimination.h"
+#include "mic_array/frame_transfer.h"
+#include "mic_array/setup.h"
+
+#ifdef __cplusplus
+# include "mic_array/cpp/Decimator.hpp"
+# include "mic_array/cpp/MicArray.hpp"
+# include "mic_array/cpp/OutputHandler.hpp"
+# include "mic_array/cpp/PdmRx.hpp"
+# include "mic_array/cpp/Prefab.hpp"
+# include "mic_array/cpp/SampleFilter.hpp"
+#endif
+

lib_mic_array/lib_mic_array/lib_build_info.cmake

@@ -0,0 +1,16 @@
+set(LIB_NAME lib_mic_array)
+set(LIB_VERSION 5.5.0)
+set(LIB_DEPENDENT_MODULES "lib_xcore_math(2.4.0)")
+set(LIB_INCLUDES
+    api
+    api/mic_array
+    api/mic_array/cpp
+    api/mic_array/etc
+    api/mic_array/impl
+    src
+    src/etc
+    ../etc/vanilla
+)
+set(LIB_COMPILER_FLAGS -g -Os)
+
+XMOS_REGISTER_MODULE()

lib_mic_array/lib_mic_array/module_build_info

@@ -0,0 +1,30 @@
+VERSION = 5.5.0
+
+DEPENDENT_MODULES = lib_xcore_math(>=2.4.0)
+
+MODULE_XCC_FLAGS = $(XCC_FLAGS) -g -Os
+
+# there is no MODULE_XCC_CPP_FLAGS
+# MODULE_XCC_CPP_FLAGS = -std=c++11
+XCC_FLAGS_Util.cpp = -std=c++11 $(XCC_FLAGS)
+
+INCLUDE_DIRS = api
+
+
+SOURCE_DIRS = src				\
+              src/etc
+
+# If using xmake/module_build_info instead of cmake, the vanilla API can still
+# be used by setting VANILLA_API_ENABLED to 1 in your application Makefile.
+# This also requires the following compile definitions to be added for your
+# application (see /etc/vanilla/vanilla.cmake):
+# 	MIC_ARRAY_CONFIG_MCLK_FREQ		# Master audio clock frequency
+#		MIC_ARRAY_CONFIG_PDM_FREQ			# PDM clock frequency
+#		MIC_ARRAY_CONFIG_MIC_COUNT		# Number of microphones
+#		MIC_ARRAY_CONFIG_SAMPLES_PER_FRAME	# Number of samples in each frame of
+#																				# audio delivered by the mic array.
+ifeq (1, $(VANILLA_API_ENABLED))
+SOURCE_DIRS += ../etc/vanilla
+INCLUDE_DIRS += ../etc/vanilla
+XCC_FLAGS_mic_array_vanilla.cpp = -std=c++11 $(XCC_FLAGS)
+endif

lib_mic_array/python/setup.py

@@ -0,0 +1,22 @@
+# Copyright 2020-2024 XMOS LIMITED.
+# This Software is subject to the terms of the XMOS Public Licence: Version 1.
+import setuptools
+
+# Another repository might depend on python code defined in this one.  The
+# procedure to set up a suitable python environment for that repository may
+# pip-install this one as editable using this setup.py file.  To minimise the
+# chance of version conflicts while ensuring a minimal degree of conformity,
+# the 3rd-party modules listed here require the same major version and at
+# least the same minor version as specified in the requirements.txt file.
+# The same modules should appear in the requirements.txt file as given below.
+setuptools.setup(
+    name='lib_mic_array',
+    packages=setuptools.find_packages(),
+    install_requires=[
+        'matplotlib==3.9.2',
+        'numpy==2.1.1',
+        'scipy==1.14.1',
+    ],
+    dependency_links=[
+    ],
+)