Merge pull request #81 from ed-xmos/feature/doc_review

Documentation update following review

Author: ed-xmos

.github/workflows/docs.yml

@@ -43,7 +43,7 @@ jobs:
       - name: Build documentation
         run: |
           pwd
-          docker run --user "$(id -u):$(id -g)" --rm -v ${{ github.workspace }}:/build -e EXCLUDE_PATTERNS="/build/doc/exclude-patterns.inc" -e OUTPUT_DIR="/build/doc/_build" -e PDF=1 -e SKIP_LINK=1 ${XCORE_DOC_BUILDER}
+          docker run --user "$(id -u):$(id -g)" --rm -v ${{ github.workspace }}:/build -e EXCLUDE_PATTERNS="/build/doc/exclude-patterns.inc" -e OUTPUT_DIR="/build/doc/_build" -e PDF=1 -e SKIP_LINK=1 -e DOXYGEN_INCLUDE=/build/doc/Doxyfile.inc -e DOXYGEN_INPUT=ignore ${XCORE_DOC_BUILDER}
           tree
           DOC_VERSION=$(grep version settings.json | grep -o "[0-9]*\.[0-9]*\.[0-9]")
           mv doc/_build/pdf/programming_guide.pdf doc/_build/pdf/programming_guide_v${DOC_VERSION}.pdf

README.rst

@@ -6,7 +6,7 @@ Overview
 
 The XMOS Sample Rate Conversion (SRC) library provides both synchronous and asynchronous audio sample rate conversion functions for use on xCORE multicore micro-controllers.
 
-In systems where the rate change is exactly equal to the ratio of nominal rates, synchronous sample rate conversion (SSRC) provides efficient and high performance rate conversion. Where the input and output rates are not locked by a common clock or clocked by an exact rational frequency ratio, the Asynchronous Sample Rate Converter (ASRC) provides a way of streaming high quality audio between the two different clock domains, at the cost of higher processing resource usage. ASRC can ease interfacing in cases where the are multiple digital audio inputs or allow cost saving by removing the need for physical clock recovery using a PLL.
+In systems where the rate change is exactly equal to the ratio of nominal rates, synchronous sample rate conversion (SSRC) provides efficient and high performance rate conversion. Where the input and output rates are not locked by a common clock or clocked by an exact rational frequency ratio, the Asynchronous Sample Rate Converter (ASRC) provides a way of streaming high quality audio between the two different clock domains, at the cost of higher processing resource usage. ASRC can ease interfacing in cases where there are multiple digital audio inputs or allow cost saving by removing the need for physical clock recovery using a PLL.
 
 Features
 ........
@@ -16,7 +16,7 @@ Multi-rate Hi-Fi functionality:
  * Conversion between 44.1, 48, 88.2, 96, 176.4 and 192 KHz input and output sample rates.
  * 32 bit PCM input and output data in Q1.31 signed format.
  * Optional output dithering to 24 bit using Triangular Probability Density Function (TPDF).
- * Optimized for xCORE-200 instruction set with dual-issue.
+ * Optimized for xCORE-200 instruction set with dual-issue and compatible with XCORE-AI.
  * Block based processing - Minimum 4 samples input per call, must be power of 2.
  * Up to 10000 ppm sample rate ratio deviation from nominal rate (ASRC only).
  * Very high quality - SNR greater than 135 dB (ASRC) or 140 dB (SSRC), with THD of less than 0.0001% (reference 1KHz).
@@ -27,7 +27,14 @@ Multi-rate Hi-Fi functionality:
 Fixed factor functionality:
 
  * Synchronous fixed factor of 3 downsample and oversample functions supporting either HiFi quality or reduced resource requirements for voice applications.
- * Synchronous fixed factor of 3 and 3/2 downsample and oversample functions for voice applications optimised for the XS3 Vector Processing Unit.
+ * Synchronous fixed factor of 3 and 3/2 downsample and oversample functions for voice applications optimized for the XS3 Vector Processing Unit.
+
+Building
+........
+
+The library can be built under `cmake` or `xcommon` via `xmake` offering backwards compatibility for legacy applications.
+It is recommended to use `cmake` where the library name `lib_src` is included in the cmake files. See `Related application notes`_ for example usage. 
+The library has no dependencies when building under `cmake` although does require `lib_logging` and `lib_xassert` when using `xcommon`. 
 
 Components
 ..........
@@ -38,23 +45,23 @@ Components
  * Synchronous factor of 3 downsample function (ds3)
  * Synchronous factor of 3 oversample function (os3)
 
