init

lib_audio_dsp/doc/rst/03_dsp_components/index.rst

@@ -0,0 +1,39 @@
+.. raw:: latex
+
+    \newpage
+
+.. _dsp_components_section:
+
+DSP Components
+##############
+
+`lib_audio_dsp` provides many common signal processing functions optimised
+for xcore. These can be combined together to make complex audio pipelines
+for many different applications, such as home audio, music production,
+voice processing, and AI feature extraction.
+
+The library is split into 2 levels of API: DSP stages and DSP modules.
+Both APIs provide similar DSP functionality, but are suited to different
+use cases.
+
+The higher-level APIs are called :ref:`dsp_stages_section`. These stages are designed
+to work with the Python DSP pipeline tool. This tool allows developers
+to quickly and easily create, test, and deploy DSP pipelines without
+needing to write a lot of code. By using DSP stages, the user can build
+complex audio processing workflows in a short amount of time, making it
+ideal for rapid prototyping and development.
+
+The lower-level APIs are called :ref:`dsp_modules_section`. They are meant to be
+used as an API directly in cases where the Python DSP pipeline tool is 
+not used. These modules can be useful when integrating DSP functionality into an
+existing system, or as a starting point for creating bespoke DSP
+functions.
+
+.. toctree::
+    :maxdepth: 1
+
+    gen/stages
+    modules
+    q_format
+    precision
+    latency

lib_audio_dsp/doc/rst/03_dsp_components/latency.rst

@@ -0,0 +1,21 @@
+Latency
+=======
+
+The latency of the DSP pipeline is dependent on the number of threads. By default, the DSP pipeline
+is configured for one sample of latency per thread. All current DSP modules have zero inbuilt
+latency (except where specified e.g. delay stages). For pipelines that fit on a single thread,
+this means the total pipeline latency is 1 sample.
+
+The pipeline can also be configured to use a higher frame size. This increases latency, but can
+reduce compute for simple functions, as the function overhead is shared. For a pipeline consisting of just biquads:
+
+
+.. table::
+  :widths: 15, 15, 15, 15, 15
+
+  ==========  =======  ==================  ===================  ======================
+  Frame size  Latency  % thread per frame  % thread per sample  Max biquads per thread
+  ==========  =======  ==================  ===================  ======================
+  1           1        4.0%                4.0%                 25
+  8           8        13.3%               1.7%                 60
+  ==========  =======  ==================  ===================  ======================

lib_audio_dsp/doc/rst/03_dsp_components/modules.rst

@@ -0,0 +1,53 @@
+
+DSP Modules List
+================
+
+This a list of all the modules that can be used independently without the DSP pipeline tool:
+
+- :ref:`biquad_filters`
+
+  * :ref:`Biquad`
+  * :ref:`BiquadSlew`
+  * :ref:`CascadedBiquads`
+  * :ref:`CascadedBiquads16`
+
+- :ref:`drc`
+
+  * :ref:`EnvelopeDetectorPeak`
+  * :ref:`EnvelopeDetectorRMS`
+  * :ref:`Clipper`
+  * :ref:`LimiterPeak`
+  * :ref:`HardLimiterPeak`
+  * :ref:`LimiterRMS`
+  * :ref:`CompressorRMS`
+  * :ref:`CompressorSidechain`
+  * :ref:`CompressorSidechainStereo`
+  * :ref:`NoiseGate`
+  * :ref:`NoiseSuppressorExpander`
+
+- :ref:`geq`
+
+  * :ref:`GraphicEq10b`
+
+- :ref:`fir`
+
+  * :ref:`FirDirect`
+  * :ref:`FirBlockTD`
+  * :ref:`FirBlockFD`
+
+- :ref:`reverb`
+
+  * :ref:`ReverbRoom`
+  * :ref:`ReverbRoomStereo`
+  * :ref:`ReverbPlateStereo`
+
+- :ref:`signal_chain`
+
+  * :ref:`Adder`
+  * :ref:`Subtractor`
+  * :ref:`FixedGain`
+  * :ref:`Mixer`
+  * :ref:`VolumeControl`
+  * :ref:`Delay`
+  * :ref:`SwitchSlew`
+  * :ref:`Crossfader`

