Merging version v2.4.0 back to main for release

.gitignore

@@ -29,3 +29,6 @@ tests/vpu_ff3_test/autogen
 tests/vpu_rat_test/autogen
 *.csv
 python/lib_src.egg-info
+**/tmp_models/
+*.bak
+make_docs.sh

CHANGELOG.rst

@@ -1,6 +1,16 @@
 lib_src change log
 ==================
 
+2.4.0
+-----
+
+  * ADDED: Support for building the core ASRC code in the C emulator as a
+    library
+  * ADDED: Auto-generated ASRC and SSRC performance plots in documentation
+  * CHANGED: Documents built under Jenkins instead of Github Actions
+  * ADDED: Documentation warning about overflow in XS3 optimized SRC components
+  * CHANGED: Tested against fwk_core v1.0.2 updated from v1.0.0
+
 2.3.0
 -----
 

CMakeLists.txt

@@ -7,7 +7,7 @@ if(PROJECT_IS_TOP_LEVEL)
     FetchContent_Declare(
       fwk_core
       GIT_REPOSITORY https://github.com/xmos/fwk_core.git
-      GIT_TAG        v1.0.0
+      GIT_TAG        v1.0.2
     )
     FetchContent_MakeAvailable(fwk_core)
 endif()

Jenkinsfile

