DFU operations (UA only)#

The Device Firmware Update (DFU) allows updating the firmware of the device from a host machine. The XVF3800 v2.0.0 supports only upgrades for the UA device over USB Endpoint 0.

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.

Setting up the host machine#

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.

After installing the dfu-util(.exe) application, only Windows requires some extra steps to install the correct USB driver. The following instructions must be followed:

  1. Connect the XVF3800 board to the host PC using a USB cable.

  2. If some USB driver has been installed for the XMOS Control (Interface 3) as described in xvf_host application setup, the device must be disabled by using Device Manager:

    1. Open Device Manager and find the XMOS Control (Interface 3), this is usually located under the libusb-win32 devices.

    2. Right click on the interface and select Disable device as shown below:

    ../../_images/07_device_manager_disable_control_1.png

    Fig. 32 Disable the control device in Device Control#

    1. Click Yes if the message below appears:

    ../../_images/07_device_manager_disable_control_2.png

    Fig. 33 Accept warning message#

Note

The driver can be re-enabled again by selecting Enable device after a right-click on the device in Device Manager

  1. Download the third-party installation tool Zadig from https://zadig.akeo.ie/.

  2. Open Zadig and select XMOS DFU Factory (Interface 4) from the list of devices. If the device is not present, ensure Options -> List All Devices is checked.

  3. Select WinUSB from the list of drivers.

  4. Click the Install Driver button and wait for the installation to complete.

../../_images/07_zadig_install_dfu.png

Fig. 34 Selecting the WinUSB driver in Zadig for the DFU Interface#

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.2.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.

Examples of DFU operations#

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

Note

All the commands in this section use the default USB Vendor and Product ID of the XVF3800-UA device: 0x20b1 and 0x4f00. The customer will need to use the correct ones if they are changed.

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

dfu-util(.exe) -h

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 the following:

(sudo) dfu-util(.exe) -d 0x20b1:0x4f00 -a 1 -D [UPGRADE_BINARY] -R

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.

Warning

If the download operation fails and the first data blocks have been transferred to the device, the device must be rebooted before another DFU download is performed. If this is not done, the host application incorrectly reports the last operation as successful. After the reboot the device will use 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 the following command:

(sudo) dfu-util(.exe) -d 0x20b1:0x4f00 -a 1 -e

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

Upload the images from the device#

The DFU upload operation allows the user to read the factory and upgrade images of the XVF3800-UA. 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 is the following:

(sudo) dfu-util(.exe) -d 0x20b1:0x4f00 -a [ALTSETTING] -U [IMAGE_BINARY]

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.

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.