Merge pull request #397 from xmos/release/v0.6.0

Release v0.6.0

.github/workflows/docs.yml

@@ -32,7 +32,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Voice Framework
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
 
       - name: Pull doc_builder container
         run: |
@@ -43,9 +43,9 @@ jobs:
           docker run --rm -t -u "$(id -u):$(id -g)" -v ${{ github.workspace }}:/build -e REPO:/build -e DOXYGEN_INCLUDE=/build/doc/Doxyfile.inc -e EXCLUDE_PATTERNS=/build/doc/exclude_patterns.inc -e DOXYGEN_INPUT=ignore -e PDF=1 ghcr.io/xmos/doc_builder:main
       
       - name: Save documentation artifacts
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v3
         with:
           name: fwk_voice_docs
-          path: ./doc/_build/html
+          path: ./doc/_build
           if-no-files-found: error # 'warn' or 'ignore' are also available, defaults to `warn` 
           retention-days: 5

.gitignore

@@ -4,6 +4,7 @@
 # Build cruft
 **/build*/
 **/_build*/
+**/_templates*/
 **/bin*/
 **/dist*/
 **/fatfs_mkimage

CHANGELOG.rst

@@ -1,9 +1,16 @@
 XMOS Voice Framework Change Log
 ===============================
 
+0.6.0
+-----
+
+  * CHANGED: Improved documentation style
+  * CHANGED: Replace lib_xs3_math with the lib_xcore_math v2.1.1
+  * CHANGED: Integrate new version of lib_tflite_micro in VNR module
+
 0.5.1
 -----
-  
+
   * ADDED: Windows documentation
   * REMOVED: VAD module
   * CHANGED: Git hash at which lib_tflite_micro is fetched during CMake FetchContent

Jenkinsfile

