Merge pull request #130 from xmos/feature/dfu

Add DFU to STLP UA and update docs

doc/user_guide/stlp/stlp.rst

@@ -141,6 +141,83 @@ From the build folder run:
         nmake run_example_stlp_int_adec
         nmake run_example_stlp_ua_adec
 
+--------------------
+Upgrading the Firmware
+--------------------
+
+The UA variants of this application contain DFU over the USB DFU Class V1.1 transport method.
+
+To create an upgrade image from the build folder run:
+
+.. tab:: Linux and Mac
+
+    .. code-block:: console
+
+        make create_upgrade_img_example_stlp_ua_adec
+        make create_upgrade_img_example_stlp_ua_adec_altarch
+
+.. tab:: Windows
+
+    .. code-block:: console
+
+        nmake create_upgrade_img_example_stlp_ua_adec
+        nmake create_upgrade_img_example_stlp_ua_adec_altarch
+
+Once the application is running, a USB DFU v1.1 tool can be used to perform various actions.  This example will demonstrate with dfu-util commands.  Installation instructions for respective operating system can be found `here <https://dfu-util.sourceforge.net/>`__
+
+To verify the device is running run:
+
+.. code-block:: console
+
+    dfu-util -l
+
+This should result in an output containing:
+
+.. code-block:: console
+
+    Found DFU: [20b1:0020] ver=0001, devnum=100, cfg=1, intf=3, path="3-4.3", alt=2, name="DFU DATAPARTITION", serial="123456"
+    Found DFU: [20b1:0020] ver=0001, devnum=100, cfg=1, intf=3, path="3-4.3", alt=1, name="DFU UPGRADE", serial="123456"
+    Found DFU: [20b1:0020] ver=0001, devnum=100, cfg=1, intf=3, path="3-4.3", alt=0, name="DFU FACTORY", serial="123456"
+
+The DFU interprets the flash as 3 separate partitions, the read only factory image, the read/write upgrade image, and the read/write data partition containing the filesystem.
+
+The factory image can be read back by running:
+
+.. code-block:: console
+
+    dfu-util -e -d 0020 -a 0 -U readback_factory_img.bin
+
+The factory image can not be written to.
+
+From the build folder, the upgrade image can be written by running:
+
+.. code-block:: console
+
+    dfu-util -e -d 0020 -a 1 -D example_stlp_ua_adec_upgrade.bin
+    dfu-util -e -d 0020 -a 1 -D example_stlp_ua_adec_altarch_upgrade.bin
+
+The upgrade image can be read back by running:
+
+.. code-block:: console
+
+    dfu-util -e -d 0020 -a 1 -U readback_upgrade_img.bin
+
+On system reboot, the upgrade image will always be loaded if valid.  If the upgrade image is invalid, the factory image will be loaded.  To revert back to the factory image, you can upload an file containing the word 0xFFFFFFFF.
+
+The data partition image can be read back by running:
+
+.. code-block:: console
+
+    dfu-util -e -d 0020 -a 2 -U readback_data_partition_img.bin
+
+The data partition image can be written by running:
+
+.. code-block:: console
+
+    dfu-util -e -d 0020 -a 2 -D readback_data_partition_img.bin
+
+Note that the data partition will always be at the address specified in the initial flashing call.
+
 ----------------------
 Debugging the Firmware
 ----------------------

examples/stlp/bsp_config/XK_VOICE_L71/XK_VOICE_L71.cmake

