diff --git a/.github/ISSUE_TEMPLATE/application-note-not-compliant.md b/.github/ISSUE_TEMPLATE/application-note-not-compliant.md deleted file mode 100644 index 90723cbc..00000000 --- a/.github/ISSUE_TEMPLATE/application-note-not-compliant.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -name: Application Note Issue -about: Template for an Application note issue report -title: examples/ANXXXXX Application Note not compliant -labels: documentation -assignees: '' - ---- - - - - -**Issues:** - - - xdoc-custom RST directives used in the Application Note README - - application note code not compiling for xcore-ai - - application note code not running successfully on xcore-ai diff --git a/.github/ISSUE_TEMPLATE/example-not-compliant.md b/.github/ISSUE_TEMPLATE/example-not-compliant.md deleted file mode 100644 index 5e68cdb0..00000000 --- a/.github/ISSUE_TEMPLATE/example-not-compliant.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -name: Example Issue -about: Template for an example issue report -title: examples/xxx Example not compliant -labels: documentation -assignees: '' - ---- - - - - -**Issues:** - - - convert example to Application Note - - xdoc-custom RST directives used in the README - - example code not compiling for xcore-ai - - example code not running successfully on xcore-ai diff --git a/.github/ISSUE_TEMPLATE/missing-application-note.md b/.github/ISSUE_TEMPLATE/missing-application-note.md deleted file mode 100644 index 9404dde5..00000000 --- a/.github/ISSUE_TEMPLATE/missing-application-note.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -name: Missing Application Note -about: Template for a Missing Application Note issue report -title: Missing Application Note -labels: documentation -assignees: '' - ---- - - diff --git a/.github/ISSUE_TEMPLATE/missing-c-api.md b/.github/ISSUE_TEMPLATE/missing-c-api.md deleted file mode 100644 index 6230ef70..00000000 --- a/.github/ISSUE_TEMPLATE/missing-c-api.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -name: Missing C API Issue -about: Template for a Missing C API issue report -title: Missing C API -labels: enhancement -assignees: '' - ---- - - diff --git a/.github/ISSUE_TEMPLATE/missing-xcore-test.md b/.github/ISSUE_TEMPLATE/missing-xcore-test.md deleted file mode 100644 index 866e97cc..00000000 --- a/.github/ISSUE_TEMPLATE/missing-xcore-test.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -name: Missing xCore Test Issue -about: Template for a Missing xCore test issue report -title: Missing xCore test -labels: testing -assignees: '' - ---- - - diff --git a/.github/ISSUE_TEMPLATE/test-not-compliant.md b/.github/ISSUE_TEMPLATE/test-not-compliant.md deleted file mode 100644 index cce3e918..00000000 --- a/.github/ISSUE_TEMPLATE/test-not-compliant.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -name: Test Issue -about: Template for a Test issue report -title: tests/XXX does not build or fails -labels: testing -assignees: '' - ---- - - - - -**Issues:** - - - Test not compiling for xcore-ai - - Test not running successfully on xcore-ai diff --git a/.github/ISSUE_TEMPLATE/top-level-readme-not-compliant.md b/.github/ISSUE_TEMPLATE/top-level-readme-not-compliant.md deleted file mode 100644 index 931414c1..00000000 --- a/.github/ISSUE_TEMPLATE/top-level-readme-not-compliant.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -name: Top-level README Issue -about: Template for the top-level README issue report -title: Top-level README not compliant -labels: documentation -assignees: '' - ---- - - -**Issues:** - - - xdoc-custom RST directives used in the README diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 5d993c2e..f8b6df03 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,6 +1,17 @@ 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 ----- diff --git a/CMakeLists.txt b/CMakeLists.txt index 883f9462..6981c376 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -6,14 +6,14 @@ 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) +include(tests/custom_cmake_build/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 +# 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) @@ -24,7 +24,7 @@ if(NOT DEFINED DEV_LIB_MIC_ARRAY) endif() endif() -project(lib_mic_array +project(lib_mic_array VERSION 5.0.1 LANGUAGES CXX C ASM) diff --git a/Jenkinsfile b/Jenkinsfile index 20bfdedb..97ca1447 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -1,208 +1,226 @@ @Library('xmos_jenkins_shared_library@v0.34.0') _ + +def archiveLib(String repoName) { + sh "git -C ${repoName} clean -xdf" + zip zipFile: "${repoName}_sw.zip", dir: "${repoName}", archive: true, defaultExcludes: false +} + +def checkout_shallow() +{ + checkout scm: [ + $class: 'GitSCM', + branches: scm.branches, + userRemoteConfigs: scm.userRemoteConfigs, + extensions: [[$class: 'CloneOption', depth: 1, shallow: true, noTags: false]] + ] +} + getApproval() pipeline { - agent none - - environment { - REPO = 'lib_mic_array' - PIP_VERSION = "24.0" - PYTHON_VERSION = "3.11" - XMOSDOC_VERSION = "v6.1.2" - } - options { - skipDefaultCheckout() - timestamps() - // on develop discard builds after a certain number else keep forever - buildDiscarder(logRotator( - numToKeepStr: env.BRANCH_NAME ==~ /develop/ ? '25' : '', - artifactNumToKeepStr: env.BRANCH_NAME ==~ /develop/ ? '25' : '' - )) - } - parameters { - string( - name: 'TOOLS_VERSION', - defaultValue: '15.3.0', - description: 'The XTC tools version' - ) - } - stages { - stage('Build and Docs') { - parallel { - stage('Documentation') { - agent { - label "docker" - } - steps { - dir("${REPO}") { - warnError("Docs") { - checkout scm - sh "docker pull ghcr.io/xmos/xmosdoc:$XMOSDOC_VERSION" - sh """docker run -u "\$(id -u):\$(id -g)" \ - --rm \ - -v \$(pwd):/build \ - ghcr.io/xmos/xmosdoc:$XMOSDOC_VERSION -v html latex""" + agent none - // Zip and archive doc files - zip dir: "doc/_build/html", zipFile: "${REPO}_docs_html.zip" - archiveArtifacts artifacts: "${REPO}_docs_html.zip" - archiveArtifacts artifacts: "doc/_build/pdf/${REPO}*.pdf" - } - } - } - post { - cleanup { - xcoreCleanSandbox() - } - } + environment { + REPO = 'lib_mic_array' + PIP_VERSION = "24.0" + PYTHON_VERSION = "3.11" + } + options { + skipDefaultCheckout() + timestamps() + // on develop discard builds after a certain number else keep forever + buildDiscarder(logRotator( + numToKeepStr: env.BRANCH_NAME ==~ /develop/ ? '25' : '', + artifactNumToKeepStr: env.BRANCH_NAME ==~ /develop/ ? '25' : '' + )) + } + parameters { + string( + name: 'TOOLS_VERSION', + defaultValue: '15.3.0', + description: 'The XTC tools version' + ) + string( + name: 'XMOSDOC_VERSION', + defaultValue: 'v6.1.2', + description: 'The xmosdoc version' + ) + string( + name: 'INFR_APPS_VERSION', + defaultValue: 'v2.0.1', + description: 'The infr_apps version' + ) + } + stages { + stage('Build and Docs') { + parallel { + stage('Documentation') { + agent { + label "documentation" + } + steps { + dir("${REPO}") { + warnError("Docs") { + checkout_shallow() + buildDocs() + } + } + } + post { + cleanup { + xcoreCleanSandbox() + } + } + } + stage('XCommon build ') { + agent { + label "x86_64 && linux" + } + steps { + dir("${REPO}") { + checkout_shallow() + dir("tests") { + withTools(params.TOOLS_VERSION) { + sh 'cmake -B build -G "Unix Makefiles"' + // Note no -C build so builds the xcommon Makefile + sh "xmake all -j 16" } - stage('XCommon build') { - agent { - label "x86_64 && linux" - } - steps { - dir("${REPO}") { - checkout scm - dir("tests") { - withTools(params.TOOLS_VERSION) { - sh 'cmake -B build -G "Unix Makefiles"' - // Note no -C build so builds the xcommon Makefile - sh "xmake all -j 16" - } - archiveArtifacts artifacts: "**/*.xe", allowEmptyArchive: true - } - } - } - post { - cleanup { - xcoreCleanSandbox() - } + archiveArtifacts artifacts: "**/*.xe", allowEmptyArchive: true + } + } + } // steps + post { + cleanup { + xcoreCleanSandbox() + } + } //post + } // stage('XCommon build') + stage('Custom CMake build') { + agent { + label "x86_64 && linux" + } + steps { + sh "git clone git@github.com:xmos/xmos_cmake_toolchain.git --branch v1.0.0" + dir("${REPO}") { + checkout_shallow() + withTools(params.TOOLS_VERSION) { + sh "cmake -B build.xcore -DDEV_LIB_MIC_ARRAY=1 -DCMAKE_TOOLCHAIN_FILE=../xmos_cmake_toolchain/xs3a.cmake" + sh "cd build.xcore && make all -j 16" + } + } + } + post { + cleanup { + xcoreCleanSandbox() + } + } + } // stage('Custom CMake build') + stage('XCCM build and basic tests') { + agent { + label 'x86_64 && linux' + } + stages { + stage("XCCM Build") { + // Clone and install build dependencies + steps { + // Clone infrastructure repos + sh "git clone --branch v1.6.0 git@github.com:xmos/infr_apps" + sh "git clone --branch v1.3.0 git@github.com:xmos/infr_scripts_py" + // clone + dir("${REPO}") { + checkout_shallow() + withTools(params.TOOLS_VERSION) { + dir("examples") { + sh 'cmake -B build -G "Unix Makefiles" -DDEPS_CLONE_SHALLOW=TRUE' + sh 'xmake -j 16 -C build' } + } + archiveArtifacts artifacts: "**/*.xe", allowEmptyArchive: true } - stage('Custom CMake build') { - agent { - label "x86_64 && linux" - } - steps { - sh "git clone git@github.com:xmos/xmos_cmake_toolchain.git --branch v1.0.0" - dir("${REPO}") { - checkout scm - withTools(params.TOOLS_VERSION) { - sh "cmake -B build.xcore -DDEV_LIB_MIC_ARRAY=1 -DCMAKE_TOOLCHAIN_FILE=../xmos_cmake_toolchain/xs3a.cmake" - sh "cd build.xcore && make all -j 16" - } - } - } - post { - cleanup { - xcoreCleanSandbox() - } - } + } + } + stage("Lib checks") { + steps { + warnError("lib checks") { + runLibraryChecks("${WORKSPACE}/${REPO}", "${params.INFR_APPS_VERSION}") } - stage('XCCM build and basic tests') { - agent { - label 'x86_64 && linux' - } - stages { - stage("XCCM Build") { - // Clone and install build dependencies - steps { - // Clone infrastructure repos - sh "git clone --branch v1.6.0 git@github.com:xmos/infr_apps" - sh "git clone --branch v1.3.0 git@github.com:xmos/infr_scripts_py" - // clone - dir("${REPO}") { - checkout scm - createVenv(reqFile: "requirements.txt") - withVenv { - withTools(params.TOOLS_VERSION) { - dir("examples") { - sh 'cmake -B build -G "Unix Makefiles"' - sh 'xmake -j 16 -C build' - } - } - } - archiveArtifacts artifacts: "**/*.xe", allowEmptyArchive: true - } - } - } - stage("Lib checks") { - steps { - warnError("lib checks") { - runLibraryChecks("${WORKSPACE}/${REPO}", "v2.0.1") - } - } - } - } - post { - cleanup { - xcoreCleanSandbox() - } + } + } + stage("Archive Lib") { + steps { + archiveLib(REPO) + } + } //stage("Archive Lib") + } // stages + post { + cleanup { + xcoreCleanSandbox() + } + } + } // stage('XCCM build and basic tests') + stage('HW tests') { + agent { + label 'xcore.ai' // Did include xvf3800 but XTAG speed meant occasional test fail + } + stages { + stage("Checkout and Build") { + steps { + dir("${REPO}") { + println "RUNNING ON" + println env.NODE_NAME + checkout_shallow() + dir("tests") { + createVenv(reqFile: "requirements.txt") + withVenv { + withTools(params.TOOLS_VERSION) { + sh 'cmake -B build -G "Unix Makefiles"' + sh 'xmake -j 8 -C build' + } } + } } - stage('HW tests') { - agent { - label 'xcore.ai' // Did include xvf3800 but XTAG speed meant occasional test fail - } - stages { - stage("Checkout and Build") { - steps { - dir("${REPO}") { - println "RUNNING ON" - println env.NODE_NAME - checkout scm - createVenv(reqFile: "requirements.txt") - withVenv { - withTools(params.TOOLS_VERSION) { - dir("tests") { - sh 'cmake -B build -G "Unix Makefiles"' - sh 'xmake -j 8 -C build' - } - } - } - } - } - } - stage('Run tests') { - steps { - dir("${REPO}/tests") { - withTools(params.TOOLS_VERSION) { - withVenv { - // Use xtagctl to reset the relevent adapters first, if attached, to be safe. - // sh "xtagctl reset_all XVF3800_INT XVF3600_USB" + } + } // stage("Checkout and Build") + stage('Run tests') { + steps { + dir("${REPO}/tests") { + withTools(params.TOOLS_VERSION) { + withVenv { + // Use xtagctl to reset the relevent adapters first, if attached, to be safe. + // sh "xtagctl reset_all XVF3800_INT XVF3600_USB" - // This ensures a project for XS2 can be built and runs OK - sh "xsim test_xs2_benign/bin/xs2.xe" - - // Run this first to ensure the XTAG is up and running for subsequent tests - timeout(time: 2, unit: 'MINUTES') { - sh "xrun --xscope --id 0 unit/bin/tests-unit.xe" - } - - // note no xdist for HW tests as only 1 hw instance - // Each test has it's own conftest.py so we need to run these seprarately - dir("signal/BasicMicArray") { - runPytest('-vv --numprocesses=1') - } - dir("signal/TwoStageDecimator") { - runPytest('-vv --numprocesses=1') - } - dir("signal/FilterDesign") { - runPytest('-vv') - } - } - } - archiveArtifacts artifacts: "**/*.pkl", allowEmptyArchive: true - } - } - } - } - post { - cleanup { - xcoreCleanSandbox() - } + // This ensures a project for XS2 can be built and runs OK + sh "xsim test_xs2_benign/bin/xs2.xe" + + // Run this first to ensure the XTAG is up and running for subsequent tests + timeout(time: 2, unit: 'MINUTES') { + sh "xrun --xscope --id 0 unit/bin/tests-unit.xe" + } + + // note no xdist for HW tests as only 1 hw instance + // Each test has it's own conftest.py so we need to run these seprarately + dir("signal/BasicMicArray") { + runPytest('-vv --numprocesses=1') + } + dir("signal/TwoStageDecimator") { + runPytest('-vv --numprocesses=1') + } + dir("signal/FilterDesign") { + runPytest('-vv') + } } + } + archiveArtifacts artifacts: "**/*.pkl", allowEmptyArchive: true } + } + } // stage('Run tests') + } // stages + post { + cleanup { + xcoreCleanSandbox() } - } - } -} + } + } // stage('HW tests') + } // parallel + } // stage('Build and Docs') + } // stages +} // pipeline diff --git a/README.rst b/README.rst index 9888ed8e..1b15fa65 100644 --- a/README.rst +++ b/README.rst @@ -2,20 +2,20 @@ :orphan: ########################################### -lib_mic_array: PDM Microphone Array Library +lib_mic_array: PDM microphone array library ########################################### :vendor: XMOS -:version: 5.4.0 +:version: 5.5.0 :scope: General Use -:description: PDM Microphone Array Library +:description: PDM microphone array library :category: General Purpose :keywords: PDM, microphone :devices: xcore.ai -******** -Overview -******** +******* +Summary +******* The XMOS microphone array library is designed to allow interfacing to PDM microphones coupled with efficient decimation to user configurable output sample rates. @@ -42,39 +42,39 @@ The microphone array library has the following features: ************ -Known Issues +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 `_ + ************** -Required Tools +Required tools ************** * XMOS XTC Tools: 15.3.0 ********************************* -Required Libraries (dependencies) +Required libraries (dependencies) ********************************* - * None + * `lib_xcore_math `_ ************************* -Related Application Notes +Related application notes ************************* The following application notes use this library: * AN000248 - Using lib_xua with lib_mic_array -See the `examples/` subdirectory for simple usage examples. - -The examples in `sln_voice `_ use this library extensively and contain multiple examples for both bare-metal and under FreeRTOS. - -The `XVF3800 `_ VocalFusion voice processor products also use this library. - ******* Support ******* diff --git a/doc/Doxyfile.inc b/doc/Doxyfile.inc index e092302e..81eadc72 100644 --- a/doc/Doxyfile.inc +++ b/doc/Doxyfile.inc @@ -1,8 +1,8 @@ # This file provides overrides to the Doxyfile configuration PROJECT_NAME = lib_mic_array -PROJECT_BRIEF = "PDM Mic Array library for the XMOS XS3 architecture" +PROJECT_BRIEF = "PDM microphone array library" -INPUT = ../lib_mic_array/api ../etc/vanilla ../doc/programming_guide/src +INPUT = ../lib_mic_array/api ../etc/vanilla ../doc/rst/src PREDEFINED = MA_C_API= C_API_START= C_API_END= __DOXYGEN__=1 diff --git a/doc/README.rst b/doc/README.rst deleted file mode 100644 index 8c9fe66a..00000000 --- a/doc/README.rst +++ /dev/null @@ -1,63 +0,0 @@ -#################### -Documentation Source -#################### - -This folder contains source files for the documentation. The sources do not render well in GitHub or an RST viewer. -In addition, some information is not visible at all and some links will not be functional. - -********************** -Building Documentation -********************** - -============= -Prerequisites -============= - -Use the `xmosdoc tool `_ either via docker or install it into a pip environment. - -======== -Building -======== - -To build the documentation, run the following command in the root of the repository: - -.. code-block:: console - - # via pip package - xmosdoc clean html latex - # via docker - $ docker run --rm -t -u "$(id -u):$(id -g)" -v $(pwd):/build ghcr.io/xmos/xmosdoc clean html latex - -HTML document output is saved in the ``doc/_build/html`` folder. Open ``index.html`` to preview the saved documentation. - -Please refer to the ``xmosdoc`` documentation for a complete guide on how to use the tool. - -********************** -Adding a New Component -********************** - -Follow the following steps to add a new component. - -- Add an entry for the new component's top-level document to the appropriate TOC in the documents tree. -- If the new component uses `Doxygen`, append the appropriate path(s) to the INPUT variable in `Doxyfile.inc`. -- If the new component includes `.rst` files that should **not** be part of the documentation build, append the appropriate pattern(s) to `exclude_patterns.inc`. - -*** -FAQ -*** - -Q: Is it possible to build just a subset of the documentation? - -A: Yes, however it is not recommended at this time. - -Q: Is it possible to used the ``livehtml`` feature of Sphinx? - -A: Yes, run xmosdoc with the ``--auto`` option. - -Q: Where can I learn more about the XMOS ``xmosdoc`` tools? - -A: See the https://github.com/xmos/xmosdoc repository. See the ``xmosdoc`` repository README for details on additional build options. - -Q: How do I suggest enhancements to the XMOS ``xmosdoc`` tool? - -A: Create a new issue here: https://github.com/xmos/xmosdoc/issues diff --git a/doc/exclude_patterns.inc b/doc/exclude_patterns.inc index 58f40d7e..63d302ae 100644 --- a/doc/exclude_patterns.inc +++ b/doc/exclude_patterns.inc @@ -2,5 +2,4 @@ /build/*build*/**/*.md CHANGELOG.rst LICENSE.rst -**README* build.xcore diff --git a/doc/programming_guide/index.rst b/doc/rst/lib_mic_array.rst similarity index 76% rename from doc/programming_guide/index.rst rename to doc/rst/lib_mic_array.rst index 50902389..8be9b5a2 100644 --- a/doc/programming_guide/index.rst +++ b/doc/rst/lib_mic_array.rst @@ -1,10 +1,11 @@ .. lib_mic_array documentation master file -Mic Array Library -================= +############# +lib_mic_array: PDM microphone array library +############# .. toctree:: - :maxdepth: 1 + :maxdepth: 2 :caption: Contents: src/introduction diff --git a/doc/programming_guide/src/32k_freq_response.png b/doc/rst/src/32k_freq_response.png similarity index 100% rename from doc/programming_guide/src/32k_freq_response.png rename to doc/rst/src/32k_freq_response.png diff --git a/doc/programming_guide/src/48k_freq_response.png b/doc/rst/src/48k_freq_response.png similarity index 100% rename from doc/programming_guide/src/48k_freq_response.png rename to doc/rst/src/48k_freq_response.png diff --git a/doc/programming_guide/src/dcoe_freq_response.png b/doc/rst/src/dcoe_freq_response.png similarity index 100% rename from doc/programming_guide/src/dcoe_freq_response.png rename to doc/rst/src/dcoe_freq_response.png diff --git a/doc/programming_guide/src/decimator_stages.rst b/doc/rst/src/decimator_stages.rst similarity index 84% rename from doc/programming_guide/src/decimator_stages.rst rename to doc/rst/src/decimator_stages.rst index 8cf2e16a..d8c5d442 100644 --- a/doc/programming_guide/src/decimator_stages.rst +++ b/doc/rst/src/decimator_stages.rst @@ -1,18 +1,22 @@ .. _decimator_stages: +**************** Decimator Stages -================ +**************** The mic array unit provided by this library uses a two-stage decimation process to convert a high sample rate stream of (1-bit) PDM samples into a lower sample rate stream of (32-bit) PCM samples. -Below is a simplified model of the mic array unit. +Below is a :ref:`decimator_stages_simplified`. + +.. _decimator_stages_simplified: .. figure:: diagrams/decimator_stages.drawio.png :align: center :scale: 100 % - :alt: Simplified Decimator Model + + Simplified Decimator Model The first stage filter is a decimating FIR filter with a fixed tap count (``S1_TAP_COUNT``) of ``256`` and a fixed decimation factor (``S1_DEC_FACTOR``) @@ -23,7 +27,7 @@ The second stage decimator is a fully configurable FIR filter with tap count ``1``). Decimator Stage 1 ------------------ +================= For the first stage decimating FIR filter, the actual filter coefficients used are configurable, so an application is free to use a custom first stage filter, @@ -32,7 +36,7 @@ the first stage filter, whose filter characteristics are adequate for most applications. Filter Implementation (Stage 1) -******************************* +------------------------------- The input to the first stage decimator (here called "Stream A") is a stream of 1-bit PDM samples with a sample rate of ``PDM_FREQ``. Rather than each PDM @@ -49,7 +53,7 @@ processing unit (VPU), which can compute the dot product of a pair of 256-element 1-bit vectors in a single cycle. The first stage uses 256 16-bit coefficients for its filter taps. -The signature of the filter function is +The signature of the filter function is .. code-block:: c @@ -71,30 +75,36 @@ rearranged bit-by-bit into a block form suitable for VPU processing. See the section below on filter conversion if supplying a custom filter for stage 1. Provided Filter (Stage 1) -************************* +------------------------- This library provides filter coefficients that may be used with the first stage decimator. These coefficients are available in your application through the header ``mic_array/etc/filters_default.h`` as ``stage1_coef``. Filter Characteristics (Stage 1) -'''''''''''''''''''''''''''''''' +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The plot below indicates the frequency response of the provided first stage -decimation filter. +decimation filter :ref:`first_stage_decimation_filter`. + +.. _first_stage_decimation_filter: -.. image:: stage1_freq_response.png +.. figure:: stage1_freq_response.png + :align: center + :scale: 100 % + + First stage decimation filter freq response Filter Conversion Script -************************ +------------------------ Taking a set of floating-point coefficients, quantizing them into 16-bit coefficients and 'boggling' them into the correct memory layout can be a tricky business. To simplify this process, this library provides a Python (3) script which does this process for you. -The script can be found in this repository at ``script/stage1.py``. +The script can be found in this repository at ``python/stage1.py``. .. todo:: @@ -103,14 +113,14 @@ The script can be found in this repository at ``script/stage1.py``. Decimator Stage 2 ------------------ +================= -An application is free to supply its own second stage filter. This library also -provides a second stage filter whose characteristics are adequate for many or +An application is free to supply its own second stage filter. This library also +provides a second stage filter whose characteristics are adequate for many or most applications. Filter Implementation (Stage 2) -******************************* +------------------------------- The input to the second stage decimator (here called "Stream B") is the stream of 32-bit PCM samples emitted from the first stage decimator with a sample rate @@ -119,7 +129,7 @@ of ``PDM_FREQ/32``. The output from the second stage decimator, Stream C, is a stream of 32-bit PCM samples with a sample rate of ``PDM_FREQ/(32*S2_DEC_FACTOR)``. For example, if ``PDM_FREQ`` is 3.072 MHz, and ``S2_DEC_FACTOR`` is ``6``, then Stream C's -sample rate (the sample rate received by the main application code) is +sample rate (the sample rate received by the main application code) is 3.072 MHz / (32*6) = 16 kHz @@ -128,7 +138,7 @@ The second stage filter uses the 32-bit FIR filter implementation from ``xs3_filter_fir_s32()`` in that library for more implementation details. Provided Filter (Stage 2) -************************* +------------------------- This library provides a filter suitable for the second stage decimator. It is available in your application through the header @@ -137,16 +147,22 @@ available in your application through the header For the provided filter ``S2_TAP_COUNT = 65``, and ``S2_DEC_FACTOR = 6``. Filter Characteristics (Stage 2) -'''''''''''''''''''''''''''''''' +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The plot below indicates the frequency response of the provided second stage -decimation filter. +decimation filter :ref:`second_stage_decimation_filter`. -.. image:: stage2_freq_response.png +.. _second_stage_decimation_filter: + +.. figure:: stage2_freq_response.png + :align: center + :scale: 100 % + + Second stage decimation filter freq response Custom Filters --------------- +============== Without writing a custom decimator implementation, the tap count and decimation factor for the first stage decimator are fixed to ``256`` and ``32`` @@ -173,7 +189,7 @@ this library, can be used to help with this formatting. See the associated READM Configuring for 32 kHz or 48 kHz output -*************************************** +--------------------------------------- Filter design scripts are provided to support higher output sampling rates than the default 16 kHz. @@ -208,21 +224,21 @@ file which launches the mic array tasks. It may look something like this:: .... the coeffs }; -The new decimation object must now be declared that references your new filter coefficients. +The new decimation object must now be declared that references your new filter coefficients. Again, this example is for 32 kHz output since the decimation factor is 3.:: using TMicArray = mic_array::MicArray, mic_array::StandardPdmRxService, + 3>, typename std::conditional, mic_array::NopSampleFilter>::type, - mic_array::FrameOutputHandler>; @@ -257,7 +273,7 @@ to using the custom version of the object:: mics.ThreadEntry(); -The increased sample rate will place a higher MIPS burden on the processor. The typical +The increased sample rate will place a higher MIPS burden on the processor. The typical MIPS usage (see section :ref:`resource_usage`) is in the order of 11 MIPS per channel using a 16 kHz output decimator. @@ -268,20 +284,32 @@ Increasing the filer lengths to 148 and 96 for stages 1 and 2 respectively at 48 will increase processor usage per channel to around 20 MIPS. Filter Characteristics for `good_32k_filter_int.pkl` -'''''''''''''''''''''''''''''''''''''''''''''''''''' +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The plot below indicates the frequency response of the first and second stages of the -provided 32 kHz filters as well as the cascaded overall response. Note that the -overall combined response provides a nice flat passband. +The plot below indicates the frequency response of the first and second stages of the +provided 32 kHz filters as well as the cascaded overall response. Note that the +overall combined response provides a nice flat passband as shown in the :ref:`freq_response_32k`. -.. image:: 32k_freq_response.png +.. _freq_response_32k: + +.. figure:: 32k_freq_response.png + :align: center + :scale: 100 % + + good_32k_filter_int.pkl frequency response Filter Characteristics for `good_48k_filter_int.pkl` -'''''''''''''''''''''''''''''''''''''''''''''''''''' +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The plot below indicates the frequency response of the first and second stages of the -provided 48 kHz filters as well as the cascaded overall response. Note that the -overall combined response provides a nice flat passband. +The plot below indicates the frequency response of the first and second stages of the +provided 48 kHz filters as well as the cascaded overall response. Note that the +overall combined response provides a nice flat passband as shown :ref:`freq_response_48k`. -.. image:: 48k_freq_response.png +.. _freq_response_48k: + +.. figure:: 48k_freq_response.png + :align: center + :scale: 100 % + + good_48k_filter_int.pkl frequency response diff --git a/doc/programming_guide/src/diagrams/decimator_stages.drawio b/doc/rst/src/diagrams/decimator_stages.drawio similarity index 100% rename from doc/programming_guide/src/diagrams/decimator_stages.drawio rename to doc/rst/src/diagrams/decimator_stages.drawio diff --git a/doc/programming_guide/src/diagrams/decimator_stages.drawio.png b/doc/rst/src/diagrams/decimator_stages.drawio.png similarity index 100% rename from doc/programming_guide/src/diagrams/decimator_stages.drawio.png rename to doc/rst/src/diagrams/decimator_stages.drawio.png diff --git a/doc/programming_guide/src/diagrams/high_level_process.drawio b/doc/rst/src/diagrams/high_level_process.drawio similarity index 100% rename from doc/programming_guide/src/diagrams/high_level_process.drawio rename to doc/rst/src/diagrams/high_level_process.drawio diff --git a/doc/programming_guide/src/diagrams/high_level_process.drawio.png b/doc/rst/src/diagrams/high_level_process.drawio.png similarity index 100% rename from doc/programming_guide/src/diagrams/high_level_process.drawio.png rename to doc/rst/src/diagrams/high_level_process.drawio.png diff --git a/doc/programming_guide/src/getting_started.rst b/doc/rst/src/getting_started.rst similarity index 96% rename from doc/programming_guide/src/getting_started.rst rename to doc/rst/src/getting_started.rst index d91f4ee8..c49b9f8b 100644 --- a/doc/programming_guide/src/getting_started.rst +++ b/doc/rst/src/getting_started.rst @@ -1,7 +1,8 @@ .. _mic_array_getting_started: +*************** Getting Started -=============== +*************** There are three models for how the mic array unit can be included in an application. The details of how to allocate, initialize and start the mic array @@ -29,7 +30,7 @@ application is to *identify the required hardware resources*. Identify Resources ------------------- +================== The key hardware resources to be identified are the *ports* and *clock blocks* that will be used by the mic array unit. The ports correspond to the physical @@ -38,7 +39,7 @@ of hardware resource which can be attached to ports to coordinate the presentation and capture of signals on physical pins. Clock Blocks -************ +------------ While clock blocks may be more abstract than ports, their implications for this library are actually simpler. First, the mic array unit will need a way of @@ -55,7 +56,7 @@ to as "Clock B" in the API documentation. Each tile on an xcore.ai device has 5 clock blocks available. In code, a clock block is identified by its resource ID, which are given as the preprocessor -macros ``XS1_CLKBLK_1`` through ``XS1_CLKBLK_5``. +macros ``XS1_CLKBLK_1`` through ``XS1_CLKBLK_5``. Unlike ports, which are tied to specific physical pins, clock blocks are fungible. Your application is free to use any clock block that has not already @@ -63,7 +64,7 @@ been allocated for another purpose. The vanilla component model defaults to using ``XS1_CLKBLK_1`` and ``XS1_CLKBLK_2``. Ports -***** +----- Three ports are needed for the mic array component. As mentioned above, ports are physically tied to specific device pins, and so the correct ports must be @@ -115,13 +116,13 @@ described above: The first 3 ports listed, ``PORT_PDM_CLK``, ``PORT_PDM_DATA`` and ``PORT_MCLK_IN_OUT`` are respectively ``p_pdm_clk``, ``p_pdm_mics`` and ``p_mclk``. The value in the ``Location`` attribute (e.g. ``XS1_PORT_1G``) is -the port name as you will find it in your package documentation. +the port name as you will find it in your package documentation. In this case, either ``PORT_PDM_CLK`` or ``XS1_PORT_1G`` can be used in code to identify this port. Declaring Resources -******************* +------------------- Once the ports and clock blocks to be used have been identified, these resources can be represented in code using a ``pdm_rx_resources_t`` struct. The @@ -142,7 +143,7 @@ following is an example of declaring resources in a DDR configuration. See Note that this is not necessary in applications using the vanilla model. Other Resources -*************** +--------------- In addition to ports and clock blocks, there are also several other hardware resource types used by ``lib_mic_array`` which are worth considering. Running @@ -161,7 +162,7 @@ all) Vanilla Model -------------- +============= Mic array configuration with the vanilla model is achieved mostly through the application's build system configuration. @@ -173,7 +174,7 @@ those files to your *application*'s build (*not* the library target), and defining several compile options which tell it how to behave. Vanilla - CMake Macro -********************* +--------------------- To simplify this further, a CMake macro called ``mic_array_vanilla_add()`` has been included with the build system. @@ -181,23 +182,23 @@ been included with the build system. ``mic_array_vanilla_add()`` takes several arguments: * ``TARGET_NAME`` - The name of the CMake application target that the vanilla - mode source should be added to. -* ``MCLK_FREQ`` - The frequency of the master audio clock, in Hz. -* ``PDM_FREQ`` - The desired frequency of the PDM clock, in Hz. -* ``MIC_COUNT`` - The number of microphone channels to be captured. + mode source should be added to. +* ``MCLK_FREQ`` - The frequency of the master audio clock, in Hz. +* ``PDM_FREQ`` - The desired frequency of the PDM clock, in Hz. +* ``MIC_COUNT`` - The number of microphone channels to be captured. * ``SAMPLES_PER_FRAME`` - The size of the audio frames produced by the mic array unit (frames will be 2 dimensional arrays with shape ``(MIC_COUNT,SAMPLES_PER_FRAME)``). Vanilla - Optional Configuration -******************************** +-------------------------------- Though not exposed by the ``mic_array_vanilla_add()`` macro, several additional configuration options are available when using the vanilla model. These are all configured by adding defines to the application target. Vanilla - Initializing and Starting -*********************************** +----------------------------------- Once the configuration options have been chosen, initializing and starting the mic array at run-time is easily achieved. Two function calls are necessary, both @@ -223,7 +224,7 @@ on the tile. core which will host the decimation thread. Prefab Model ------------- +============ The ``lib_mic_array`` library has a C++ namespace ``mic_array::prefab`` which contains class templates for typical mic array setups using common @@ -234,7 +235,7 @@ they can focus only on pieces they care about. .. note:: As of version 5.0.1, only one prefab class template, - :cpp:class:`BasicMicArray `, has been + :cpp:class:`BasicMicArray `, has been defined. To configure the mic array using a prefab, you will need to add a C++ source @@ -242,7 +243,7 @@ file to your application. NB: This will end up looking a lot like the contents of ``mic_array_vanilla.cpp`` when you are through. Prefab - Declare Resources -************************** +-------------------------- The example in this section will use ``2`` microphones in a DDR configuration with DC offset elimination enabled, and using 128-sample frames. The resource @@ -271,7 +272,7 @@ Within a C++ source file: Prefab - Allocate MicArray -************************** +-------------------------- The C++ class template :cpp:class:`MicArray ` is central to the mic array unit in this library. The class templates defined in the @@ -300,7 +301,7 @@ optimized out at build time so that at run time it won't even need to check whether DCOE is enabled. Prefab - Init and Start Functions -********************************* +--------------------------------- Now a couple functions need to be implemented in your C++ file. In most cases these functions will need to be callable from C or XC, and so they should not be @@ -309,7 +310,7 @@ preprocessor macro provided by the library). First, a function which initializes the ``MicArray`` object and configures the port and clock block resources. The documentation for -:cpp:class:`BasicMicArray ` indicates any +:cpp:class:`BasicMicArray ` indicates any parts of the ``MicArray`` object that need to be initialized. .. code-block:: c++ diff --git a/doc/programming_guide/src/introduction.rst b/doc/rst/src/introduction.rst similarity index 92% rename from doc/programming_guide/src/introduction.rst rename to doc/rst/src/introduction.rst index aa575f6f..8ec605f2 100644 --- a/doc/programming_guide/src/introduction.rst +++ b/doc/rst/src/introduction.rst @@ -1,9 +1,10 @@ +************ Introduction -============ +************ ``lib_mic_array`` is a library for interfacing with one or more PDM microphones -on an XMOS device. +on an XMOS device. Version 5.0 of this library has been redesigned from scratch to make efficient usage of the XMOS XS3 architecture. diff --git a/doc/programming_guide/src/mic_array_diagrams.drawio b/doc/rst/src/mic_array_diagrams.drawio similarity index 100% rename from doc/programming_guide/src/mic_array_diagrams.drawio rename to doc/rst/src/mic_array_diagrams.drawio diff --git a/doc/programming_guide/src/overview.rst b/doc/rst/src/overview.rst similarity index 94% rename from doc/programming_guide/src/overview.rst rename to doc/rst/src/overview.rst index 9961f6d4..a8c352be 100644 --- a/doc/programming_guide/src/overview.rst +++ b/doc/rst/src/overview.rst @@ -1,7 +1,7 @@ - +******** Overview -======== +******** ``lib_mic_array`` is a library for capturing and processing PDM microphone data on xcore.ai devices. @@ -12,7 +12,7 @@ stream is captured by the device, filtered and decimated to a 32-bit PCM audio stream. Capabilities ------------- +============ * Both SDR (1 mic per pin) and DDR (2 mics per pin) microphone configurations are supported @@ -39,26 +39,28 @@ Capabilities * Most configurations require only a single hardware thread -.. raw:: latex - \newpage +|newpage| High-Level Process View ------------------------ +======================= This section gives a brief overview of the steps to process a PDM audio stream into a PCM audio stream. This section is concerned with the steady state -behavior and does not describe any necessary initialization steps. +behavior and does not describe any necessary initialization steps. The high level +process view is depicted in the figure :ref:`image_high_level_process`. +.. _image_high_level_process: .. figure:: diagrams/high_level_process.drawio.png :align: center :scale: 100 % - :alt: Mic Array High Level Process + + Mic Array High Level Process Execution Contexts -****************** +------------------ The mic array unit uses two different execution contexts. The first is the PDM rx service ("PDM rx"), which is responsible for reading PDM samples from the @@ -68,7 +70,7 @@ decimation thread, which is where all processing other than PDM capture is performed. This two-context model relaxes the need for tight coupling and synchronization -between PDM rx and the decimation thread, allowing significant flexibility in +between PDM rx and the decimation thread, allowing significant flexibility in how samples are processed in the decimation thread. PDM rx is typically run within an interrupt on the same hardware core as the @@ -80,7 +82,7 @@ in the case where the processing load exceeds the MIPS available in a single thread. Step 1: PDM Capture -******************* +------------------- The PDM data signal is captured by the xcore.ai device's port hardware. The port receiving the PDM signals buffers the received samples. Each time the port @@ -90,16 +92,16 @@ Samples are collected word-by-word and assembled into blocks. Each time a block has been filled, the block is transferred to the decimation thread where all remaining mic array processing takes place. -The size of PDM data blocks varies depending upon the configured number of -microphone channels and the configured second stage decimator's decimation +The size of PDM data blocks varies depending upon the configured number of +microphone channels and the configured second stage decimator's decimation factor. Each PDM data block will contain exactly enough PDM samples to produce one new mic array (multi-channel) output sample. Step 2: First Stage Decimation -****************************** +------------------------------ -The conversion from the high-sample-rate PDM stream to lower-sample-rate PCM -stream involves two stages of decimating filters. After the decimation thread +The conversion from the high-sample-rate PDM stream to lower-sample-rate PCM +stream involves two stages of decimating filters. After the decimation thread receives a block of PDM samples, the samples are filtered by the first stage decimator. @@ -117,7 +119,7 @@ samples with a sample time ``32`` times longer than the PDM sample time. See :ref:`decimator_stages` for further details. Step 3: Second Stage Decimation -******************************* +------------------------------- The second stage decimator is a decimating FIR filter with a configurable decimation factor and tap count. Like the first stage decimator, this library @@ -136,9 +138,9 @@ and a 3.072 MHz PDM clock, the output sample rate is 16 kHz. See :ref:`decimator_stages` for further details. Step 4: Post-Processing -*********************** +----------------------- -After second stage decimation, the resulting sample goes to post-processing +After second stage decimation, the resulting sample goes to post-processing where two (optional) post-processing steps are available. The first is a simple IIR filter, called DC Offset Elimination, which seeks to @@ -155,7 +157,7 @@ Finally, the sample or frame is transmitted over a channel from the mic array module to the next stage of the processing pipeline. Extending/Modifying Mic Array Behavior -************************************** +-------------------------------------- At the core of ``lib_mic_array`` are several C++ class templates which are loosely coupled and intended to be easily overridden for modified behavior. The @@ -169,4 +171,4 @@ instantiating the mic array class template with the new class as the appropriate template parameter. With that in mind, while most applications will have no need to modify the mic -array behavior, it is nevertheless designed to be easy to do so. \ No newline at end of file +array behavior, it is nevertheless designed to be easy to do so. diff --git a/doc/programming_guide/src/reference/api_index.rst b/doc/rst/src/reference/api_index.rst similarity index 72% rename from doc/programming_guide/src/reference/api_index.rst rename to doc/rst/src/reference/api_index.rst index 11936d19..6dceb105 100644 --- a/doc/programming_guide/src/reference/api_index.rst +++ b/doc/rst/src/reference/api_index.rst @@ -1,6 +1,6 @@ -############# +************* API Reference -############# +************* .. toctree:: :maxdepth: 2 diff --git a/doc/programming_guide/src/reference/c/c_api.rst b/doc/rst/src/reference/c/c_api.rst similarity index 72% rename from doc/programming_guide/src/reference/c/c_api.rst rename to doc/rst/src/reference/c/c_api.rst index 5cdf4c05..aaed1159 100644 --- a/doc/programming_guide/src/reference/c/c_api.rst +++ b/doc/rst/src/reference/c/c_api.rst @@ -1,6 +1,6 @@ -############### + C API Reference -############### +=============== .. toctree:: :maxdepth: 1 @@ -11,4 +11,4 @@ C API Reference frame_transfer dc_elimination util - mic_array_vanilla \ No newline at end of file + mic_array_vanilla diff --git a/doc/programming_guide/src/reference/c/dc_elimination.rst b/doc/rst/src/reference/c/dc_elimination.rst similarity index 89% rename from doc/programming_guide/src/reference/c/dc_elimination.rst rename to doc/rst/src/reference/c/dc_elimination.rst index e7602906..115a1b54 100644 --- a/doc/programming_guide/src/reference/c/dc_elimination.rst +++ b/doc/rst/src/reference/c/dc_elimination.rst @@ -1,5 +1,5 @@ dc_elimination.h -================ +---------------- .. doxygenstruct:: dcoe_chan_state_t :members: diff --git a/doc/programming_guide/src/reference/c/filters_default.rst b/doc/rst/src/reference/c/filters_default.rst similarity index 91% rename from doc/programming_guide/src/reference/c/filters_default.rst rename to doc/rst/src/reference/c/filters_default.rst index c8d05da9..f7d73dc9 100644 --- a/doc/programming_guide/src/reference/c/filters_default.rst +++ b/doc/rst/src/reference/c/filters_default.rst @@ -1,26 +1,26 @@ filters_default.h -================= +----------------- The filters described below are the first and second stage filters provided by -this library which are used with the -:cpp:class:`TwoStageDecimator ` class template by +this library which are used with the +:cpp:class:`TwoStageDecimator ` class template by default. Stage 1 - PDM-to-PCM Decimating FIR Filter ------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: - - Decimation Factor: 32 + + Decimation Factor: 32 Tap Count: 256 -The first stage decimation FIR filter converts 1-bit PDM samples into 32-bit +The first stage decimation FIR filter converts 1-bit PDM samples into 32-bit PCM samples and simultaneously decimates by a factor of 32. -A typical input PDM sample rate will be 3.072M samples/sec, thus the +A typical input PDM sample rate will be 3.072M samples/sec, thus the corresponding output sample rate will be 96k samples/sec. -The first stage filter uses 16-bit coefficients for its taps. Because +The first stage filter uses 16-bit coefficients for its taps. Because this is a highly optimized filter targeting the VPU hardware, the first stage filter is presently restricted to using exactly 256 filter taps. @@ -32,7 +32,7 @@ filter, see :ref:`decimator_stages`. .. doxygendefine:: STAGE1_DEC_FACTOR .. doxygendefine:: STAGE1_TAP_COUNT - + .. doxygendefine:: STAGE1_WORDS .. doxygenvariable:: stage1_coef @@ -43,7 +43,7 @@ Stage 2 - PCM Decimating FIR Filter ----------------------------------- .. code-block:: - + Decimation Factor: (configurable) Tap Count: (configurable) @@ -61,10 +61,10 @@ complete description of the FIR implementation is outside the scope of this documentation, but it can be found in the ```xs3_filter_fir_s32_t``` documentation of ``lib_xcore_math``. -In brief, the second stage filter coefficients are quantized to a Q1.30 -fixed-point format with input samples treated as integers. The tap outputs -are added into a 40-bit accumulator, and an output sample is produced by -applying a rounding arithmetic right-shift to the accumulator and then +In brief, the second stage filter coefficients are quantized to a Q1.30 +fixed-point format with input samples treated as integers. The tap outputs +are added into a 40-bit accumulator, and an output sample is produced by +applying a rounding arithmetic right-shift to the accumulator and then clipping the result to the interval ``[INT32_MAX, INT32_MIN)``. For more information about the example second stage filter supplies with the @@ -77,6 +77,6 @@ see :ref:`decimator_stages`. .. doxygendefine:: STAGE2_TAP_COUNT .. doxygenvariable:: stage2_coef - + .. doxygenvariable:: stage2_shr diff --git a/doc/programming_guide/src/reference/c/frame_transfer.rst b/doc/rst/src/reference/c/frame_transfer.rst similarity index 88% rename from doc/programming_guide/src/reference/c/frame_transfer.rst rename to doc/rst/src/reference/c/frame_transfer.rst index f3e6f971..6da09b29 100644 --- a/doc/programming_guide/src/reference/c/frame_transfer.rst +++ b/doc/rst/src/reference/c/frame_transfer.rst @@ -1,5 +1,5 @@ frame_transfer.h -================ +---------------- .. doxygenfunction:: ma_frame_tx diff --git a/doc/programming_guide/src/reference/c/mic_array_vanilla.rst b/doc/rst/src/reference/c/mic_array_vanilla.rst similarity index 82% rename from doc/programming_guide/src/reference/c/mic_array_vanilla.rst rename to doc/rst/src/reference/c/mic_array_vanilla.rst index 388e0811..eeab0723 100644 --- a/doc/programming_guide/src/reference/c/mic_array_vanilla.rst +++ b/doc/rst/src/reference/c/mic_array_vanilla.rst @@ -1,5 +1,5 @@ mic_array_vanilla.h -=================== +------------------- .. doxygenfunction:: ma_vanilla_init diff --git a/doc/programming_guide/src/reference/c/pdm_resources.rst b/doc/rst/src/reference/c/pdm_resources.rst similarity index 65% rename from doc/programming_guide/src/reference/c/pdm_resources.rst rename to doc/rst/src/reference/c/pdm_resources.rst index 1665f085..26de3431 100644 --- a/doc/programming_guide/src/reference/c/pdm_resources.rst +++ b/doc/rst/src/reference/c/pdm_resources.rst @@ -1,9 +1,9 @@ pdm_resources.h -=============== +--------------- .. doxygenstruct:: pdm_rx_resources_t :members: .. doxygendefine:: PDM_RX_RESOURCES_SDR - -.. doxygendefine:: PDM_RX_RESOURCES_DDR \ No newline at end of file + +.. doxygendefine:: PDM_RX_RESOURCES_DDR diff --git a/doc/programming_guide/src/reference/c/setup.rst b/doc/rst/src/reference/c/setup.rst similarity index 67% rename from doc/programming_guide/src/reference/c/setup.rst rename to doc/rst/src/reference/c/setup.rst index 839e11f8..9b1d2746 100644 --- a/doc/programming_guide/src/reference/c/setup.rst +++ b/doc/rst/src/reference/c/setup.rst @@ -1,8 +1,8 @@ setup.h -======= +------- .. doxygenfunction:: mic_array_resources_configure .. doxygenfunction:: mic_array_pdm_clock_start -.. doxygenfunction:: mic_array_mclk_divider \ No newline at end of file +.. doxygenfunction:: mic_array_mclk_divider diff --git a/doc/programming_guide/src/reference/c/util.rst b/doc/rst/src/reference/c/util.rst similarity index 68% rename from doc/programming_guide/src/reference/c/util.rst rename to doc/rst/src/reference/c/util.rst index a7a86c5c..dfc81086 100644 --- a/doc/programming_guide/src/reference/c/util.rst +++ b/doc/rst/src/reference/c/util.rst @@ -1,10 +1,10 @@ util.h -====== +------ .. doxygenfunction:: deinterleave2 - + .. doxygenfunction:: deinterleave4 - + .. doxygenfunction:: deinterleave8 - -.. doxygenfunction:: deinterleave16 \ No newline at end of file + +.. doxygenfunction:: deinterleave16 diff --git a/doc/programming_guide/src/reference/cpp/cpp_api.rst b/doc/rst/src/reference/cpp/cpp_api.rst similarity index 85% rename from doc/programming_guide/src/reference/cpp/cpp_api.rst rename to doc/rst/src/reference/cpp/cpp_api.rst index a9f0f9c8..7833711d 100644 --- a/doc/programming_guide/src/reference/cpp/cpp_api.rst +++ b/doc/rst/src/reference/cpp/cpp_api.rst @@ -1,11 +1,11 @@ -################# + C++ API Reference -################# +================= MicArray -======== +-------- .. doxygenclass:: mic_array::MicArray :members: @@ -18,7 +18,7 @@ MicArray BasicMicArray -============= +------------- .. doxygenclass:: mic_array::prefab::BasicMicArray :members: @@ -32,14 +32,14 @@ BasicMicArray PdmRxService -============ +------------ .. doxygenclass:: mic_array::PdmRxService :members: StandardPdmRxService --------------------- +^^^^^^^^^^^^^^^^^^^^ .. doxygenstruct:: pdm_rx_isr_context_t :members: @@ -60,11 +60,11 @@ StandardPdmRxService TwoStageDecimator -================= +----------------- .. doxygenclass:: mic_array::TwoStageDecimator :members: - + .. raw:: latex \newpage @@ -75,21 +75,21 @@ TwoStageDecimator SampleFilter -============ +------------ NopSampleFilter ---------------- +^^^^^^^^^^^^^^^ .. doxygenclass:: mic_array::NopSampleFilter :members: DcoeSampleFilter ----------------- - +^^^^^^^^^^^^^^^^ + .. doxygenclass:: mic_array::DcoeSampleFilter :members: - + .. raw:: latex \newpage @@ -101,11 +101,11 @@ DcoeSampleFilter OutputHandler -================= +------------- -An OutputHandler is a class which meets the requirements to be used as the -``TOutputHandler`` template parameter of the -:cpp:class:`MicArray ` class template. The basic +An OutputHandler is a class which meets the requirements to be used as the +``TOutputHandler`` template parameter of the +:cpp:class:`MicArray ` class template. The basic requirement is that it have a method: .. code-block::c++ @@ -120,15 +120,15 @@ See :cpp:member:`MicArray::OutputHandler ` for more details. FrameOutputHandler ------------------- +^^^^^^^^^^^^^^^^^^ .. doxygenclass:: mic_array::FrameOutputHandler :members: ChannelFrameTransmitter -*********************** - +""""""""""""""""""""""" + .. doxygenclass:: mic_array::ChannelFrameTransmitter :members: @@ -142,7 +142,7 @@ ChannelFrameTransmitter Misc -==== +---- .. doxygenfunction:: mic_array::deinterleave_pdm_samples diff --git a/doc/programming_guide/src/resource_usage.rst b/doc/rst/src/resource_usage.rst similarity index 97% rename from doc/programming_guide/src/resource_usage.rst rename to doc/rst/src/resource_usage.rst index a926a673..c3124b0e 100644 --- a/doc/programming_guide/src/resource_usage.rst +++ b/doc/rst/src/resource_usage.rst @@ -1,22 +1,23 @@ .. _resource_usage: +************************ Mic Array Resource Usage -######################## +************************ -The mic array unit requires several kinds of hardware resources, including +The mic array unit requires several kinds of hardware resources, including ports, clock blocks, chanends, hardware threads, compute time (MIPS) and memory. -Compared to previous versions of this library, the biggest advantage to the +Compared to previous versions of this library, the biggest advantage to the current version with respect to hardware resources is a greatly reduced compute -requirement. This was made possible by the introduction of the VPU in the XMOS -XS3 architecture. The VPU can do certain operations in a single instruction +requirement. This was made possible by the introduction of the VPU in the XMOS +XS3 architecture. The VPU can do certain operations in a single instruction which would take many, many instructions on previous architectures. -This page attempts to capture the requirements for each hardware type with +This page attempts to capture the requirements for each hardware type with relevant configurations. .. warning:: - The usage information below applies when the Vanilla API or prefab APIs are - used. Resource usage in an application which uses custom mic array + The usage information below applies when the Vanilla API or prefab APIs are + used. Resource usage in an application which uses custom mic array sub-components will depend crucially on the specifics of the customization. Discrete Resources @@ -77,7 +78,7 @@ The prefab API can run the PDM rx service either as a stand-alone thread or as an interrupt in another thread. The Vanilla API only supports running it as an interrupt. The Vanilla API requires only on hardware thread. The prefab API requires 1 thread if PDM rx is used in interrupt mode, and 2 if PDM rx is a -stand-alone thread.. +stand-alone thread.. Running PDM rx as a stand-alone thread modestly reduces the mic array unit's MIPS consumption by eliminating the context switch overhead of an interrupt. The @@ -85,7 +86,7 @@ cost of that is one hardware thread. .. note:: - When configured as an interrupt, PDM rx ISR is typically configured on the + When configured as an interrupt, PDM rx ISR is typically configured on the decimation thread, but this is not a strict requirement. The PDM rx interrupt can be configured for any thread on the same tile as the decimation thread. They must be on the same tile because shared memory is used between the two @@ -150,7 +151,7 @@ PdmRx Measurements indicate that enabling or disabling the DC offset removal filter has little effect on the MIPS usage. The selected frame size has only a slight -negative correlation with MIPS usage. +negative correlation with MIPS usage. @@ -170,7 +171,7 @@ Not included in the table is the space allocated for the first and second stage filter coefficients. The first stage filter coefficients take a constant ``523`` bytes. The second stage filter coefficients use ``4*S2TC`` bytes, where ``S2TC`` is the stage 2 decimator tap count. The value shown in the 'data' column of the -table is the ``sizeof()`` the +table is the ``sizeof()`` the :cpp:class:`BasicMicArray ` that is instantiated. The table below indicates the data size for various configurations. @@ -214,4 +215,4 @@ SPF Samples per frame in frames delivered by the mic array unit. DCOE - DC Offset Elimination \ No newline at end of file + DC Offset Elimination diff --git a/doc/programming_guide/src/sample_filters.rst b/doc/rst/src/sample_filters.rst similarity index 86% rename from doc/programming_guide/src/sample_filters.rst rename to doc/rst/src/sample_filters.rst index bd9805b3..db6d90b4 100644 --- a/doc/programming_guide/src/sample_filters.rst +++ b/doc/rst/src/sample_filters.rst @@ -1,7 +1,8 @@ .. _sample_filters: +************** Sample Filters -============== +************** Following the two-stage decimation procedure is an optional post-processing stage called the sample filter. This stage operates on each sample emitted by @@ -9,32 +10,32 @@ the second stage decimator, one at a time, before the samples are handed off for framing or transfer to the rest of the application's audio pipeline. .. note:: - - This is represented by the ``SampleFilter`` sub-component of the + + This is represented by the ``SampleFilter`` sub-component of the :cpp:class:`MicArray ` class template. An application may implement its own sample filter in the form of a C++ class which implements the ``Filter()`` function as required by ``MicArray``. See the -implementation of :cpp:class:`DcoeSampleFilter ` +implementation of :cpp:class:`DcoeSampleFilter ` for a simple example. DC Offset Elimination ---------------------- +===================== -The current version of this library provides a simple IIR filter called DC -Offset Elimination (DCOE) that can be used as the sample filter. This is a -high-pass filter meant to ensure that each audio channel will tend towards a +The current version of this library provides a simple IIR filter called DC +Offset Elimination (DCOE) that can be used as the sample filter. This is a +high-pass filter meant to ensure that each audio channel will tend towards a mean sample value of zero. Enabling/Disabling DCOE -*********************** +----------------------- Whether the DCOE filter is enabled by default and how to enable or disable it depends on which approach your project uses to include the mic array component in the application. Vanilla Model -''''''''''''' +^^^^^^^^^^^^^ If your project uses the vanilla model (see :ref:`vanilla_api`) to include the mic array unit in your application, then DCOE is **enabled** by default. To @@ -50,7 +51,7 @@ the following. # Gather sources and create application target # ... # Add vanilla source to application build - mic_array_vanilla_add(my_app ${MCLK_FREQ} ${PDM_FREQ} + mic_array_vanilla_add(my_app ${MCLK_FREQ} ${PDM_FREQ} ${MIC_COUNT} ${FRAME_SIZE} ) # ... # Disable DCOE @@ -59,10 +60,10 @@ the following. Prefab Model -'''''''''''' +^^^^^^^^^^^^ -If your project instantiates the -:cpp:class:`BasicMicArray ` class template to +If your project instantiates the +:cpp:class:`BasicMicArray ` class template to include the mic array unit, DC offset elimination is enabled or disabled with the ``USE_DCOE`` boolean template parameter (there is no default). @@ -74,7 +75,7 @@ the ``USE_DCOE`` boolean template parameter (there is no default). The sample filter chosen is based on the ``USE_DCOE`` template parameter when the class template gets instantiated. If ``true``, -:cpp:class:`DcoeSampleFilter ` will be selected as +:cpp:class:`DcoeSampleFilter ` will be selected as the ``MicArray`` ``SampleFilter`` sub-component. Otherwise :cpp:class:`NopSampleFilter ` will be used. @@ -96,14 +97,14 @@ For example, in your application source: General Model -''''''''''''' +^^^^^^^^^^^^^ If your project does not use either the vanilla or prefab models to include the mic array unit in your application, then precisely how the DCOE filter is included may depend on the specifics of your application. In general, however, the DCOE filter will be enabled by using -:cpp:class:`DcoeSampleFilter ` as the -``TSampleFilter`` template parameter for the +:cpp:class:`DcoeSampleFilter ` as the +``TSampleFilter`` template parameter for the :cpp:class:`MicArray ` class template. For example, sub-classing ``mic_array::MicArray`` as follows will enable DCOE @@ -114,9 +115,9 @@ for any ``MicArray`` implementation deriving from that sub-class. #include "mic_array/cpp/MicArray.hpp" using namespace mic_array; ... - template - class DcoeEnabledMicArray : public MicArray { ... @@ -124,9 +125,9 @@ for any ``MicArray`` implementation deriving from that sub-class. DCOE Filter Equation -******************** +-------------------- -As mentioned above, the DCOE filter is a simple IIR filter given by the +As mentioned above, the DCOE filter is a simple IIR filter given by the following equation, where ``x[t]`` and ``x[t-1]`` are the current and previous input sample values respectively, and ``y[t]`` and ``y[t-1]`` are the current and previous output sample values respectively. @@ -138,8 +139,14 @@ and previous output sample values respectively. DCOE Filter Frequency Response -****************************** +------------------------------ + +The plot below indicates the frequency response of DCOE filter :ref:`freq_response_dcoe`. + +.. _freq_response_dcoe: -The plot below indicates the frequency response of DCOE filter. +.. figure:: dcoe_freq_response.png + :align: center + :scale: 100 % -.. image:: dcoe_freq_response.png + DCOE filter frequency response diff --git a/doc/programming_guide/src/software_structure.rst b/doc/rst/src/software_structure.rst similarity index 91% rename from doc/programming_guide/src/software_structure.rst rename to doc/rst/src/software_structure.rst index 934bae93..4b7709fd 100644 --- a/doc/programming_guide/src/software_structure.rst +++ b/doc/rst/src/software_structure.rst @@ -1,10 +1,11 @@ .. _software_structure: +****************** Software Structure -================== - +****************** + The core of ``lib_mic_array`` are a set of C++ class templates representing the -mic array unit and its sub-components. +mic array unit and its sub-components. The template parameters of these class templates are (mainly) used for two different purposes. Non-type template parameters are used to specify certain @@ -13,16 +14,16 @@ the second stage decimator tap count. Type template parameters, on the other hand, are used for configuring the behavior of sub-components. High-Level View ---------------- +=============== -At the heart of the mic array API is the +At the heart of the mic array API is the :cpp:class:`MicArray ` class template. .. note:: - - All classes and class templates mentioned are in the ``mic_array`` C++ + + All classes and class templates mentioned are in the ``mic_array`` C++ namespace unless otherwise specified. Additionally, this documentation may - refer to class templates (e.g. ``MicArray``) with unbound template + refer to class templates (e.g. ``MicArray``) with unbound template parameters as "classes" when doing so is unlikely to lead to confusion. The :cpp:class:`MicArray ` class template looks like the @@ -32,9 +33,9 @@ following: template + class TPdmRx, + class TSampleFilter, + class TOutputHandler> class MicArray; @@ -50,7 +51,7 @@ A ``MicArray`` object comprises 4 sub-components: +=================================================================+=========================+================================+ | :cpp:member:`PdmRx ` | ``TPdmRx`` | Capturing PDM data from a port.| +-----------------------------------------------------------------+-------------------------+--------------------------------+ -| :cpp:member:`Decimator ` | ``TDecimator`` | 2-stage decimation on blocks of| +| :cpp:member:`Decimator ` | ``TDecimator`` | 2-stage decimation on blocks of| | | | PDM data. | +-----------------------------------------------------------------+-------------------------+--------------------------------+ | :cpp:member:`SampleFilter ` | ``TSampleFilter`` | Post-processing of decimated | @@ -68,30 +69,33 @@ interface. The ``MicArray`` object interacts with its sub-components using this interface. .. note:: - - Abstract classes are **not** used to enforce this interface contract. Instead, - the contract is enforced (at compile time) solely in how the ``MicArray`` + + Abstract classes are **not** used to enforce this interface contract. Instead, + the contract is enforced (at compile time) solely in how the ``MicArray`` object makes use of the sub-component. -The following diagram conceptually captures the flow of information through the +The following diagram :ref:`high_level_flow` conceptually captures the flow of information through the ``MicArray`` sub-components. +.. _high_level_flow: + .. figure:: diagrams/high_level_process.drawio.png :align: center :scale: 100 % - :alt: Mic Array High Level Process + + Mic Array High Level Process .. note:: - ``MicArray`` does not enforce the use of an XCore port for collecting PDM - samples or an XCore channel for transferring processed data. This is just the + ``MicArray`` does not enforce the use of an XCore port for collecting PDM + samples or an XCore channel for transferring processed data. This is just the typical usage. Mic Array / Decimator Thread -**************************** +---------------------------- Aside from aggregating its sub-components into a single logical entity, the -``MicArray`` class template also holds the high-level logic for capturing, +``MicArray`` class template also holds the high-level logic for capturing, processing and coordinating movement of the audio stream data. The following code snippet is the implementation for the main mic array thread @@ -101,7 +105,7 @@ The following code snippet is the implementation for the main mic array thread void mic_array::MicArray::ThreadEntry() + TOutputHandler>::ThreadEntry() { int32_t sample_out[MIC_COUNT] = {0}; @@ -137,10 +141,10 @@ thread. .. _crtp: Curiously Recurring Template Pattern -************************************ +------------------------------------ The C++ API of this library makes heavy use of the `Curiously Recurring Template -Pattern `_ +Pattern `_ (CRTP). Instead of providing flexibility through abstract classes or polymorphism, CRTP @@ -170,26 +174,26 @@ names, where templated classes end up with type parameter assignments are themselves templated classes with their own template parameters. Sub-Component Initialization -**************************** +---------------------------- -Each of ``MicArray``'s sub-components may have implementation-specific +Each of ``MicArray``'s sub-components may have implementation-specific configuration or initialization requirements. Each sub-component is a ``public`` -member of ``MicArray`` (see table above). An application can access a +member of ``MicArray`` (see table above). An application can access a sub-component directly to perform any type-specific initialization or other manipulation. -For example, the -:cpp:class:`ChannelFrameTransmitter ` output -handler class needs to know the ``chanend`` to be used for sending samples. This -can be initialized on a ``MicArray`` object ``mics`` with +For example, the +:cpp:class:`ChannelFrameTransmitter ` output +handler class needs to know the ``chanend`` to be used for sending samples. This +can be initialized on a ``MicArray`` object ``mics`` with ``mics.OutputHandler.SetChannel(c_sample_out)``. Sub-Components --------------- +============== PdmRx -***** +----- :cpp:member:`PdmRx `, or the PDM rx service is the ``MicArray`` sub-component responsible for capturing PDM sample data, assembling @@ -199,8 +203,8 @@ The ``MicArray`` class requires only that ``PdmRx`` implement ``GetPdmBlock()``, a blocking call that returns a pointer to a block of PDM data which is ready for further processing. -Generally speaking, ``PdmRx`` will derive from the -:cpp:class:`PdmRxService ` +Generally speaking, ``PdmRx`` will derive from the +:cpp:class:`PdmRxService ` class template. ``PdmRxService`` encapsulates the logic of using an xCore ``port`` for capturing PDM samples one word (32 bits) at a time, and managing two buffers where blocks of samples are collected. It also simplifies the logic @@ -220,11 +224,11 @@ decimator. It also provides methods for installing an optimized ISR for PDM capture. Decimator -********* +--------- The :cpp:member:`Decimator ` sub-component encapsulates the logic of converting blocks of PDM samples into PCM samples. The -:cpp:class:`TwoStageDecimator ` class is a +:cpp:class:`TwoStageDecimator ` class is a decimator implementation that uses a pair of decimating FIR filters to accomplish this. @@ -234,7 +238,7 @@ of ``32``. The second stage has a configurable tap count and decimation factor. For more details, see :ref:`decimator_stages`. SampleFilter -************ +------------ The :cpp:member:`SampleFilter ` sub-component is used for post-processing samples emitted by the decimator. Two @@ -254,18 +258,18 @@ tends toward zero. For more details, see :ref:`sample_filters`. OutputHandler -************* +------------- The :cpp:member:`OutputHandler ` sub-component is responsible for transferring processed sample data to subsequent processing stages. -There are two main considerations for output handlers. The first is whether +There are two main considerations for output handlers. The first is whether audio data should be transferred *sample-by-sample* or as *frames* containing many samples. The second is the method of actually transferring the audio data. -The class -:cpp:class:`ChannelSampleTransmitter ` +The class +:cpp:class:`ChannelSampleTransmitter ` sends samples one at a time to subsequent processing stages using an xCore channel. @@ -283,10 +287,10 @@ the following is the fully qualified name of a (particular) concrete .. code-block:: c++ - mic_array::MicArray<2, - mic_array::TwoStageDecimator<2,6,65>, - mic_array::StandardPdmRxService<2,2,6>, - mic_array::DcoeSampleFilter<2>, + mic_array::MicArray<2, + mic_array::TwoStageDecimator<2,6,65>, + mic_array::StandardPdmRxService<2,2,6>, + mic_array::DcoeSampleFilter<2>, mic_array::FrameOutputHandler<2,256, mic_array::ChannelFrameTransmitter>> diff --git a/doc/programming_guide/src/stage1_freq_response.png b/doc/rst/src/stage1_freq_response.png similarity index 100% rename from doc/programming_guide/src/stage1_freq_response.png rename to doc/rst/src/stage1_freq_response.png diff --git a/doc/programming_guide/src/stage2_freq_response.png b/doc/rst/src/stage2_freq_response.png similarity index 100% rename from doc/programming_guide/src/stage2_freq_response.png rename to doc/rst/src/stage2_freq_response.png diff --git a/doc/programming_guide/src/vanilla_api.rst b/doc/rst/src/vanilla_api.rst similarity index 96% rename from doc/programming_guide/src/vanilla_api.rst rename to doc/rst/src/vanilla_api.rst index b131f0ce..e0a487b8 100644 --- a/doc/programming_guide/src/vanilla_api.rst +++ b/doc/rst/src/vanilla_api.rst @@ -1,14 +1,15 @@ .. _vanilla_api: +*********** Vanilla API -########### +*********** The Vanilla API is a small optional API which greatly simplifies the process of including a mic array unit in an xcore.ai application. Most applications that make use of a PDM mic array will not have complicated needs from the mic array software component beyond delivery of frames of audio data from a configurable -set of microphones at a configurable rate. This API targets that majority of -applications. +set of microphones at a configurable rate. This API targets that majority of +applications. The prefab API requires the application developer to have at least some minimal understanding of the objects and classes associated with the mic array @@ -19,8 +20,8 @@ and instead moves the majority of the application logic into the application's build project. .. note:: - - **Why "Vanilla"?** "Vanilla" was originally meant as a generic placeholder + + **Why "Vanilla"?** "Vanilla" was originally meant as a generic placeholder name, but no better name was ever suggested. How It Works @@ -34,7 +35,7 @@ control configuration, the source file relies on a set of pre-processor macros instantiated. The API is included in an application by using a CMake macro -(``mic_array_vanilla_add()``) provided in this library. The macro updates the +(``mic_array_vanilla_add()``) provided in this library. The macro updates the application's sources, includes and compile definitions to include the API. In the application code, two function calls are needed. First, @@ -56,8 +57,8 @@ a (non-streaming) channel using the :c:func:`ma_frame_rx()` or .. note:: - The Vanilla API uses the default filters provided with this library, - and does not currently provide a way to override this. To use custom filters, + The Vanilla API uses the default filters provided with this library, + and does not currently provide a way to override this. To use custom filters, you must either use a lower-level API or modify the vanilla API. Configuration @@ -77,12 +78,12 @@ application. macro( mic_array_vanilla_add TARGET_NAME - MCLK_FREQ + MCLK_FREQ PDM_FREQ MIC_COUNT SAMPLES_PER_FRAME ) -``TARGET_NAME`` +``TARGET_NAME`` The name of the application's CMake target. It is the target the Vanilla API is added to. @@ -92,9 +93,9 @@ application. master audio clock. (Equivalent compile definition: ``MIC_ARRAY_CONFIG_MCLK_FREQ``) -``PDM_FREQ`` +``PDM_FREQ`` The desired frequency, in Hz, of the PDM clock. This should be an integer - factor of ``MCLK_FREQ`` between ``1`` and ``510``. (Equivalent compile + factor of ``MCLK_FREQ`` between ``1`` and ``510``. (Equivalent compile definition: ``MIC_ARRAY_CONFIG_PDM_FREQ``) ``MIC_COUNT`` @@ -106,13 +107,13 @@ application. width. (Equivalent compile definition: ``MIC_ARRAY_CONFIG_MIC_COUNT``) .. note:: - This API does not support capturing only a subset of the capture port's + This API does not support capturing only a subset of the capture port's channels, e.g. capturing only 3 channels on a 4-bit port. To accomplish this the prefab API should be used. .. note:: Though listed under Optional Configuration below, if the microphones are in - a DDR configuration and ``MIC_COUNT`` is not ``2``, the application must + a DDR configuration and ``MIC_COUNT`` is not ``2``, the application must also define ``MIC_ARRAY_CONFIG_USE_DDR``. ``SAMPLES_PER_FRAME`` is the number of samples (for each microphone channel) @@ -132,22 +133,22 @@ application's ``CMakeLists.txt`` using CMake's built-in ``MIC_ARRAY_CONFIG_USE_DDR`` - Indicates whether the microphones are arranged in an SDR (``0``) or DDR + Indicates whether the microphones are arranged in an SDR (``0``) or DDR (``1``) configuration. An SDR configuration is one in which each port pin is - connected to a single PDM microphone. A DDR configuration is one which each + connected to a single PDM microphone. A DDR configuration is one which each port pin is connected to two PDM microphones. Defaults to ``0`` (SDR), unless - ``MIC_ARRAY_CONFIG_MIC_COUNT`` is ``2`` in which case it defaults to ``1`` + ``MIC_ARRAY_CONFIG_MIC_COUNT`` is ``2`` in which case it defaults to ``1`` (DDR). ``MIC_ARRAY_CONFIG_USE_DC_ELIMINATION`` - Indicates whether the :ref:`DC offset elimination ` filter + Indicates whether the :ref:`DC offset elimination ` filter should be applied to the output of the decimator. Set to ``0`` to disable or ``1`` to enable. Defaults to ``1`` (filter on). The next three parameters are the identifiers for hardware port resources used by the mic array unit. They can be specified as either the identifier listed in -your device's datasheet (e.g. ``XS1_PORT_1D``) or as an alias for the port +your device's datasheet (e.g. ``XS1_PORT_1D``) or as an alias for the port listed in your application's XN file (e.g. ``PORT_MCLK_IN_OUT``). For example: .. code-block:: xml @@ -199,8 +200,8 @@ Using the Vanilla API with build systems other than CMake is simple. * Add the file ``etc/vanilla/mic_array_vanilla.cpp`` to the application's source files. -* Add ``etc/vanilla/`` (relative to repository root) to the application include +* Add ``etc/vanilla/`` (relative to repository root) to the application include paths. -* Add the compile definitions for the parameters listed in the previous sections +* Add the compile definitions for the parameters listed in the previous sections (each parameter beginning with ``MIC_ARRAY_CONFIG_``) to the compile options for ``mic_array_vanilla.cpp``. diff --git a/etc/vanilla/mic_array_vanilla.h b/etc/vanilla/mic_array_vanilla.h index 3ef5cf45..6e8af38c 100644 --- a/etc/vanilla/mic_array_vanilla.h +++ b/etc/vanilla/mic_array_vanilla.h @@ -1,4 +1,4 @@ -// Copyright 2022-2023 XMOS LIMITED. +// Copyright 2022-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #pragma once diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt index 04a22b37..2c914da1 100644 --- a/examples/CMakeLists.txt +++ b/examples/CMakeLists.txt @@ -1,7 +1,7 @@ cmake_minimum_required(VERSION 3.21) include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake) project(mic_array_examples) -add_subdirectory(demo) -add_subdirectory(demo_vanilla) -add_subdirectory(demo_par_decimator) -add_subdirectory(measure_mips) \ No newline at end of file +add_subdirectory(app_mic_array) +add_subdirectory(app_vanilla) +add_subdirectory(app_par_decimator) +add_subdirectory(app_measure_mips) diff --git a/examples/measure_mips/CMakeLists.txt b/examples/app_measure_mips/CMakeLists.txt similarity index 100% rename from examples/measure_mips/CMakeLists.txt rename to examples/app_measure_mips/CMakeLists.txt diff --git a/examples/demo/XVF3610_Q60A.xn b/examples/app_measure_mips/XVF3610_Q60A.xn similarity index 100% rename from examples/demo/XVF3610_Q60A.xn rename to examples/app_measure_mips/XVF3610_Q60A.xn diff --git a/examples/measure_mips/src/app.cpp b/examples/app_measure_mips/src/app.cpp similarity index 100% rename from examples/measure_mips/src/app.cpp rename to examples/app_measure_mips/src/app.cpp diff --git a/examples/measure_mips/src/app.h b/examples/app_measure_mips/src/app.h similarity index 100% rename from examples/measure_mips/src/app.h rename to examples/app_measure_mips/src/app.h diff --git a/examples/measure_mips/src/app_config.h b/examples/app_measure_mips/src/app_config.h similarity index 100% rename from examples/measure_mips/src/app_config.h rename to examples/app_measure_mips/src/app_config.h diff --git a/examples/demo/src/config.xscope b/examples/app_measure_mips/src/config.xscope similarity index 100% rename from examples/demo/src/config.xscope rename to examples/app_measure_mips/src/config.xscope diff --git a/examples/measure_mips/src/main.xc b/examples/app_measure_mips/src/main.xc similarity index 100% rename from examples/measure_mips/src/main.xc rename to examples/app_measure_mips/src/main.xc diff --git a/examples/demo/CMakeLists.txt b/examples/app_mic_array/CMakeLists.txt similarity index 100% rename from examples/demo/CMakeLists.txt rename to examples/app_mic_array/CMakeLists.txt diff --git a/examples/demo_vanilla/XVF3610_Q60A.xn b/examples/app_mic_array/XVF3610_Q60A.xn similarity index 100% rename from examples/demo_vanilla/XVF3610_Q60A.xn rename to examples/app_mic_array/XVF3610_Q60A.xn diff --git a/examples/demo/src/app.cpp b/examples/app_mic_array/src/app.cpp similarity index 100% rename from examples/demo/src/app.cpp rename to examples/app_mic_array/src/app.cpp diff --git a/examples/demo/src/app.h b/examples/app_mic_array/src/app.h similarity index 100% rename from examples/demo/src/app.h rename to examples/app_mic_array/src/app.h diff --git a/examples/demo/src/app_config.h b/examples/app_mic_array/src/app_config.h similarity index 100% rename from examples/demo/src/app_config.h rename to examples/app_mic_array/src/app_config.h diff --git a/examples/demo/src/app_i2s.c b/examples/app_mic_array/src/app_i2s.c similarity index 100% rename from examples/demo/src/app_i2s.c rename to examples/app_mic_array/src/app_i2s.c diff --git a/examples/demo_vanilla/src/config.xscope b/examples/app_mic_array/src/config.xscope similarity index 100% rename from examples/demo_vanilla/src/config.xscope rename to examples/app_mic_array/src/config.xscope diff --git a/examples/demo/src/main.xc b/examples/app_mic_array/src/main.xc similarity index 100% rename from examples/demo/src/main.xc rename to examples/app_mic_array/src/main.xc diff --git a/examples/demo_par_decimator/CMakeLists.txt b/examples/app_par_decimator/CMakeLists.txt similarity index 100% rename from examples/demo_par_decimator/CMakeLists.txt rename to examples/app_par_decimator/CMakeLists.txt diff --git a/examples/demo_par_decimator/src/app.cpp b/examples/app_par_decimator/src/app.cpp similarity index 100% rename from examples/demo_par_decimator/src/app.cpp rename to examples/app_par_decimator/src/app.cpp diff --git a/examples/demo_par_decimator/src/app.h b/examples/app_par_decimator/src/app.h similarity index 100% rename from examples/demo_par_decimator/src/app.h rename to examples/app_par_decimator/src/app.h diff --git a/examples/demo_par_decimator/src/app_config.h b/examples/app_par_decimator/src/app_config.h similarity index 100% rename from examples/demo_par_decimator/src/app_config.h rename to examples/app_par_decimator/src/app_config.h diff --git a/examples/demo_par_decimator/src/app_decimator.hpp b/examples/app_par_decimator/src/app_decimator.hpp similarity index 100% rename from examples/demo_par_decimator/src/app_decimator.hpp rename to examples/app_par_decimator/src/app_decimator.hpp diff --git a/examples/demo_par_decimator/src/app_i2s.c b/examples/app_par_decimator/src/app_i2s.c similarity index 100% rename from examples/demo_par_decimator/src/app_i2s.c rename to examples/app_par_decimator/src/app_i2s.c diff --git a/examples/demo_par_decimator/src/app_mic_array.hpp b/examples/app_par_decimator/src/app_mic_array.hpp similarity index 100% rename from examples/demo_par_decimator/src/app_mic_array.hpp rename to examples/app_par_decimator/src/app_mic_array.hpp diff --git a/examples/demo_par_decimator/src/app_mic_dataline_selector.c b/examples/app_par_decimator/src/app_mic_dataline_selector.c similarity index 100% rename from examples/demo_par_decimator/src/app_mic_dataline_selector.c rename to examples/app_par_decimator/src/app_mic_dataline_selector.c diff --git a/examples/demo_par_decimator/src/decimator_subtask.c b/examples/app_par_decimator/src/decimator_subtask.c similarity index 100% rename from examples/demo_par_decimator/src/decimator_subtask.c rename to examples/app_par_decimator/src/decimator_subtask.c diff --git a/examples/demo_par_decimator/src/decimator_subtask.h b/examples/app_par_decimator/src/decimator_subtask.h similarity index 100% rename from examples/demo_par_decimator/src/decimator_subtask.h rename to examples/app_par_decimator/src/decimator_subtask.h diff --git a/examples/demo_par_decimator/src/main.xc b/examples/app_par_decimator/src/main.xc similarity index 100% rename from examples/demo_par_decimator/src/main.xc rename to examples/app_par_decimator/src/main.xc diff --git a/examples/demo_vanilla/CMakeLists.txt b/examples/app_vanilla/CMakeLists.txt similarity index 100% rename from examples/demo_vanilla/CMakeLists.txt rename to examples/app_vanilla/CMakeLists.txt diff --git a/examples/measure_mips/XVF3610_Q60A.xn b/examples/app_vanilla/XVF3610_Q60A.xn similarity index 100% rename from examples/measure_mips/XVF3610_Q60A.xn rename to examples/app_vanilla/XVF3610_Q60A.xn diff --git a/examples/demo_vanilla/src/app.h b/examples/app_vanilla/src/app.h similarity index 100% rename from examples/demo_vanilla/src/app.h rename to examples/app_vanilla/src/app.h diff --git a/examples/demo_vanilla/src/app_config.h b/examples/app_vanilla/src/app_config.h similarity index 100% rename from examples/demo_vanilla/src/app_config.h rename to examples/app_vanilla/src/app_config.h diff --git a/examples/demo_vanilla/src/app_i2s.c b/examples/app_vanilla/src/app_i2s.c similarity index 100% rename from examples/demo_vanilla/src/app_i2s.c rename to examples/app_vanilla/src/app_i2s.c diff --git a/examples/measure_mips/src/config.xscope b/examples/app_vanilla/src/config.xscope similarity index 100% rename from examples/measure_mips/src/config.xscope rename to examples/app_vanilla/src/config.xscope diff --git a/examples/demo_vanilla/src/main.xc b/examples/app_vanilla/src/main.xc similarity index 100% rename from examples/demo_vanilla/src/main.xc rename to examples/app_vanilla/src/main.xc diff --git a/index.rst b/index.rst deleted file mode 100644 index 86ca70f5..00000000 --- a/index.rst +++ /dev/null @@ -1,9 +0,0 @@ - -lib_mic_array Programming Guide -=============================== - -.. toctree:: - :maxdepth: 1 - :caption: Contents: - - doc/programming_guide/index diff --git a/lib_mic_array/api/mic_array/api.h b/lib_mic_array/api/mic_array/api.h index 2d585937..bf69b345 100644 --- a/lib_mic_array/api/mic_array/api.h +++ b/lib_mic_array/api/mic_array/api.h @@ -1,4 +1,4 @@ -// Copyright 2022 XMOS LIMITED. +// Copyright 2022-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #pragma once diff --git a/lib_mic_array/api/mic_array/cpp/PdmRx.hpp b/lib_mic_array/api/mic_array/cpp/PdmRx.hpp index 91508717..1375ea4d 100644 --- a/lib_mic_array/api/mic_array/cpp/PdmRx.hpp +++ b/lib_mic_array/api/mic_array/cpp/PdmRx.hpp @@ -1,4 +1,4 @@ -// Copyright 2022-2023 XMOS LIMITED. +// Copyright 2022-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #pragma once diff --git a/lib_mic_array/api/mic_array/cpp/Util.hpp b/lib_mic_array/api/mic_array/cpp/Util.hpp index dcc22982..ae5840a3 100644 --- a/lib_mic_array/api/mic_array/cpp/Util.hpp +++ b/lib_mic_array/api/mic_array/cpp/Util.hpp @@ -1,4 +1,4 @@ -// Copyright 2022 XMOS LIMITED. +// Copyright 2022-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #pragma once diff --git a/lib_mic_array/api/mic_array/etc/fir_1x16_bit.h b/lib_mic_array/api/mic_array/etc/fir_1x16_bit.h index b10e9b90..958292c2 100644 --- a/lib_mic_array/api/mic_array/etc/fir_1x16_bit.h +++ b/lib_mic_array/api/mic_array/etc/fir_1x16_bit.h @@ -1,4 +1,4 @@ -// Copyright 2021-2022 XMOS LIMITED. +// Copyright 2021-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #pragma once diff --git a/lib_mic_array/api/mic_array/etc/xcore_compat.h b/lib_mic_array/api/mic_array/etc/xcore_compat.h index a76b0260..21d7aa0e 100644 --- a/lib_mic_array/api/mic_array/etc/xcore_compat.h +++ b/lib_mic_array/api/mic_array/etc/xcore_compat.h @@ -1,4 +1,4 @@ -// Copyright 2022 XMOS LIMITED. +// Copyright 2022-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #pragma once diff --git a/lib_mic_array/api/mic_array/frame_transfer.h b/lib_mic_array/api/mic_array/frame_transfer.h index be1d95ca..ea23eda6 100644 --- a/lib_mic_array/api/mic_array/frame_transfer.h +++ b/lib_mic_array/api/mic_array/frame_transfer.h @@ -1,4 +1,4 @@ -// Copyright 2022 XMOS LIMITED. +// Copyright 2022-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #pragma once diff --git a/lib_mic_array/api/mic_array/pdm_resources.h b/lib_mic_array/api/mic_array/pdm_resources.h index 22cd3f64..ea310db6 100644 --- a/lib_mic_array/api/mic_array/pdm_resources.h +++ b/lib_mic_array/api/mic_array/pdm_resources.h @@ -1,4 +1,4 @@ -// Copyright 2021-2023 XMOS LIMITED. +// Copyright 2021-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #pragma once diff --git a/lib_mic_array/lib_build_info.cmake b/lib_mic_array/lib_build_info.cmake index 9ad4943d..3fd01870 100644 --- a/lib_mic_array/lib_build_info.cmake +++ b/lib_mic_array/lib_build_info.cmake @@ -1,13 +1,13 @@ set(LIB_NAME lib_mic_array) -set(LIB_VERSION 5.4.0) -set(LIB_DEPENDENT_MODULES "lib_xcore_math(2.3.0)") -set(LIB_INCLUDES +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 src/etc ../etc/vanilla ) diff --git a/lib_mic_array/module_build_info b/lib_mic_array/module_build_info index 8c6749df..21e8931c 100644 --- a/lib_mic_array/module_build_info +++ b/lib_mic_array/module_build_info @@ -1,6 +1,6 @@ -VERSION = 5.4.0 +VERSION = 5.5.0 -DEPENDENT_MODULES = lib_xcore_math(>=2.3.0) +DEPENDENT_MODULES = lib_xcore_math(>=2.4.0) MODULE_XCC_FLAGS = $(XCC_FLAGS) -g -Os @@ -13,7 +13,7 @@ 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 @@ -27,4 +27,4 @@ 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 \ No newline at end of file +endif diff --git a/lib_mic_array/src/deinterleave16.S b/lib_mic_array/src/deinterleave16.S index 7aa7c903..7087b7f6 100644 --- a/lib_mic_array/src/deinterleave16.S +++ b/lib_mic_array/src/deinterleave16.S @@ -1,4 +1,4 @@ -// Copyright 2023 XMOS LIMITED. +// Copyright 2023-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #define NSTACKWORDS 6 diff --git a/lib_mic_array/src/deinterleave2.S b/lib_mic_array/src/deinterleave2.S index e22737e2..36a03b7a 100644 --- a/lib_mic_array/src/deinterleave2.S +++ b/lib_mic_array/src/deinterleave2.S @@ -1,4 +1,4 @@ -// Copyright 2022 XMOS LIMITED. +// Copyright 2022-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #define NSTACKWORDS 0 diff --git a/lib_mic_array/src/deinterleave4.S b/lib_mic_array/src/deinterleave4.S index 77412cab..c024afa2 100644 --- a/lib_mic_array/src/deinterleave4.S +++ b/lib_mic_array/src/deinterleave4.S @@ -1,4 +1,4 @@ -// Copyright 2022 XMOS LIMITED. +// Copyright 2022-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #define NSTACKWORDS 2 diff --git a/lib_mic_array/src/deinterleave8.S b/lib_mic_array/src/deinterleave8.S index f3771cfa..e19275d4 100644 --- a/lib_mic_array/src/deinterleave8.S +++ b/lib_mic_array/src/deinterleave8.S @@ -1,4 +1,4 @@ -// Copyright 2022 XMOS LIMITED. +// Copyright 2022-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #define NSTACKWORDS 6 diff --git a/lib_mic_array/src/frame_transfer.c b/lib_mic_array/src/frame_transfer.c index 12eb1931..6040e516 100644 --- a/lib_mic_array/src/frame_transfer.c +++ b/lib_mic_array/src/frame_transfer.c @@ -1,4 +1,4 @@ -// Copyright 2022 XMOS LIMITED. +// Copyright 2022-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #include diff --git a/lib_mic_array/src/pdm_rx_isr.S b/lib_mic_array/src/pdm_rx_isr.S index 25d2e045..a8d3176d 100644 --- a/lib_mic_array/src/pdm_rx_isr.S +++ b/lib_mic_array/src/pdm_rx_isr.S @@ -1,4 +1,4 @@ -// Copyright 2021-2022 XMOS LIMITED. +// Copyright 2021-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #if defined(__XS3A__) diff --git a/script/.gitignore b/python/.gitignore similarity index 100% rename from script/.gitignore rename to python/.gitignore diff --git a/script/README.rst b/python/README.rst similarity index 97% rename from script/README.rst rename to python/README.rst index feb12d94..139a5592 100644 --- a/script/README.rst +++ b/python/README.rst @@ -1,4 +1,4 @@ - +:orphan: Scripts @@ -24,7 +24,7 @@ The following is an example of running ``stage1.py``. .. code:: - lib_mic_array\script>python stage1.py filter_design\good_2_stage_filter_int.pkl + lib_mic_array\python>python stage1.py filter_design\good_2_stage_filter_int.pkl Stage 1 Decimation Factor: 32 Stage 1 Tap Count: 125 Stage 2 Decimation Factor: 6 @@ -64,7 +64,7 @@ The following is an example of ``stage2.py`` being run with the same input file. .. code:: - lib_mic_array\script>python stage2.py filter_design\good_2_stage_filter_int.pkl + lib_mic_array\python>python stage2.py filter_design\good_2_stage_filter_int.pkl Stage 1 Decimation Factor: 32 Stage 1 Tap Count: 125 Stage 2 Decimation Factor: 6 @@ -113,7 +113,7 @@ Using Custom Coefficients in an Application The C files ../lib_mic_array/src/etc/stage1_fir_coef.c and ../lib_mic_array/src/etc/stage2_fir_coef.c provide an example of how the outputs -of ``stage1.py`` and ``stage2.py`` may be used. +of ``stage1.py`` and ``stage2.py`` may be used. .. note:: If the stage 2 decimation factor or tap count changes `../lib_mic_array/api/etc/filters_default.h` must also be updated to reflect that change. diff --git a/script/filter_design/README.rst b/python/filter_design/README.rst similarity index 97% rename from script/filter_design/README.rst rename to python/filter_design/README.rst index 122d3512..393a9bff 100644 --- a/script/filter_design/README.rst +++ b/python/filter_design/README.rst @@ -1,3 +1,5 @@ +:orphan: + ======================== PDM to PCM Filter Design ======================== @@ -27,7 +29,7 @@ Functions to design 2 and 3 stage decimation filters can be found in ``design_filters.py``. This also contains several example designs: * ``good_2_stage_filter``: decimation from 3.072 MHz to 16 kHz using 2 stages. -* ``small_2_stage_filter``: as above, but using fewer filter taps in stage 2. +* ``small_2_stage_filter``: as above, but using fewer filter taps in stage 2. This saves memory, at the cost of reduced alias suppression and early passband rolloff. * ``good_3_stage_filter``: similar performance to ``good_2_stage_filter``, but @@ -39,11 +41,11 @@ Each example design returns coefficients in a packed format of returned as either float or int. If ``int_coeffs=True``, stage 1 will be int16 and subsequent stages will be int32. -Calling ``python ./script/filter_design/design_filter.py`` will generate a -``.pkl`` file for each example. These can be run though script/stage1.py to +Calling ``python ./python/filter_design/design_filter.py`` will generate a +``.pkl`` file for each example. These can be run though python/stage1.py to convert the coefficients to hexadecimal values for use in ``lib_mic_array/src/etc/stage1_fir_coef.c``. More details on this process are -in ``script/README.rst`` +in ``python/README.rst`` Plotting utilities diff --git a/python/filter_design/__init__.py b/python/filter_design/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/script/filter_design/design_filter.py b/python/filter_design/design_filter.py similarity index 99% rename from script/filter_design/design_filter.py rename to python/filter_design/design_filter.py index 2e8e2cfa..3a78f33b 100644 --- a/script/filter_design/design_filter.py +++ b/python/filter_design/design_filter.py @@ -1,4 +1,4 @@ -# Copyright 2023 XMOS LIMITED. +# Copyright 2023-2024 XMOS LIMITED. # This Software is subject to the terms of the XMOS Public Licence: Version 1. import numpy as np diff --git a/script/filter_design/filter_tools.py b/python/filter_design/filter_tools.py similarity index 99% rename from script/filter_design/filter_tools.py rename to python/filter_design/filter_tools.py index 58396887..a48050f4 100644 --- a/script/filter_design/filter_tools.py +++ b/python/filter_design/filter_tools.py @@ -1,4 +1,4 @@ -# Copyright 2023 XMOS LIMITED. +# Copyright 2023-2024 XMOS LIMITED. # This Software is subject to the terms of the XMOS Public Licence: Version 1. import pickle diff --git a/script/filter_design/plot_coeffs.py b/python/filter_design/plot_coeffs.py similarity index 99% rename from script/filter_design/plot_coeffs.py rename to python/filter_design/plot_coeffs.py index 2473aa0d..5f01e9a9 100644 --- a/script/filter_design/plot_coeffs.py +++ b/python/filter_design/plot_coeffs.py @@ -1,4 +1,4 @@ -# Copyright 2023 XMOS LIMITED. +# Copyright 2023-2024 XMOS LIMITED. # This Software is subject to the terms of the XMOS Public Licence: Version 1. from pathlib import Path diff --git a/script/mic_array/__init__.py b/python/mic_array/__init__.py similarity index 68% rename from script/mic_array/__init__.py rename to python/mic_array/__init__.py index 4f4da1ea..4cd36f39 100644 --- a/script/mic_array/__init__.py +++ b/python/mic_array/__init__.py @@ -1,3 +1,3 @@ -# Copyright 2022 XMOS LIMITED. +# Copyright 2022-2024 XMOS LIMITED. # This Software is subject to the terms of the XMOS Public Licence: Version 1. diff --git a/script/mic_array/device_context.py b/python/mic_array/device_context.py similarity index 100% rename from script/mic_array/device_context.py rename to python/mic_array/device_context.py diff --git a/script/mic_array/filters.py b/python/mic_array/filters.py similarity index 100% rename from script/mic_array/filters.py rename to python/mic_array/filters.py diff --git a/script/mic_array/pdm_signal.py b/python/mic_array/pdm_signal.py similarity index 100% rename from script/mic_array/pdm_signal.py rename to python/mic_array/pdm_signal.py diff --git a/script/mic_array/util.py b/python/mic_array/util.py similarity index 100% rename from script/mic_array/util.py rename to python/mic_array/util.py diff --git a/script/mic_array/xscope.py b/python/mic_array/xscope.py similarity index 99% rename from script/mic_array/xscope.py rename to python/mic_array/xscope.py index 31edbd3d..a80008a6 100644 --- a/script/mic_array/xscope.py +++ b/python/mic_array/xscope.py @@ -1,4 +1,4 @@ -# Copyright 2022 XMOS LIMITED. +# Copyright 2022-2024 XMOS LIMITED. # This Software is subject to the terms of the XMOS Public Licence: Version 1. import os, ctypes, platform, sys, time, queue diff --git a/python/setup.py b/python/setup.py new file mode 100644 index 00000000..0314ae1a --- /dev/null +++ b/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=[ + ], +) diff --git a/script/stage1.py b/python/stage1.py similarity index 100% rename from script/stage1.py rename to python/stage1.py diff --git a/script/stage2.py b/python/stage2.py similarity index 100% rename from script/stage2.py rename to python/stage2.py diff --git a/settings.yml b/settings.yml index a4a42da3..d9f7cf5d 100644 --- a/settings.yml +++ b/settings.yml @@ -1,20 +1,21 @@ +# This file relates to internal XMOS infrastructure and should be ignored by external users --- lib_name: lib_mic_array project: '{{lib_name}}' -title: '{{lib_name}}: PDM Microphone Arrays' -version: 5.4.0 +title: '{{lib_name}}: PDM microphone array library' +version: 5.5.0 documentation: exclude_patterns_path: doc/exclude_patterns.inc substitutions_path: doc/substitutions.inc - root_doc: doc/programming_guide/index.rst + root_doc: doc/rst/lib_mic_array.rst linkcheck_ignore_regex: [''] cognidox_part_number: XM-010267-UG doxygen_projects: lib_mic_array: doxyfile_path: doc/Doxyfile.inc pdfs: - doc/programming_guide/index.rst: + doc/rst/lib_mic_array.rst: pdf_title: '{{title}}' pdf_filename: '{{lib_name}}_v{{version}}' README.rst: diff --git a/tests/README.rst b/tests/README.rst index 209e2bda..c7ae1441 100644 --- a/tests/README.rst +++ b/tests/README.rst @@ -1,3 +1,4 @@ +:orphan: tests ===== @@ -24,7 +25,7 @@ respective subsets of test cases. Building tests -------------- -With your CMake project properly configured, to build all test binaries, +With your CMake project properly configured, to build all test binaries, navigate to your CMake build directory and use the following command: :: @@ -39,11 +40,11 @@ Each group of tests is run differently. For the tests associated with the ``tests-build`` CMake target, building the targets is itself the test. It ensures that there are no syntax or other errors -in the C++ class templates defined in the library (because no actual +in the C++ class templates defined in the library (because no actual implementation of the template is generated until an application uses it). -The test cases associated with the ``tests-unit`` CMake target use the Unity -unit test framework. The compiled binaries are stand-alone test applications +The test cases associated with the ``tests-unit`` CMake target use the Unity +unit test framework. The compiled binaries are stand-alone test applications that can be run using ``xrun``. The test cases associated with the ``tests-signal`` CMake target use the @@ -51,4 +52,4 @@ The test cases associated with the ``tests-signal`` CMake target use the .. _building: building/ .. _signal: signal/ -.. _unit: unit/ \ No newline at end of file +.. _unit: unit/ diff --git a/tests/custom_cmake_build/README.rst b/tests/custom_cmake_build/README.rst index 80b62a8c..9ad9e0dd 100644 --- a/tests/custom_cmake_build/README.rst +++ b/tests/custom_cmake_build/README.rst @@ -1,3 +1,4 @@ +:orphan: tests-build =========== @@ -33,4 +34,4 @@ Running Test Apps The generated binaries can be run with ``xrun`` to verify that no run-time exceptions happen during initialization or steady-state operation. .. _vanilla: vanilla/ -.. _prefab: prefab/ \ No newline at end of file +.. _prefab: prefab/ diff --git a/cmake/CPM.cmake b/tests/custom_cmake_build/cmake/CPM.cmake similarity index 100% rename from cmake/CPM.cmake rename to tests/custom_cmake_build/cmake/CPM.cmake diff --git a/tests/custom_cmake_build/prefab/README.rst b/tests/custom_cmake_build/prefab/README.rst index fce5316c..5b2849e0 100644 --- a/tests/custom_cmake_build/prefab/README.rst +++ b/tests/custom_cmake_build/prefab/README.rst @@ -1,3 +1,4 @@ +:orphan: tests-build-prefab ================== @@ -34,4 +35,4 @@ of the following parameters and values: * Mic Count: 1, 2 * Frame Size: 1, 16, 256 -* DC Offset Elimination: disabled, enabled \ No newline at end of file +* DC Offset Elimination: disabled, enabled diff --git a/tests/custom_cmake_build/vanilla/README.rst b/tests/custom_cmake_build/vanilla/README.rst index 35608e6b..5c1feb7e 100644 --- a/tests/custom_cmake_build/vanilla/README.rst +++ b/tests/custom_cmake_build/vanilla/README.rst @@ -1,3 +1,4 @@ +:orphan: tests-build-vanilla =================== @@ -19,7 +20,7 @@ parameters, a separate target with different preprocessor defintions is generated for each test configuration. A custom target, called `tests-build-vanilla`, is defined which builds each -generated test target. +generated test target. To build, (with your CMake project properly configured) navigate to your CMake build directory and use the following command: @@ -38,4 +39,4 @@ each of the following parameters and values: * Mic Count: 1, 2 * Frame Size: 1, 16, 256 * PDM Freq: 3.072 MHz, 6.144 MHz -* DC Offset Elimination: disabled, enabled \ No newline at end of file +* DC Offset Elimination: disabled, enabled diff --git a/requirements.txt b/tests/requirements.txt similarity index 50% rename from requirements.txt rename to tests/requirements.txt index 01f87671..786054e7 100644 --- a/requirements.txt +++ b/tests/requirements.txt @@ -2,6 +2,8 @@ pytest==8.3.2 pytest-xdist==3.6.1 -numpy==2.0.1 -scipy==1.14.0 -matplotlib==3.9.0 +numpy==2.1.1 +scipy==1.14.1 +matplotlib==3.9.2 + +-e ../python diff --git a/tests/signal/BasicMicArray/README.rst b/tests/signal/BasicMicArray/README.rst index 34b86e49..7580701f 100644 --- a/tests/signal/BasicMicArray/README.rst +++ b/tests/signal/BasicMicArray/README.rst @@ -1,4 +1,6 @@ +:orphan: + tests-signal-BasicMicArray ========================== @@ -37,5 +39,5 @@ the path to the test script as the only necessary argument. For example, to run :: - pytest ..\tests\signal\BasicMicArray\test_mic_array.py + pytest ..\tests\signal\BasicMicArray\test_mic_array.py diff --git a/tests/signal/BasicMicArray/conftest.py b/tests/signal/BasicMicArray/conftest.py index 07b81753..4747dd53 100644 --- a/tests/signal/BasicMicArray/conftest.py +++ b/tests/signal/BasicMicArray/conftest.py @@ -1,8 +1,7 @@ # Copyright 2022-2024 XMOS LIMITED. # This Software is subject to the terms of the XMOS Public Licence: Version 1. - -import sys, os, pytest, enum -sys.path.append(os.path.join(os.path.dirname(__file__), '..', '..','..',"script")) + +import enum FLAGS = [ @@ -23,4 +22,4 @@ def pytest_addoption(parser): class DevCommand(enum.Enum): RESUME = 0 TERMINATE = 1 - PRINT_FILTERS = 2 \ No newline at end of file + PRINT_FILTERS = 2 diff --git a/tests/signal/FilterDesign/conftest.py b/tests/signal/FilterDesign/conftest.py index 33e505d3..420518de 100644 --- a/tests/signal/FilterDesign/conftest.py +++ b/tests/signal/FilterDesign/conftest.py @@ -1,4 +1,4 @@ -# Copyright 2023 XMOS LIMITED. +# Copyright 2023-2024 XMOS LIMITED. # This Software is subject to the terms of the XMOS Public Licence: Version 1. import pytest diff --git a/tests/signal/FilterDesign/test_filter_design.py b/tests/signal/FilterDesign/test_filter_design.py index 11738e59..b4411e27 100644 --- a/tests/signal/FilterDesign/test_filter_design.py +++ b/tests/signal/FilterDesign/test_filter_design.py @@ -1,13 +1,8 @@ -# Copyright 2023 XMOS LIMITED. +# Copyright 2023-2024 XMOS LIMITED. # This Software is subject to the terms of the XMOS Public Licence: Version 1. -import os -import sys - -sys.path.append(os.path.join(os.path.dirname(__file__), '../../..')) - -import script.filter_design.plot_coeffs as pc -import script.filter_design.design_filter as df +import filter_design.plot_coeffs as pc +import filter_design.design_filter as df def test_design_filter(): diff --git a/tests/signal/README.rst b/tests/signal/README.rst index 989f8a31..806f2fd0 100644 --- a/tests/signal/README.rst +++ b/tests/signal/README.rst @@ -1,3 +1,4 @@ +:orphan: tests-signal ============ @@ -41,9 +42,9 @@ the TwoStageDecimator stage2 tests: :: - pytest ..\tests\signal\TwoStageDecimator\test_stage2.py + pytest ..\tests\signal\TwoStageDecimator\test_stage2.py .. _BasicMicArray: BasicMicArray/ -.. _TwoStageDecimator: TwoStageDecimator/ \ No newline at end of file +.. _TwoStageDecimator: TwoStageDecimator/ diff --git a/tests/signal/TwoStageDecimator/README.rst b/tests/signal/TwoStageDecimator/README.rst index f8c3c796..e35520e1 100644 --- a/tests/signal/TwoStageDecimator/README.rst +++ b/tests/signal/TwoStageDecimator/README.rst @@ -1,8 +1,9 @@ +:orphan: tests-signal-TwoStageDecimator ============================== -Tests in this directory ensure that the signal processing performed by the +Tests in this directory ensure that the signal processing performed by the ``TwoStageDecimator`` class template behaves as expected. Each of these scripts are run using ``pytest``, which will launch the @@ -37,5 +38,5 @@ the TwoStageDecimator stage2 tests: :: - pytest ..\tests\signal\TwoStageDecimator\test_stage2.py + pytest ..\tests\signal\TwoStageDecimator\test_stage2.py diff --git a/tests/signal/TwoStageDecimator/conftest.py b/tests/signal/TwoStageDecimator/conftest.py index c66b14c4..92db6b3f 100644 --- a/tests/signal/TwoStageDecimator/conftest.py +++ b/tests/signal/TwoStageDecimator/conftest.py @@ -1,8 +1,8 @@ # Copyright 2022-2024 XMOS LIMITED. # This Software is subject to the terms of the XMOS Public Licence: Version 1. - + import sys, os, pytest -sys.path.append(os.path.join(os.path.dirname(__file__), '..', '..','..',"script")) +sys.path.append(os.path.join(os.path.dirname(__file__), '..', '..','..',"python")) def pytest_addoption(parser): parser.addoption("--build-dir", action="store", default='.') diff --git a/tests/signal/TwoStageDecimator/src/main.xc b/tests/signal/TwoStageDecimator/src/main.xc index 26f620a7..635dbf88 100644 --- a/tests/signal/TwoStageDecimator/src/main.xc +++ b/tests/signal/TwoStageDecimator/src/main.xc @@ -1,4 +1,4 @@ -// Copyright 2020-2022 XMOS LIMITED. +// Copyright 2020-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #include diff --git a/tests/signal/TwoStageDecimator/src/run.cpp b/tests/signal/TwoStageDecimator/src/run.cpp index ecc7c8f7..01f67e12 100644 --- a/tests/signal/TwoStageDecimator/src/run.cpp +++ b/tests/signal/TwoStageDecimator/src/run.cpp @@ -1,4 +1,4 @@ -// Copyright 2020-2022 XMOS LIMITED. +// Copyright 2020-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #include diff --git a/tests/unit/README.rst b/tests/unit/README.rst index bf7f3cf1..435e6ac7 100644 --- a/tests/unit/README.rst +++ b/tests/unit/README.rst @@ -1,3 +1,4 @@ +:orphan: tests-unit ========== diff --git a/tests/unit/src/test_ChannelFrameTransmitter.cpp b/tests/unit/src/test_ChannelFrameTransmitter.cpp index 37cfdf68..cdfd1c8d 100644 --- a/tests/unit/src/test_ChannelFrameTransmitter.cpp +++ b/tests/unit/src/test_ChannelFrameTransmitter.cpp @@ -1,4 +1,4 @@ -// Copyright 2020-2022 XMOS LIMITED. +// Copyright 2020-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #include diff --git a/tests/unit/src/test_FrameOutputHandler.cpp b/tests/unit/src/test_FrameOutputHandler.cpp index b414effb..641ae2ae 100644 --- a/tests/unit/src/test_FrameOutputHandler.cpp +++ b/tests/unit/src/test_FrameOutputHandler.cpp @@ -1,4 +1,4 @@ -// Copyright 2020-2022 XMOS LIMITED. +// Copyright 2020-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #include diff --git a/tests/unit/src/test_dcoe_state_init.cpp b/tests/unit/src/test_dcoe_state_init.cpp index 0d3eb3a6..0e76d073 100644 --- a/tests/unit/src/test_dcoe_state_init.cpp +++ b/tests/unit/src/test_dcoe_state_init.cpp @@ -1,4 +1,4 @@ -// Copyright 2020-2022 XMOS LIMITED. +// Copyright 2020-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #include diff --git a/tests/unit/src/test_deinterleave16.c b/tests/unit/src/test_deinterleave16.c index 331ba980..50908843 100644 --- a/tests/unit/src/test_deinterleave16.c +++ b/tests/unit/src/test_deinterleave16.c @@ -1,4 +1,4 @@ -// Copyright 2020-2023 XMOS LIMITED. +// Copyright 2020-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #include diff --git a/tests/unit/src/test_deinterleave2.c b/tests/unit/src/test_deinterleave2.c index 78068c0a..6a95e36a 100644 --- a/tests/unit/src/test_deinterleave2.c +++ b/tests/unit/src/test_deinterleave2.c @@ -1,4 +1,4 @@ -// Copyright 2020-2022 XMOS LIMITED. +// Copyright 2020-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #include diff --git a/tests/unit/src/test_deinterleave4.c b/tests/unit/src/test_deinterleave4.c index 32c8be2a..cab97844 100644 --- a/tests/unit/src/test_deinterleave4.c +++ b/tests/unit/src/test_deinterleave4.c @@ -1,4 +1,4 @@ -// Copyright 2020-2022 XMOS LIMITED. +// Copyright 2020-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #include diff --git a/tests/unit/src/test_deinterleave8.c b/tests/unit/src/test_deinterleave8.c index 889b9630..6677ea65 100644 --- a/tests/unit/src/test_deinterleave8.c +++ b/tests/unit/src/test_deinterleave8.c @@ -1,4 +1,4 @@ -// Copyright 2020-2022 XMOS LIMITED. +// Copyright 2020-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #include diff --git a/tests/unit/src/test_deinterleave_pdm_samples.cpp b/tests/unit/src/test_deinterleave_pdm_samples.cpp index 27a2f6a7..06fe6dc9 100644 --- a/tests/unit/src/test_deinterleave_pdm_samples.cpp +++ b/tests/unit/src/test_deinterleave_pdm_samples.cpp @@ -1,4 +1,4 @@ -// Copyright 2020-2022 XMOS LIMITED. +// Copyright 2020-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #include diff --git a/tests/unit/src/test_ma_frame_tx_rx.cpp b/tests/unit/src/test_ma_frame_tx_rx.cpp index f5f1d158..3851d7fe 100644 --- a/tests/unit/src/test_ma_frame_tx_rx.cpp +++ b/tests/unit/src/test_ma_frame_tx_rx.cpp @@ -1,4 +1,4 @@ -// Copyright 2020-2022 XMOS LIMITED. +// Copyright 2020-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #include diff --git a/tests/unit/src/test_ma_frame_tx_rx_transpose.cpp b/tests/unit/src/test_ma_frame_tx_rx_transpose.cpp index 06d49ac1..a313e4fb 100644 --- a/tests/unit/src/test_ma_frame_tx_rx_transpose.cpp +++ b/tests/unit/src/test_ma_frame_tx_rx_transpose.cpp @@ -1,4 +1,4 @@ -// Copyright 2020-2022 XMOS LIMITED. +// Copyright 2020-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #include diff --git a/tests/unit/src/unity_config.h b/tests/unit/src/unity_config.h index a1108b52..02dd0d2e 100644 --- a/tests/unit/src/unity_config.h +++ b/tests/unit/src/unity_config.h @@ -1,4 +1,4 @@ -// Copyright 2020-2022 XMOS LIMITED. +// Copyright 2020-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #pragma once