Building the Application Firmware#

Introduction#

The XVF3800 comprises a specialised xcore.ai processor and a firmware executable. A set of firmware images is provided in the binary release package which are configured to run correctly on the XK-VOICE-SQ66 evaluation kit. However, when using the XVF3800 in a product design it is normally necessary to modify the firmware to match the hardware and to configure a number of settings. This is achieved by modification of the configuration files supplied as source code and rebuilding the modified code to create a new firmware image.

Instructions on configuring the firmware is included in the [ FINAL - link to section] Tuning the application section

This section explains how to build the XVF3800 application from the source files.

Prerequisites#

The XVF3800 source code can be build on Windows, MacOS and Linux platforms.

Note

An active internet connection is required as part of the process as the build scripts download additional packages to configure the environment.

The XVF3800 build procedure requires that a set of 3rd Party software packages, listed below, are installed on a development computer before attempting to build firmware for the XVF3800.

Python3#

A standard installation of Python version 3.9 or higher should be present on the development machine. This is available by default on some platforms, but if required it can be installed from https://www.python.org/downloads/

The pip3 package manager included in the standard python configuration is used to install some tools and python is required to run some setup and tuning tools.

XMOS tools#

XTC Tools 15.2.x : This is the XMOS toolchain which allows users to compile, link, deploy and debug applications on all XMOS processors.

The XTC Tools can be downloaded from https://www.xmos.ai/software-tools/ and installed on a development machine following the instructions in the https://www.xmos.ai/view/Tools-15-Documentation. XTC tools can run on Windows, MacOS and Linux platforms.

Build Tools#

CMake >= version 3.21.0 : CMake is a build tool for managing application compilation.

The CMake tool package can be installed following the instructions for your specific platform at https://cmake.org/install/

XVF3800 Release Package#

The XVF3800 firmware is supplied in two different release packages which are distributed as ZIP archive files with the following contents:

  1. Binary release - a set of pre-compiled images that will run on the XK-VOICE-SQ66 evaluation kit

  2. Source release - Source code and libraries to allow customisation of the XVF3800

This section describes how to use the second package.

Release packages can be obtained from FINAL www.xmos.ai/xxx or your XMOS representative.

Load ZIP archive onto your development plaform and expand the archive into a convenient directory. The contents of the source release package are shown below:

.
├── CHANGELOG.rst    <- list of changes of current and past releases
├── LICENSE.rst      <- license file
├── precompiled      <- folder containing the precompiled libraries
├── README.md        <- readme file
└── sources          <- source files necessary to build  XVF3800 applications

The user modifiable code is found in the sources/applications folder.

Standard Configurations#

The XVF3800 release package contains a set of standard build configurations that will suit the majority of use cases for the XVF3800 device. The table below lists the key configuration parameters.

Table 23 Build-time combinable parameters#

Parameter

Options

Abbreviation

Notes

Device configuration
INT Device
INT Host
USB
-intdev
-inthost
-usb
Note - only intdev is avalable in |version|

I2S LR clock rate
16000
48000
-lr16
-lr48

Select sampling rate for I2S interface

USB IN sample rate
16000
48000
-i16
-i48

Only valid in USB configuration; ignored for INT configurations.

USB OUT sample rate
16000
48000
-o16
-o48

Only valid in USB configuration; ignored for INT configurations.

Input/output bit depth
24
32
-b24
-b32

Only valid in USB configuration; implicitly 32b for INT configurations.

Microphone geometry
Linear
Square or circular
-lin
-sqr

Selects microphone configuration on EVK board

Control protocol
|I2C|
SPI
-i2c
-spi

Selects which interface is used for the device control.

Audio MCLK

Use external MCLK signal
-extmclk

Only valid on intdev configuration. Should be omitted if external MCLK not used.

Note

USB support is not available in XVF3800 v 1.0 so the USB options above are not shown in the build presets at this time.

Image Names#

The XVF3800 built image names comprise the parameter abbreviations listed above in a set order:

|project|-<device config>-<sample rate>-<mic geometry>-<control protocol>-<audio MCLK>