@@ -1,4 +1,4 @@
-@Library('xmos_jenkins_shared_library@v0.19.0') _
+@Library('xmos_jenkins_shared_library@v0.20.0') _
 getApproval()
 
 pipeline {
@@ -59,10 +59,10 @@ pipeline {
                 withVenv {
                   script {
                       if (env.FULL_TEST == "1") {
-                        sh 'cmake -S.. -DCMAKE_TOOLCHAIN_FILE=../xmos_cmake_toolchain/xs3a.cmake -DPython3_VIRTUALENV_FIND="ONLY" -DFWK_VOICE_BUILD_TESTS=ON'
+                        sh 'cmake -S.. -DCMAKE_TOOLCHAIN_FILE=../xmos_cmake_toolchain/xs3a.cmake -DPython3_VIRTUALENV_FIND="ONLY" -DFWK_VOICE_BUILD_TESTS=ON -DFETCHCONTENT_UPDATES_DISCONNECTED=ON'
                       }
                       else {
-                        sh 'cmake -S.. -DCMAKE_TOOLCHAIN_FILE=../xmos_cmake_toolchain/xs3a.cmake -DPython3_VIRTUALENV_FIND="ONLY" -DTEST_SPEEDUP_FACTOR=4 -DFWK_VOICE_BUILD_TESTS=ON'
+                        sh 'cmake -S.. -DCMAKE_TOOLCHAIN_FILE=../xmos_cmake_toolchain/xs3a.cmake -DPython3_VIRTUALENV_FIND="ONLY" -DTEST_SPEEDUP_FACTOR=4 -DFWK_VOICE_BUILD_TESTS=ON -DFETCHCONTENT_UPDATES_DISCONNECTED=ON'
                       }
                   }
                   sh "make -j8"
@@ -114,7 +114,7 @@ pipeline {
               viewEnv() {
                 withVenv {
                   sh "cmake --version"
-                  sh 'cmake -S.. -DPython3_FIND_VIRTUALENV="ONLY" -DTEST_WAV_ADEC_BUILD_CONFIG="1 2 2 10 5" -DFWK_VOICE_BUILD_TESTS=ON'
+                  sh 'cmake -S.. -DPython3_FIND_VIRTUALENV="ONLY" -DTEST_WAV_ADEC_BUILD_CONFIG="1 2 2 10 5" -DFWK_VOICE_BUILD_TESTS=ON -DFETCHCONTENT_UPDATES_DISCONNECTED=ON'
                   sh "make -j8"
 
                   // We need to put this here because it is not fetched until we build
@@ -422,8 +422,7 @@ pipeline {
                 withVenv {
                   withMounts([["projects", "projects/hydra_audio", "hydra_audio_stage_b_tests"]]) {
                     withEnv(["hydra_audio_PATH=$hydra_audio_stage_b_tests_PATH"]) {
-                      sh "pytest -s --junitxml=pytest_result.xml"
-                      junit "pytest_result.xml"
+                      sh "pytest -n1"
                     }
                   }
                 }

doc/getting_started/index.rst

@@ -0,0 +1,95 @@
+###########
+QUICK START
+###########
+
+Requirements
+------------
+
+* XTC Tools 15.0.6 or higher
+* CMake 3.20 or higher
+* Python 3.7 or higher
+
+
+Building
+--------
+
+The following instructions show how to build the Voice Framework and run one of the example applications. This
+procedure is currently supported on MacOS, Linux and Windows.
+
+#. Enter the clone of the Voice Framework and initialise submodules
+
+   .. code-block:: console
+
+     cd fwk_voice
+     git submodule update --init --recursive
+
+#. Create a build directory
+
+   .. code-block:: console
+
+     mkdir build
+     cd build
+
+#. Run cmake to setup the build environment for the XMOS toolchain
+
+   - On Linux and Mac
+
+      .. code-block:: console
+
+        cmake -S.. -DCMAKE_TOOLCHAIN_FILE=../xmos_cmake_toolchain/xs3a.cmake
+
+   - On Windows
+
+      .. code-block:: console
+
+
+        # make sure you have the patch command available
+        cmake -G "NMake Makefiles" -S.. -DCMAKE_TOOLCHAIN_FILE=../xmos_cmake_toolchain/xs3a.cmake
+
+   As part of the cmake, some dependencies are fetched using CMake FetchContent. One of these dependencies, lib_tflite_micro has a patch applied to it as part of the FetchContent. This means, when trying to rerun the cmake in the same build directory, sometimes errors
+   related to not being able to apply a patch to an already patched library are seen. To get rid of these errors, add the -DFETCHCONTENT_UPDATES_DISCONNECTED=ON option to the cmake command line, which will disable the FetchContent if the content has been downloaded previously.
+
+#. Running make will then build the Voice Framework libraries and example applications
+
+   - On Linux and Mac
+
+      .. code-block:: console
+
+         make fwk_voice_example_bare_metal_aec_1_thread
+
+   - On Windows
+
+      .. code-block:: console
+
+         nmake fwk_voice_example_bare_metal_aec_1_thread
+
+#. Install dependencies
+
+   - On Linux and Mac
+
+      .. code-block:: console
+
+         pip install -e build/fwk_voice_deps/xscope_fileio/
+
+   - On Windows
+
+      .. code-block:: console
+
+         pip install -e fwk_voice_deps/xscope_fileio
+         cd fwk_voice_deps/xscope_fileio/host
+         cmake -G "NMake Makefiles" .
+         nmake
+         cd ../../../
+
+.. raw:: pdf
+
+   PageBreak oneColumn
+
+6. Run the single-threaded AEC example
+
+   .. code-block:: console
+
+      cd ../examples/bare-metal/aec_1_thread
+      python ../shared_src/python/run_xcoreai.py ../../../build/examples/bare-metal/aec_1_thread/bin/fwk_voice_example_bare_metal_aec_1_thread.xe --input ../shared_src/test_streams/aec_example_input.wav
+
+   See ``Example Applications`` section in the User Guide for full details about the examples.

doc/user_guide/audio_processing/index.rst

@@ -6,21 +6,16 @@ At the core of the Voice Framework are high-performance audio processing algorit
 
 A flexible audio signal routing infrastructure and a range of digital inputs and outputs enables the Voice Framework to be integrated into a wide range of system configurations, that can be configured at start up and during operation through a set of control registers.  In addition, all source code is provided to allow for full customization or the addition of other audio processing algorithms.
 
-AUDIO FEATURES
+**************
+Audio Features
+**************
 
 .. toctree:: 
-   :maxdepth: 1
+   :maxdepth: 3
 
    ../../../modules/lib_aec/doc/index
    ../../../modules/lib_ns/doc/index
    ../../../modules/lib_agc/doc/index
    ../../../modules/lib_adec/doc/index
    ../../../modules/lib_ic/doc/index
    ../../../modules/lib_vnr/doc/index
-
-EXAMPLES
-
-.. toctree:: 
-   :maxdepth: 1
-
-   ../../../examples/bare-metal/doc/index

doc/user_guide/index.rst

@@ -7,6 +7,7 @@ The Voice Framework Design Guide is written for system architects and engineers
 It is expected that this document is read in conjunction with the relevant datasheet and that the user is familiar with basic voice processing terminology.
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 3
 
    audio_processing/index
+   ../../examples/bare-metal/doc/index

examples/bare-metal/aec_1_thread/CMakeLists.txt

@@ -16,7 +16,7 @@ target_include_directories(fwk_voice_example_bare_metal_aec_1_thread
 target_link_libraries(fwk_voice_example_bare_metal_aec_1_thread
     PUBLIC
         fwk_voice::example::aec1thread
-        core::xs3_math
+        lib_xcore_math
         fwk_voice::example::fileutils
 )
 

examples/bare-metal/aec_1_thread/README.rst

@@ -1,6 +1,6 @@
 
 aec_1_thread
-=========================
+============
 
 This example demonstrates how AEC functions are called on a single thread to process data through the AEC stage of a pipeline.
 
@@ -26,6 +26,7 @@ Run the following commands in the fwk_voice/build folder to build the firmware f
 
     .. code-block:: console
 
+        # make sure you have the patch command available
         cmake -G "NMake Makefiles" -S.. -DCMAKE_TOOLCHAIN_FILE=../xmos_cmake_toolchain/xs3a.cmake
         nmake fwk_voice_example_bare_metal_aec_1_thread
 
@@ -54,7 +55,7 @@ From the fwk_voice/build folder run:
         python ../shared_src/python/run_xcoreai.py ../../../build/examples/bare-metal/aec_1_thread/bin/fwk_voice_example_bare_metal_aec_1_thread.xe --input ../shared_src/test_streams/aec_example_input.wav
 
 Output
-------
+******
 
 The output file output.wav is generated in the `fwk_voice/examples/bare-metal/aec_1_thread` directory. The input file
 input.wav is also present in the same directory. View output.wav and input.wav in Audacity to compare the echo cancelled

examples/bare-metal/aec_1_thread/src/main.xc

@@ -11,7 +11,7 @@
 #endif
 
 extern "C" {
-#include "xs3_math.h"
+#include "xmath/xmath.h"
 void aec_task(const char *input_file_name, const char *output_file_name);
 #if TEST_WAV_XSCOPE
     #include "xscope_io_device.h"

examples/bare-metal/aec_2_threads/README.rst

@@ -1,6 +1,6 @@
 
 aec_2_threads
-==========================
+=============
 
 This example demonstrates how AEC functions are called on 2 threads to process data through the AEC stage of a pipeline.
 
@@ -27,6 +27,7 @@ Run the following commands in the fwk_voice/build folder to build the firmware f
 
     .. code-block:: console
 
+        # make sure you have the patch command available
         cmake -G "NMake Makefiles" -S.. -DCMAKE_TOOLCHAIN_FILE=../xmos_cmake_toolchain/xs3a.cmake
         nmake fwk_voice_example_bare_metal_aec_2_thread
 
@@ -55,7 +56,7 @@ From the fwk_voice/build folder run:
         python ../shared_src/python/run_xcoreai.py ../../../build/examples/bare-metal/aec_2_thread/bin/fwk_voice_example_bare_metal_aec_2_thread.xe --input ../shared_src/test_streams/aec_example_input.wav
 
 Output
-------
+******
 
 The output file output.wav is generated in the `fwk_voice/examples/bare-metal/aec_2_threads` directory. The input file
 input.wav is also present in the same directory. View output.wav and input.wav in Audacity to compare the echo cancelled

examples/bare-metal/aec_2_threads/src/main.xc

@@ -11,7 +11,7 @@
 #endif
 
 extern "C" {
-#include "xs3_math.h"
+#include "xmath/xmath.h"
 void aec_task(const char *input_file_name, const char *output_file_name);
 #if TEST_WAV_XSCOPE
     #include "xscope_io_device.h"

examples/bare-metal/agc/CMakeLists.txt

@@ -13,7 +13,7 @@ target_include_directories(fwk_voice_example_bare_metal_agc
 target_link_libraries(fwk_voice_example_bare_metal_agc
     PUBLIC
         fwk_voice::agc
-        core::xs3_math
+        lib_xcore_math
         fwk_voice::example::fileutils)
 
 if(${CMAKE_SYSTEM_NAME} STREQUAL XCORE_XS3A)