@@ -20,6 +20,7 @@ target_link_libraries(sln_voice_app_stlp_board_support_xk_voice_l71
         rtos::drivers::general
         rtos::drivers::audio
         rtos::drivers::usb
+        rtos::drivers::dfu_image
         sln_voice::app::stlp::dac::dac3101
 )
 target_compile_options(sln_voice_app_stlp_board_support_xk_voice_l71
@@ -39,8 +40,6 @@ target_compile_definitions(sln_voice_app_stlp_board_support_xk_voice_l71
         PLATFORM_SUPPORTS_TILE_3=0
         USB_TILE_NO=0
         USB_TILE=tile[USB_TILE_NO]
-        # MIC_ARRAY_CONFIG_MCLK_FREQ=24576000
-        # MIC_ARRAY_CONFIG_MCLK_FREQ=12288000
         MIC_ARRAY_CONFIG_PDM_FREQ=3072000
         MIC_ARRAY_CONFIG_SAMPLES_PER_FRAME=240
         MIC_ARRAY_CONFIG_MIC_COUNT=2

examples/stlp/bsp_config/XK_VOICE_L71/platform/driver_instances.c

@@ -29,3 +29,6 @@ rtos_i2c_slave_t *i2c_slave_ctx = &i2c_slave_ctx_s;
 
 static rtos_spi_slave_t spi_slave_ctx_s;
 rtos_spi_slave_t *spi_slave_ctx = &spi_slave_ctx_s;
+
+static rtos_dfu_image_t dfu_image_ctx_s;
+rtos_dfu_image_t *dfu_image_ctx = &dfu_image_ctx_s;

examples/stlp/bsp_config/XK_VOICE_L71/platform/driver_instances.h

@@ -11,6 +11,7 @@
 #include "rtos_i2s.h"
 #include "rtos_mic_array.h"
 #include "rtos_qspi_flash.h"
+#include "rtos_dfu_image.h"
 #include "rtos_spi_slave.h"
 
 /* Tile specifiers */
@@ -56,5 +57,6 @@ extern rtos_i2c_master_t *i2c_master_ctx;
 extern rtos_i2c_slave_t *i2c_slave_ctx;
 extern rtos_spi_slave_t *spi_slave_ctx;
 extern rtos_i2s_t *i2s_ctx;
+extern rtos_dfu_image_t *dfu_image_ctx;
 
 #endif /* DRIVER_INSTANCES_H_ */

examples/stlp/bsp_config/XK_VOICE_L71/platform/platform_conf.h

@@ -162,4 +162,56 @@
 #define appconfSPI_TASK_PRIORITY                (configMAX_PRIORITIES/2)
 #endif /* appconfSPI_TASK_PRIORITY */
 
+/*****************************************/
+/*  DFU Settings                         */
+/*****************************************/
+#define FL_QUADDEVICE_W25Q64JW \
+{ \
+    0,                      /* Just specify 0 as flash_id */ \
+    256,                    /* page size */ \
+    32768,                  /* num pages */ \
+    3,                      /* address size */ \
+    4,                      /* log2 clock divider */ \
+    0x9F,                   /* QSPI_RDID */ \
+    0,                      /* id dummy bytes */ \
+    3,                      /* id size in bytes */ \
+    0,                      /* device id */ \
+    0x20,                   /* QSPI_SE */ \
+    4096,                   /* Sector erase is always 4KB */ \
+    0x06,                   /* QSPI_WREN */ \
+    0x04,                   /* QSPI_WRDI */ \
+    PROT_TYPE_SR,           /* Protection via SR */ \
+    {{0x18,0x00},{0,0}},    /* QSPI_SP, QSPI_SU */ \
+    0x02,                   /* QSPI_PP */ \
+    0xEB,                   /* QSPI_READ_FAST */ \
+    1,                      /* 1 read dummy byte */ \
+    SECTOR_LAYOUT_REGULAR,  /* mad sectors */ \
+    {4096,{0,{0}}},         /* regular sector sizes */ \
+    0x05,                   /* QSPI_RDSR */ \
+    0x01,                   /* QSPI_WRSR */ \
+    0x01,                   /* QSPI_WIP_BIT_MASK */ \
+}
+
+#ifndef BOARD_QSPI_SPEC
+/* Set up a default SPI spec if the app has not provided
+ * one explicitly.
+ * Note: The version checks only work in XTC Tools >15.3.0 
+ *       By default FL_QUADDEVICE_AT25FF321A is used 
+ */
+#ifdef __XMOS_XTC_VERSION_MAJOR__
+#if (__XMOS_XTC_VERSION_MAJOR__ == 15)      \
+    && (__XMOS_XTC_VERSION_MINOR__ >= 2)    \
+    && (__XMOS_XTC_VERSION_PATCH__ >= 0)
+/* In XTC >15.2.0 some SFDP support enables a generic 
+ * default spec
+ */
+#define BOARD_QSPI_SPEC     FL_QUADDEVICE_DEFAULT
+#else
+#define BOARD_QSPI_SPEC     FL_QUADDEVICE_W25Q64JW
+#endif
+#else
+#define BOARD_QSPI_SPEC     FL_QUADDEVICE_W25Q64JW
+#endif /* __XMOS_XTC_VERSION_MAJOR__ */
+#endif /* BOARD_QSPI_SPEC */
+
 #endif /* PLATFORM_CONF_H_ */

examples/stlp/bsp_config/XK_VOICE_L71/platform/platform_init.c

@@ -25,6 +25,20 @@ static void mclk_init(chanend_t other_tile_c)
 static void flash_init(void)
 {
 #if ON_TILE(FLASH_TILE_NO)
+    fl_QuadDeviceSpec qspi_spec = BOARD_QSPI_SPEC;
+    fl_QSPIPorts qspi_ports = {
+        .qspiCS = PORT_SQI_CS,
+        .qspiSCLK = PORT_SQI_SCLK,
+        .qspiSIO = PORT_SQI_SIO,
+        .qspiClkblk = FLASH_CLKBLK,
+    };
+
+    rtos_dfu_image_init(
+            dfu_image_ctx,
+            &qspi_ports,
+            &qspi_spec,
+            1);
+
     rtos_qspi_flash_init(
             qspi_flash_ctx,
             FLASH_CLKBLK,
@@ -47,7 +61,7 @@ static void flash_init(void)
             qspi_io_sample_edge_falling,
             0,
 
-            qspi_flash_page_program_1_4_4);
+            qspi_flash_page_program_1_1_4);
 #endif
 }
 

examples/stlp/src/main.c

@@ -340,6 +340,7 @@ void startup_task(void *arg)
 
 #if ON_TILE(FS_TILE_NO)
     rtos_fatfs_init(qspi_flash_ctx);
+    rtos_dfu_image_print_debug(dfu_image_ctx);
 #endif
 
 #if appconfWW_ENABLED && ON_TILE(WW_TILE_NO)

examples/stlp/src/usb/tusb_config.h

@@ -44,7 +44,7 @@
 #define CFG_TUSB_DEBUG             0
 #endif
 
-#define CFG_TUSB_MEM_ALIGN         __attribute__ ((aligned(4)))
+#define CFG_TUSB_MEM_ALIGN         __attribute__ ((aligned(8)))
 
 #define CFG_TUSB_DEBUG_PRINTF     rtos_printf
 
@@ -67,6 +67,13 @@
 #define CFG_TUD_MIDI              0
 #define CFG_TUD_AUDIO             1
 #define CFG_TUD_VENDOR            0
+#define CFG_TUD_DFU         1
+
+//--------------------------------------------------------------------
+// DFU DRIVER CONFIGURATION
+//--------------------------------------------------------------------
+// DFU buffer size, it has to be set to the buffer size used in TUD_DFU_DESCRIPTOR
+#define CFG_TUD_DFU_XFER_BUFSIZE    4096
 
 //--------------------------------------------------------------------
 // AUDIO CLASS DRIVER CONFIGURATION

examples/stlp/src/usb/usb_descriptors.c

@@ -115,11 +115,11 @@ const uint16_t tud_audio_desc_lengths[CFG_TUD_AUDIO] = {
         uac2_total_descriptors_length
 };
 
-#define CONFIG_TOTAL_LEN        (TUD_CONFIG_DESC_LEN + CFG_TUD_AUDIO * uac2_total_descriptors_length)
+#define CONFIG_TOTAL_LEN        (TUD_CONFIG_DESC_LEN + (CFG_TUD_AUDIO * uac2_total_descriptors_length) + TUD_DFU_DESC_LEN(DFU_ALT_COUNT))
 #define EPNUM_AUDIO   0x01
 
-
 #define AUDIO_INTERFACE_STRING_INDEX 4
+#define DFU_INTERFACE_STRING_INDEX   5
 
 uint8_t const desc_configuration[] = {
     // Interface count, string index, total length, attribute, power in mA
@@ -196,6 +196,9 @@ uint8_t const desc_configuration[] = {
     TUD_AUDIO_DESC_CS_AS_ISO_EP(/*_attr*/ AUDIO_CS_AS_ISO_DATA_EP_ATT_NON_MAX_PACKETS_OK, /*_ctrl*/ AUDIO_CTRL_NONE, /*_lockdelayunit*/ AUDIO_CS_AS_ISO_DATA_EP_LOCK_DELAY_UNIT_MILLISEC, /*_lockdelay*/ 0x0003),
 #endif
 
+    // Interface number, Alternate count, starting string index, attributes, detach timeout, transfer size
+    TUD_DFU_DESCRIPTOR(ITF_NUM_DFU_MODE, DFU_ALT_COUNT, DFU_INTERFACE_STRING_INDEX, DFU_FUNC_ATTRS, 1000, CFG_TUD_DFU_XFER_BUFSIZE),
+
     }; // desc_configuration
 
 // Invoked when received GET CONFIGURATION DESCRIPTOR
@@ -213,10 +216,13 @@ uint8_t const* tud_descriptor_configuration_cb(uint8_t index)
 
 // array of pointer to string descriptors
 char const *string_desc_arr[] = {(const char[]) {0x09, 0x04}, // 0: is supported language is English (0x0409)
-        "XMOS",                     // 1: Manufacturer
-        XCORE_VOICE_PRODUCT_STR,          // 2: Product
-        "123456",                   // 3: Serials, should use chip ID
-        XCORE_VOICE_PRODUCT_STR          // 4: Audio Interface
+        "XMOS",                      // 1: Manufacturer
+        XCORE_VOICE_PRODUCT_STR,     // 2: Product
+        "123456",                    // 3: Serials, should use chip ID
+        XCORE_VOICE_PRODUCT_STR,     // 4: Audio Interface
+        "DFU FACTORY",               // 5: DFU device
+        "DFU UPGRADE",               // 6: DFU device
+        "DFU DATAPARTITION",         // 7: DFU device
         };
 
 static uint16_t _desc_str[32];

examples/stlp/src/usb/usb_descriptors.h

@@ -25,9 +25,15 @@ enum {
 #if AUDIO_INPUT_ENABLED
     ITF_NUM_AUDIO_STREAMING_MIC,
 #endif
+    ITF_NUM_DFU_MODE,
     ITF_NUM_TOTAL
 };
 
+// Number of DFU alt interfaces
+#define DFU_ALT_COUNT                   3
+// DFU functional attributes
+#define DFU_FUNC_ATTRS (DFU_ATTR_CAN_UPLOAD | DFU_ATTR_CAN_DOWNLOAD | DFU_ATTR_WILL_DETACH | DFU_ATTR_MANIFESTATION_TOLERANT)
+
 // Unit numbers are arbitrary selected
 #define UAC2_ENTITY_CLOCK               0x01
 // Speaker path