forked from PAWPAW-Mirror/lib_xua
Initial file tidy-up. Created app_xua_simple.
This commit is contained in:
xross
1
doc_dfu/Makefile
Normal file
1
doc_dfu/Makefile
Normal file
@@ -0,0 +1 @@
|
||||
SOURCE_INCLUDE_DIRS=../host/xmosdfu
|
||||
18
doc_dfu/building_xmos_dfu.rst
Normal file
18
doc_dfu/building_xmos_dfu.rst
Normal file
@@ -0,0 +1,18 @@
|
||||
.. _usb_audiosec_building_xmos_dfu:
|
||||
|
||||
Building the XMOS DFU loader - macOS
|
||||
====================================
|
||||
|
||||
The XMOS DFU loader is provided as source as part of the USB Audio
|
||||
framework, located in sc_usb_audio/module_dfu/host/xmos_dfu_osx.
|
||||
|
||||
The loader is compiled using libusb, the code for the loader is contained in the
|
||||
file ``xmosdfu.cpp``
|
||||
|
||||
To build the loader a Makefile is provided, which can be run as follows:
|
||||
|
||||
``make -f Makefile.OSX all``
|
||||
|
||||
This Makefile contains the following:
|
||||
|
||||
.. literalinclude:: Makefile.OSX
|
||||
91
doc_dfu/factory_image.rst
Normal file
91
doc_dfu/factory_image.rst
Normal file
@@ -0,0 +1,91 @@
|
||||
Creating factory and upgrade images with XFLASH
|
||||
===============================================
|
||||
|
||||
Installing the factory image to the device
|
||||
------------------------------------------
|
||||
|
||||
The DFU device interface is enabled by default in the XMOS USB Audio framework
|
||||
(see ``devicedefines.h``), and explicitly enabled in each reference design
|
||||
by the following line included in the ``customdefines.h`` file of each
|
||||
application::
|
||||
|
||||
#define DFU (1)
|
||||
|
||||
Use the XMOS Development Tools to run the command:
|
||||
|
||||
``xflash --boot-partition-size 0x30000 --factory usb_audio.xe``
|
||||
|
||||
Where the size passed using the ``--boot-partition-size n`` argument specifies
|
||||
in bytes the minimum size required to store the boot loader, factory image and
|
||||
any upgrade images.
|
||||
|
||||
The following can be used as a guide to help calculate the required boot
|
||||
partition size for a design:
|
||||
|
||||
- boot partition size = loader size + maximum size of factory image +
|
||||
maximum size of upgrade images + padding to sector boundaries
|
||||
|
||||
Where:
|
||||
|
||||
- loader size = 0x1000 bytes, or 0x4000 bytes if secure boot functionality is
|
||||
used (for tools version 13.1.0 and older)
|
||||
- maximum size of factory image = number of xCORE tiles *
|
||||
xCORE SRAM size
|
||||
- maximum size of upgrade images = (number of xCORE tiles *
|
||||
xCORE SRAM size) * number of images to be held in flash concurrently
|
||||
|
||||
The above example sets the boot partition to a size appropriate for designs
|
||||
based on a single xCORE tile, where a single upgrade image is required
|
||||
in flash at any one time.
|
||||
|
||||
This programs the factory default firmware image into the flash device.
|
||||
The device will now support the DFU mechanism, and can use it to safely receive
|
||||
firmware updates, as well as revert to the factory firmware image when required,
|
||||
such as in the event of a failed upgrade attempt.
|
||||
|
||||
Creating the upgrade image
|
||||
--------------------------
|
||||
|
||||
To use the firmware upgrade mechanism you need to build a firmware upgrade
|
||||
image:
|
||||
|
||||
#. Edit the ``customdefines.h`` file of the application for the hardware in use,
|
||||
and change the Device Version Number by defining ``BCD_DEVICE``.
|
||||
#. Rebuild the application.
|
||||
|
||||
To generate the firmware upgrade image run the following command:
|
||||
|
||||
``xflash --factory-version 13 --upgrade 1 usb_audio.xe -o new_firmware.bin``
|
||||
|
||||
Where the tools version passed using the ``--factory-version version``
|
||||
argument specifies the version of the tools used to create the factory image.
|
||||
This should be passed as ``12`` for images created using tools versions 10, 11
|
||||
and 12.
|
||||
|
||||
The ``--upgrade id xe-file [size]`` argument specifies xe-file as an upgrade
|
||||
image with version ``id``. Each version number must be a unique number greater
|
||||
than 0.
|
||||
|
||||
You should now have the file ``new_firmware.bin`` which contains the
|
||||
firmware with the newly specified Device Version Number.
|
||||
|
||||
Related documents
|
||||
-----------------
|
||||
|
||||
.. only :: latex
|
||||
|
||||
For further details of the DFU features included in the XMOS USB Audio
|
||||
framework and their configuration please see the "Device Firmware Upgrade
|
||||
(DFU)" (:ref:`usb_audio_sec_dfu`) and the "Configuration Defines"
|
||||
(:ref:`sec_custom_defines_api`) sections of the USB Audio Design Guide.
|
||||
|
||||
.. only :: html
|
||||
|
||||
For further details of the DFU features included in the XMOS USB Audio
|
||||
framework and their configuration please see the :ref:`usb_audio_sec_dfu`
|
||||
and the :ref:`sec_custom_defines_api` sections of the USB Audio Design
|
||||
Guide.
|
||||
|
||||
For further details on the use of XFLASH to create factory and upgrade firmware
|
||||
images please see the XFLASH Command-Line Manual section of the
|
||||
`xTIMEcomposer User Guide <https://www.xmos.com/published/xtimecomposer-user-guide>`_.
|
||||
10
doc_dfu/index.rst
Normal file
10
doc_dfu/index.rst
Normal file
@@ -0,0 +1,10 @@
|
||||
DFU loader for XMOS USB AUDIO devices
|
||||
=====================================
|
||||
|
||||
.. toctree::
|
||||
|
||||
Overview <overview>
|
||||
Creating factory and upgrade images with XFLASH <factory_image>
|
||||
Using the DFU loader - Windows (via the Thesycon driver) <thesycon_dfu>
|
||||
Using the DFU loader - macOS (via the XMOS DFU loader) <xmos_dfu>
|
||||
Building the XMOS DFU loader - macOS <building_xmos_dfu>
|
||||
21
doc_dfu/overview.rst
Normal file
21
doc_dfu/overview.rst
Normal file
@@ -0,0 +1,21 @@
|
||||
Overview
|
||||
========
|
||||
|
||||
The DFU loader is a flash device firmware upgrade mechanism. To work correctly
|
||||
your development board must contain the latest DFU enabled firmware.
|
||||
|
||||
The firmware upgrade for XMOS USB devices implementation uses the USB standard
|
||||
DFU device class mechanism and is based on the following specification:
|
||||
http://www.usb.org/developers/devclass_docs/DFU_1.1.pdf
|
||||
|
||||
Supported functionality:
|
||||
|
||||
- Download of new firmware to device
|
||||
- Upload of existing firmware from device
|
||||
- Revert device back to factory image
|
||||
- Automatic reboot of device on firmware upgrade
|
||||
|
||||
You must use XMOS Development Tools version 10.4.1 (or later).
|
||||
|
||||
The DFU device on Windows requires the Theyscon USB Audio 2.0 Windows driver
|
||||
version 1.13.3 or later.
|
||||
70
doc_dfu/thesycon_dfu.rst
Normal file
70
doc_dfu/thesycon_dfu.rst
Normal file
@@ -0,0 +1,70 @@
|
||||
Using the DFU loader - Windows (via the Thesycon driver)
|
||||
========================================================
|
||||
|
||||
Thesycon provide both GUI and CLI DFU tools, TUSBAudioDfu.exe and dfucons.exe
|
||||
respectively. The use of the GUI tool is not covered by this document.
|
||||
|
||||
The correct installation of the Thesycon driver and DFU tools exceeds
|
||||
the scope of this document.
|
||||
|
||||
Set up the image loader
|
||||
-----------------------
|
||||
|
||||
Run the DFU console tool (``dfucons.exe``) from the Thesycon install folder,
|
||||
in a Command Prompt by navigating to:
|
||||
|
||||
``C:\Program Files\Thesycon\TUSBAudio_Driver\``
|
||||
|
||||
To check the device has been detected, run the following command in the DFU
|
||||
console:
|
||||
|
||||
``dfucons info``
|
||||
|
||||
The console shows the DFU devices that have been detected.
|
||||
|
||||
Download new firmware
|
||||
---------------------
|
||||
|
||||
To program the new firmware run the command:
|
||||
|
||||
``dfucons download new_firmware.bin``
|
||||
|
||||
Note that once this is done the device restarts. The original factory default
|
||||
application is still present but the device is now running the upgraded
|
||||
application firmware.
|
||||
|
||||
You can check the device has been updated by running the command:
|
||||
|
||||
``dfucons info``
|
||||
|
||||
This will display the device revision.
|
||||
|
||||
Uploading existing firmware from the device
|
||||
-------------------------------------------
|
||||
|
||||
You can retrieve a firmware image from the device, providing an upgrade image is
|
||||
present.
|
||||
Run the command:
|
||||
|
||||
``dfucons upload currentfirmware.bin``
|
||||
|
||||
The file ``currentfirmware.bin`` contains the latest upgrade image. This file is
|
||||
an exact copy of the data from the flash and can be downloaded to the device
|
||||
again to test.
|
||||
|
||||
Reverting firmware to factory image
|
||||
-----------------------------------
|
||||
|
||||
To revert the device back to its factory (i.e XFLASH) installed state from the
|
||||
new firmware, run the command:
|
||||
|
||||
``dfucons revertfactory``
|
||||
|
||||
The device will now be running, and only contain the factory firmware, which can
|
||||
be seen by checking the device version once more.
|
||||
|
||||
Related documents
|
||||
-----------------
|
||||
|
||||
For further details on the use of the Thesycon DFU tools please see
|
||||
`Thesycon USB Audio 2.0 Driver for Windows User Manual <https://www.xmos.com/published/usb-audio-class-20-evaluation-driver-windows>`_.
|
||||
49
doc_dfu/xmos_dfu.rst
Normal file
49
doc_dfu/xmos_dfu.rst
Normal file
@@ -0,0 +1,49 @@
|
||||
Using the DFU loader - macOS (via the XMOS DFU loader)
|
||||
======================================================
|
||||
|
||||
The XMOS DFU loader is provided as source as part of the XMOS USB Audio software
|
||||
framework, see :ref:`usb_audiosec_building_xmos_dfu`.
|
||||
|
||||
Set up the image loader
|
||||
-----------------------
|
||||
|
||||
#. Open a terminal
|
||||
#. Change directory to where the loader has been built
|
||||
#. Run the command:
|
||||
|
||||
``source setup.sh``
|
||||
|
||||
Download new firmware
|
||||
---------------------
|
||||
|
||||
To program the new firmware run the command:
|
||||
|
||||
``./xmosdfu --download new_firmware.bin``
|
||||
|
||||
Note that once this is done the device restarts. The original factory default
|
||||
application is still present but the device is now running the upgraded
|
||||
application firmware.
|
||||
|
||||
Uploading existing firmware from the device
|
||||
-------------------------------------------
|
||||
|
||||
You can retrieve a firmware image from the device, providing an upgrade image is
|
||||
present.
|
||||
|
||||
Run the command:
|
||||
|
||||
``./xmosdfu --upload currentfirmware.bin``
|
||||
|
||||
The file ``currentfirmware.bin`` contains the latest upgrade image. This file is
|
||||
an exact copy of the data from the flash and can be downloaded to the device
|
||||
again to test.
|
||||
|
||||
Reverting firmware to factory image
|
||||
-----------------------------------
|
||||
|
||||
To revert the device back to its factory (i.e XFLASH) installed state from the
|
||||
new firmware, run the command:
|
||||
|
||||
``./xmosdfu --revertfactory``
|
||||
|
||||
The device will now be running, and only contain the factory firmware.
|
||||
Reference in New Issue
Block a user