lib_xcore_math

Library Info

Summary

lib_xcore_math is an arithmetic and DSP library which leverages the XS3 Vector Processing Unit (VPU) to accelerate costly operations on vectors of 16- or 32-bit data. Included are functions for block floating-point arithmetic, fast Fourier transforms, discrete cosine transforms, linear filtering and more.

Repository Structure

• /lib_xcore_math/ - The lib_xcore_math library directory.
  • api/ - Headers containing the public API for lib_xcore_math.
  • script/ - Scripts used for source generation.
  • src/ - Library source code.
• /doc/ - Sphinx library documentation source and build directory.
• /example/ - Example applications for lib_xcore_math.
• /test/ - Unit test projects for lib_xcore_math.

Requirements

• xTIMEcomposer tools version 15.0.6 or later
• CMake (for building the library and unit tests, version 3.14 or later)
• Doxygen (for building documentation)
• Python 3 (for running source generation scripts, if necessary)

The recommended make tools depend on the development platform:

(Linux and MacOS): GNU Make - Available through your system package manager.

Ninja (Windows): Ninja - Follow install instructions at https://ninja-build.org/ or on Windows install with winget by running the following commands in PowerShell:

# Install
winget install Ninja-build.ninja
# Reload user Path
$env:Path=[System.Environment]::GetEnvironmentVariable("Path","User")

API Structure

This library is organized around several sub-APIs. These APIs collect the provided operations into coherent groups based on the kind of operation or the types of object being acted upon.

The current APIs are:

• Block Floating-Point Vector API
• Vector/Array API
• Scalar API
• Linear Filtering API
• Fast Fourier Transform API
• Discrete Cosine Transform API

See the full documentation for more details about each of these as well as usage examples.

Getting and Building

Clone the Repository

To clone this repository you may use the following: :

git clone --recurse-submodules git@github.com:xmos/lib_xcore_math

Note

This repository uses submodules to include the XMOS CMake toolchain

Including lib_xcore_math in External Applications

lib_xcore_math can be compiled for both x86 platforms and xs3a processors.

On x86 platforms you can develop DSP algorithms and test them for functional correctness; this is an optional step before porting the library to an xs3a device.

Note

The instructions in this section refer to the compilation for xs3a; the steps to compile for the x86 platforms are the same, except that the XTC build tools are not necessary and the default toolchain must be used. This can be done by skipping the option --toolchain= pointing to xs3a.cmake when configuring CMake.

lib_xcore_math may be included in your own applications either as source to be compiled by your application or as a static library to be linked into your own application. This library uses CMake to manage build configurations.

On Linux and MacOS, to configure your CMake build environment for lib_xcore_math to compile for xs3a, from the root of the cloned repository, the following command may be used (ensure that the XTC build tools are on your path): :

mkdir build && cd build && cmake --toolchain=../etc/xmos_cmake_toolchain/xs3a.cmake ..

Then to actually build the library as a static binary just use the make command from the build directory.

The unit tests and example applications are built by default when running the commands above.

On Windows, to configure your CMake build environment for lib_xcore_math, from the root of the cloned repository, the following command may be used (ensure that the XTC build tools are on your path): :

mkdir build && cd build && cmake --toolchain=../etc/xmos_cmake_toolchain/xs3a.cmake -G Ninja ..

Then to actually build the library as a static binary just use the ninja command from the build directory.

The unit tests and example applications are built by default when running the commands above.

If you wish to include lib_xcore_math in your own application as a static library, the generated lib_xcore_math.a can then be linked into your own application. Be sure to also add lib_xcore_math/api as an include directory for your project.

To incorporate lib_xcore_math into your own CMake project, you have two options. You can either add /lib_xcore_math as a CMake subdirectory (via add_subdirectory()), which will include it as a static library. Or, to include it as a source library you can include /lib_xcore_math/lib_xcore_math.cmake in your application's CMake project, which will populate various CMake variables (prepended with LIB_XCORE_MATH_) with the source files, include directories and build flags required. See /lib_xcore_math/lib_xcore_math.cmake for the specific variables.

For other build systems

• Add lib_xcore_math/api as an include directory
• Add all .c files within lib_xcore_math/src/ except for those within lib_xcore_math/src/arch/ref
• Add all .S files within lib_xcore_math/src/arch/xs3 as source files
  • These are assembly files and should be compiled with xcc as are the C files.

Then, from your source files, include xmath/xmath.h.

Unit Tests and Examples

This project uses CMake to build the unit test and example applications. Use the steps described above to configure and build the unit test and example applications. Both unit test and example projects currently target the xcore.ai explorer board and x86 platforms. All unit tests are currently in the /test/ directory:

• /test/ - Unit test projects for lib_xcore_math:
  • bfp_tests/ - BFP unit tests
  • dct_tests/ - DCT unit tests
  • filter_tests/ - Filtering unit tests
  • fft_tests/ - FFT unit tests
  • scalar_tests/ - Scalar op unit tests
  • vect_tests/ - Vector op unit tests
  • xs3_tests/ - XS3-specific unit tests

All examples are currently in the /example/ directory:

• /example/ - Example projects for lib_xcore_math:
  • bfp_demo/ - BFP demo
  • filter_demo/ - Filtering demo
  • fft_demo/ - FFT demo
  • vect_demo/ - Vector op demo

Each example above has a ReadMe file with a short description.

All unit tests and examples are built and executed in a similar manner. The following shows how to do this with the BFP unit tests.

BFP Unit Tests

This application runs unit tests for the various 16- and 32-bit BFP vectorized arithmetic functions. This application is located at /test/bfp_tests/.

To execute the BFP unit tests on the explorer board, from your CMake build directory use the following (after ensuring that the hardware is connected and drivers properly installed): :

xrun --xscope test/bfp_tests/bfp_tests.xe

Or, to run the unit tests in the software simulator: :

xsim test/bfp_tests/bfp_tests.xe

Note that running the unit tests in the simulator may be very slow.

To execute the BFP unit tests built for an x86 host platform, from your CMake build directory run on Linux and MacOS: :

./test/bfp_tests/bfp_tests -v

and on Windows: :

test\bfp_tests\bfp_tests.exe -v

where -v is an optional argument to increase verbosity.

Building Documentation

The following information is intended for XMOS users. Pre-built documentation may be found on the XMOS website.

The documentation is built using the xmosdoc tool. Refer to it's readme for the build instructions.