xmos · xluciano · Nov 20, 2023 · Oct 24, 2023 · Nov 17, 2023 · Nov 17, 2023
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -11,6 +11,8 @@ XCORE-VOICE change log
   * CHANGED: Updated submodule fwk_voice to version 0.7.0 from 0.6.0
   * CHANGED: Updated submodule xscope_fileio to version 1.1.2 from 1.1.1
   * CHANGED: Updated submodule lib_qspi_fast_read to version 1.0.2 from 1.0.1
+  * ADDED: Support for Microsoft OS 2.0 Descriptors for FFVA and ASRC examples
+           so the DFU interface automatically shows up as a WinUSB interface on Windows.
   * ADDED: FFD example with Cyberon speech recognition engine and model (DSpotter v2.2.18.0)
 
 2.1.0
@@ -20,6 +22,7 @@ XCORE-VOICE change log
   * ADDED: Asynchronous Sampling Rate Converter (ASRC) example application
   * ADDED: lib_xua 3.5.1 as submodule to support Mic aggregator app
   * CHANGED: Updated submodule fwk_io on to version 3.1.0 from version 3.0.1
+             to add support for TDM16 slave tx and 16ch mic_array
 
 2.0.0
 -----

diff --git a/doc/programming_guide/low_power_ffd/deploying/linux_macos.rst b/doc/programming_guide/low_power_ffd/deploying/linux_macos.rst
@@ -35,7 +35,7 @@ Run the following commands in the root folder to build the firmware:
 
     cmake -B build --toolchain=xmos_cmake_toolchain/xs3a.cmake
     cd build
-    make example_low_power_ffd
+    make example_low_power_ffd_sensory
 
 Running the Firmware
 ====================
@@ -46,7 +46,7 @@ Within the root of the build folder, run:
 
 .. code-block:: console
 
-    make flash_app_example_low_power_ffd
+    make flash_app_example_low_power_ffd_sensory
 
 After this command completes, the application will be running.
 
@@ -57,7 +57,7 @@ From the build folder run:
 
 .. code-block:: console
 
-    xrun --xscope example_low_power_ffd.xe
+    xrun --xscope example_low_power_ffd_sensory.xe
 
 Debugging the Firmware
 ======================
@@ -66,6 +66,6 @@ To debug with xgdb, from the build folder run:
 
 .. code-block:: console
 
-    xgdb -ex "connect --xscope" -ex "run" example_low_power_ffd.xe
+    xgdb -ex "connect --xscope" -ex "run" example_low_power_ffd_sensory.xe
 
 |newpage|
diff --git a/doc/programming_guide/low_power_ffd/deploying/native_windows.rst b/doc/programming_guide/low_power_ffd/deploying/native_windows.rst
@@ -59,7 +59,7 @@ Run the following commands in the root folder to build the firmware:
 
     cmake -G Ninja -B build --toolchain=xmos_cmake_toolchain/xs3a.cmake
     cd build
-    ninja example_low_power_ffd
+    ninja example_low_power_ffd_sensory
 
 Running the Firmware
 ====================
@@ -70,7 +70,7 @@ Within the root of the build folder, run:
 
 .. code-block:: console
 
-    ninja flash_app_example_low_power_ffd
+    ninja flash_app_example_low_power_ffd_sensory
 
 After this command completes, the application will be running.
 
@@ -81,7 +81,7 @@ From the build folder run:
 
 .. code-block:: console
 
-    xrun --xscope example_low_power_ffd.xe
+    xrun --xscope example_low_power_ffd_sensory.xe
 
 Debugging the Firmware
 ======================
@@ -90,6 +90,6 @@ To debug with xgdb, from the build folder run:
 
 .. code-block:: console
 
-    xgdb -ex "connect --xscope" -ex "run" example_low_power_ffd.xe
+    xgdb -ex "connect --xscope" -ex "run" example_low_power_ffd_sensory.xe
 
 |newpage|
diff --git a/doc/programming_guide/prerequisites.rst b/doc/programming_guide/prerequisites.rst
@@ -4,7 +4,7 @@
 Prerequisites
 #############
 
-It is recommended that you download and install the latest release of the `XTC Tools <https://www.xmos.com/software/tools/>`__.  XTC Tools 15.1.4 or newer are required for building, running, flashing and debugging the example applications.
+It is recommended that you download and install the latest release of the `XTC Tools <https://www.xmos.com/software/tools/>`__.  XTC Tools 15.2.1 or newer are required for building, running, flashing and debugging the example applications.
 
 `CMake 3.21 <https://cmake.org/download/>`_ or newer and `Git <https://git-scm.com/>`_ are also required for building the example applications.
 
