Firmware release package¶

There are two release packages available for the XVF3610, one for the XVF3610-UA and one for the XVF3610-INT.

Release packages and firmware builds are identified via a version number, which follows the standard semantic version specification. The version number format is X.Y.Z, eg 5.2.0, and these numbers have the following meaning.

Table 3 Firmware version number structure¶
Digit	Name	Meaning
X	Major version number	Significant release of the firmware. The control interface may not be backwards compatible with earlier versions
Y	Minor version number	New features added, but the control interface is backwards compatible with earlier host applications
Z	Patch version number	Bug fixes for incorrect functionality only. No change to host interface

The release version is contained in the file name of firmware file distribution and can also be read via the control interface using the GET_VERSION command.

Each package consists of several directories and files containing released firmware binaries, data-partition tools, host binaries and host source code. A simplified directory structure is shown below.

├── bin
|    ├── dfu
|    |    └── <config>
│    ├── spi_boot
|    |    └── <config>
│    └── xflash
|         └── <config>
├── data-partition
|    └── input
└── host
     ├── Linux
     │    └── bin
     ├── MAC
     │    └── bin
     ├-─ Pi
     |    ├── bin
     │    └── scripts
     ├── Win32
     │    └── bin
     └── src
          ├── dfu
          ├── dpgen
          └── vfctrl

Note

<config> in the structure above refers to the configurations supported by the firmware release package. See the System Architecture section for further details on these configurations.

The contents of the main top level directories are shown below:

“bin” Directory¶

Note

Structure has changed in version 5.6 - firmware and corresponding default datapartition images are now in the same folder

This directory contains the released firmware for the XVF3610. There are different versions of the firmware which are stored in separate subdirectories:

xflash - Firmware intended for loading from an external flash device. This process is described in Updating Firmware below.

dfu An image that can be used to upgrade an operational system using the Device Firmware Update process.

spi_boot Firmware for loading from an external host over SPI (XVF3610 is the slave). Please refer to the SPI Slave boot section of the datasheet for connections to the external boot source.

See the System Boot and Initial Configuration section of the User Guide for further information on of the process of installing and updating the firmware for the XVF3610.

“data-partition” Directory¶

The data partition contains configuration data for the XVF3610 firmware, implemented as a set of commands that are run at boot time. The data partition is created using input command source files and a set of tools which are described in the Data Partition section of this document. The contents of the data-partition directory are as follows:

The root directory contains default data partition image source files (int.json or ua.json) as well as the generic flash device specification 16mbit_12.5mhz_sector_4kb.spispec, data partition generation scripts and short instructions about how to generate data partition binary files.

For convenience, the pre-generated data partition binary files generated from these default data partition image source files are contained in the “bin” directory (see above). These files are suitable for direct programming into the external flash along with the firmware, should the default settings be suitable.

The input subdirectory contains short command sequences which are referenced by the data partition image source file when the data partition binary file is generated.

In addition, an output directory is created during the running of the data partition generation script which contains the newly generated data partition binary file.

“host” Directory¶

This directory contains files and utilities relating to the host. The various host utilities that perform parameter control, device firmware update (DFU) and data partition generation are provided pre-compiled for Linux (ARM and x86), Windows and MacOS platforms. These binaries can be found in the Linux, Pi, Mac and Win32 directories along with an additional script for the Raspberry Pi release called send_image_from_rpi.py which provides an example of sending an SPI boot image from the host.

The root of the host directory also contains scripts for unpacking packed signals which can be captured using the controls described in the signal routing section of this document.

Instructions for building the host utilities from the source are also provided in the same directory. The source files for the host utilities are contained in the src sub-directory allowing building, modification or integration into other projects.

Within this directory there are three further sub-directories dfu, dpgen and vfctrl which contain the source files (and dependent libraries) for the DFU, data partition generator and parameter control utilities.

Required Tools¶

In order to update the firmware, modify and regenerate Data Partitions and rebuild the host utilities the following tools are required.

XTC Tools¶

The XMOS XTC Tools contains a comprehensive suite of tools for compilation, debug and programming of XMOS devices. It is available to download from https://www.xmos.ai/software-tools

Note

At the time of writing v15.1 of XTC Tools is recommend for programming XVF3610 firmware. More recent versions may be available, but unless specified on the xmos.ai website they will not have been tested and verified for operation with XVF3610.

Further information about the full tool suite, including installation instructions for different platforms is available here in the XTC Tools user guide, available from https://www.xmos.ai/file/tools-user-guide

Updating Firmware¶

The XVF3610 Voice Processor is provided in two pre-compiled builds (-UA and -INT) and as such only requires the usage of one of the XTC Tools programming tools, specifically xflash. This operates as a command-line application, to create the boot image, and if using flash, program the boot image to the attached device.

An XTAG debugger must be connected to the XVF3610 for flash programming operations. Refer to the Development Kit User Guide for information on using XTAG connections to XVF3610 development kits.

The basic form of the xflash command for flash image creation and programming with a data partition is as follows (note multiple lines have been used for clarity, but command should be executed on single line).

xflash --boot-partition-size 0x100000 --factory [Application executable (.xe)] --data [Data partition description (.bin)]

Note

Boot over SPI from a host processor uses a specific image which is supplied in the release package. No data partition is included as configuration command are assumed to be supplied by the host controller used.

Application executable (.xe) The .xe file is a boot image provided with a VocalFusion release package in one of the supported configurations (-UA or -INT product variants).
Data partition description (.bin) The .bin file is a data partition description either supplied in the release package (-UA or -INT) or customised as described later in this guide.

Warning

Running XTC Tools on macOS Catalina or above may trigger a security alert. The process to resolve this is detailed here : https://www.xmos.ai/file/running-XTimecomposer-on-macos-catalina/

Python 3¶

Some operations, such as running the SPI boot example on the Raspberry Pi, require the use of Python 3 (v3.7 onward is recommended). Python can be downloaded from http://python.org/downloads.

Host build tools¶

The release package contains executable versions of the host tools. The source code is also indluded to provide the option for users to customise these tools. In order to build the host utilities, the use of a platform-specific compiler is required.

Windows

The host utilities are built with the x86 Native Tools Command Prompt for VS which is installed as part of the Build Tools for Visual Studio. This can be downloaded from Microsoft website (at the time of writing latest versions available here: https://visualstudio.microsoft.com/downloads. It is important to ensure that the optional C++ CMake tools for Windows are included when setting up the installation.

For cross-platform support vfctrl_usb uses libusb. This requires the installation of a driver for use on a Windows host. Driver installation should be done using a third-party installation tool like Zadig (https://zadig.akeo.ie/).

Linux

Depending on the distribution and version of Linux used, the following packages may need to be installed:

sudo apt-get install -y build-essential
sudo apt-get install -y pkg-config
sudo apt-get install -y libusb-1.0-0-dev

Mac OS

The XCode Command Line tools are required to build in on macOS. The following command can be used to install the tools.

xcode-select --install