From 4c9c8530507973aab86dd6cf13c3be5e4cd93833 Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Mon, 28 Oct 2024 14:05:47 +0000 Subject: [PATCH 01/27] v5.5.0 release prep --- CHANGELOG.rst | 7 +++++++ README.rst | 2 +- lib_mic_array/lib_build_info.cmake | 8 ++++---- lib_mic_array/module_build_info | 8 ++++---- settings.yml | 2 +- 5 files changed, 17 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 5d993c2e..e155e245 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,6 +1,13 @@ lib_mic_array change log ======================== +5.5.0 +----- + + * Changes to dependencies: + + - lib_xcore_math: 2.3.0 -> 2.4.0 + 5.4.0 ----- diff --git a/README.rst b/README.rst index 9888ed8e..242add41 100644 --- a/README.rst +++ b/README.rst @@ -6,7 +6,7 @@ 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 :category: General Purpose 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/settings.yml b/settings.yml index a4a42da3..dcc30878 100644 --- a/settings.yml +++ b/settings.yml @@ -2,7 +2,7 @@ lib_name: lib_mic_array project: '{{lib_name}}' title: '{{lib_name}}: PDM Microphone Arrays' -version: 5.4.0 +version: 5.5.0 documentation: exclude_patterns_path: doc/exclude_patterns.inc From d033f073ff9b109ce51d9a8d35b847fc8a986eb5 Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Mon, 28 Oct 2024 14:40:26 +0000 Subject: [PATCH 02/27] Moved requirements.txt to tests --- Jenkinsfile | 27 ++++++++++------------ requirements.txt => tests/requirements.txt | 0 2 files changed, 12 insertions(+), 15 deletions(-) rename requirements.txt => tests/requirements.txt (100%) diff --git a/Jenkinsfile b/Jenkinsfile index 20bfdedb..d5322d75 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -7,7 +7,7 @@ pipeline { REPO = 'lib_mic_array' PIP_VERSION = "24.0" PYTHON_VERSION = "3.11" - XMOSDOC_VERSION = "v6.1.2" + XMOSDOC_VERSION = "v6.1.2" } options { skipDefaultCheckout() @@ -80,7 +80,7 @@ pipeline { } stage('Custom CMake build') { agent { - label "x86_64 && linux" + label "x86_64 && linux" } steps { sh "git clone git@github.com:xmos/xmos_cmake_toolchain.git --branch v1.0.0" @@ -112,13 +112,10 @@ pipeline { // 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' - } + withTools(params.TOOLS_VERSION) { + dir("examples") { + sh 'cmake -B build -G "Unix Makefiles"' + sh 'xmake -j 16 -C build' } } archiveArtifacts artifacts: "**/*.xe", allowEmptyArchive: true @@ -150,10 +147,10 @@ pipeline { println "RUNNING ON" println env.NODE_NAME checkout scm - createVenv(reqFile: "requirements.txt") - withVenv { - withTools(params.TOOLS_VERSION) { - dir("tests") { + dir("tests") { + createVenv(reqFile: "requirements.txt") + withVenv { + withTools(params.TOOLS_VERSION) { sh 'cmake -B build -G "Unix Makefiles"' sh 'xmake -j 8 -C build' } @@ -172,12 +169,12 @@ pipeline { // 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") { diff --git a/requirements.txt b/tests/requirements.txt similarity index 100% rename from requirements.txt rename to tests/requirements.txt From 798017a17915b76a593b830a2fc90c5fe1e14b12 Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Mon, 28 Oct 2024 14:43:23 +0000 Subject: [PATCH 03/27] deleted top level index.rst --- index.rst | 9 --------- 1 file changed, 9 deletions(-) delete mode 100644 index.rst 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 From 42798ce66c1da329c59b053ea1f46ad57e6e1ee3 Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Mon, 28 Oct 2024 14:49:43 +0000 Subject: [PATCH 04/27] Call buildDocs() in Jenkinsfile and rename programming_guide/index.rst to rst/lib_mic_array.rst --- Jenkinsfile | 19 +++++++----------- .../index.rst => rst/lib_mic_array.rst} | 0 .../src/32k_freq_response.png | Bin .../src/48k_freq_response.png | Bin .../src/dcoe_freq_response.png | Bin .../src/decimator_stages.rst | 0 .../src/diagrams/decimator_stages.drawio | 0 .../src/diagrams/decimator_stages.drawio.png | Bin .../src/diagrams/high_level_process.drawio | 0 .../diagrams/high_level_process.drawio.png | Bin .../src/getting_started.rst | 0 .../src/introduction.rst | 0 .../src/mic_array_diagrams.drawio | 0 .../src/overview.rst | 0 .../src/reference/api_index.rst | 0 .../src/reference/c/c_api.rst | 0 .../src/reference/c/dc_elimination.rst | 0 .../src/reference/c/filters_default.rst | 0 .../src/reference/c/frame_transfer.rst | 0 .../src/reference/c/mic_array_vanilla.rst | 0 .../src/reference/c/pdm_resources.rst | 0 .../src/reference/c/setup.rst | 0 .../src/reference/c/util.rst | 0 .../src/reference/cpp/cpp_api.rst | 0 .../src/resource_usage.rst | 0 .../src/sample_filters.rst | 0 .../src/software_structure.rst | 0 .../src/stage1_freq_response.png | Bin .../src/stage2_freq_response.png | Bin .../src/vanilla_api.rst | 0 settings.yml | 4 ++-- 31 files changed, 9 insertions(+), 14 deletions(-) rename doc/{programming_guide/index.rst => rst/lib_mic_array.rst} (100%) rename doc/{programming_guide => rst}/src/32k_freq_response.png (100%) rename doc/{programming_guide => rst}/src/48k_freq_response.png (100%) rename doc/{programming_guide => rst}/src/dcoe_freq_response.png (100%) rename doc/{programming_guide => rst}/src/decimator_stages.rst (100%) rename doc/{programming_guide => rst}/src/diagrams/decimator_stages.drawio (100%) rename doc/{programming_guide => rst}/src/diagrams/decimator_stages.drawio.png (100%) rename doc/{programming_guide => rst}/src/diagrams/high_level_process.drawio (100%) rename doc/{programming_guide => rst}/src/diagrams/high_level_process.drawio.png (100%) rename doc/{programming_guide => rst}/src/getting_started.rst (100%) rename doc/{programming_guide => rst}/src/introduction.rst (100%) rename doc/{programming_guide => rst}/src/mic_array_diagrams.drawio (100%) rename doc/{programming_guide => rst}/src/overview.rst (100%) rename doc/{programming_guide => rst}/src/reference/api_index.rst (100%) rename doc/{programming_guide => rst}/src/reference/c/c_api.rst (100%) rename doc/{programming_guide => rst}/src/reference/c/dc_elimination.rst (100%) rename doc/{programming_guide => rst}/src/reference/c/filters_default.rst (100%) rename doc/{programming_guide => rst}/src/reference/c/frame_transfer.rst (100%) rename doc/{programming_guide => rst}/src/reference/c/mic_array_vanilla.rst (100%) rename doc/{programming_guide => rst}/src/reference/c/pdm_resources.rst (100%) rename doc/{programming_guide => rst}/src/reference/c/setup.rst (100%) rename doc/{programming_guide => rst}/src/reference/c/util.rst (100%) rename doc/{programming_guide => rst}/src/reference/cpp/cpp_api.rst (100%) rename doc/{programming_guide => rst}/src/resource_usage.rst (100%) rename doc/{programming_guide => rst}/src/sample_filters.rst (100%) rename doc/{programming_guide => rst}/src/software_structure.rst (100%) rename doc/{programming_guide => rst}/src/stage1_freq_response.png (100%) rename doc/{programming_guide => rst}/src/stage2_freq_response.png (100%) rename doc/{programming_guide => rst}/src/vanilla_api.rst (100%) diff --git a/Jenkinsfile b/Jenkinsfile index d5322d75..e5144853 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -7,7 +7,6 @@ pipeline { REPO = 'lib_mic_array' PIP_VERSION = "24.0" PYTHON_VERSION = "3.11" - XMOSDOC_VERSION = "v6.1.2" } options { skipDefaultCheckout() @@ -24,28 +23,24 @@ pipeline { defaultValue: '15.3.0', description: 'The XTC tools version' ) + string( + name: 'XMOSDOC_VERSION', + defaultValue: 'v6.1.2', + description: 'The xmosdoc version' + ) } stages { stage('Build and Docs') { parallel { stage('Documentation') { agent { - label "docker" + label "documentatation" } 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""" - - // 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" + buildDocs() } } } diff --git a/doc/programming_guide/index.rst b/doc/rst/lib_mic_array.rst similarity index 100% rename from doc/programming_guide/index.rst rename to doc/rst/lib_mic_array.rst 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 100% rename from doc/programming_guide/src/decimator_stages.rst rename to doc/rst/src/decimator_stages.rst 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 100% rename from doc/programming_guide/src/getting_started.rst rename to doc/rst/src/getting_started.rst diff --git a/doc/programming_guide/src/introduction.rst b/doc/rst/src/introduction.rst similarity index 100% rename from doc/programming_guide/src/introduction.rst rename to doc/rst/src/introduction.rst 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 100% rename from doc/programming_guide/src/overview.rst rename to doc/rst/src/overview.rst diff --git a/doc/programming_guide/src/reference/api_index.rst b/doc/rst/src/reference/api_index.rst similarity index 100% rename from doc/programming_guide/src/reference/api_index.rst rename to doc/rst/src/reference/api_index.rst diff --git a/doc/programming_guide/src/reference/c/c_api.rst b/doc/rst/src/reference/c/c_api.rst similarity index 100% rename from doc/programming_guide/src/reference/c/c_api.rst rename to doc/rst/src/reference/c/c_api.rst diff --git a/doc/programming_guide/src/reference/c/dc_elimination.rst b/doc/rst/src/reference/c/dc_elimination.rst similarity index 100% rename from doc/programming_guide/src/reference/c/dc_elimination.rst rename to doc/rst/src/reference/c/dc_elimination.rst diff --git a/doc/programming_guide/src/reference/c/filters_default.rst b/doc/rst/src/reference/c/filters_default.rst similarity index 100% rename from doc/programming_guide/src/reference/c/filters_default.rst rename to doc/rst/src/reference/c/filters_default.rst diff --git a/doc/programming_guide/src/reference/c/frame_transfer.rst b/doc/rst/src/reference/c/frame_transfer.rst similarity index 100% rename from doc/programming_guide/src/reference/c/frame_transfer.rst rename to doc/rst/src/reference/c/frame_transfer.rst 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 100% rename from doc/programming_guide/src/reference/c/mic_array_vanilla.rst rename to doc/rst/src/reference/c/mic_array_vanilla.rst diff --git a/doc/programming_guide/src/reference/c/pdm_resources.rst b/doc/rst/src/reference/c/pdm_resources.rst similarity index 100% rename from doc/programming_guide/src/reference/c/pdm_resources.rst rename to doc/rst/src/reference/c/pdm_resources.rst diff --git a/doc/programming_guide/src/reference/c/setup.rst b/doc/rst/src/reference/c/setup.rst similarity index 100% rename from doc/programming_guide/src/reference/c/setup.rst rename to doc/rst/src/reference/c/setup.rst diff --git a/doc/programming_guide/src/reference/c/util.rst b/doc/rst/src/reference/c/util.rst similarity index 100% rename from doc/programming_guide/src/reference/c/util.rst rename to doc/rst/src/reference/c/util.rst diff --git a/doc/programming_guide/src/reference/cpp/cpp_api.rst b/doc/rst/src/reference/cpp/cpp_api.rst similarity index 100% rename from doc/programming_guide/src/reference/cpp/cpp_api.rst rename to doc/rst/src/reference/cpp/cpp_api.rst diff --git a/doc/programming_guide/src/resource_usage.rst b/doc/rst/src/resource_usage.rst similarity index 100% rename from doc/programming_guide/src/resource_usage.rst rename to doc/rst/src/resource_usage.rst diff --git a/doc/programming_guide/src/sample_filters.rst b/doc/rst/src/sample_filters.rst similarity index 100% rename from doc/programming_guide/src/sample_filters.rst rename to doc/rst/src/sample_filters.rst diff --git a/doc/programming_guide/src/software_structure.rst b/doc/rst/src/software_structure.rst similarity index 100% rename from doc/programming_guide/src/software_structure.rst rename to doc/rst/src/software_structure.rst 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 100% rename from doc/programming_guide/src/vanilla_api.rst rename to doc/rst/src/vanilla_api.rst diff --git a/settings.yml b/settings.yml index dcc30878..a586e9fc 100644 --- a/settings.yml +++ b/settings.yml @@ -7,14 +7,14 @@ 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: From 88aac1a669f46069235e24ceb16613d3356fb667 Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Mon, 28 Oct 2024 14:59:52 +0000 Subject: [PATCH 05/27] Fixed settings.yml and README format --- Jenkinsfile | 2 +- README.rst | 22 ++++++++++++++-------- settings.yml | 3 ++- 3 files changed, 17 insertions(+), 10 deletions(-) diff --git a/Jenkinsfile b/Jenkinsfile index e5144853..b711ea5c 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -34,7 +34,7 @@ pipeline { parallel { stage('Documentation') { agent { - label "documentatation" + label "documentation" } steps { dir("${REPO}") { diff --git a/README.rst b/README.rst index 242add41..ef88f20f 100644 --- a/README.rst +++ b/README.rst @@ -13,9 +13,9 @@ lib_mic_array: PDM Microphone Array Library :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,27 +42,33 @@ 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: diff --git a/settings.yml b/settings.yml index a586e9fc..da91e188 100644 --- a/settings.yml +++ b/settings.yml @@ -1,7 +1,8 @@ +# 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' +title: '{{lib_name}}: PDM Mic Array library for the XMOS XS3 architecture' version: 5.5.0 documentation: From 4e8fca601c3dad46307158eb443068c922e3e195 Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Mon, 28 Oct 2024 15:01:58 +0000 Subject: [PATCH 06/27] Removed .github/ISSUE_TEMPLATE --- .../application-note-not-compliant.md | 17 ----------------- .../ISSUE_TEMPLATE/example-not-compliant.md | 18 ------------------ .../ISSUE_TEMPLATE/missing-application-note.md | 10 ---------- .github/ISSUE_TEMPLATE/missing-c-api.md | 10 ---------- .github/ISSUE_TEMPLATE/missing-xcore-test.md | 10 ---------- .github/ISSUE_TEMPLATE/test-not-compliant.md | 16 ---------------- .../top-level-readme-not-compliant.md | 13 ------------- 7 files changed, 94 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/application-note-not-compliant.md delete mode 100644 .github/ISSUE_TEMPLATE/example-not-compliant.md delete mode 100644 .github/ISSUE_TEMPLATE/missing-application-note.md delete mode 100644 .github/ISSUE_TEMPLATE/missing-c-api.md delete mode 100644 .github/ISSUE_TEMPLATE/missing-xcore-test.md delete mode 100644 .github/ISSUE_TEMPLATE/test-not-compliant.md delete mode 100644 .github/ISSUE_TEMPLATE/top-level-readme-not-compliant.md 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 From b6e8bbe2a77d5414e137722652cc235fdd616c6c Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Mon, 28 Oct 2024 15:11:32 +0000 Subject: [PATCH 07/27] Get README building. --- doc/README.rst | 63 --------------------- doc/exclude_patterns.inc | 1 - script/README.rst | 4 +- script/filter_design/README.rst | 4 +- tests/README.rst | 11 ++-- tests/custom_cmake_build/README.rst | 3 +- tests/custom_cmake_build/prefab/README.rst | 3 +- tests/custom_cmake_build/vanilla/README.rst | 5 +- tests/signal/BasicMicArray/README.rst | 4 +- tests/signal/README.rst | 5 +- tests/signal/TwoStageDecimator/README.rst | 5 +- tests/unit/README.rst | 1 + 12 files changed, 28 insertions(+), 81 deletions(-) delete mode 100644 doc/README.rst 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/script/README.rst b/script/README.rst index feb12d94..7ee27e1a 100644 --- a/script/README.rst +++ b/script/README.rst @@ -1,4 +1,4 @@ - +:orphan: Scripts @@ -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/script/filter_design/README.rst index 122d3512..8fe53765 100644 --- a/script/filter_design/README.rst +++ b/script/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 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/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/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/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/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 ========== From 0be1d9ac52e94782ac134de5842ac0193e3de4bd Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Mon, 28 Oct 2024 15:19:38 +0000 Subject: [PATCH 08/27] Parametrise INFR_APPS_VERSION --- Jenkinsfile | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/Jenkinsfile b/Jenkinsfile index b711ea5c..787388a7 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -28,6 +28,11 @@ pipeline { 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') { @@ -120,7 +125,7 @@ pipeline { stage("Lib checks") { steps { warnError("lib checks") { - runLibraryChecks("${WORKSPACE}/${REPO}", "v2.0.1") + runLibraryChecks("${WORKSPACE}/${REPO}", "${params.INFR_APPS_VERSION}") } } } From 322b5fb446e9b9624309e5da86e0b2003caa74d7 Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Mon, 28 Oct 2024 15:59:29 +0000 Subject: [PATCH 09/27] Renamed script/ to python/. Added setup.py --- {script => python}/.gitignore | 0 {script => python}/README.rst | 0 {script => python}/filter_design/README.rst | 0 python/filter_design/__init__.py | 0 .../filter_design/design_filter.py | 0 .../filter_design/filter_tools.py | 0 .../filter_design/plot_coeffs.py | 0 {script => python}/mic_array/__init__.py | 0 .../mic_array/device_context.py | 0 {script => python}/mic_array/filters.py | 0 {script => python}/mic_array/pdm_signal.py | 0 {script => python}/mic_array/util.py | 0 {script => python}/mic_array/xscope.py | 0 python/setup.py | 22 +++++++++++++++++++ {script => python}/stage1.py | 0 {script => python}/stage2.py | 0 tests/requirements.txt | 8 ++++--- tests/signal/BasicMicArray/conftest.py | 7 +++--- .../signal/FilterDesign/test_filter_design.py | 9 ++------ tests/signal/TwoStageDecimator/conftest.py | 4 ++-- 20 files changed, 34 insertions(+), 16 deletions(-) rename {script => python}/.gitignore (100%) rename {script => python}/README.rst (100%) rename {script => python}/filter_design/README.rst (100%) create mode 100644 python/filter_design/__init__.py rename {script => python}/filter_design/design_filter.py (100%) rename {script => python}/filter_design/filter_tools.py (100%) rename {script => python}/filter_design/plot_coeffs.py (100%) rename {script => python}/mic_array/__init__.py (100%) rename {script => python}/mic_array/device_context.py (100%) rename {script => python}/mic_array/filters.py (100%) rename {script => python}/mic_array/pdm_signal.py (100%) rename {script => python}/mic_array/util.py (100%) rename {script => python}/mic_array/xscope.py (100%) create mode 100644 python/setup.py rename {script => python}/stage1.py (100%) rename {script => python}/stage2.py (100%) 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 100% rename from script/README.rst rename to python/README.rst diff --git a/script/filter_design/README.rst b/python/filter_design/README.rst similarity index 100% rename from script/filter_design/README.rst rename to python/filter_design/README.rst 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 100% rename from script/filter_design/design_filter.py rename to python/filter_design/design_filter.py diff --git a/script/filter_design/filter_tools.py b/python/filter_design/filter_tools.py similarity index 100% rename from script/filter_design/filter_tools.py rename to python/filter_design/filter_tools.py diff --git a/script/filter_design/plot_coeffs.py b/python/filter_design/plot_coeffs.py similarity index 100% rename from script/filter_design/plot_coeffs.py rename to python/filter_design/plot_coeffs.py diff --git a/script/mic_array/__init__.py b/python/mic_array/__init__.py similarity index 100% rename from script/mic_array/__init__.py rename to python/mic_array/__init__.py 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 100% rename from script/mic_array/xscope.py rename to python/mic_array/xscope.py 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/tests/requirements.txt b/tests/requirements.txt index 01f87671..786054e7 100644 --- a/tests/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/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/test_filter_design.py b/tests/signal/FilterDesign/test_filter_design.py index 11738e59..77e55e5d 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. # 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/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='.') From 3c2c504d7ea7a85059fd949f9ba83ba05346fe73 Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Mon, 28 Oct 2024 16:00:28 +0000 Subject: [PATCH 10/27] Replaced references to script/ to python/ in the documentation --- doc/rst/src/decimator_stages.rst | 32 ++++++++++++++++---------------- python/README.rst | 4 ++-- python/filter_design/README.rst | 6 +++--- 3 files changed, 21 insertions(+), 21 deletions(-) diff --git a/doc/rst/src/decimator_stages.rst b/doc/rst/src/decimator_stages.rst index 8cf2e16a..043184c4 100644 --- a/doc/rst/src/decimator_stages.rst +++ b/doc/rst/src/decimator_stages.rst @@ -49,7 +49,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 @@ -94,7 +94,7 @@ 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:: @@ -105,8 +105,8 @@ 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) @@ -119,7 +119,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 @@ -208,21 +208,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 +257,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. @@ -270,8 +270,8 @@ 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 +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. .. image:: 32k_freq_response.png @@ -279,8 +279,8 @@ overall combined response provides a nice flat passband. 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 +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. .. image:: 48k_freq_response.png diff --git a/python/README.rst b/python/README.rst index 7ee27e1a..139a5592 100644 --- a/python/README.rst +++ b/python/README.rst @@ -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 diff --git a/python/filter_design/README.rst b/python/filter_design/README.rst index 8fe53765..393a9bff 100644 --- a/python/filter_design/README.rst +++ b/python/filter_design/README.rst @@ -41,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 From fe343e81f511f343597e25bf15e721962042c9cd Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Mon, 28 Oct 2024 16:04:35 +0000 Subject: [PATCH 11/27] source check --- python/filter_design/design_filter.py | 2 +- python/filter_design/filter_tools.py | 2 +- python/filter_design/plot_coeffs.py | 2 +- python/mic_array/__init__.py | 2 +- python/mic_array/xscope.py | 2 +- tests/signal/FilterDesign/test_filter_design.py | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/python/filter_design/design_filter.py b/python/filter_design/design_filter.py index 2e8e2cfa..3a78f33b 100644 --- a/python/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/python/filter_design/filter_tools.py b/python/filter_design/filter_tools.py index 58396887..a48050f4 100644 --- a/python/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/python/filter_design/plot_coeffs.py b/python/filter_design/plot_coeffs.py index 2473aa0d..5f01e9a9 100644 --- a/python/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/python/mic_array/__init__.py b/python/mic_array/__init__.py index 4f4da1ea..4cd36f39 100644 --- a/python/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/python/mic_array/xscope.py b/python/mic_array/xscope.py index 31edbd3d..a80008a6 100644 --- a/python/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/tests/signal/FilterDesign/test_filter_design.py b/tests/signal/FilterDesign/test_filter_design.py index 77e55e5d..b4411e27 100644 --- a/tests/signal/FilterDesign/test_filter_design.py +++ b/tests/signal/FilterDesign/test_filter_design.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 filter_design.plot_coeffs as pc From 45eb06c0bed24263f2889ce3180ebde8d4ecc4ff Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Tue, 29 Oct 2024 09:28:40 +0000 Subject: [PATCH 12/27] Move cmake/CPM.cmake from top level to tests/custom_cmake_build/ --- CMakeLists.txt | 6 +++--- {cmake => tests/custom_cmake_build/cmake}/CPM.cmake | 0 2 files changed, 3 insertions(+), 3 deletions(-) rename {cmake => tests/custom_cmake_build/cmake}/CPM.cmake (100%) 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/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 From f42ca6356c16ce823f6cd026052b11cebf42db28 Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Tue, 29 Oct 2024 09:40:50 +0000 Subject: [PATCH 13/27] Rename examples to app --- examples/CMakeLists.txt | 8 ++++---- .../{measure_mips => app_measure_mips}/CMakeLists.txt | 0 examples/{demo => app_measure_mips}/XVF3610_Q60A.xn | 0 examples/{measure_mips => app_measure_mips}/src/app.cpp | 0 examples/{measure_mips => app_measure_mips}/src/app.h | 0 .../{measure_mips => app_measure_mips}/src/app_config.h | 0 examples/{demo => app_measure_mips}/src/config.xscope | 0 examples/{measure_mips => app_measure_mips}/src/main.xc | 0 examples/{demo => app_mic_array}/CMakeLists.txt | 0 examples/{demo_vanilla => app_mic_array}/XVF3610_Q60A.xn | 0 examples/{demo => app_mic_array}/src/app.cpp | 0 examples/{demo => app_mic_array}/src/app.h | 0 examples/{demo => app_mic_array}/src/app_config.h | 0 examples/{demo => app_mic_array}/src/app_i2s.c | 0 .../{demo_vanilla => app_mic_array}/src/config.xscope | 0 examples/{demo => app_mic_array}/src/main.xc | 0 .../CMakeLists.txt | 0 .../{demo_par_decimator => app_par_decimator}/src/app.cpp | 0 .../{demo_par_decimator => app_par_decimator}/src/app.h | 0 .../src/app_config.h | 0 .../src/app_decimator.hpp | 0 .../src/app_i2s.c | 0 .../src/app_mic_array.hpp | 0 .../src/app_mic_dataline_selector.c | 0 .../src/decimator_subtask.c | 0 .../src/decimator_subtask.h | 0 .../{demo_par_decimator => app_par_decimator}/src/main.xc | 0 examples/{demo_vanilla => app_vanilla}/CMakeLists.txt | 0 examples/{measure_mips => app_vanilla}/XVF3610_Q60A.xn | 0 examples/{demo_vanilla => app_vanilla}/src/app.h | 0 examples/{demo_vanilla => app_vanilla}/src/app_config.h | 0 examples/{demo_vanilla => app_vanilla}/src/app_i2s.c | 0 examples/{measure_mips => app_vanilla}/src/config.xscope | 0 examples/{demo_vanilla => app_vanilla}/src/main.xc | 0 34 files changed, 4 insertions(+), 4 deletions(-) rename examples/{measure_mips => app_measure_mips}/CMakeLists.txt (100%) rename examples/{demo => app_measure_mips}/XVF3610_Q60A.xn (100%) rename examples/{measure_mips => app_measure_mips}/src/app.cpp (100%) rename examples/{measure_mips => app_measure_mips}/src/app.h (100%) rename examples/{measure_mips => app_measure_mips}/src/app_config.h (100%) rename examples/{demo => app_measure_mips}/src/config.xscope (100%) rename examples/{measure_mips => app_measure_mips}/src/main.xc (100%) rename examples/{demo => app_mic_array}/CMakeLists.txt (100%) rename examples/{demo_vanilla => app_mic_array}/XVF3610_Q60A.xn (100%) rename examples/{demo => app_mic_array}/src/app.cpp (100%) rename examples/{demo => app_mic_array}/src/app.h (100%) rename examples/{demo => app_mic_array}/src/app_config.h (100%) rename examples/{demo => app_mic_array}/src/app_i2s.c (100%) rename examples/{demo_vanilla => app_mic_array}/src/config.xscope (100%) rename examples/{demo => app_mic_array}/src/main.xc (100%) rename examples/{demo_par_decimator => app_par_decimator}/CMakeLists.txt (100%) rename examples/{demo_par_decimator => app_par_decimator}/src/app.cpp (100%) rename examples/{demo_par_decimator => app_par_decimator}/src/app.h (100%) rename examples/{demo_par_decimator => app_par_decimator}/src/app_config.h (100%) rename examples/{demo_par_decimator => app_par_decimator}/src/app_decimator.hpp (100%) rename examples/{demo_par_decimator => app_par_decimator}/src/app_i2s.c (100%) rename examples/{demo_par_decimator => app_par_decimator}/src/app_mic_array.hpp (100%) rename examples/{demo_par_decimator => app_par_decimator}/src/app_mic_dataline_selector.c (100%) rename examples/{demo_par_decimator => app_par_decimator}/src/decimator_subtask.c (100%) rename examples/{demo_par_decimator => app_par_decimator}/src/decimator_subtask.h (100%) rename examples/{demo_par_decimator => app_par_decimator}/src/main.xc (100%) rename examples/{demo_vanilla => app_vanilla}/CMakeLists.txt (100%) rename examples/{measure_mips => app_vanilla}/XVF3610_Q60A.xn (100%) rename examples/{demo_vanilla => app_vanilla}/src/app.h (100%) rename examples/{demo_vanilla => app_vanilla}/src/app_config.h (100%) rename examples/{demo_vanilla => app_vanilla}/src/app_i2s.c (100%) rename examples/{measure_mips => app_vanilla}/src/config.xscope (100%) rename examples/{demo_vanilla => app_vanilla}/src/main.xc (100%) 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 From c89052c6c949311ac4aa3b19a3e0565e7717bd1c Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Tue, 29 Oct 2024 09:59:32 +0000 Subject: [PATCH 14/27] Fix headings --- doc/rst/lib_mic_array.rst | 7 ++- doc/rst/src/decimator_stages.rst | 29 +++++----- doc/rst/src/getting_started.rst | 45 +++++++-------- doc/rst/src/introduction.rst | 5 +- doc/rst/src/overview.rst | 34 ++++++------ doc/rst/src/resource_usage.rst | 27 ++++----- doc/rst/src/sample_filters.rst | 47 ++++++++-------- doc/rst/src/software_structure.rst | 89 +++++++++++++++--------------- doc/rst/src/vanilla_api.rst | 43 ++++++++------- 9 files changed, 167 insertions(+), 159 deletions(-) diff --git a/doc/rst/lib_mic_array.rst b/doc/rst/lib_mic_array.rst index 50902389..5c6402d7 100644 --- a/doc/rst/lib_mic_array.rst +++ b/doc/rst/lib_mic_array.rst @@ -1,10 +1,11 @@ .. lib_mic_array documentation master file -Mic Array Library -================= +############# +lib_mic_array +############# .. toctree:: - :maxdepth: 1 + :maxdepth: 2 :caption: Contents: src/introduction diff --git a/doc/rst/src/decimator_stages.rst b/doc/rst/src/decimator_stages.rst index 043184c4..05e5f1f5 100644 --- a/doc/rst/src/decimator_stages.rst +++ b/doc/rst/src/decimator_stages.rst @@ -1,7 +1,8 @@ .. _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 @@ -23,7 +24,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 +33,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 @@ -71,14 +72,14 @@ 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. @@ -87,7 +88,7 @@ decimation filter. 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 @@ -103,14 +104,14 @@ The script can be found in this repository at ``python/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 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 @@ -128,7 +129,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,7 +138,7 @@ 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. @@ -146,7 +147,7 @@ decimation filter. 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 +174,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. @@ -268,7 +269,7 @@ 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 @@ -277,7 +278,7 @@ overall combined response provides a nice flat passband. .. image:: 32k_freq_response.png 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 diff --git a/doc/rst/src/getting_started.rst b/doc/rst/src/getting_started.rst index d91f4ee8..c49b9f8b 100644 --- a/doc/rst/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/rst/src/introduction.rst b/doc/rst/src/introduction.rst index aa575f6f..8ec605f2 100644 --- a/doc/rst/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/rst/src/overview.rst b/doc/rst/src/overview.rst index 9961f6d4..df16757e 100644 --- a/doc/rst/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 @@ -44,7 +44,7 @@ Capabilities \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 @@ -58,7 +58,7 @@ behavior and does not describe any necessary initialization steps. 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 +68,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 +80,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 +90,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 +117,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 +136,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 +155,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 +169,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/rst/src/resource_usage.rst b/doc/rst/src/resource_usage.rst index a926a673..c3124b0e 100644 --- a/doc/rst/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/rst/src/sample_filters.rst b/doc/rst/src/sample_filters.rst index bd9805b3..900a81a6 100644 --- a/doc/rst/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,7 +139,7 @@ and previous output sample values respectively. DCOE Filter Frequency Response -****************************** +------------------------------ The plot below indicates the frequency response of DCOE filter. diff --git a/doc/rst/src/software_structure.rst b/doc/rst/src/software_structure.rst index 934bae93..145fca42 100644 --- a/doc/rst/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,9 +69,9 @@ 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 @@ -83,15 +84,15 @@ The following diagram conceptually captures the flow of information through the .. 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 +102,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 +138,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 +171,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 +200,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 +221,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 +235,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 +255,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 +284,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/rst/src/vanilla_api.rst b/doc/rst/src/vanilla_api.rst index b131f0ce..e0a487b8 100644 --- a/doc/rst/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``. From c3a937bcee5939beff1b32385ad2470cad8d47b0 Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Tue, 29 Oct 2024 10:13:49 +0000 Subject: [PATCH 15/27] fix api section heading --- doc/rst/src/reference/api_index.rst | 4 +- doc/rst/src/reference/c/c_api.rst | 6 +-- doc/rst/src/reference/c/dc_elimination.rst | 2 +- doc/rst/src/reference/c/filters_default.rst | 32 +++++++------- doc/rst/src/reference/c/frame_transfer.rst | 2 +- doc/rst/src/reference/c/mic_array_vanilla.rst | 2 +- doc/rst/src/reference/c/pdm_resources.rst | 6 +-- doc/rst/src/reference/c/setup.rst | 4 +- doc/rst/src/reference/c/util.rst | 10 ++--- doc/rst/src/reference/cpp/cpp_api.rst | 42 +++++++++---------- 10 files changed, 55 insertions(+), 55 deletions(-) diff --git a/doc/rst/src/reference/api_index.rst b/doc/rst/src/reference/api_index.rst index 11936d19..6dceb105 100644 --- a/doc/rst/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/rst/src/reference/c/c_api.rst b/doc/rst/src/reference/c/c_api.rst index 5cdf4c05..aaed1159 100644 --- a/doc/rst/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/rst/src/reference/c/dc_elimination.rst b/doc/rst/src/reference/c/dc_elimination.rst index e7602906..115a1b54 100644 --- a/doc/rst/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/rst/src/reference/c/filters_default.rst b/doc/rst/src/reference/c/filters_default.rst index c8d05da9..f7d73dc9 100644 --- a/doc/rst/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/rst/src/reference/c/frame_transfer.rst b/doc/rst/src/reference/c/frame_transfer.rst index f3e6f971..6da09b29 100644 --- a/doc/rst/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/rst/src/reference/c/mic_array_vanilla.rst b/doc/rst/src/reference/c/mic_array_vanilla.rst index 388e0811..eeab0723 100644 --- a/doc/rst/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/rst/src/reference/c/pdm_resources.rst b/doc/rst/src/reference/c/pdm_resources.rst index 1665f085..26de3431 100644 --- a/doc/rst/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/rst/src/reference/c/setup.rst b/doc/rst/src/reference/c/setup.rst index 839e11f8..9b1d2746 100644 --- a/doc/rst/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/rst/src/reference/c/util.rst b/doc/rst/src/reference/c/util.rst index a7a86c5c..dfc81086 100644 --- a/doc/rst/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/rst/src/reference/cpp/cpp_api.rst b/doc/rst/src/reference/cpp/cpp_api.rst index a9f0f9c8..7833711d 100644 --- a/doc/rst/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 From dcb74712ccd166d93563e6be7e35e05ac91b4b14 Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Tue, 29 Oct 2024 10:32:08 +0000 Subject: [PATCH 16/27] Add reference to figures --- doc/rst/src/decimator_stages.rst | 28 +++++++++++++++++++--------- doc/rst/src/overview.rst | 4 +++- doc/rst/src/sample_filters.rst | 4 +++- doc/rst/src/software_structure.rst | 4 +++- 4 files changed, 28 insertions(+), 12 deletions(-) diff --git a/doc/rst/src/decimator_stages.rst b/doc/rst/src/decimator_stages.rst index 05e5f1f5..d5362b49 100644 --- a/doc/rst/src/decimator_stages.rst +++ b/doc/rst/src/decimator_stages.rst @@ -8,7 +8,9 @@ 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:`simplified model of the mic array unit `. + +.. _decimator_stages_simplified: .. figure:: diagrams/decimator_stages.drawio.png :align: center @@ -81,8 +83,10 @@ 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. +The plot below indicates the :ref:`frequency response of the provided first stage +decimation filter `. + +.. _first_stage_decimation_filter: .. image:: stage1_freq_response.png @@ -140,8 +144,10 @@ 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. +The plot below indicates the :ref:`frequency response of the provided second stage +decimation filter `. + +.. _second_stage_decimation_filter: .. image:: stage2_freq_response.png @@ -269,20 +275,24 @@ 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. +overall combined response provides a nice flat passband as shown in the :ref:`figure `. + +.. _freq_response_32k: .. image:: 32k_freq_response.png 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. +overall combined response provides a nice flat passband as shown :ref:`here `. + +.. _freq_response_48k: .. image:: 48k_freq_response.png diff --git a/doc/rst/src/overview.rst b/doc/rst/src/overview.rst index df16757e..519eb51a 100644 --- a/doc/rst/src/overview.rst +++ b/doc/rst/src/overview.rst @@ -48,8 +48,10 @@ 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:`below `. +.. _high_level_process: .. figure:: diagrams/high_level_process.drawio.png :align: center diff --git a/doc/rst/src/sample_filters.rst b/doc/rst/src/sample_filters.rst index 900a81a6..582a0370 100644 --- a/doc/rst/src/sample_filters.rst +++ b/doc/rst/src/sample_filters.rst @@ -141,6 +141,8 @@ and previous output sample values respectively. DCOE Filter Frequency Response ------------------------------ -The plot below indicates the frequency response of DCOE filter. +The plot below indicates the :ref:`frequency response of DCOE filter `. + +.. _freq_response_dcoe: .. image:: dcoe_freq_response.png diff --git a/doc/rst/src/software_structure.rst b/doc/rst/src/software_structure.rst index 145fca42..09477c65 100644 --- a/doc/rst/src/software_structure.rst +++ b/doc/rst/src/software_structure.rst @@ -74,9 +74,11 @@ interface. 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 :ref:`diagram ` 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 % From 861669e9991b7ec897aec56e0e465f61d572f302 Mon Sep 17 00:00:00 2001 From: xmos-xmos Date: Tue, 29 Oct 2024 10:53:55 +0000 Subject: [PATCH 17/27] Fix image reference --- doc/rst/src/decimator_stages.rst | 5 +++-- doc/rst/src/overview.rst | 10 +++++----- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/doc/rst/src/decimator_stages.rst b/doc/rst/src/decimator_stages.rst index d5362b49..5a81d6b8 100644 --- a/doc/rst/src/decimator_stages.rst +++ b/doc/rst/src/decimator_stages.rst @@ -8,14 +8,15 @@ 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 :ref:`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``) diff --git a/doc/rst/src/overview.rst b/doc/rst/src/overview.rst index 519eb51a..a8c352be 100644 --- a/doc/rst/src/overview.rst +++ b/doc/rst/src/overview.rst @@ -39,9 +39,8 @@ Capabilities * Most configurations require only a single hardware thread -.. raw:: latex - \newpage +|newpage| High-Level Process View ======================= @@ -49,14 +48,15 @@ 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. The high level -process view is depicted in the figure :ref:`below `. +process view is depicted in the figure :ref:`image_high_level_process`. -.. _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 From e25741da81bfb9bb21e37b65b74d207edda0443c Mon Sep 17 00:00:00 2001 From: xmos-xmos Date: Tue, 29 Oct 2024 11:05:49 +0000 Subject: [PATCH 18/27] Fix image reference --- doc/rst/src/decimator_stages.rst | 36 +++++++++++++++++++++--------- doc/rst/src/sample_filters.rst | 8 +++++-- doc/rst/src/software_structure.rst | 5 +++-- 3 files changed, 35 insertions(+), 14 deletions(-) diff --git a/doc/rst/src/decimator_stages.rst b/doc/rst/src/decimator_stages.rst index 5a81d6b8..d8c5d442 100644 --- a/doc/rst/src/decimator_stages.rst +++ b/doc/rst/src/decimator_stages.rst @@ -84,12 +84,16 @@ header ``mic_array/etc/filters_default.h`` as ``stage1_coef``. Filter Characteristics (Stage 1) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The plot below indicates the :ref:`frequency response of the provided first stage -decimation filter `. +The plot below indicates the frequency response of the provided first stage +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 @@ -145,12 +149,16 @@ For the provided filter ``S2_TAP_COUNT = 65``, and ``S2_DEC_FACTOR = 6``. Filter Characteristics (Stage 2) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The plot below indicates the :ref:`frequency response of the provided second stage -decimation filter `. +The plot below indicates the frequency response of the provided second stage +decimation filter :ref:`second_stage_decimation_filter`. .. _second_stage_decimation_filter: -.. image:: stage2_freq_response.png +.. figure:: stage2_freq_response.png + :align: center + :scale: 100 % + + Second stage decimation filter freq response Custom Filters @@ -280,20 +288,28 @@ 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 as shown in the :ref:`figure `. +overall combined response provides a nice flat passband as shown in the :ref:`freq_response_32k`. .. _freq_response_32k: -.. image:: 32k_freq_response.png +.. 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 as shown :ref:`here `. +overall combined response provides a nice flat passband as shown :ref:`freq_response_48k`. .. _freq_response_48k: -.. image:: 48k_freq_response.png +.. figure:: 48k_freq_response.png + :align: center + :scale: 100 % + + good_48k_filter_int.pkl frequency response diff --git a/doc/rst/src/sample_filters.rst b/doc/rst/src/sample_filters.rst index 582a0370..db6d90b4 100644 --- a/doc/rst/src/sample_filters.rst +++ b/doc/rst/src/sample_filters.rst @@ -141,8 +141,12 @@ and previous output sample values respectively. DCOE Filter Frequency Response ------------------------------ -The plot below indicates the :ref:`frequency response of DCOE filter `. +The plot below indicates the frequency response of DCOE filter :ref:`freq_response_dcoe`. .. _freq_response_dcoe: -.. image:: dcoe_freq_response.png +.. figure:: dcoe_freq_response.png + :align: center + :scale: 100 % + + DCOE filter frequency response diff --git a/doc/rst/src/software_structure.rst b/doc/rst/src/software_structure.rst index 09477c65..4b7709fd 100644 --- a/doc/rst/src/software_structure.rst +++ b/doc/rst/src/software_structure.rst @@ -74,7 +74,7 @@ interface. the contract is enforced (at compile time) solely in how the ``MicArray`` object makes use of the sub-component. -The following :ref:`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: @@ -82,7 +82,8 @@ The following :ref:`diagram ` conceptually captures the flow of .. figure:: diagrams/high_level_process.drawio.png :align: center :scale: 100 % - :alt: Mic Array High Level Process + + Mic Array High Level Process .. note:: From d3a2bdf42f33a40e3a4a584037e8f8ad93057e0c Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Tue, 29 Oct 2024 11:42:01 +0000 Subject: [PATCH 19/27] Fix Jenkinsfile indentation --- Jenkinsfile | 389 +++++++++++++++++++++++++++------------------------- 1 file changed, 200 insertions(+), 189 deletions(-) diff --git a/Jenkinsfile b/Jenkinsfile index 787388a7..d4dd02c3 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -1,205 +1,216 @@ @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 +} + getApproval() pipeline { - agent none + agent none - 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 scm - buildDocs() - } - } - } - 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 scm + buildDocs() + } + } + } + post { + cleanup { + xcoreCleanSandbox() + } + } + } + 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" } - 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 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('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 scm + 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('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 - 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}", "${params.INFR_APPS_VERSION}") - } - } - } - } - 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 scm + 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 - 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('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" + // 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" - } + // 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() - } + // 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 From 4e66af73a1db8e4fcf5b336f9f8a4d6189eaecfa Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Tue, 29 Oct 2024 11:58:26 +0000 Subject: [PATCH 20/27] checkout shallow --- Jenkinsfile | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/Jenkinsfile b/Jenkinsfile index d4dd02c3..b4993e53 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -5,6 +5,16 @@ def archiveLib(String repoName) { 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 @@ -50,7 +60,7 @@ pipeline { steps { dir("${REPO}") { warnError("Docs") { - checkout scm + checkout_shallow() buildDocs() } } @@ -67,7 +77,7 @@ pipeline { } steps { dir("${REPO}") { - checkout scm + checkout_shallow() dir("tests") { withTools(params.TOOLS_VERSION) { sh 'cmake -B build -G "Unix Makefiles"' @@ -91,7 +101,7 @@ pipeline { steps { sh "git clone git@github.com:xmos/xmos_cmake_toolchain.git --branch v1.0.0" dir("${REPO}") { - checkout scm + 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" @@ -117,7 +127,7 @@ pipeline { sh "git clone --branch v1.3.0 git@github.com:xmos/infr_scripts_py" // clone dir("${REPO}") { - checkout scm + checkout_shallow() withTools(params.TOOLS_VERSION) { dir("examples") { sh 'cmake -B build -G "Unix Makefiles"' @@ -157,7 +167,7 @@ pipeline { dir("${REPO}") { println "RUNNING ON" println env.NODE_NAME - checkout scm + checkout_shallow() dir("tests") { createVenv(reqFile: "requirements.txt") withVenv { From ce0faac3af99e9bb425a64f9d45e4210c29c1b4a Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Tue, 29 Oct 2024 12:11:49 +0000 Subject: [PATCH 21/27] Add -DDEPS_CLONE_SHALLOW=TRUE to example build --- Jenkinsfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Jenkinsfile b/Jenkinsfile index b4993e53..97ca1447 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -130,7 +130,7 @@ pipeline { checkout_shallow() withTools(params.TOOLS_VERSION) { dir("examples") { - sh 'cmake -B build -G "Unix Makefiles"' + sh 'cmake -B build -G "Unix Makefiles" -DDEPS_CLONE_SHALLOW=TRUE' sh 'xmake -j 16 -C build' } } From 0128b1de4d946009eddb5d5a1dec7e6f7cf5088d Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Tue, 29 Oct 2024 13:31:54 +0000 Subject: [PATCH 22/27] copyright check --- etc/vanilla/mic_array_vanilla.h | 2 +- lib_mic_array/api/mic_array/api.h | 2 +- lib_mic_array/api/mic_array/cpp/PdmRx.hpp | 2 +- lib_mic_array/api/mic_array/cpp/Util.hpp | 2 +- lib_mic_array/api/mic_array/etc/fir_1x16_bit.h | 2 +- lib_mic_array/api/mic_array/etc/xcore_compat.h | 2 +- lib_mic_array/api/mic_array/frame_transfer.h | 2 +- lib_mic_array/api/mic_array/pdm_resources.h | 2 +- lib_mic_array/src/deinterleave16.S | 2 +- lib_mic_array/src/deinterleave2.S | 2 +- lib_mic_array/src/deinterleave4.S | 2 +- lib_mic_array/src/deinterleave8.S | 2 +- lib_mic_array/src/frame_transfer.c | 2 +- lib_mic_array/src/pdm_rx_isr.S | 2 +- tests/signal/FilterDesign/conftest.py | 2 +- tests/signal/TwoStageDecimator/src/main.xc | 2 +- tests/signal/TwoStageDecimator/src/run.cpp | 2 +- tests/unit/src/test_ChannelFrameTransmitter.cpp | 2 +- tests/unit/src/test_FrameOutputHandler.cpp | 2 +- tests/unit/src/test_dcoe_state_init.cpp | 2 +- tests/unit/src/test_deinterleave16.c | 2 +- tests/unit/src/test_deinterleave2.c | 2 +- tests/unit/src/test_deinterleave4.c | 2 +- tests/unit/src/test_deinterleave8.c | 2 +- tests/unit/src/test_deinterleave_pdm_samples.cpp | 2 +- tests/unit/src/test_ma_frame_tx_rx.cpp | 2 +- tests/unit/src/test_ma_frame_tx_rx_transpose.cpp | 2 +- tests/unit/src/unity_config.h | 2 +- 28 files changed, 28 insertions(+), 28 deletions(-) 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/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/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/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/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/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 From 25c245225754ae45d6b13eeda520fcb2f3e48e05 Mon Sep 17 00:00:00 2001 From: Ross Owen Date: Tue, 29 Oct 2024 15:21:54 +0000 Subject: [PATCH 23/27] Update Doxyfile.inc Fixes to Doxyfile --- doc/Doxyfile.inc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 From 7c094599767afe5d57b4e79a604b2a1085594078 Mon Sep 17 00:00:00 2001 From: Ross Owen Date: Tue, 29 Oct 2024 15:23:10 +0000 Subject: [PATCH 24/27] Update README.rst Tidy readme --- README.rst | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/README.rst b/README.rst index ef88f20f..1b15fa65 100644 --- a/README.rst +++ b/README.rst @@ -2,13 +2,13 @@ :orphan: ########################################### -lib_mic_array: PDM Microphone Array Library +lib_mic_array: PDM microphone array library ########################################### :vendor: XMOS :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 @@ -75,12 +75,6 @@ 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 ******* From 1a0823b29dc0a16bdfba2e29cef21c8e419fdf41 Mon Sep 17 00:00:00 2001 From: shuchitak <38428600+shuchitak@users.noreply.github.com> Date: Tue, 29 Oct 2024 16:57:08 +0000 Subject: [PATCH 25/27] Update doc/rst/lib_mic_array.rst Co-authored-by: Ross Owen --- doc/rst/lib_mic_array.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/rst/lib_mic_array.rst b/doc/rst/lib_mic_array.rst index 5c6402d7..8be9b5a2 100644 --- a/doc/rst/lib_mic_array.rst +++ b/doc/rst/lib_mic_array.rst @@ -1,7 +1,7 @@ .. lib_mic_array documentation master file ############# -lib_mic_array +lib_mic_array: PDM microphone array library ############# .. toctree:: From 5cbf1b7e3fc019b8e77c5a2b3e22e271f03975a9 Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Tue, 29 Oct 2024 17:00:40 +0000 Subject: [PATCH 26/27] Fix title in settings.yml --- settings.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/settings.yml b/settings.yml index da91e188..d9f7cf5d 100644 --- a/settings.yml +++ b/settings.yml @@ -2,7 +2,7 @@ --- lib_name: lib_mic_array project: '{{lib_name}}' -title: '{{lib_name}}: PDM Mic Array library for the XMOS XS3 architecture' +title: '{{lib_name}}: PDM microphone array library' version: 5.5.0 documentation: From f2fc8bf8582d34e5c2d9195f5f0032a79b0e2a68 Mon Sep 17 00:00:00 2001 From: Shuchita Khare Date: Tue, 29 Oct 2024 17:06:09 +0000 Subject: [PATCH 27/27] Changelog --- CHANGELOG.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index e155e245..f8b6df03 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -4,6 +4,10 @@ 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