- * Synchronous factor of 3 downsample function optimised for use with voice (src_ds3_voice)
+ * Synchronous factor of 3 downsample function optimized for use with voice (src_ds3_voice)
  * Synchronous factor of 3 oversample function optimised for use with voice (src_us3_voice)
 
- * Synchronous factor of 3 downsample function optimised for use with voice optimised for XS3 (src_ff3_96t_ds)
- * Synchronous factor of 3 oversample function optimised for use with voice optimised for XS3 (src_ff3_96t_us)
+ * Synchronous factor of 3 downsample function for use with voice optimized for XS3 (ff3_96t_ds)
+ * Synchronous factor of 3 oversample function for use with voice optimized for XS3 (ff3_96t_us)
 
- * Synchronous factor of 3/2 downsample function optimised for use with voice optimised for XS3 (src_rat_2_3_96t_ds)
- * Synchronous factor of 3/2 oversample function optimised for use with voice optimised for XS3 (src_rat_3_2_96t_us)
+ * Synchronous factor of 3/2 downsample function for use with voice optimized for XS3 (rat_2_3_96t_ds)
+ * Synchronous factor of 3/2 oversample function for use with voice optimized for XS3 (rat_3_2_96t_us)
 
 There are three different component options that support fixed factor of 3 up/downsampling. To help choose which one to use follow these steps:
 
- #. If you require HiFi quality (130 dB SNR) up/downsampling, use src_ds3_voice or src_us3_voice.
- #. If you require voice quality (65 dB SNR) and are using xCORE-200, use src_ds3_voice or src_us3_voice.
- #. If you require voice quality (75 dB SNR) and are using xCORE-AI, use src_ff3_96t_ds or src_ff3_96t_us.
+ #. If HiFi quality (130 dB SNR) up/downsampling is required, use ds3 or os3.
+ #. 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.
 
 
-Related application notes
+Related Application Notes
 .........................
 
 An adaptive USB Audio ASRC example can be found in https://github.com/xmos/sln_voice/tree/develop/examples.

doc/exclude-patterns.inc

@@ -7,9 +7,8 @@ build/*
 *.md
 **/*.md
 
-# Do not build the app docs
-# app_xvf3800/*
-# tools/*
-
-# Don't include libraries in user docs
-# lib_sw_pll/*
+# 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

doc/rst/overview.rst

@@ -1,18 +1,21 @@
-Fixed factor of 3 functions
-===========================
+Fixed factor of 3 HiFi functions
+================================
 
-The SRC library also includes synchronous sample rate conversion functions to downsample (decimate) and oversample (upsample or interpolate) by a fixed factor of three.
+Overview
+--------
+
+The SRC library includes synchronous sample rate conversion functions to downsample (decimate) and oversample (upsample or interpolate) by a fixed factor of 3.
 
 These components offer a high quality conversion with an SNR of 130 dB.
 
-In each case, the processing is carried out each time a single output sample is required. In the case of the decimator, three input samples passed to filter with a resulting one sample output on calling the processing function. The interpolator produces an output sample each time the processing function is called but will require a single sample to be pushed into the filter every third cycle. All samples use Q31 format (left justified signed 32b integer).
+In each case, the processing is carried out each time a single output sample is required. In the case of the decimator, three input samples are passed to the filter with a resulting one sample output on calling the processing function. The interpolator produces an output sample each time the processing function is called but will require a single sample to be pushed into the filter every third cycle. All samples use Q1.31 format (left justified signed 32b integer).
 
 Both sample rate converters are based on a 144 tap FIR filter with two sets of coefficients available, depending on application requirements:
 
- * firos3_b_144.dat / firds3_b_144.dat - These filters have 20dB of attenuation at the nyquist frequency and a higher cutoff frequency
- * firos3_144.dat / firds3_144.dat - These filters have 60dB of attenuation at the nyquist frequency but trade this off with a lower cutoff frequency
+ * firos3_b_144.dat / firds3_b_144.dat - These filters have 20 dB of attenuation at the Nyquist frequency and a higher cutoff frequency
+ * firos3_144.dat / firds3_144.dat - These filters have 60 dB of attenuation at the Nyquist frequency but trade this off with a lower cutoff frequency
 
-The default setting is to use the 60dB of attenuation at the nyquist frequency coefficients.
+The default setting is to use the coefficients that provide 60 dB of attenuation at the Nyquist frequency.
 
 The filter coefficients may be selected by adjusting the line::
 