@@ -14,12 +14,23 @@ Windows
 
 A standard C/C++ compiler is required to build applications for the host PC.  Windows users may use `Build Tools for Visual Studio <https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-170#download-and-install-the-tools>`__ command-line interface.
 
-XCORE-VOICE host build should also work using other Windows GNU development environments like GNU Make, MinGW or Cygwin.
+It is highly recommended to use *Ninja* as the build system for native Windows firmware builds.
+To install *Ninja* follow install instructions at https://ninja-build.org/ or on Windows
+install with ``winget`` by running the following commands in *PowerShell*:
+
+.. code-block:: PowerShell
+
+    # Install
+    winget install Ninja-build.ninja
+    # Reload user Path
+    $env:Path=[System.Environment]::GetEnvironmentVariable("Path","User")
+
+XCORE-VOICE host builds should also work using other Windows GNU development environments like GNU Make, MinGW or Cygwin.
 
 libusb
 ======
 
-The DFU feature of XCORE-VOICE requires `dfu-util <https://dfu-util.sourceforge.net/>`_ which requires ``libusb v1.0``. ``libusb`` requires the installation of a driver for use on a Windows host. Driver installation should be done using a third-party installation tool like `Zadig <https://zadig.akeo.ie/>`_.
+The DFU feature of XCORE-VOICE requires `dfu-util <https://dfu-util.sourceforge.net/>`_.
 
 *****
 macOS

diff --git a/examples/asrc_demo/README.rst b/examples/asrc_demo/README.rst
@@ -136,13 +136,14 @@ To run the app, either xrun or xflash can be used. Connect the XK-VOICE-L71 boar
 
    $ xrun example_asrc_demo.xe
 
+Optionally, xrun ``--xscope`` can be used to provide debug output.
+
 or
 
 ::
 
    $ xflash example_asrc_demo.xe
 
-Optionally, xrun ``--xscope`` can be used to provide debug output.
 
 
 Operation

diff --git a/examples/asrc_demo/src/usb/usb_descriptors.c b/examples/asrc_demo/src/usb/usb_descriptors.c
@@ -37,7 +37,7 @@
 tusb_desc_device_t const desc_device = {
     .bLength            = sizeof(tusb_desc_device_t),
     .bDescriptorType    = TUSB_DESC_DEVICE,
-    .bcdUSB             = 0x0200,
+    .bcdUSB             = 0x0201,   // For BOS descriptor! https://microchip.my.site.com/s/article/Does-a-USB2-1-Specification-Exist
 
     .bDeviceClass       = TUSB_CLASS_UNSPECIFIED,
     .bDeviceSubClass    = TUSB_CLASS_UNSPECIFIED,
@@ -62,6 +62,58 @@ uint8_t const* tud_descriptor_device_cb(void)
     return (uint8_t const*) &desc_device;
 }
 
