Merge pull request #569 from xmos/develop

merge develop into main for release v0.12.0
xmos · Dec 19, 2022 · a305fcf · a305fcf
2 parents 3e2b44f + f669af0
commit a305fcf
Show file tree

Hide file tree

Showing 166 changed files with 8,200 additions and 673 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -22,7 +22,7 @@ on:
   workflow_dispatch: {}
 
 env:
-  DOC_BUILDER_IMAGE: 'ghcr.io/xmos/doc_builder:main'
+  DOC_BUILDER_IMAGE: 'ghcr.io/xmos/doc_builder:latest'
 
 jobs:
   build_documentation:

diff --git a/.gitmodules b/.gitmodules
@@ -16,3 +16,6 @@
 [submodule "frameworks/rtos"]
 	path = modules/rtos
 	url = [email protected]:xmos/fwk_rtos.git
+[submodule "modules/xscope_fileio/xscope_fileio"]
+	path = modules/xscope_fileio/xscope_fileio
+	url = [email protected]:xmos/xscope_fileio.git
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -1,6 +1,17 @@
 XCORE SDK change log
 ====================
 
+0.12.0
+------
+
+  * Addition of FreeRTOS Tracealyzer example application
+  * Addition of FreeRTOS DFU example application
+  * Addition of FreeRTOS xscope_fileio example application
+  * Addition of FreeRTOS xlink example application
+  * Addition of Voice framework module
+  * Removed FreeRTOS Dispatcher example application
+  * Minor documentation updates
+
 0.11.0
 ------
 

