.. include:: ../../README.rst

Introduction
------------

The XMOS xCORE-200 DSP Elements Library provides foundation Digital
Signal Processing functions.

The library is split into the following modules :

   * Adaptive Filters - dsp_adaptive.h
   * Filtering - dsp_filters.h
   * Basic Math - dsp_math.h
   * Matrix Math - dsp_matrix.h
   * Statistics - dsp_statistics.h
   * Vectors - dsp_vector.h
   * FFT and inverse FFT - dsp_fft.h

The library supports variable Q formats from Q8 to Q31, using the
macros in the following header file : dsp_qformat.h.

The Downsample and Oversample functions are fixed Q31 format.

Getting Started
---------------

Ensure you are in the xTIMEcomposer edit perspective by clicking on the Edit perspective button on the left hand side toolbar.

In the Project Explorer view you will see the following applications :

   * Adaptive Filters - app_adaptive
   * Filtering - app_filters
   * Basic Math - app_math
   * Matrix Math - app_matrix
   * Statistics - app_statistics
   * Vectors (Real and Complex) - app_vector
   * FFT and inverse FFT - app_fft
   * FFT Processing of signals received through a double buffer - app_fft_double_buf

The applications contain code to generate the simulation data and call all of the functions in each module and print the results in the xTIMEcomposer console.

Build the applications
......................

To build the application, select ‘Project -> Build Project’ in the menu, or click the ‘Build’ button on the toolbar. The output from the compilation process will be visible on the console.
Note that some applications offer different configurations. Particular Build Configurations can be selected by clicking the small arrow next to the Build Icon (Hammer). 

Create and launch a run configuration
.....................................

To run or debug the application, you have to initially create a run or debug configuration. The xTIMEcomposer allows multiple configurations to exist, thus allowing you to store configurations for running on different targets/with different runtime options and arguments.
Right-click on the generated binary in the *Project Explorer* view, and select *Run As -> Run Configurations*.
To debug, select *Run As -> Debug Configurations*.

In the resulting dialog, double click on *xCORE Application*, then perform the following operations:

   * On the *Main* tab select the desired Hardware Target, or check the *simulator* option.
   * Select the Run button to launch the application.

The results will be displayed in the xTIMEcomposer *console* tab.

Using The DSP Library In Other Applications
-------------------------------------------

Makefile Additions For These Examples
.....................................

To start using the DSP Library, you need to add lib_dsp to your Makefile::

  USED_MODULES = ... lib_dsp ...

Including The Library Into Your Source Code
...........................................

In order to use any of these modules and the Q formats it is
only necessary to include the following header file::

  #include "dsp.h"

|appendix|

.. _references:

References
----------
  
.. nopoints::

  * XMOS Tools User Guide

    http://www.xmos.com/published/xtimecomposer-user-guide

  * XMOS xCORE Programming Guide

    http://www.xmos.com/published/xmos-programming-guide
  
  * XMOS DSP Library

    http://www.xmos.com/support/libraries/lib_dsp

  * XMOS Sample Rate Conversion Library

    https://www.xmos.com/published/lib_src-userguide

  * xCORE-200: The XMOS XS2 Architecture (ISA)
  
    https://www.xmos.com/published/xs2-isa-specification


Full Source Code Listings
-------------------------

This section includes the source code for all of the example programs.

Adaptive Filtering Functions
............................

.. literalinclude:: ../../app_adaptive/src/app_adaptive.xc
  :largelisting:

|newpage|

Fixed Coefficient Filtering Functions
.....................................

.. literalinclude:: ../../app_filters/src/app_filters.xc
  :largelisting:

|newpage|

Math Functions
..............

.. literalinclude:: ../../app_math/src/app_math.xc
  :largelisting:

|newpage|

Matrix Functions
................

.. literalinclude:: ../../app_matrix/src/app_matrix.xc
  :largelisting:

|newpage|

Statistics Functions
....................

.. literalinclude:: ../../app_statistics/src/app_statistics.xc
  :largelisting:

|newpage|

Vector Functions
................

.. literalinclude:: ../../app_vector/src/app_vector.xc
  :largelisting:

|newpage|

FFT and inverse FFT
...................

**Note:** The method for processing two real signals with a single complex FFT was improved.
It now requires only half the memory. See Build Configurations tworeals and tworeals_int16_buf.

.. literalinclude:: ../../app_fft/src/app_fft.xc
  :largelisting:

|newpage|

FFT Processing of signals received through a double buffer
..........................................................

.. literalinclude:: ../../app_fft_double_buf/src/app_fft_double_buf.xc
  :largelisting:

|newpage|


Correct Results Listings
------------------------

This section includes the source code for all of the example programs.

Adaptive Filtering Functions
............................

.. literalinclude:: ../../../tests/adaptive_test.expect
  :largelisting:

|newpage|

Fixed Coefficient Filtering Functions
.....................................

.. literalinclude:: ../../../tests/filters_test.expect
  :largelisting:

|newpage|

Math Functions
..............

.. literalinclude:: ../../../tests/math_test.expect
  :largelisting:

|newpage|

Matrix Functions
................

.. literalinclude:: ../../../tests/matrix_test.expect
  :largelisting:

|newpage|

Statistics Functions
....................

.. literalinclude:: ../../../tests/statistics_test.expect
  :largelisting:

|newpage|

Vector Functions
................

.. literalinclude:: ../../../tests/vector_test.expect
  :largelisting:

|newpage|