@@ -17,17 +17,17 @@ def localRunPytest(String extra_args="") {
 getApproval()
 
 pipeline {
-  agent {
-    label 'x86_64&&macOS' // These agents have 24 cores so good for parallel xsim runs
-  }
+  agent none
   environment {
     REPO = 'lib_src'
     VIEW = getViewName(REPO)
     PYTHON_VERSION = "3.10.5"
     VENV_DIRNAME = ".venv"
+    XMOSDOC_VERSION = "v4.0"
   }
   options {
     skipDefaultCheckout()
+    timestamps()
   }
   parameters {
     string(
@@ -37,119 +37,142 @@ pipeline {
     )
   }
   stages {
-    stage('Get repo') {
-      steps {
-        sh "mkdir ${REPO}"
-        // source checks require the directory
-        // name to be the same as the repo name
-        dir("${REPO}") {
-          // checkout repo
-          checkout scm
-          sh 'git submodule update --init --recursive --depth 1'
-        }
+    stage('Build and Test') {
+      when {
+        expression { !env.GH_LABEL_DOC_ONLY.toBoolean() }
       }
-    }
-    stage ("Create Python environment")
-    {
-      steps {
-        dir("${REPO}") {
-          createVenv('requirements.txt')
-          withVenv {
-            sh 'pip install -r requirements.txt'
+      agent {
+        label 'x86_64&&docker' // These agents have 24 cores so good for parallel xsim runs
+      }
+      stages {
+        stage('Get repo') {
+          steps {
+            sh "mkdir ${REPO}"
+            // source checks require the directory
+            // name to be the same as the repo name
+            dir("${REPO}") {
+              // checkout repo
+              checkout scm
+              sh 'git submodule update --init --recursive --depth 1'
+            }
           }
         }
-      }
-    }
-    stage('Library checks') {
-      steps {
-        dir("${REPO}") {
-          sh 'git clone git@github.com:xmos/infr_apps.git'
-          sh 'git clone git@github.com:xmos/infr_scripts_py.git'
-          // These are needed for xmake legacy build and also changelog check
-          sh 'git clone git@github.com:xmos/lib_logging.git'
-          sh 'git clone git@github.com:xmos/lib_xassert.git'
-          withVenv {
-            sh 'pip install -e infr_scripts_py'
-            sh 'pip install -e infr_apps'
-            dir("tests") {
-              withEnv(["XMOS_ROOT=.."]) {
-                localRunPytest('-s test_lib_checks.py -vv')
+        stage ("Create Python environment") {
+          steps {
+            dir("${REPO}") {
+              createVenv('requirements.txt')
+              withVenv {
+                sh 'pip install -r requirements.txt'
               }
             }
           }
         }
-      }
-    }
-    stage('Test xmake build') {
-      steps {
-        runningOn(env.NODE_NAME)
-        dir("${REPO}") {
-          withTools(params.TOOLS_VERSION) {
-            withVenv {
-              dir("tests") {
-                localRunPytest('-k "legacy" -vv')
+        stage('Library checks') {
+          steps {
+            dir("${REPO}") {
+              sh 'git clone git@github.com:xmos/infr_apps.git'
+              sh 'git clone git@github.com:xmos/infr_scripts_py.git'
+              // These are needed for xmake legacy build and also changelog check
+              sh 'git clone git@github.com:xmos/lib_logging.git'
+              sh 'git clone git@github.com:xmos/lib_xassert.git'
+              withVenv {
+                sh 'pip install -e infr_scripts_py'
+                sh 'pip install -e infr_apps'
+                dir("tests") {
+                  withEnv(["XMOS_ROOT=.."]) {
+                    localRunPytest('-s test_lib_checks.py -vv')
+                  }
+                }
               }
             }
           }
         }
-      }
-    }
-    stage('Tests XS2') {
-      steps {
-        runningOn(env.NODE_NAME)
-        dir("${REPO}") {
-          withTools(params.TOOLS_VERSION) {
-            withVenv {
-              sh 'mkdir build'
-              dir("build") {
-                sh 'rm -rf'
-                sh 'cmake --toolchain ../xmos_cmake_toolchain/xs2a.cmake ..'
-                sh 'make test_ds3_voice test_us3_voice test_unity_gain_voice -j'
+        stage('Test xmake build') {
+          steps {
+            runningOn(env.NODE_NAME)
+            dir("${REPO}") {
+              withTools(params.TOOLS_VERSION) {
+                withVenv {
+                  dir("tests") {
+                    localRunPytest('-k "legacy" -vv')
+                  }
+                }
               }
-              dir("tests") {
-                localRunPytest('-n auto -k "xs2" -vv')
+            }
+          }
+        }
+        stage('Run doc python') {
+          steps {
+            runningOn(env.NODE_NAME)
+            dir("${REPO}") {
+              withTools(params.TOOLS_VERSION) {
+                withVenv {
+                  sh "sh doc/build_docs_ci.sh $XMOSDOC_VERSION"
+                  archiveArtifacts artifacts: "doc_build.zip", allowEmptyArchive: true
+                }
               }
-              dir("build") {
-                sh 'rm -rf' // Cleanup XS2 cmake cache for next stage
+            }
+          }
+        }
+        stage('Tests XS2') {
+          steps {
+            runningOn(env.NODE_NAME)
+            dir("${REPO}") {
+              withTools(params.TOOLS_VERSION) {
+                withVenv {
+                  sh 'mkdir -p build'
+                  dir("build") {
+                    sh 'rm CMakeCache.txt'
+                    sh 'cmake --toolchain ../xmos_cmake_toolchain/xs2a.cmake ..'
+                    sh 'make test_ds3_voice test_us3_voice test_unity_gain_voice -j'
+                  }
+                  dir("tests") {
+                    localRunPytest('-n auto -k "xs2" -vv')
+                  }
+                  dir("build") {
+                    sh 'rm CMakeCache.txt' // Cleanup XS2 cmake cache for next stage
+                  }
+                }
               }
             }
           }
         }
-      }
-    }
-    stage('Tests XS3') {
-      steps {
-        runningOn(env.NODE_NAME)
-        dir("${REPO}") {
-          withTools(params.TOOLS_VERSION) {
-            withVenv {
-              dir("tests") {
-                localRunPytest('-m prepare') // Do all pre work like building and generating golden ref where needed
+        stage('Tests XS3') {
+          steps {
+            runningOn(env.NODE_NAME)
+            dir("${REPO}") {
+              withTools(params.TOOLS_VERSION) {
+                withVenv {
+                  dir("tests") {
+                    localRunPytest('-m prepare') // Do all pre work like building and generating golden ref where needed
 
-                // FF3 HiFi tests for OS3 and DS3
-                localRunPytest('-m main -n auto -k "hifi_ff3" -vv')
+                    // FF3 HiFi tests for OS3 and DS3
+                    localRunPytest('-m main -n auto -k "hifi_ff3" -vv')
 
-                // ASRC and SSRC tests across all in/out freqs and deviations (asrc only)
-                localRunPytest('-m main -n auto -k "mrhf" -vv')
-                archiveArtifacts artifacts: "mips_report*.csv", allowEmptyArchive: true
+                    // ASRC and SSRC tests across all in/out freqs and deviations (asrc only)
+                    localRunPytest('-m main -n auto -k "mrhf" -vv')
+                    archiveArtifacts artifacts: "mips_report*.csv", allowEmptyArchive: true
 
-                // VPU enabled ff3 and rat tests
-                localRunPytest('-m main -k "vpu" -vv') // xdist not working yet so no -n auto
+                    // VPU enabled ff3 and rat tests
+                    localRunPytest('-m main -k "vpu" -vv') // xdist not working yet so no -n auto
 
-                // Profile the ASRC
-                localRunPytest('-m main -k "profile_asrc" -vv')
-                sh 'tree'
-                archiveArtifacts artifacts: "gprof_results/*.png", allowEmptyArchive: true
+                    // Profile the ASRC
+                    localRunPytest('-m main -k "profile_asrc" -vv')
+                    sh 'tree'
+                    archiveArtifacts artifacts: "gprof_results/*.png", allowEmptyArchive: true
+                  }
+                }
               }
             }
           }
         }
       }
+      post {
+        cleanup {
+          xcoreCleanSandbox()
+        }
+      }
     }
-  }
-  post {
-    cleanup {
-      xcoreCleanSandbox()
-    }
+
   }
 }

README.rst

@@ -60,6 +60,12 @@ There are three different component options that support fixed factor of 3 up/do
  #. If voice quality (65 dB SNR) is required running on xCORE-200, use ds3_voice or us3_voice.
  #. If voice quality (75 dB SNR) is required running xcore-ai, use ff3_96t_ds or ff3_96t_us.
 
+.. warning::
+    Synchronous fixed factor of 3 and 3/2 downsample and oversample functions for voice applications optimized for the XS3 Vector Processing Unit
+    currently overflow rather than saturate in cases where a full scale input causes a perturbation above full scale at the output.
+    To avoid this scenario, please ensure that the input amplitude is always 3.5 dB below full scale.
+    The overflow behavior of these SRC components will be replaced by saturating behavior (to match all other SRC components) in a future release.
+
 
 Related Application Notes
 .........................

doc/build_docs_ci.sh

@@ -0,0 +1,21 @@
+# This script is designed to be run by the CI under a venv set by requirements.txt in the repo root.
+# Take a look at the Jenkinsfile for the general idea.
+# It should be run as /doc/build_docs_ci.sh from the repo root as the cwd.
+
+if [ -z "$1" ]
+  then
+    echo "Please pass the xmosdoc version. Eg. $/doc/build_docs_ci.sh v4.0"
+    exit -1
+fi
+
+# Build the autogenerated section
+cd doc/python
+python doc_asrc.py
+cd ../..
+
+# Create the docs from source
+docker pull ghcr.io/xmos/xmosdoc:$1
+docker run -u "$(id -u):$(id -g)" --rm -v `pwd`:/build  ghcr.io/xmos/xmosdoc:$1 -v
+
+# Leave a nice zip file for picking up as an artefact
+zip -r doc_build.zip doc/_build

doc/exclude-patterns.inc → doc/exclude_patterns.inc

@@ -1,14 +1,15 @@
 # The following patterns are to be excluded from the documentation build
 tests/*
 build/*
+**LICENSE*
 
 # Do not build .md files
 
 *.md
 **/*.md
+lib_logging/**
+lib_xassert/**
 
 # We need to ensure these are not processed twice which breaks figure numbering. They are included via index.rst.
-**/multi_rate_hifi_src.rst
-**/fixed_ratio_src.rst
 **/resource_usage_asrc.rst
-**/resource_usage_ssrc.rst
+**/resource_usage_ssrc.rst