DFU operations#

The Device Firmware Update (DFU) allows updating the firmware of the device from a host computer. The XVF3800 supports two different implementations of the DFU protocol: one over USB for the UA device and one over I2C for the INT device.

Only one upgrade image may be transferred to the flash of the XVF3800. The first upgrade image will be replaced by a subsequent upgrade process. The factory image cannot be overwritten and in case of DFU failure, the factory settings will be restored after rebooting the device.

Note

The DFU procedures of XVF3800 only support a transfer block size of 256 bytes over USB and 128 bytes over I2C.

Setting up the host computer (UA)#

The UA build of the XVF3800 firmware is compliant with dfu-util. This is a host side implementation of the DFU 1.0 and DFU 1.1 specifications of the USB forum. The software is licensed under the GPL version 2. The instructions to download and install the application can be found in https://dfu-util.sourceforge.net/. The XVF3800 is compatible with the default release binaries from https://dfu-util.sourceforge.net/releases/. The host app is available for Linux, macOS, Raspberry Pi OS and Windows.

Note

In the rest of this document when using the dfu-util app in the code examples, the command is written as (sudo) dfu-util(.exe). The .exe extension is only required on Windows. The sudo command is only required on Linux, macOS and Raspberry Pi OS if the user does not have the necessary permissions to access the device. On these platforms it may be necessary to use ./ before the command if the directory containing the dfu_util app is not in the PATH.

Setting up the host computer (INT)#

The INT build of the XVF3800 firmware is able to perform DFU over an I2C interface, using a custom implementation closely following that set out by the USB Device Class Specification for DFU, Version 1.1. An example host application is included for the Raspberry Pi to showcase this implementation and to provide guidelines on how a custom compliant host application may be written. To use this application:

  1. Set up the device as described in Hardware Setup - I2S (INT-Device) Configuration.

  2. Extract xvf_dfu, libdevice_i2c.so, dfu_cmds.yaml, and transport_config.yaml from the XVF3800 release package; these will be located in the host_v<version>\rpi directory.

  3. The application may now be run from a terminal. Sudo privileges are required.

Generation of Binary Upgrade Image#

The upgrade executable (.xe) needs to be converted into a binary format. Use xflash and the following command to convert the .xe application into a binary form:

xflash --noinq --factory-version 15.2 --upgrade [UPGRADE_VERSION] [UPGRADE_EXECUTABLE] -o [OUTPUT_BINARY]

Specify --factory-version value of 15.2 for all 15.3.x releases of the XTC tools. (The 15.2 value refers to boot loader API for the XTC tool chain).

Note

Should a different version of the XTC tools be used in a future firmware release, the tools version number should be noted such that an update image of compatible format can be created. The --factory-version must match the tools version used to build the factory image.

The UPGRADE_VERSION number is the 16-bit format 0xJJMP of the executable firmware where:

  • J is major

  • M is minor

  • P is patch

UPGRADE_EXECUTABLE is the path to the .xe application to convert. OUTPUT_BINARY is the path to the binary to generate.

The dfu-util application issues a warning if a suffix is not added to the upgrade binary. The suffix can be added using the dfu-suffix host application from https://dfu-util.sourceforge.net/dfu-suffix.1.html. The xvf_dfu application issues no such warning.

Examples of DFU operations#

Using either the dfu-util application or the xvf_dfu application the following operations can be performed.

Note

All the commands in this section that relate to the dfu-util application use the XMOS-supplied USB Vendor ID and USB Product ID for the XVF3800-UA device:

  • Vendor ID 0x20b1, and either

  • Product ID 0x4f00 for 48 kHz sample rate, or

  • Product ID 0x4f01 for 16 kHz sample rate.

These values will change if the customer has used their own Vendor ID and Product ID.

The options used in the rest of the section are described in more detail in either the help menu of dfu-util(.exe):

dfu-util(.exe) -h

or the help menu of xvf_dfu:

xvf_dfu -h

A more detailed description of the I2C implementation and its control process may be found in Section 2 of the Programming Guide.

Download an upgrade image to the device#

The DFU download operation allows the user to upgrade the firmware of the XVF3800-UA. The command to do that is one of the following:

(sudo) dfu-util(.exe) -d 20b1:4f00 -a 1 -D [UPGRADE_BINARY] -R # 48 kHz sample rate
(sudo) dfu-util(.exe) -d 20b1:4f01 -a 1 -D [UPGRADE_BINARY] -R # 16 kHz sample rate