+// MSOS 2.0 descriptor copied from the examples in https://github.com/xmos/xcore_iot/blob/develop/test/usb/tinyusb_demos/webusb_serial/src/usb_descriptors.c#L152
+// and https://github.com/pololu/libusbp/blob/master/test/firmware/wixel/main.c#L460
+#define MS_OS_20_DESC_LEN  0xB2
+#define REQUEST_GET_MS_DESCRIPTOR    0x20
+
+// Microsoft OS 2.0 Descriptors, Table 8
+#define MS_OS_20_DESCRIPTOR_INDEX 7
+
+#define BOS_TOTAL_LEN      (TUD_BOS_DESC_LEN + TUD_BOS_MICROSOFT_OS_DESC_LEN)
+
+uint8_t const desc_bos[] =
+{
+  // total length, number of device caps
+  TUD_BOS_DESCRIPTOR(BOS_TOTAL_LEN, 1),
+
+  // Microsoft OS 2.0 descriptor
+  TUD_BOS_MS_OS_20_DESCRIPTOR(MS_OS_20_DESC_LEN, REQUEST_GET_MS_DESCRIPTOR)
+};
+
+uint8_t const desc_ms_os_20[] =
+{
+  // Set header: length, type, windows version, total length
+  U16_TO_U8S_LE(0x000A), U16_TO_U8S_LE(MS_OS_20_SET_HEADER_DESCRIPTOR), U32_TO_U8S_LE(0x06030000), U16_TO_U8S_LE(MS_OS_20_DESC_LEN),
+
+  // Configuration subset header: length, type, configuration index, reserved, configuration total length
+  U16_TO_U8S_LE(0x0008), U16_TO_U8S_LE(MS_OS_20_SUBSET_HEADER_CONFIGURATION), 0, 0, U16_TO_U8S_LE(MS_OS_20_DESC_LEN-0x0A),
+
+  // Function Subset header: length, type, first interface, reserved, subset length
+  U16_TO_U8S_LE(0x0008), U16_TO_U8S_LE(MS_OS_20_SUBSET_HEADER_FUNCTION), ITF_NUM_DFU_MODE, 0, U16_TO_U8S_LE(MS_OS_20_DESC_LEN-0x0A-0x08),
+
+  // MS OS 2.0 Compatible ID descriptor: length, type, compatible ID, sub compatible ID
+  U16_TO_U8S_LE(0x0014), U16_TO_U8S_LE(MS_OS_20_FEATURE_COMPATBLE_ID), 'W', 'I', 'N', 'U', 'S', 'B', 0x00, 0x00,
+  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // sub-compatible
+
+  // MS OS 2.0 Registry property descriptor: length, type
+  U16_TO_U8S_LE(MS_OS_20_DESC_LEN-0x0A-0x08-0x08-0x14), U16_TO_U8S_LE(MS_OS_20_FEATURE_REG_PROPERTY),
+  U16_TO_U8S_LE(0x0007), U16_TO_U8S_LE(0x002A), // wPropertyDataType, wPropertyNameLength and PropertyName "DeviceInterfaceGUIDs\0" in UTF-16
+  'D', 0x00, 'e', 0x00, 'v', 0x00, 'i', 0x00, 'c', 0x00, 'e', 0x00, 'I', 0x00, 'n', 0x00, 't', 0x00, 'e', 0x00,
+  'r', 0x00, 'f', 0x00, 'a', 0x00, 'c', 0x00, 'e', 0x00, 'G', 0x00, 'U', 0x00, 'I', 0x00, 'D', 0x00, 's', 0x00, 0x00, 0x00,
+  U16_TO_U8S_LE(0x0050), // wPropertyDataLength
+	//bPropertyData: “{975F44D9-0D08-43FD-8B3E-127CA8AFFF9D}”.
+  '{', 0x00, '9', 0x00, '7', 0x00, '5', 0x00, 'F', 0x00, '4', 0x00, '4', 0x00, 'D', 0x00, '9', 0x00, '-', 0x00,
+  '0', 0x00, 'D', 0x00, '0', 0x00, '8', 0x00, '-', 0x00, '4', 0x00, '3', 0x00, 'F', 0x00, 'D', 0x00, '-', 0x00,
+  '8', 0x00, 'B', 0x00, '3', 0x00, 'E', 0x00, '-', 0x00, '1', 0x00, '2', 0x00, '7', 0x00, 'C', 0x00, 'A', 0x00,
+  '8', 0x00, 'A', 0x00, 'F', 0x00, 'F', 0x00, 'F', 0x00, '9', 0x00, 'D', 0x00, '}', 0x00, 0x00, 0x00, 0x00, 0x00
+};
+
+uint8_t const * tud_descriptor_bos_cb(void)
+{
+  return desc_bos;
+}
+
 //--------------------------------------------------------------------+
 // Configuration Descriptor
 //--------------------------------------------------------------------+
@@ -250,3 +302,24 @@ uint16_t const* tud_descriptor_string_cb(uint8_t index,
 
     return _desc_str;
 }
+
+
+bool tud_vendor_control_xfer_cb(uint8_t rhport, uint8_t stage, tusb_control_request_t const *request)
+{
+    switch (request->bRequest)
+    {
+        case REQUEST_GET_MS_DESCRIPTOR:
+            if ( request->wIndex == MS_OS_20_DESCRIPTOR_INDEX )
+            {
+                if (stage != CONTROL_STAGE_SETUP) return true; // nothing to with DATA & ACK stage
+                // Send Microsoft OS 2.0 compatible descriptor
+                return tud_control_xfer(rhport, request, (void*)(uintptr_t) desc_ms_os_20, MS_OS_20_DESC_LEN);
+            }else
+            {
+                return false;
+            }
+
+        default:
+            return false;
+    }
+}
diff --git a/examples/ffd/README.rst b/examples/ffd/README.rst
@@ -121,15 +121,15 @@ On Linux and Mac run:
 
 ::
 
-    cmake -B build -DCMAKE_TOOLCHAIN_FILE=xmos_cmake_toolchain/xs3a.cmake
+    cmake -B build --toolchain xmos_cmake_toolchain/xs3a.cmake
     cd build
     make example_ffd_<speech_engine>
 
 On Windows run:
 
 ::
 
-    cmake -G Ninja -B build -D CMAKE_TOOLCHAIN_FILE=xmos_cmake_toolchain/xs3a.cmake
+    cmake -G Ninja -B build --toolchain xmos_cmake_toolchain/xs3a.cmake
     cd build
     ninja example_ffd_<speech_engine>
 