diff --git a/Jenkinsfile b/Jenkinsfile
@@ -1,14 +1,4 @@
-@Library('[email protected]') _
-
-def withXTAG(String target, Closure body) {
-    // Acquire an xtag adapter-id by target name
-    def adapterID = sh (script: "xtagctl acquire ${target}", returnStdout: true).trim()
-    // Run the closure
-    body(adapterID)
-    // Release the xtag by adapter-id
-    sh ("xtagctl release ${adapterID}")
-}
-
+@Library('[email protected]') _
 
 // Wait here until specified artifacts appear
 def artifactUrls = getGithubArtifactUrls([
@@ -23,7 +13,7 @@ getApproval()
 
 pipeline {
     agent {
-        label 'sdk'
+        label 'us-hw-xcai-exp0'
     }
     options {
         disableConcurrentBuilds()
@@ -45,7 +35,7 @@ pipeline {
     environment {
         PYTHON_VERSION = "3.8.11"
         VENV_DIRNAME = ".venv"
-        DOWNLOAD_DIRNAME = "build"
+        DOWNLOAD_DIRNAME = "dist"
         SDK_TEST_RIG_TARGET = "xcore_sdk_test_rig"
     }        
     stages {
@@ -93,44 +83,45 @@ pipeline {
                     withVenv {
                         script {
                             if (fileExists("$DOWNLOAD_DIRNAME/example_freertos_getting_started.xe")) {
-                                withXTAG("$SDK_TEST_RIG_TARGET") { adapterID ->
-                                    sh "test/examples/run_freertos_getting_started_tests.sh $adapterID"
+                                withXTAG(["$SDK_TEST_RIG_TARGET"]) { adapterIDs ->
+                                    sh "test/examples/run_freertos_getting_started_tests.sh " + adapterIDs[0]
                                 }
                             } else {
                                 echo 'SKIPPED: example_freertos_getting_started'
                             }
                         } 
                         script {
                             if (fileExists("$DOWNLOAD_DIRNAME/example_freertos_explorer_board.xe")) {
-                                withXTAG("$SDK_TEST_RIG_TARGET") { adapterID ->
-                                    sh "test/examples/run_freertos_explorer_board_tests.sh $adapterID"
+                                withXTAG(["$SDK_TEST_RIG_TARGET"]) { adapterIDs ->
+                                    sh "test/examples/run_freertos_explorer_board_tests.sh " + adapterIDs[0]
                                 }
                             } else {
                                 echo 'SKIPPED: example_freertos_explorer_board'
                             }
                         } 
                         script {
-                            if (fileExists("$DOWNLOAD_DIRNAME/example_freertos_dispatcher.xe")) {
-                                withXTAG("$SDK_TEST_RIG_TARGET") { adapterID ->
-                                    sh "test/examples/run_freertos_dispatcher_tests.sh $adapterID"
+                            if (fileExists("$DOWNLOAD_DIRNAME/example_freertos_l2_cache.xe")) {
+                                withXTAG(["$SDK_TEST_RIG_TARGET"]) { adapterIDs ->
+                                    sh "test/examples/run_freertos_l2_cache_tests.sh " + adapterIDs[0]
                                 }
                             } else {
-                                echo 'SKIPPED: example_freertos_dispatcher'
+                                echo 'SKIPPED: example_freertos_l2_cache'
                             }
                         } 
                         script {
-                            if (fileExists("$DOWNLOAD_DIRNAME/example_freertos_l2_cache.xe")) {
-                                withXTAG("$SDK_TEST_RIG_TARGET") { adapterID ->
-                                    sh "test/examples/run_freertos_l2_cache_tests.sh $adapterID"
+                            if (fileExists("$DOWNLOAD_DIRNAME/example_freertos_tracealyzer.xe")) {
+                                withXTAG(["$SDK_TEST_RIG_TARGET"]) { adapterIDs ->
+                                    sh "test/examples/run_freertos_tracealyzer_tests.sh " + adapterIDs[0]
                                 }
                             } else {
-                                echo 'SKIPPED: example_freertos_l2_cache'
+                                echo 'SKIPPED: example_freertos_tracealyzer'
                             }
-                        } 
+                        }
                     }
                 }
             }
         }
+
         // stage('Run bare-metal examples') {
         //     steps {
         //         withTools(params.TOOLS_VERSION) {

diff --git a/README.md b/README.md
@@ -37,7 +37,7 @@ Download and install the xcore [XTC Tools](https://www.xmos.ai/software-tools/)
 
 ## Documentation
 
-See the [official documentation](https://www.xmos.com/documentation/XM-014660-PC-2/html/) for more information including:
+See the [official documentation](https://www.xmos.ai/documentation/XM-014660-PC-2/html/) for more information including:
 
 - Instructions for installing
 - Getting started guides

diff --git a/doc/README.rst b/doc/README.rst
@@ -25,7 +25,7 @@ Pull the docker container:
 
 .. code-block:: console
 
-    docker pull ghcr.io/xmos/doc_builder:main
+    docker pull ghcr.io/xmos/doc_builder:latest
 
 ========
 Building
@@ -35,7 +35,7 @@ To build the documentation, run the following command in the root of the reposit
 
 .. code-block:: console
 
-    docker run --rm -t -u "$(id -u):$(id -g)" -v $(pwd):/build -e REPO:/build -e DOXYGEN_INCLUDE=/build/doc/Doxyfile.inc -e EXCLUDE_PATTERNS=/build/doc/exclude_patterns.inc -e DOXYGEN_INPUT=ignore ghcr.io/xmos/doc_builder:main
+    docker run --rm -t -u "$(id -u):$(id -g)" -v $(pwd):/build -e REPO:/build -e DOXYGEN_INCLUDE=/build/doc/Doxyfile.inc -e EXCLUDE_PATTERNS=/build/doc/exclude_patterns.inc -e DOXYGEN_INPUT=ignore ghcr.io/xmos/doc_builder:latest
 
 **********************
 Adding a New Component

diff --git a/doc/contributing.rst b/doc/contributing.rst
@@ -132,16 +132,7 @@ The following conventions are used when naming CMake targets:
 - Targets that match ``example_freertos_*`` are FreeRTOS examples
 - Targets that match ``run_example_*`` are a shortcut recipe to call ``xrun`` with ``xscope`` and the associated firmware
 - Targets that match ``debug_example_*`` are a shortcut recipe to call ``xgdb`` with ``xscope`` and the associated firmware
+- Targets that match ``install_example_*`` are a shortcut recipe to copy the associated firmware to the ``dist`` output directory 
 - Targets that match ``xsim_example_*`` are a shortcut recipe to call ``xsim`` with the associated firmware
 - Targets that match ``flash_example_*`` are a shortcut recipe to flash required data
 - Targets that match ``flash_fs_example_*`` are a shortcut recipe to flash required data for applications using a filesystem
-
-****************
-Development Tips
-****************
-
-At times submodule repositories will need to be updated.  To update all submodules, run the following command
-
-.. code-block:: console
-
-    git submodule update --init --recursive
diff --git a/doc/exclude_patterns.inc b/doc/exclude_patterns.inc
@@ -8,7 +8,7 @@ modules/sample_rate_conversion
 modules/core/modules/legacy_compat
 modules/core/modules/otpinfo
 modules/core/modules/random
-modules/core/modules/inferencing
+modules/core/modules/trycatch
 modules/io/modules/xud
 modules/io/doc/substitutions.rst
 modules/voice/doc/substitutions.rst
diff --git a/doc/faq.rst b/doc/faq.rst
@@ -0,0 +1,41 @@
+.. _sdk-faq:
+
+#############################
+Frequently Asked Questions
+#############################
+
+************
+Build Issues
+************
+
+=================
+Submodule updates
+=================
+
+The XCORE SDK uses submodules.  If you have cloned the repository and later perform an update, it will sometimes also be necessary to update the submodules.  To update all submodules, run the following command
+
+.. code-block:: console
+
+    git submodule update --init --recursive
+
+========================
+fatfs_mkimage: not found
+========================
+
+This issue occurs when the XCORE SDK `fatfs_mkimage` utility cannot be found.  The most common cause for these issues are an incomplete installation of the XCORE SDK.
+
+Ensure that the host applications setup has been completed.  Verify that the `fatfs_mkimage` binary is installed to a location on PATH, or that the default application installation folder is added to PATH.  See the :ref:`sdk-installation` guide for more information on installing the host applications.
+
+===============================================
+xcc2clang.exe: error: no such file or directory
+===============================================
+
+Those strange characters at the beginning of the path are known as a byte-order mark (BOM). CMake adds them to the beginning of the response files it generates during the configure step. Why does it add them? Because the MSVC compiler toolchain requires them. However, some compiler toolchains, like `gcc` and `xcc`, do not ignore the BOM. Why did CMake think the compiler toolchain was MSVC and not the XTC toolchain? Because of a bug in which certain versions of CMake and certain versions of Visual Studio do not play nice together. The good news is that this appears to have been addressed in CMake version 3.22.3. 
+
+Update to CMake version 3.22.2 or newer.
+
+********
+FreeRTOS
+********
+
+See the :ref:`freertos-faq` or :ref:`freertos-common_issues`
diff --git a/doc/quick_start/index.rst b/doc/quick_start/index.rst
@@ -4,11 +4,11 @@ Introduction
 
 The XCORE SDK is a collection of C/C++ software libraries designed to simplify and accelerate application development on xcore processors. It is composed of the following components:
 
-- Peripheral IO libraries including; UART, I2C, I2S, SPI, QSPI, PDM microphones, and USB. These libraries support bare-metal and RTOS application development.
-- Libraries core to DSP applications, including vectorized math.  These libraries support bare-metal and RTOS application development. 
+- :ref:`Peripheral IO <fwk_io-peripherals>` libraries including; UART, I2C, I2S, SPI, QSPI, PDM microphones, and USB. These libraries support bare-metal and RTOS application development.
+- Libraries core to :ref:`DSP applications <fwk_core-optimized>`, including :ref:`vectorized math <fwk_core-optimized>`.  These libraries support bare-metal and RTOS application development. 
 - Voice processing libraries including; adaptive echo cancellation, adaptive gain control, noise suppression, interference cancellation (IC), and voice activity detection. These libraries support bare-metal and RTOS application development.
-- Libraries that enable `multi-core FreeRTOS development <https://www.freertos.org/symmetric-multiprocessing-introduction.html>`__ on xcore including a wide array of RTOS drivers and middleware.
-- Code Examples - Examples showing a variety of xcore features based on bare-metal and FreeRTOS programming.
+- Libraries that enable `multi-core FreeRTOS development <https://www.freertos.org/symmetric-multiprocessing-introduction.html>`__ on xcore including a wide array of :ref:`RTOS drivers and middleware <fwk_rtos-framework>`.
+- Code Examples - Examples showing a variety of xcore features based on :ref:`bare-metal <sdk-baremetal-code-examples>` and :ref:`FreeRTOS <sdk-freertos-code-examples>` programming.
 - Documentation - Getting started guides, references and API guides.
 
 The SDK is designed to be used in conjunction with the xcore.ai Explorer board and the Voice Reference evaluation kit. The example applications compile targeting these boards. Further information about the Explorer board, the Voice Reference evaluation kit, and xcore.ai devices is available to on `www.xmos.ai <https://www.xmos.ai/>`__.
@@ -17,4 +17,4 @@ The SDK is designed to be used in conjunction with the xcore.ai Explorer board a
 Getting Started
 ***************
 
-Fast-forward to the :ref:`Tutorials <sdk-tutorials>` for information on installing and using the XCORE SDK.   
+Fast-forward to the :ref:`Tutorials <sdk-tutorials>` for information on :ref:`system requirements <sdk-system-requirements>`, :ref:`installing <sdk-installation>` and :ref:`using the XCORE SDK <sdk-tutorials>`.   
diff --git a/doc/quick_start/installation.rst b/doc/quick_start/installation.rst
@@ -28,12 +28,20 @@ The SDK includes utilities that run on the PC host.  Run the following command t
         $ cd build_host
         $ sudo make install
 
-    This command installs the applications at ``/opt/xmos/SDK/<sdk version>/bin/`` directory.  You may wish to append this directory to your ``PATH`` variable.
+    This command installs the applications at `/opt/xmos/SDK/<sdk version>/bin/` directory.  You may wish to append this directory to your `PATH` variable.
 
     .. code-block:: console
 
         $ export PATH=$PATH:/opt/xmos/SDK/<sdk_version>/bin/
 
+    Some host applications require that the location of `xscope_endpoint.so` be added to your `LD_LIBRARY_PATH` environment variable.  This environment variable will be set if you run the host application in the XTC Tools command-line environment.  For more information see `Configuring the command-line environment <https://www.xmos.ai/documentation/XM-014363-PC-LATEST/html/tools-guide/install-configure/getting-started.html>`__.   
+
+    Or, you may prefer to set this environment variable manually.
+
+    .. code-block:: console
+
+        $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<path-to-XTC-Tools>/lib
+
 .. tab:: Windows
 
     Windows users must run the x86 native tools command prompt from Visual Studio
@@ -44,8 +52,9 @@ The SDK includes utilities that run on the PC host.  Run the following command t
         $ cd build_host
         $ nmake install
 
-    This command installs the applications at ``<USERPROFILE>\.xmos\SDK\<sdk version>\bin\`` directory.  You may wish to add this directory to your ``PATH`` variable.
+    This command installs the applications at `<USERPROFILE>\.xmos\SDK\<sdk version>\bin\` directory.  You may wish to add this directory to your `PATH` variable.
 
+    Some host applications require that the location of `xscope_endpoint.dll` be added to your PATH. This environment variable will be set if you run the host application in the XTC Tools command-line environment.  For more information see `Configuring the command-line environment <https://www.xmos.ai/documentation/XM-014363-PC-LATEST/html/tools-guide/install-configure/getting-started.html>`__.
 
 Optional Step 3. Install Python and Python Requirements
 =======================================================

diff --git a/doc/quick_start/system-requirements.rst b/doc/quick_start/system-requirements.rst
@@ -10,7 +10,9 @@ The XCORE SDK is officially supported on the following platforms. Unofficial sup
 .. tab:: Windows
 
    Windows 10 is supported.
-
+
+   A standard C/C++ compiler is required to build applications and libraries on the host PC.  Windows users may use `Build Tools for Visual Studio <https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-170#download-and-install-the-tools>`__ command-line interface.
+
    Windows users can also use the Windows Subsystem for Linux (WSL).  See `Windows Subsystem for Linux Installation Guide for Windows 10 <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`__ to install WSL.
 
    The SDK should also work using other Windows GNU development environments like GNU Make, MinGW or Cygwin.
@@ -19,7 +21,7 @@ The XCORE SDK is officially supported on the following platforms. Unofficial sup
 
    Operating systems macOS 10.5 (Catalina) and newer are supported. Intel processors only.  Older operating systems are likely to also work, though they are not supported.
 
-   A standard C/C++ compiler is required to build applications and libraries on the host PC.  Mac users may use the Xcode command line tools.
+   A standard C/C++ compiler is required to build applications and libraries on the host PC.  Mac users may use the Xcode command-line tools.
 
 .. tab:: Linux
 

diff --git a/doc/reference/index.rst b/doc/reference/index.rst
@@ -8,3 +8,4 @@ References
    ../../modules/core/index.rst
    ../../modules/io/index.rst
    ../../modules/rtos/index.rst
+   ../../modules/voice/index.rst
diff --git a/doc/tutorials/bare-metal/examples/index.rst b/doc/tutorials/bare-metal/examples/index.rst
@@ -1,3 +1,5 @@
+.. _sdk-baremetal-code-examples:
+
 ########################
 Bare-metal Code Examples
 ########################

diff --git a/doc/tutorials/build_system/cmakelists.rst b/doc/tutorials/build_system/cmakelists.rst
@@ -1,11 +1,18 @@
 ######################
-Example CMakeLists.txt 
+Example CMakeLists.txt
 ######################
 
 .. note::
 
    CMake is powerful tool that provides the developer a great deal of flexibility in how their projects are built.  As a result, CMakeLists.txt files in the example applications may vary from the examples below.  This example can be used as a starting point for your bare-metal application.  Or, you may choose to copy a ``CMakeLists.txt`` from one of the applications in the SDK that closely resembles your application.
 
+
+This repository supports being added as a CMake subproject. A parent CMake project can use add_subdirectory() to include the xcore_sdk as a subproject.
+
+.. note::
+
+    The xcore_sdk subproject should be added before declaring application targets, as some xcore_sdk provided macros may be needed.  Additionally, when included as a subproject, xcore_sdk examples targets are not added to the CMake build.
+
 **********
 Bare-Metal
 **********
@@ -133,4 +140,4 @@ Below is an example ``CMakeLists.txt`` that shows both required and conventional
 
    ## Optionally create run and debug targets
    create_run_target(my_app)
-   create_debug_target(my_app)
+   create_debug_target(my_app)
diff --git a/doc/tutorials/build_system/index.rst b/doc/tutorials/build_system/index.rst
@@ -6,7 +6,9 @@
 Build System
 ############
 
-This document describes the `CMake <https://cmake.org/>`_-based build system used by the example applications in the XCORE SDK.  The build system is designed so a user does not have to be an expert using CMake.  However, some familiarity with CMake is helpful.  You can familiarize yourself by reading the `Cmake Tutorial <https://cmake.org/cmake/help/latest/guide/tutorial/index.html>`_ or `CMake documentation <https://cmake.org/cmake/help/v3.20/>`_.  
+This document describes the `CMake <https://cmake.org/>`_-based build system used by the example applications in the XCORE SDK.  The build system is designed so a user does not have to be an expert using CMake.  However, some familiarity with CMake is helpful.  You can familiarize yourself by reading the `Cmake Tutorial <https://cmake.org/cmake/help/latest/guide/tutorial/index.html>`_ or `CMake documentation <https://cmake.org/cmake/help/v3.20/>`_.
+
+Check the :ref:`system requirement prerequisites <sdk-prerequisites>` for the supported versions of CMake.
 
 ********
 Overview

diff --git a/doc/tutorials/build_system/target_aliases.rst b/doc/tutorials/build_system/target_aliases.rst
@@ -176,8 +176,6 @@ If you prefer, you can specify individual software service libraries.
       - Device control library
     * - rtos::sw_services::usb_device_control
       - USB device control library
-    * - rtos::sw_services::dispatcher
-      - Dispatcher thread pool library
     * - rtos::sw_services::wifi_manager
       - WiFi manager library
     * - rtos::sw_services::tls_support