where -a 1 is fixed and it indicates the altsetting for the upgrade image, and UPGRADE_BINARY is the path to the upgrade binary generated as described in Generation of Binary Upgrade Image. The -R option will trigger a reboot of the device after the download is complete.

For the INT build of the device, the command sequence is the following:

sudo xvf_dfu -u i2c -d [UPGRADE_BINARY]
sudo xvf_dfu -u i2c -r

where UPGRADE_BINARY is the path to the upgrade binary generated as described in Generation of Binary Upgrade Image, -u i2c selects I2C as the transport medium over which to send the device control commands (currently the only supported medium), and -r forces a reboot of the device. Should the download operation fail, both the xvf_dfu and dfu-util applications will exit with an error code. Another download operation may be reattempted; should this continue to fail, rebooting the device will reset the device into the factory image, as any pre-existing upgrade image has been corrupted by the failed DFU operation.

Revert the device to factory image#

To restore the device to its factory configuration, effectively discarding any upgrades made, the same process as outlined above is followed but using a blank upgrade image. This is the only way a restore can be initiated, as the device does not have the ability to restore itself.

The blank file can be generated using dd on MAC and Linux, and fsutil on Windows. A blank image can be created with a file of zeroes the size of one flash sector. In the normal case of 4KB sectors on a UNIX-compatible platform, this can be created as follows:

dd bs=4096 count=1 < /dev/zero 2>/dev/null blank.bin

and for Windows systems:

fsutil file createNew blank.bin 4096

This process outlined in the DFU download operation section can now be followed using blank.bin file as UPGRADE_BINARY.

Reboot the device#

The dfu-util application can be used to reboot the device via the USB interface. This can be done with one of the following commands:

(sudo) dfu-util(.exe) -d 20b1:4f00 -a 0 -e # 48 kHz sample rate
(sudo) dfu-util(.exe) -d 20b1:4f01 -a 0 -e # 16 kHz sample rate

In this command either -a 0 and -a 1 are valid.

Via the I2C interface, xvf_dfu may be used as:

sudo xvf_dfu -u i2c -r

Upload the images from the device#

The DFU upload operation allows the user to read the factory and upgrade images of the XVF3800. This feature is useful for debugging purposes, for example to provide XMOS with the exact firmware used on a device. The command to do that in the UA build is one of the following:

(sudo) dfu-util(.exe) -d 20b1:4f00 -a [ALTSETTING] -U [IMAGE_BINARY] # 48 kHz sample rate
(sudo) dfu-util(.exe) -d 20b1:4f01 -a [ALTSETTING] -U [IMAGE_BINARY] # 16 kHz sample rate

where ALTSETTING is 0 for the factory image and 1 for the upgrade image, and IMAGE_BINARY is the path to the binary to store the image read from the device.

For the I2C implementation, xvf_dfu may be used as:

sudo xvf_dfu -u i2c -uf [IMAGE_BINARY]

to read the factory image to IMAGE_BINARY, or:

sudo xvf_dfu -u i2c -uu [IMAGE_BINARY]

to read the upgrade image to IMAGE_BINARY.

The uploaded upgrade image should match the same image created in Generation of Binary Upgrade Image, but without any extra suffix.

The uploaded factory image contains the bootloader data and the image obtained using the command:

xflash [FACTORY_EXECUTABLE] -o [OUTPUT_BINARY]

where FACTORY_EXECUTABLE is the path to the .xe application flashed on the device and OUTPUT_BINARY is the path to the binary to generate.

Note

All the images uploaded from the device have some padding bytes, so that their size is a multiple of DFU transfer size. This value is set to 256 bytes by default in UA and 128 bytes in INT.

Error handling#

The XVF3800 device supports the following errors, and they are used only during the download operation:

  • errWRITE: this error is returned if the host sends a download request for the wrong partition, for example the factory partition

  • errADDRESS: this error is returned if the host sends a data block outside the address range of the memory partition, for example if the image is too large.

During the download operations, the device expects to receive the data blocks in the correct order, and it writes them to the flash as soon as they are received. The sequence number included in the download messages is not checked by the device.

If the following happens during a download or upload phase:

  • the operations are interrupted by the host

  • the device returns a DFU error

if the device is version 3.1.0 or higher, the user can restart the operation from the beginning of the image. For older versions, the device must be rebooted before resuming the DFU procedure. Resuming a download operation midway through an image is not supported in any version.

If the image downloaded to the device is not correct, for example if any data is corrupted or if the download is not completed, the upgrade image will be replaced, but after rebooting the bootloader will deem the upgrade image invalid, and the device will load the factory image.