diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml deleted file mode 100644 index afb0bdce..00000000 --- a/.github/workflows/docs.yml +++ /dev/null @@ -1,57 +0,0 @@ -# YAML schema for GitHub Actions: -# https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions -# -# Helpful YAML parser to clarify YAML syntax: -# https://yaml-online-parser.appspot.com/ -# -# This workflow uses actions that are not certified by GitHub. They are provided by a third-party and are governed by -# separate terms of service, privacy policy, and support documentation. -# -# This file contains the workflows that are run prior to merging a pull request. - -name: Docs - -on: - push: - branches: - - 'develop' - - 'master' - pull_request: - branches: - - 'develop' - - 'master' - - # Allow manually triggering of the workflow. - workflow_dispatch: {} - -jobs: - build_documentation: - name: Build and package documentation - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v2 - - - name: Pull doc_builder container - run: | - docker pull ghcr.io/xmos/doc_builder:v3.0.0 - - - name: Build documentation - run: | - 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/doc_excludes.txt -e DOXYGEN=1 -e DOXYGEN_INCLUDE=/build/doc/Doxyfile.inc -e PDF=1 ghcr.io/xmos/doc_builder:v2.0.0 - - - name: Save HTML documentation artifact - uses: actions/upload-artifact@v2 - with: - name: lib_mic_array_docs_html - path: ./doc/_build/html - if-no-files-found: error # 'warn' or 'ignore' are also available, defaults to `warn` - retention-days: 5 - - - name: Save PDF documentation artifact - uses: actions/upload-artifact@v2 - with: - name: lib_mic_array_docs_pdf - path: ./doc/_build/pdf/programming_guide.pdf - if-no-files-found: error # 'warn' or 'ignore' are also available, defaults to `warn` - retention-days: 5 diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 01e96d07..193731fe 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,6 +1,12 @@ lib_mic_array change log ======================== +5.3.0 +----- + + * FIXED: Vanilla configuration now compiles correctly under XTC 15.3.0 + * ADDED: Support for XCommon CMake build system + 5.2.0 ----- @@ -215,4 +221,3 @@ lib_mic_array change log - lib_logging: Added dependency 2.0.0 - lib_xassert: Added dependency 2.0.0 - diff --git a/Jenkinsfile b/Jenkinsfile index 9d8cd3f8..1ff3af5c 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -1,4 +1,4 @@ -@Library('xmos_jenkins_shared_library@v0.25.0') _ +@Library('xmos_jenkins_shared_library@v0.33.0') _ getApproval() pipeline { agent none @@ -15,7 +15,7 @@ pipeline { parameters { string( name: 'TOOLS_VERSION', - defaultValue: '15.2.1', + defaultValue: '15.3.0', description: 'The XTC tools version' ) } @@ -23,45 +23,74 @@ pipeline { REPO = 'lib_mic_array' } stages { - stage('Basic tests') { - agent { - label 'x86_64 && linux' - } - stages { - stage("Setup") { - // Clone and install build dependencies + stage('Build and Docs') { + parallel { + stage('Build Docs') { + agent { label "docker" } + environment { XMOSDOC_VERSION = "v4.0" } steps { - // Print the build agent name - println "RUNNING ON" - println env.NODE_NAME - // Clone infrastructure repos - sh "git clone --branch v1.4.6 git@github.com:xmos/infr_apps" - sh "git clone --branch v1.2.1 git@github.com:xmos/infr_scripts_py" - // clone - dir("$REPO") { - checkout scm - sh "git submodule update --init --recursive" - withTools(params.TOOLS_VERSION) { - installDependencies() - } + checkout scm + sh 'git submodule update --init --recursive --depth 1' + sh "docker pull ghcr.io/xmos/xmosdoc:$XMOSDOC_VERSION" + sh """docker run -u "\$(id -u):\$(id -g)" \ + --rm \ + -v ${WORKSPACE}:/build \ + ghcr.io/xmos/xmosdoc:$XMOSDOC_VERSION -v""" + archiveArtifacts artifacts: "doc/_build/**", allowEmptyArchive: true + } + post { + cleanup { + xcoreCleanSandbox() } } } - stage("Lib checks") { - steps { - println "Unlikely these will pass.." - // warnError("Source Check"){ sourceCheck("${REPO}") } - // warnError("Changelog Check"){ xcoreChangelogCheck("${REPO}") } + stage('Basic tests') { + when { + expression { !env.GH_LABEL_DOC_ONLY.toBoolean() } + } + agent { + label 'x86_64 && linux' + } + stages { + stage("Setup") { + // Clone and install build dependencies + steps { + // Print the build agent name + println "RUNNING ON" + println env.NODE_NAME + // 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 + sh "git submodule update --init --recursive" + withTools(params.TOOLS_VERSION) { + installDependencies() + } + } + } + } + stage("Lib checks") { + steps { + println "Unlikely these will pass.." + // warnError("Source Check"){ sourceCheck("${REPO}") } + // warnError("Changelog Check"){ xcoreChangelogCheck("${REPO}") } + } + } + } + post { + cleanup { + xcoreCleanSandbox() + } } - } - } - post { - cleanup { - xcoreCleanSandbox() } } } stage('HW tests') { + when { + expression { !env.GH_LABEL_DOC_ONLY.toBoolean() } + } agent { label 'xvf3800' // We have plenty of these (6) and they have a single XTAG connected } @@ -115,4 +144,4 @@ pipeline { } } } -} \ No newline at end of file +} diff --git a/demos/common/src/dac_port.c b/demos/common/src/dac_port.c index bdd8fa58..c10d6183 100644 --- a/demos/common/src/dac_port.c +++ b/demos/common/src/dac_port.c @@ -1,4 +1,4 @@ -// Copyright (c) 2022-2023 XMOS LIMITED. +// Copyright (c) 2022-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public License: Version 1 #include @@ -6,6 +6,7 @@ #include "app_config.h" #include "i2c.h" #include "aic3204/aic3204.h" +#include "platform.h" i2c_master_t i2c_master_ctx; diff --git a/demos/demo/src/app.cpp b/demos/demo/src/app.cpp index 2e923f4c..2181639a 100644 --- a/demos/demo/src/app.cpp +++ b/demos/demo/src/app.cpp @@ -1,8 +1,8 @@ -// Copyright 2022 XMOS LIMITED. +// Copyright 2022-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #include "app.h" - +#include #include "mic_array/cpp/Prefab.hpp" #define DCOE_ENABLED true diff --git a/demos/demo/src/app_i2s.c b/demos/demo/src/app_i2s.c index b2c6ea59..90fde3b5 100644 --- a/demos/demo/src/app_i2s.c +++ b/demos/demo/src/app_i2s.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 @@ -15,6 +15,7 @@ #include #include #include +#include #include diff --git a/demos/demo_par_decimator/src/app.cpp b/demos/demo_par_decimator/src/app.cpp index 16efa007..346588d3 100644 --- a/demos/demo_par_decimator/src/app.cpp +++ b/demos/demo_par_decimator/src/app.cpp @@ -1,9 +1,10 @@ -// Copyright 2023 XMOS LIMITED. +// Copyright 2023-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #include #include #include +#include #include "app_config.h" #include "app_mic_array.hpp" diff --git a/demos/demo_par_decimator/src/app_i2s.c b/demos/demo_par_decimator/src/app_i2s.c index 9efb0b3b..091bc236 100644 --- a/demos/demo_par_decimator/src/app_i2s.c +++ b/demos/demo_par_decimator/src/app_i2s.c @@ -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. #include @@ -18,6 +18,7 @@ #include #include #include +#include #include diff --git a/demos/demo_vanilla/src/app_i2s.c b/demos/demo_vanilla/src/app_i2s.c index bb161bb9..3d3b149d 100644 --- a/demos/demo_vanilla/src/app_i2s.c +++ b/demos/demo_vanilla/src/app_i2s.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 @@ -15,6 +15,7 @@ #include #include #include +#include #include diff --git a/demos/measure_mips/src/app.cpp b/demos/measure_mips/src/app.cpp index ec0f70ba..5ff93d32 100644 --- a/demos/measure_mips/src/app.cpp +++ b/demos/measure_mips/src/app.cpp @@ -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 @@ -6,6 +6,7 @@ #include #include "app.h" +#include #include "mic_array/cpp/MicArray.hpp" #include "mic_array/cpp/Prefab.hpp" diff --git a/doc/README.rst b/doc/README.rst index c58b21b1..8c9fe66a 100644 --- a/doc/README.rst +++ b/doc/README.rst @@ -1,33 +1,19 @@ -###################### -Building Documentation -###################### - -Instructions are given below to build the documentation. The recommended method is using Docker, -however, alternative instructions are provided in case using Docker in not an option. - -To develop the content of this repository, it is recommended to launch a `sphinx-autobuild` -server as per the instructions below. Once started, point a web-browser at -http://127.0.0.1:8000. If running the server within a VM, remember to configure -port forwarding. +#################### +Documentation Source +#################### -You can now edit the .rst documentation, and your web-browser content will automatically -update. +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. -************ -Using Docker -************ +********************** +Building Documentation +********************** ============= Prerequisites ============= -Install `Docker `_. - -Pull the docker container: - -.. code-block:: console - - $ docker pull ghcr.io/xmos/doc_builder:main +Use the `xmosdoc tool `_ either via docker or install it into a pip environment. ======== Building @@ -37,48 +23,41 @@ 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 ghcr.io/xmos/doc_builder:main + # 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 -******************** -Without Using Docker -******************** +HTML document output is saved in the ``doc/_build/html`` folder. Open ``index.html`` to preview the saved documentation. -============= -Prerequisites -============= +Please refer to the ``xmosdoc`` documentation for a complete guide on how to use the tool. -Install `Doxygen `_. +********************** +Adding a New Component +********************** -Install the required Python packages: +Follow the following steps to add a new component. -.. code-block:: console +- 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`. - $ pip install -r requirements.txt +*** +FAQ +*** -======== -Building -======== +Q: Is it possible to build just a subset of the documentation? -Build documentation: +A: Yes, however it is not recommended at this time. -.. code-block:: console - - $ make html +Q: Is it possible to used the ``livehtml`` feature of Sphinx? -Launch sphinx-autobuild server: +A: Yes, run xmosdoc with the ``--auto`` option. -.. code-block:: console +Q: Where can I learn more about the XMOS ``xmosdoc`` tools? - $ make livehtml +A: See the https://github.com/xmos/xmosdoc repository. See the ``xmosdoc`` repository README for details on additional build options. -Clean documentation: +Q: How do I suggest enhancements to the XMOS ``xmosdoc`` tool? -.. code-block:: console - - $ make clean - -Clean and build documentation with link check: - -.. code-block:: console - - $ make clean html linkcheck SPHINXOPTS="-W --keep-going" +A: Create a new issue here: https://github.com/xmos/xmosdoc/issues diff --git a/doc/doc_excludes.txt b/doc/exclude_patterns.inc similarity index 56% rename from doc/doc_excludes.txt rename to doc/exclude_patterns.inc index c8bb370e..cac7b406 100644 --- a/doc/doc_excludes.txt +++ b/doc/exclude_patterns.inc @@ -1,3 +1,5 @@ /build/*build*/**/*.rst /build/*build*/**/*.md -**/disclaimer.rst +CHANGELOG.rst +LICENSE.rst +**README* \ No newline at end of file diff --git a/doc/programming_guide/src/decimator_stages.rst b/doc/programming_guide/src/decimator_stages.rst index 09fac522..8cf2e16a 100644 --- a/doc/programming_guide/src/decimator_stages.rst +++ b/doc/programming_guide/src/decimator_stages.rst @@ -277,7 +277,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/programming_guide/src/getting_started.rst b/doc/programming_guide/src/getting_started.rst index d54b72ba..d91f4ee8 100644 --- a/doc/programming_guide/src/getting_started.rst +++ b/doc/programming_guide/src/getting_started.rst @@ -1,4 +1,4 @@ -.. _getting_started: +.. _mic_array_getting_started: Getting Started =============== diff --git a/etc/vanilla/mic_array_vanilla.cpp b/etc/vanilla/mic_array_vanilla.cpp index 4f13955f..fcaec48d 100644 --- a/etc/vanilla/mic_array_vanilla.cpp +++ b/etc/vanilla/mic_array_vanilla.cpp @@ -1,10 +1,12 @@ -// Copyright 2022 XMOS LIMITED. +// Copyright 2022-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #include #include #include +#include + #include "mic_array_vanilla.h" #include "mic_array/cpp/Prefab.hpp" #include "mic_array.h" diff --git a/lib_mic_array/lib_build_info.cmake b/lib_mic_array/lib_build_info.cmake new file mode 100644 index 00000000..9071e687 --- /dev/null +++ b/lib_mic_array/lib_build_info.cmake @@ -0,0 +1,15 @@ +set(LIB_NAME lib_mic_array) +set(LIB_VERSION 5.2.0) +set(LIB_DEPENDENT_MODULES "lib_xcore_math(2.2.0)") +set(LIB_INCLUDES + api + api/mic_array + api/mic_array/cpp + api/mic_array/etc + api/mic_array/impl + src + src/etc +) +set(LIB_COMPILER_FLAGS -g -Os) + +XMOS_REGISTER_MODULE() diff --git a/script/mic_array/device_context.py b/script/mic_array/device_context.py index 2dc8d87f..41444159 100644 --- a/script/mic_array/device_context.py +++ b/script/mic_array/device_context.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, signal, subprocess @@ -7,7 +7,7 @@ class DeviceContext(object): - XRUN_CMD_BASE = ('xrun', '--xscope-realtime', '--xscope-port','localhost:10234') + XRUN_CMD_BASE = ('xrun', '--xscope', '--xscope-port','localhost:10234') def __init__(self, xe_path, /, probes=[], **kwargs): diff --git a/settings.json b/settings.json deleted file mode 100644 index c2b9a67f..00000000 --- a/settings.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "title": "Mic Array Library", - "project": "lib_mic_array", - "version": "5.2.0" -} diff --git a/settings.yml b/settings.yml new file mode 100644 index 00000000..90b8f5bf --- /dev/null +++ b/settings.yml @@ -0,0 +1,14 @@ +--- +project: lib_mic_array +title: Mic Array Library +version: 5.3.0 + +documentation: + exclude_patterns_path: doc/exclude_patterns.inc + doxygen_projects: + lib_mic_array: + doxyfile_path: doc/Doxyfile.inc + pdfs: + doc/programming_guide/index: + pdf_title: "{{title}} - Programming Guide" + pdf_filename: "{{project}}_programming_guide_v{{version}}" diff --git a/tests/building/prefab/src/app.cpp b/tests/building/prefab/src/app.cpp index 33bb8dd7..e85d1f86 100644 --- a/tests/building/prefab/src/app.cpp +++ b/tests/building/prefab/src/app.cpp @@ -1,7 +1,8 @@ -// Copyright 2022 XMOS LIMITED. +// Copyright 2022-2024 XMOS LIMITED. // This Software is subject to the terms of the XMOS Public Licence: Version 1. #include "app.h" +#include #include "mic_array/cpp/Prefab.hpp" diff --git a/tests/legacy/src/app.cpp b/tests/legacy/src/app.cpp index 3d34cc03..ea46b047 100644 --- a/tests/legacy/src/app.cpp +++ b/tests/legacy/src/app.cpp @@ -1,8 +1,10 @@ - +// Copyright 2022-2024 XMOS LIMITED. +// This Software is subject to the terms of the XMOS Public Licence: Version 1. #include "mic_array.h" #include "mic_array/cpp/Prefab.hpp" #include "app.h" +#include #if (N_MICS != 2)