lib_audio_dsp/doc/rst/03_dsp_components/precision.rst

@@ -0,0 +1,23 @@
+Precision
+=========
+
+.. note::
+    For fixed point Q formats this document uses the format QM.N, where M is the number of bits
+    before the decimal point (excluding the sign bit), and N is the number of bits after the decimal
+    point. For an int32 number, M+N=31.
+
+By default, the signal processing in the audio pipeline is carried out at 32 bit fixed point
+precision in Q4.27 format. Assuming a 24 bit input signal in Q0.24 format, this gives 4 bits of internal headroom in
+the audio pipeline, which is equivalent to 24 dB. The output of the audio pipeline will be clipped back to Q0.24 before
+returning. For more precision, the pipeline can be configured to run with no headroom
+in Q0.31 format, but this requires manual headroom management. More information on setting the Q
+format can be found in the :ref:`library_q_format_section` section.
+
+DSP algorithms are implemented either on the XS3 CPU or VPU (vector processing unit).
+
+CPU algorithms are typically implemented as 32-bit x 32-bit operations into 64-bit results and
+accumulators, before rounding back to 32-bit outputs.
+
+The VPU allows for 8 simultaneous operations, with a small cost in precision. VPU algorithms are
+typically implemented as 32-bit x 32-bit operations into 34-bit results and 40-bit accumulators,
+before rounding back to 32-bit outputs.

lib_audio_dsp/doc/rst/03_dsp_components/q_format.rst

@@ -0,0 +1,64 @@
+.. _library_q_format_section:
+
+################
+Library Q Format
+################
+
+.. note::
+    For fixed point Q formats this document uses the format QM.N, where M is the number of bits
+    before the decimal point (excluding the sign bit), and N is the number of bits after the decimal
+    point. For an int32 number, M+N=31.
+
+By default, the signal processing in the audio pipeline is carried out at 32 bit fixed point
+precision in Q4.27 format. Assuming a 24 bit input signal in Q0.24 format, this gives 4 bits of
+internal headroom in the audio pipeline.
+
+Most modules in this library assume that the signal is in a specific global Q format.
+This format is defined by the ``Q_SIG`` macro. An additional macro for the signal exponent,
+``SIG_EXP`` is defined, where ``SIG_EXP = - Q_SIG``.
+
+.. doxygendefine:: Q_SIG
+
+.. doxygendefine:: SIG_EXP
+
+To ensure optimal headroom and noise floor, the user should ensure that signals are in the correct
+Q format before processing. Either the input Q format can be converted to ``Q_SIG``, or ``Q_SIG``
+can be changed to the desired value. When using the DSP pipeline too, the Q format is automatically
+converted. The user should ensure that 0 dBFS is aligned with the maximum int32 value.
+
+.. note::
+   Not using the DSP pipeline tool means that Q formats
+   will not automatically be managed, and the user should take care to ensure they have the correct
+   values for optimum performance and signal level.
+
+For example, for more precision, the pipeline can be configured to run with no headroom
+in Q0.31 format, but this would require manual headroom management (e.g. reducing the signal level
+before a boost to avoid clipping).
+
+If not using the DSP pipeline tool, the APIs below provide conversions between ``Q_SIG`` and Q0.31
+in a safe and optimised method, assuming that 0 dBFS is aligned with the maximum int32 value.
+
+.. doxygenfunction:: adsp_from_q31
+
+.. doxygenfunction:: adsp_to_q31
+
+To convert a 16 bit audio signal into the Q_SIG format and back, the following functions can be used:
+
+.. code-block:: c
+
+    // input signal in Q0.15 format
+    int16_t signal = 1234;
+
+    // Convert to Q0.31
+    int32_t sig_32 = ((int32_t)signal) << 16;
+
+    // Convert to Q_SIG
+    sig_32 = adsp_from_q31(sig_32);
+
+    // Do some processing here
+
+    // Convert back to Q0.31
+    sig_32 = adsp_to_q31(sig_32);
+
+    // Convert back to 16 bit without dithering
+    signal = (int16_t)(sig_32 >> 16);