Merge pull request #49 from xmos/develop

Release staging for v2.0.0

.gitignore

@@ -5,3 +5,6 @@ compile_commands.json
 .python-version
 __pycache__/
 modules/
+doc/doc/_build
+doc/_out
+_build

.xmos_ignore_source_check

@@ -1 +1,3 @@
 python/sw_pll/pll_calc.py
+register_setup.h
+fractions.h

CHANGELOG.rst

@@ -1,6 +1,13 @@
 lib_sw_pll library change log
 =============================
 
+2.0.0
+-----
+
+  * ADDED: Double integral term to controller
+  * ADDED: Sigma Delta Modulator option for PLL
+  * CHANGED: Refactored Python model into analogous objects
+
 1.1.0
 -----
 

CMakeLists.txt

@@ -22,4 +22,6 @@ if(PROJECT_IS_TOP_LEVEL)
     add_subdirectory(modules/fwk_io)
     add_subdirectory(tests/test_app)
     add_subdirectory(tests/test_app_low_level_api)
+    add_subdirectory(tests/test_app_sdm_dco)
+    add_subdirectory(tests/test_app_sdm_ctrl)
 endif()

Jenkinsfile

@@ -25,34 +25,88 @@ pipeline {
         )
     }
     environment {
+        REPO = 'lib_sw_pll'
         PYTHON_VERSION = "3.10.5"
         VENV_DIRNAME = ".venv"
     }
 
     stages {
-        stage('ci') {
+        stage('Build and tests') {
             agent {
                 label 'linux&&64'
             }
-            steps {
-                sh 'mkdir lib_sw_pll'
-                // source checks require the directory
-                // name to be the same as the repo name
-                dir('lib_sw_pll') {
-                    // checkout repo
-                    checkout scm
-                    installPipfile(false)
-                    withVenv {
-                        withTools(params.TOOLS_VERSION) {
-                            sh './tools/ci/checkout-submodules.sh'
-                            catchError {
-                                sh './tools/ci/do-ci.sh'
+            stages{
+                stage('Checkout'){
+                    steps {
+                        sh 'mkdir ${REPO}'
+                        // source checks require the directory
+                        // name to be the same as the repo name
+                        dir("${REPO}") {
+                            // checkout repo
+                            checkout scm
+                            installPipfile(false)
+                            withVenv {
+                                withTools(params.TOOLS_VERSION) {
+                                    sh './tools/ci/checkout-submodules.sh'
+                                }
                             }
-                            zip archive: true, zipFile: "build.zip", dir: "build"
-                            zip archive: true, zipFile: "tests.zip", dir: "tests/bin"
-                            archiveArtifacts artifacts: "tests/bin/timing-report.txt", allowEmptyArchive: false
+                        }
+                    }
+                }
+                stage('Docs') {
+                    environment { XMOSDOC_VERSION = "v4.0" }
+                    steps {
+                        dir("${REPO}") {
+                            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/", zipFile: "sw_pll_docs.zip"
+                            archiveArtifacts artifacts: "sw_pll_docs.zip"
+                        }
+                    }
+                }
+                stage('Build'){
+                    steps {
+                        dir("${REPO}") {
+                            withVenv {
+                                withTools(params.TOOLS_VERSION) {
+                                    sh './tools/ci/do-ci-build.sh'
+                                }
+                            }
+                        }
+                    }
+                }
+                stage('Test'){
+                    steps {
+                        dir("${REPO}") {
+                            withVenv {
+                                withTools(params.TOOLS_VERSION) {
+                                    catchError {
+                                        sh './tools/ci/do-ci-tests.sh'
+                                    }
+                                    zip archive: true, zipFile: "build.zip", dir: "build"
+                                    zip archive: true, zipFile: "tests.zip", dir: "tests/bin"
+                                    archiveArtifacts artifacts: "tests/bin/timing-report*.txt", allowEmptyArchive: false
 
-                            junit 'tests/results.xml'
+                                    junit 'tests/results.xml'
+                                }
+                            }
+                        }
+                    }
+                }
+                stage('Python examples'){
+                    steps {
+                        dir("${REPO}") {
+                            withVenv {
+                                catchError {
+                                    sh './tools/ci/do-model-examples.sh'
+                                }
+                                archiveArtifacts artifacts: "python/sw_pll/*.png,python/sw_pll/*.wav", allowEmptyArchive: false
+                            }
                         }
                     }
                 }

README.rst

@@ -3,23 +3,32 @@ lib_sw_pll
 
 This library contains software that, together with the on-chip application PLL, provides a PLL that will generate a clock phase locked to an input clock.
 
-********************************
-Building and running the example
-********************************
+It supports both Look Up Table (LUT) and Sigma Delta Modulated (SDM) Digitally Controlled Oscillators (DCO), a Phase Frequency Detector (PFD) and
+configurable Proportional Integral (PI) controllers which together form a hybrid Software/Hardware Phase Locked Loop (PLL).
 
-Ensure a correctly configured installation of the XMOS tools.
+Examples are provided showing a master clock locking to a low frequency input reference clock and also to an I2S slave interface.
+
+*********************************
+Building and running the examples
+*********************************
+
+Ensure a correctly configured installation of the XMOS tools and open an XTC command shell. Please check that the XMOS tools are correctly
+sourced by running the following command::
+
+    $ xcc
+    xcc: no input files
 
 .. note::
     Instructions for installing and configuring the XMOS tools appear on `the XMOS web site <https://www.xmos.ai/software-tools/>`_.
 
-Place the fwk_core and fwk_io repositories in the modules directory of lib_sw_pll.
+Place the fwk_core and fwk_io repositories in the modules directory of lib_sw_pll. These are required dependencies for the example apps.
 To do so, from the root of lib_sw_pll (where this read me file exists) type::
 
     mkdir modules
-    pushd modules
+    cd modules
     git clone --recurse-submodules [email protected]:xmos/fwk_core.git
     git clone --recurse-submodules [email protected]:xmos/fwk_io.git
-    popd
+    cd ..
 
 .. note::
     The fwk_core and fwk_io repositories have not been sub-moduled into this Git repository because only the examples depend upon them.
@@ -30,43 +39,33 @@ On linux::
 
     cmake -B build -DCMAKE_TOOLCHAIN_FILE=modules/fwk_io/xmos_cmake_toolchain/xs3a.cmake
     cd build
-    make simple
+    make simple_lut simple_sdm i2s_slave_lut
 
 On Windows::
 
-    cmake -G "NMake Makefiles" -B build -DCMAKE_TOOLCHAIN_FILE=modules/fwk_io/xmos_cmake_toolchain/xs3a.cmake
+    cmake -G "Ninja" -B build -DCMAKE_TOOLCHAIN_FILE=modules/fwk_io/xmos_cmake_toolchain/xs3a.cmake
     cd build
-    nmake simple
+    ninja simple_lut simple_sdm i2s_slave_lut
 
 
-To run the firmware, first connect LRCLK and BCLK (connects the test clock output to the PLL input)
-and run the following command where <my_example> can be *simple* which uses the XCORE-AI-EXPLORER board
-or *i2s_slave* which uses either the EVK3600 of EVK3800 board::
+To run the firmware, first connect LRCLK and BCLK (connects the test clock output to the PLL reference input)
+and run the following command where <my_example> can be *simple_lut* or *simple_sdm* which use the XCORE-AI-EXPLORER board
+or *i2s_slave_lut* which uses the XK-VOICE-SQ66 board::
 
     xrun --xscope <my_example>.xe
 
 
-For simple.xe, to see the PLL lock, put one scope probe on either LRCLK/BCLK (reference) and the other on PORT_I2S_DAC_DATA to see the 
-recovered clock which has been hardware divided back down to the same rate as the input clock.
+For simple_xxx.xe, to see the PLL lock, put one scope probe on either LRCLK/BCLK (reference input) and the other on PORT_I2S_DAC_DATA to see the 
+recovered clock which has been hardware divided back down to the same rate as the input reference clock.
 
-For i2s_slave.xe you will need to connect a 48kHz I2S master to the LRCLK, BCLK pins. You may then observe the I2S input being
+For i2s_slave_lut.xe you will need to connect a 48kHz I2S master to the LRCLK, BCLK pins. You may then observe the I2S input data being
 looped back to the output and the MCLK being generated. A divided version of MCLK is output on PORT_I2S_DATA2 which allows
-direct comparison of the input reference (LRCLK) with the recovered clock at the same frequency.
-
-*****************
-Running the tests
-*****************
-
-A test is available which checks the C implementation and the simulator, to run it::
+direct comparison of the input reference (LRCLK) with the recovered clock at the same, and locked, frequency.
 
-    cmake -B build -DCMAKE_TOOLCHAIN_FILE=xmos_cmake_toolchain/xs3a.cmake
-    cmake --build build --target test_app
-    pip install -r .
-    cd tests
-    pytest
 
 *********************************
 Generating new PLL configurations
 *********************************
 
-Please see `doc/sw_pll.rst` for further details on how to design and build new sw_pll configurations. This covers the tradeoff between lock range, noise and memory usage.
+Please see `doc/rst/sw_pll.rst` for further details on how to design and build new sw_pll configurations. This covers the tradeoff between lock range, 
+oscillator noise and resource usage.