@@ -24,18 +27,18 @@ and::
 
 in the files ``src_ff3_os3.h`` (API for oversampling) and ``src_ff3_ds3.h`` (API for downsampling) respectively.
 
-The OS3 processing takes up to 153 core cycles to compute a sample which translates to 1.53us at 100MHz or 2.448us at 62.5MHz core speed. This permits up to 8 channels of 16 kHz -> 48 kHz sample rate conversion in a single 62.5MHz core.
+The OS3 processing takes up to 153 core cycles to compute a sample which translates to 1.53 :math:`{\mu}s` at 100 MHz or 2.448 :math:`{\mu}s` at 62.5 MHz core speed. This permits up to 8 channels of 16 kHz -> 48 kHz sample rate conversion in a single 62.5MHz core.
 
-The DS3 processing takes up to 389 core cycles to compute a sample which translates to 3.89us at 100MHz or 6.224us at 62.5MHz core speed. This permits up to 9 channels of 48 kHz -> 16 kHz sample rate conversion in a single 62.5MHz core.
+The DS3 processing takes up to 389 core cycles to compute a sample which translates to 3.89 :math:`{\mu}s` at 100 MHz or 6.224 :math:`{\mu}s` at 62.5 MHz core speed. This permits up to 9 channels of 48 kHz -> 16 kHz sample rate conversion in a single 62.5MHz core.
 
-Both downsample and oversample functions return ``ERROR`` or  ``NOERROR`` status codes as defined in return codes enums listed below. The only way these functions can error is if the passed `delay_base` structure member has been uninitialised and is NULL.
+Both downsample and oversample functions return ``ERROR`` or  ``NO_ERROR`` status codes as defined in the return code enums listed below. The only way these functions can error is if the passed `delay_base` structure member is uninitialized (NULL).
 
-The down sampling functions return the following error codes ::
+The downsampling functions return the following error codes ::
 
   FIRDS3_NO_ERROR
   FIRDS3_ERROR
 
-The up sampling functions return the following error codes ::
+The upsampling functions return the following error codes ::
 
   FIROS3_NO_ERROR
   FIROS3_ERROR
@@ -70,15 +73,17 @@ OS3 API
 .. doxygenfunction:: src_os3_proc
 
 
-Fixed factor of 3 functions optimised for use with voice
+Fixed factor of 3 functions optimized for use with voice
 ========================================================
 
-A pair of SRC components supporting up and down coversion by a factor of 3 are provided that are suitable for voice applications. They provide voice quality SNR (around 60 dB),
-use a 72 tap Remez FIR filter and are optimised for the XS2 instruction set. 
+Overview
+--------
+
+A pair of SRC components supporting upconversion and downconversion by a factor of 3 are provided that are suitable for voice applications. They provide voice quality SNR (around 60 dB) and use a 72 tap Remez FIR filter and are optimized for the XS2 instruction set. 
 
 
 .. warning::
-    These SRC components have been deprecated. For new designs using xCORE-AI, please use the XS3 optimised components which provide both much better performance and use approximately half of the MIPS.
+    These SRC components have been deprecated. For new designs using XCORE-AI, please use the XS3 optimized components which provide both much better performance and use approximately half of the MIPS. See `ff3_voice_vpu_hdr`_
 
 ..
   .. doxygenvariable:: src_ff3v_fir_coefs_debug
@@ -101,28 +106,32 @@ Voice US3 API
 .. doxygenfunction:: src_us3_voice_get_next_sample
 
 
-Fixed factor of 3 and 3/2 functions optimised for XS3 (xCORE-AI) and for use in voice applications
-==================================================================================================
+Fixed factor of 3 and 3/2 voice functions optimized for XS3
+===========================================================
+
+Overview
+--------
 
-A set of SRC components are provided which are optimised for the Vector Processing Unit (VPU) and are suitable for voice applications.
+A set of SRC components are provided which are optimized for the Vector Processing Unit (VPU) and are suitable for voice applications.
 The fixed factor of 3 SRC components are designed for conversion between 48 kHz to 16 kHz and the fixed factor of 3/2 are designed for conversion between 48 kHz and 32 kHz.
 
-They have been designed for voice applications and, in particular, conformance to the MS Teams specification.
+They have been designed for voice applications and, in particular, conformance to the MS Teams v5 specification.
 
 
 .. note::
-    These filters will only run on xCORE-AI due to the inner dot product calculation employing the XS3 VPU.
-
+    These filters will only run on XCORE-AI due to the inner dot product calculation employing the XS3 VPU.
 