Examples:

xvf3800-inthost-lr48-sqr-i2c

xvf3800-intdev-lr48-lin-spi-extmclk

Build Process#

Set up the environment#

Note

The software packages in the Prerequisites section must be installed before starting this process.

To build the XVF3800 application, open a command-line terminal and ensure that the XMOS tools are configured in the environment. This can be checked by typing

xcc --version

which should display the tools version information. If this does not happen please consult the Configuring the command-line environment section of https://www.xmos.ai/software-tools/ at https://www.xmos.ai/view/Tools-15-Documentation.

Configure the build system#

The build process comprises of two phases - the first phase sets up the build environment and downloads key components while the second phase builds a specific executable. Configuration is only required to be done once.

To set up the environment change directory to the sources directory of the release package and install the required Python3 packages.

cd sources

pip3 install -r requirements_build.txt

Then configure the build. This step can take several minutes.

cmake --preset=rel_app_xvf3800

When this is complete the XVF3800 build system will have been configured.

Build an executable#

The next phase is to build a specific executable. The release package contains a set of preset configurations that cover the main use case for the XVF3800 device.

To see the available build presets use

cmake --build --list-presets

The naming scheme for these presets is defined in the Standard Configurations section above.

Select the preset you wish and start the build. For example to build a 16kHz I2S configuration with a square microphone array and I2C control the command is:

cmake --build --preset=intdev-lr16-sqr-i2c

The script will compile all the source file and when it completes the generated binary file is saved in the subdirectory output.

The required executable binary will be named application_xvf3800_intdev-<build options>.xe. As an example the result of the build command above would be:

output/application_xvf3800_intdev-lr16-sqr-i2c.xe.

Installing the Executable Image#

Two methods exist to install on the XVF3800 hardware the executable image created in the previous section, using the xrun and xflash tools that are suppled in the XTC Tools suite.

Both methods require a connection between a development computer and the XVF3800 via an XTAG4 debug adapter. Instructions to set up the XK-VOICE-SQ66 evaluation kit can be found in the Setting up the hardware [FINAL add link] section of this guide.

Install Using xrun#

The xrun tool loads the executable image into the XVF3800 RAM without storing it in the XVF3800 Flash ROM. It then starts the operation of the XVF3800 using this executable image. Using the example from above the required command is:

xrun application_xvf3800_intdev-lr16-sqr-i2c.xe

Install Using xflash#

The xflash tool stores the executable image in the XVF3800 Flash ROM. A subsequent power-cycle loads the stored image into the XVF3800 RAM and starts its operation. Using the same example from above the required command is:

xlflash application_xvf3800_intdev-lr16-sqr-i2c.xe

Using SPI Boot#

Creating a SPI Boot File#

To use the built application_xvf3800_[..].xe executable generated from the above process as a SPI boot image it is necessary to convert the .xe image into a .bin file that includes a bootloader.

The files required to build this .bin image can be found in the sources/boot_spi_slave directory of the release package.

Warning

This procedure requires the XTC tools to be installed on a development computer. It cannot be run on the Raspberry Pi host.

To create a SPI boot image change into the scripts folder:

cd sources/scripts

and then generate the binary image using the following command:

python3 generate_image.py path/to/application_xvf3800_[..].xe

An SPI bootable file application_xvf3800_[..]_spi_boot.bin will be created in the output subdirectory.

Using a SPI Boot File#

The SPI boot process is documented in the XVF3800 datasheet. An example script is provided in the release package which uses a Raspberry Pi to transfer the image and boot the XVF3800 device on an XK-VOICE-SQ66 evaluation kit.

Note

The Raspberry Pi must be setup as described in the setting up the hardware section for this script to operate correctly.

The script can be found in sources/boot_spi_slave/scripts subdirectory. The _spi_boot.bin image generated using the procedure described above can be transferred to the XVF3800 device using the following command.

python3 send_image_from_rpi.py output/application_xvf3800_[..]_spi_boot.bin

The example script will need to be modified to if this procedure is executed other host systems.