Fixes for doc build (#270)
Document moving and rename. Fixes for latest xdoc.
This commit is contained in:
Ross Owen
GitHub
56
doc/dfu/rst/building_xmos_dfu.rst
Normal file
56
doc/dfu/rst/building_xmos_dfu.rst
Normal file
@@ -0,0 +1,56 @@
|
||||
.. _usb_audiosec_building_xmos_dfu:
|
||||
|
||||
Building the XMOS DFU loader
|
||||
============================
|
||||
|
||||
The XMOS DFU loader is provided as source as part of the USB Audio
|
||||
framework, located in lib_xua/host/xmosdfu.
|
||||
|
||||
The loader is compiled using libusb, the code for the loader is contained in the
|
||||
file ``xmosdfu.cpp``
|
||||
|
||||
macOS
|
||||
-----
|
||||
|
||||
To build the loader a Makefile is provided, which can be run as follows:
|
||||
|
||||
``make -f Makefile.OSX64 all``
|
||||
|
||||
This Makefile contains the following:
|
||||
|
||||
.. literalinclude:: Makefile.OSX64
|
||||
|
||||
There is also a 32bit OS X makefile, ``Makefile.OSX32``.
|
||||
|
||||
Linux
|
||||
-----
|
||||
|
||||
Similarly to macOS, there are two Linux makefiles provided, ``Makefile.Linux32`` and ``Makefile.Linux64``:
|
||||
|
||||
.. literalinclude:: Makefile.Linux64
|
||||
|
||||
System-wide libusb is used. On Debian-derived systems this can be installed with:
|
||||
|
||||
``apt-get install libusb-1.0.0-dev``
|
||||
|
||||
Raspberry Pi
|
||||
------------
|
||||
|
||||
A makefile is provided for Raspbian. libusb is required and can be installed using the ``apt-get`` command from previous Linux section.
|
||||
|
||||
.. literalinclude:: Makefile.Pi
|
||||
|
||||
Windows
|
||||
-------
|
||||
|
||||
To build on Windows, you must first install Visual Studio 2019 Build Tools with
|
||||
C++ support. `This is available from Microsoft's website. <https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019>`_
|
||||
|
||||
To build, open a Developer Command Prompt via the start menu and navigate to the
|
||||
xmosdfu folder. The command to build is as follows:
|
||||
|
||||
``nmake /f Makefile.Win32``
|
||||
|
||||
This Makefile contains the following:
|
||||
|
||||
.. literalinclude:: Makefile.Win32
|
||||
10
doc/dfu/rst/dfu.rst
Normal file
10
doc/dfu/rst/dfu.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 <building_xmos_dfu>
|
||||
91
doc/dfu/rst/factory_image.rst
Normal file
91
doc/dfu/rst/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>`_.
|
||||
21
doc/dfu/rst/overview.rst
Normal file
21
doc/dfu/rst/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/rst/thesycon_dfu.rst
Normal file
70
doc/dfu/rst/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>`_.
|
||||
3
doc/dfu/rst/xdoc.conf
Normal file
3
doc/dfu/rst/xdoc.conf
Normal file
@@ -0,0 +1,3 @@
|
||||
XMOSNEWSTYLE=2
|
||||
SOURCE_INCLUDE_DIRS=../../../lib_xua/host/xmosdfu
|
||||
SPHINX_MASTER_DOC=dfu
|
||||
55
doc/dfu/rst/xmos_dfu.rst
Normal file
55
doc/dfu/rst/xmos_dfu.rst
Normal file
@@ -0,0 +1,55 @@
|
||||
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`.
|
||||
|
||||
NOTE: Windows requires the installation of libusbK drivers on the DFU endpoint.
|
||||
We recommend using `Zadig <https://zadig.akeo.ie/>`_.
|
||||
|
||||
Set up the image loader
|
||||
-----------------------
|
||||
|
||||
#. Open a terminal
|
||||
#. Change directory to where the loader has been built
|
||||
#. Point DYLD_LIBRARY_PATH to libusb/OSX64:
|
||||
|
||||
``export DYLD_LIBRARY_PATH=$PWD/libusb/OSX64:$DYLD_LIBRARY_PATH``
|
||||
|
||||
Download new firmware
|
||||
---------------------
|
||||
|
||||
To program the new firmware run the command:
|
||||
|
||||
``./bin/xmosdfu XMOS_L2_AUDIO2_PID --download new_firmware.bin``
|
||||
|
||||
Replace ``XMOS_L2_AUDIO2_PID`` with product ID of your target device. Invoke
|
||||
``xmosdfu`` with no arguments to get a list of all supported product IDs.
|
||||
|
||||
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:
|
||||
|
||||
``./bin/xmosdfu XMOS_L2_AUDIO2_PID --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:
|
||||
|
||||
``./bin/xmosdfu XMOS_L2_AUDIO2_PID --revertfactory``
|
||||
|
||||
The device will now be running, and only contain the factory firmware.
|
||||
Reference in New Issue
Block a user