@@ -171,4 +171,4 @@ Run the following commands in the build folder:
 
 ::
 
-    xgdb -ex "connect --xscope" -ex "run" example_ffd_<speech_engine>.xe
+    xgdb -ex "connect --xscope" -ex "run" example_ffd_<speech_engine>.xe
diff --git a/examples/ffva/README.md b/examples/ffva/README.md
@@ -28,9 +28,9 @@ Before building the host application, you will need to add the path to the XTC T
 
 Then build the host application:
 
-    cmake -G "NMake Makefiles" -B build_host
+    cmake -G Ninja -B build_host
     cd build_host
-    nmake install
+    ninja install
 
 The host applications will be installed at ``%USERPROFILE%\.xmos\bin``, and may be moved if desired.  You may wish to add this directory to your ``PATH`` variable.
 
@@ -40,19 +40,19 @@ Run the following commands in the root folder to build the firmware.
 
 On Linux and Mac run:
 
-    cmake -B build -DCMAKE_TOOLCHAIN_FILE=xmos_cmake_toolchain/xs3a.cmake
+    cmake -B build --toolchain xmos_cmake_toolchain/xs3a.cmake
     cd build
 
     make example_ffva_int_fixed_delay
     make example_ffva_ua_adec_altarch
 
 On Windows run:
 
-    cmake -G "NMake Makefiles" -B build -DCMAKE_TOOLCHAIN_FILE=xmos_cmake_toolchain/xs3a.cmake
+    cmake -G Ninja -B build --toolchain xmos_cmake_toolchain/xs3a.cmake
     cd build
 
-    nmake example_ffva_int_fixed_delay
-    nmake example_ffva_ua_adec_altarch
+    ninja example_ffva_int_fixed_delay
+    ninja example_ffva_ua_adec_altarch
 
 From the build folder, create the data partition containing the filesystem and
 flash the device with the appropriate command to the desired configuration:
@@ -64,8 +64,8 @@ On Linux and Mac run:
 
 On Windows run:
 
-    nmake flash_app_example_ffva_int_fixed_delay
-    nmake flash_app_example_ffva_ua_adec_altarch
+    ninja flash_app_example_ffva_int_fixed_delay
+    ninja flash_app_example_ffva_ua_adec_altarch
 
 Once flashed, the application will run.
 
@@ -76,29 +76,15 @@ re-flashed.
 
 Run the following commands in the build folder.
 
-On Linux and Mac run:
-
-    make run_example_ffva_int_fixed_delay
-    make run_example_ffva_ua_adec_altarch
-
-On Windows run:
-
-    nmake run_example_ffva_int_fixed_delay
-    nmake run_example_ffva_ua_adec_altarch
+    xrun --xscope example_ffva_int_fixed_delay.xe
+    xrun --xscope example_ffva_ua_adec_altarch.xe
 
 ## Debugging the firmware with `xgdb`
 
 Run the following commands in the build folder.
 
-On Linux and Mac run:
-
-    make debug_example_ffva_int_fixed_delay
-    make debug_example_ffva_ua_adec_altarch
-
-On Windows run:
-
-    nmake debug_example_ffva_int_fixed_delay
-    nmake debug_example_ffva_ua_adec_altarch
+    xgdb -ex "conn --xscope" -ex "r" example_ffva_int_fixed_delay.xe
+    xgdb -ex "conn --xscope" -ex "r" example_ffva_ua_adec_altarch.xe
 
 ## Running the Firmware With WAV Files
 
@@ -110,17 +96,17 @@ Run the following commands in the root folder to build the firmware.
 
 On Linux and Mac run:
 
-    cmake -B build -DCMAKE_TOOLCHAIN_FILE=xmos_cmake_toolchain/xs3a.cmake -DDEBUG_FFVA_USB_MIC_INPUT=1
+    cmake -B build --toolchain xmos_cmake_toolchain/xs3a.cmake -DDEBUG_FFVA_USB_MIC_INPUT=1
     cd build
 
     make example_ffva_ua_adec_altarch
 
 On Windows run:
 
-    cmake -G "NMake Makefiles" -B build -DCMAKE_TOOLCHAIN_FILE=xmos_cmake_toolchain/xs3a.cmake -DDEBUG_FFVA_USB_MIC_INPUT=1
+    cmake -G Ninja -B build --toolchain xmos_cmake_toolchain/xs3a.cmake -DDEBUG_FFVA_USB_MIC_INPUT=1
     cd build
 
-    nmake example_ffva_ua_adec_altarch
+    ninja example_ffva_ua_adec_altarch
 
 After rebuilding the firmware, run the application.