+.. _ff3_voice_vpu_hdr:
 Fixed factor of 3 VPU
 ---------------------
 
 The filters use less than half of the cycles of the previous fixed factor of 3 functions but at the same time offer a much improved
 filter response thanks to an increased filter length of 96 taps (compared with 72 taps) and use of a Kaiser window with a beta of 4.0.
+The filter specification is shown in :numref:`src_ff3_vpu_filter`.
 
-
+.. _src_ff3_vpu_filter:
 .. list-table:: Fixed Factor of 3 Voice VPU SRC characteristics
-     :header-rows: 1
+    :header-rows: 1
 
     * - Filter
       - CPU cycles
@@ -136,25 +145,26 @@ filter response thanks to an increased filter length of 96 taps (compared with 7
       - 0.475
       - 0.525
       - 0.01 dB
-      - 70 dB
+      - 70 dB min
       - 96
     * - src_ff3_96t_us
       - 85
       - 0.475
       - 0.525
       - 0.01 dB
-      - 70 dB
+      - 70 dB min
       - 96
 
-The fixed factor of three components produce three samples for each call passing one sample in the case of upsampling and produce a single sample for each call passing three samples in the case of downsampling.
-All input and output samples are signed 32 bit integers.
-
+The fixed factor of 3 components produce three samples for each call passing one sample in the case of upsampling and produce a single sample for each call passing three samples in the case of downsampling.
+All input and output samples are signed 32 bit integers. The filter characteristics are shown in :numref:`src_ff3_vpu` and :numref:`src_ff3_vpu_pb`.
 
+.. _src_ff3_vpu:
 .. figure:: images/src_ff3_vpu.png
    :width: 80%
 
    Fixed Factor of 3 Voice VPU SRC filter response
 
+.. _src_ff3_vpu_pb:
 .. figure:: images/src_ff3_vpu_pb.png
   :width: 80%
 
@@ -177,11 +187,11 @@ Voice US3 API
 Fixed factor of 3/2 VPU
 -----------------------
 
-The fixed factor of 3/2 VPU sample rate converts use a rational factor polyphase architecture to achieve the non-integer rate ratio. Downsampling takes two phases while upsampling takes three. The filters have been designed with a Kaiser window with a beta of 3.2.
-
+The fixed factor of 3/2 VPU sample rate converts use a rational factor polyphase architecture to achieve the non-integer rate ratio. Downsampling takes two phases while upsampling takes three. The filters have been designed with a Kaiser window with a beta of 3.2. The filter specification is shown in :numref:`src_ff3_2_vpu_filter`.
 
+.. _src_ff3_2_vpu_filter:
 .. list-table:: Fixed Factor of 3/2 Voice VPU SRC characteristics
-     :header-rows: 1
+    :header-rows: 1
 
     * - Filter
       - CPU cycles
@@ -205,29 +215,31 @@ The fixed factor of 3/2 VPU sample rate converts use a rational factor polyphase
       - 70 dB
       - 96
 
-The fixed factor of 3/2 components produce three samples for each call passing two samples in the case of upsampling and produce a two samples for each call passing three samples in the case of downsampling. 
-All input and output samples are signed 32 bit integers.
+The fixed factor of 3/2 components produce three samples for each call passing two samples in the case of upsampling and produce two samples for each call passing three samples in the case of downsampling. 
+All input and output samples are signed 32 bit integers. The filter characteristics are shown in :numref:`src_ff3_2_vpu` and :numref:`src_ff3_2_vpu_pb`.
 
 
+.. _src_ff3_2_vpu:
 .. figure:: images/src_rat_vpu.png
    :width: 80%
 
    Fixed Factor of 3/2 Voice VPU SRC filter response
 
+.. _src_ff3_2_vpu_pb:
 .. figure:: images/src_rat_vpu_pb.png
   :width: 80%
 
   Fixed Factor of 3/2 Voice VPU SRC passband ripple
 
 
 Voice DS3/2 API
--------------
+---------------
 
 .. doxygengroup:: src_rat_2_3_96t_ds
    :content-only:
 
 Voice US3/2 API
--------------
+---------------
 
 .. doxygengroup:: src_rat_3_2_96t_us
    :content-only:

doc/rst/programming_guide/fixed_ratio_src.rst

@@ -1,5 +1,5 @@
-Programmer Guide
-################
+Programming Guide
+#################
 
 .. include:: ../../../README.rst