Merge pull request #91 from xmos/release/v3.3.0

Merge release staging v3.3.0 into main

.github/workflows/ci.yml

@@ -57,15 +57,31 @@ jobs:
             i2c:
               - 'modules/i2c/**'
               - 'test/lib_i2c/**'
+              - 'modules/xud/lib_xud/**'
+              - 'test/modules/test_support/**'
+              - 'xmos_cmake_toolchain/**'
+              - 'modules/mic_array/**'
             i2s:
               - 'modules/i2s/**'
               - 'test/lib_i2s/**'
+              - 'modules/xud/lib_xud/**'
+              - 'test/modules/test_support/**'
+              - 'xmos_cmake_toolchain/**'
+              - 'modules/mic_array/**'
             spi:
               - 'modules/spi/**'
               - 'test/lib_spi/**'
+              - 'modules/xud/lib_xud/**'
+              - 'test/modules/test_support/**'
+              - 'xmos_cmake_toolchain/**'
+              - 'modules/mic_array/**'
             uart:
               - 'modules/uart/**'
               - 'test/lib_uart/**'
+              - 'modules/xud/lib_xud/**'
+              - 'test/modules/test_support/**'
+              - 'xmos_cmake_toolchain/**'
+              - 'modules/mic_array/**'
   i2ctests:
     needs: changes
     name: I2C tests

.github/workflows/docs.yml

@@ -44,3 +44,10 @@ jobs:
       - name: Build documentation
         run: |
           docker run --rm -t -u "$(id -u):$(id -g)" -v ${{ github.workspace }}:/build -e PDF=1 -e REPO:/build -e EXCLUDE_PATTERNS=/build/doc/exclude_patterns.inc -e DOXYGEN_INCLUDE=/build/doc/Doxyfile.inc -e DOXYGEN_INPUT=ignore ${DOC_BUILDER_IMAGE}
+      - name: Save documentation artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: fwk_io_docs
+          path: ./doc/_build
+          if-no-files-found: error # 'warn' or 'ignore' are also available, defaults to `warn` 
+          retention-days: 5

CHANGELOG.rst

@@ -1,6 +1,14 @@
 IO Framework change log
 =======================
 
+3.3.0
+-----
+
+  * FIXED: TDM documentation included
+  * CHANGE: Updated xmos_cmake_toolchain to v1.0.0
+  * CHANGE: Updated lib_xud to v2.2.4
+  * CHANGE: Updated test_support to v1.0.0
+
 3.2.0
 -----
 

doc/programming_guide/reference/i2c/i2c_master.rst

@@ -12,7 +12,7 @@ The following code snippet demonstrates the basic usage of an |I2C| master devic
 .. code-block:: c
 
    #include <xs1.h>
-   #include <i2c.h>
+   #include "i2c.h"
 
    i2c_master_t i2c_ctx;
 

doc/programming_guide/reference/i2c/i2c_slave.rst

@@ -12,7 +12,7 @@ The following code snippet demonstrates the basic usage of an |I2C| slave device
 .. code-block:: c
 
    #include <xs1.h>
-   #include <i2c.h>
+   #include "i2c.h"
 
    port_t p_scl = XS1_PORT_1A;
    port_t p_sda = XS1_PORT_1B;

doc/programming_guide/reference/i2s/i2s.rst

@@ -4,22 +4,21 @@
 |I2S| Library
 #############
 
-A software defined library that allows you to control an |I2S| (Inter-IC Sound) bus via xcore ports. |I2S| is a digital data streaming interfaces particularly appropriate for transmission of audio data. The components in the library are controlled via C and can either act as |I2S| master or |I2S| slave.
+A software defined library that allows you to control an |I2S| (Inter-IC Sound) bus via xcore ports. |I2S| is a digital data streaming interfaces particularly appropriate for transmission of audio data. TDM is a special case of |I2S| which supports transport of more than two audio channels and is partially included in the library at this time. The components in the library are controlled via C and can either act as |I2S| master, |I2S| slave or TDM slave.
 
 .. note::
 
-   The TDM protocol is not yet supported by this library.
+    TDM is only currently supported as a TDM16 slave Tx component. Expansion of this library to support master or slave Rx is possible and can be done on request.
 
-|I2S| is a protocol between two devices where one is the *master* and one is the *slave* . The protocol is made up of four signals shown
-in :ref:`i2s_wire_table`.
+|I2S| is a protocol between two devices where one is the *master* and one is the *slave* which determines who drives the clock lines. The protocol is made up of four signals shown in :ref:`i2s_wire_table`.
 
 .. _i2s_wire_table:
 
 .. list-table:: |I2S| data wires
      :class: vertical-borders horizontal-borders
 
      * - *MCLK*
-       - Clock line, driven by external oscillator
+       - Clock line, driven by external oscillator. This signal is optional.
      * - *BCLK*
        - Bit clock. This is a fixed divide of the *MCLK* and is driven
          by the master.
@@ -34,7 +33,32 @@ All |I2S| functions can be accessed via the ``i2s.h`` header:
 
 .. code-block:: c
    
-   #include <i2s.h>
+   #include "i2s.h"
+
+TDM is a protocol between two devices similar to |I2S| where one is the *master* and one is the *slave* which determines who drives the clock lines. The protocol is made up of four signals shown in :ref:`tdm_wire_table`.
+
+.. _tdm_wire_table:
+
+.. list-table:: TDM data wires
+     :class: vertical-borders horizontal-borders
+
+     * - *MCLK*
+       - Clock line, driven by external oscillator. This signal is optional.
+     * - *BCLK*
+       - Bit clock. This is a fixed divide of the *MCLK* and is driven
+         by the master.
+     * - *FSYCNH*
+       - Frame synchronization. Toggles at the start of the TDM data frame. This is driven by the master.
+     * - *DATA*
+       - Data line, driven by one of the slave or master depending on
+         the data direction. There may be several data lines in
+         differing directions.
+
+Currently supported TDM functions can be accessed via the ``i2s_tdm_slave.h`` header:
+
+.. code-block:: c
+   
+   #include "i2s_tdm_slave.h"
 
 .. toctree::
    :maxdepth: 2
@@ -43,3 +67,4 @@ All |I2S| functions can be accessed via the ``i2s.h`` header:
    i2s_common.rst
    i2s_master.rst
    i2s_slave.rst
+   i2s_tdm_slave.rst

doc/programming_guide/reference/i2s/i2s_common.rst

@@ -4,7 +4,18 @@
 |I2S| Common API
 ****************
 
+|I2S| Instances
+===============
+
 The following structures and functions are used by an |I2S| master or slave instance.
 
 .. doxygengroup:: hil_i2s_core
    :content-only:
+
+TDM Instances
+=============
+
+The following structures and functions are used by an TDM master or slave instance.
+
+.. doxygengroup:: hil_i2s_tdm_core
+   :content-only:

doc/programming_guide/reference/i2s/i2s_master.rst

@@ -12,7 +12,7 @@ The following code snippet demonstrates the basic usage of an |I2S| master devic
 .. code-block:: c
 
    #include <xs1.h>
-   #include <i2s.h>
+   #include "i2s.h"
 
    port_t p_i2s_dout[1];
    port_t p_bclk;

doc/programming_guide/reference/i2s/i2s_slave.rst

@@ -12,7 +12,7 @@ The following code snippet demonstrates the basic usage of an |I2S| slave device
 .. code-block:: c
 
    #include <xs1.h>
-   #include <i2s.h>
+   #include "i2s.h"
 
    // Setup ports and clocks
    port_t p_bclk  = XS1_PORT_1B;

doc/programming_guide/reference/i2s/i2s_tdm_slave.rst

@@ -0,0 +1,59 @@
+.. include:: ../../../substitutions.rst
+
+*********
+TDM Slave
+*********
+
+TDM Slave Tx Usage
+==================
+
+The following code snippet demonstrates the basic usage of a TDM slave Tx device.
+
+.. code-block:: c
+
+   #include <xs1.h>
+   #include "i2s_tdm_slave.h"
+
+   // Setup ports and clocks
+   port_t p_bclk = XS1_PORT_1A;
+   port_t p_fsync = XS1_PORT_1B;
+   port_t p_dout = XS1_PORT_1C;
+
+   xclock_t clk_bclk = XS1_CLKBLK_1;
+
+   // Setup callbacks
+   // NOTE: See API or sln_voice examples for more on using the callbacks
+   i2s_tdm_ctx_t ctx;
+   i2s_callback_group_t i_i2s = {
+           .init = (i2s_init_t) i2s_init,
+           .restart_check = (i2s_restart_check_t) i2s_restart_check,
+           .receive = NULL,
+           .send = (i2s_send_t) i2s_send,
+           .app_data = NULL,
+   };
+
+   // Initialize the TDM slave
+   i2s_tdm_slave_tx_16_init(
+           &ctx,
+           &i_i2s,
+           p_dout,
+           p_fsync,
+           p_bclk,
+           clk_bclk,
+           0,
+           I2S_SLAVE_SAMPLE_ON_BCLK_FALLING,
+           NULL);
+
+   // Start the slave device in this thread
+   // NOTE: You may wish to launch the slave device in a different thread.  
+   //       See the XTC Tools documentation reference for lib_xcore.
+   i2s_tdm_slave_tx_16_thread(&ctx);
+
+TDM Slave Tx API
+================
+
+The following structures and functions are used to initialize and start a TDM slave Tx instance.
+
+.. doxygengroup:: hil_i2s_tdm_slave_tx16
+   :content-only:
+

doc/programming_guide/reference/spi/spi_master.rst

@@ -12,7 +12,7 @@ The following code snippet demonstrates the basic usage of an SPI master device.
 .. code-block:: c
 
    #include <xs1.h>
-   #include <spi.h>
+   #include "spi.h"
 
    spi_master_t spi_ctx;
    spi_master_device_t spi_dev;

doc/programming_guide/reference/spi/spi_slave.rst

@@ -12,7 +12,7 @@ The following code snippet demonstrates the basic usage of an SPI slave device.
 .. code-block:: c
 
    #include <xs1.h>
-   #include <spi.h>
+   #include "spi.h"
 
    // Setup callbacks
    //  NOTE: See API or SDK examples for more on using the callbacks

doc/programming_guide/reference/uart/uart.rst

@@ -30,7 +30,8 @@ All UART functions can be accessed via the ``uart.h`` header:
 
 .. code-block:: c
    
-   #include <uart.h>
+   #include "uart.h"
+
 
 .. toctree::
    :maxdepth: 2

doc/shared/introduction.rst

@@ -8,5 +8,5 @@ The peripheral IO framework is a collection of IO libraries written in C for XCO
 
 - UART - transmit and receive
 - |I2C| - master and slave
-- |I2S| - master and slave 
+- |I2S| - master and slave and TDM slave Tx
 - SPI - master and slave

modules/uart/api/uart.h

@@ -26,7 +26,7 @@
  * Enum type representing the different options
  * parity types.
  */
-typedef enum uart_parity_t {
+typedef enum uart_parity {
   UART_PARITY_NONE = 0,
   UART_PARITY_EVEN,
   UART_PARITY_ODD

settings.json

@@ -1,5 +1,5 @@
 {
     "title": "XCORE Peripheral IO Framework",
     "project": "fwk_io",
-    "version": "3.1.0"
+    "version": "3.3.0"
 }

test/lib_i2c/i2c_slave_checker.py

@@ -20,11 +20,13 @@ def __init__(
         self,
         scl_port: str,
         sda_port: str,
+        ready_port: str,
         speed: int,
         tsequence: Sequence[Tuple[Literal["r", "w"], Union[Sequence[int], int]]],
     ) -> None:
         self._scl_port = scl_port
         self._sda_port = sda_port
+        self._ready_port = ready_port
         self._tsequence = tsequence
         self._speed = speed
         self._bit_time = 1000000000 / speed
@@ -117,7 +119,11 @@ def run(self) -> None:
         xsi = self.xsi
         xsi.drive_port_pins(self._scl_port, 1)
         xsi.drive_port_pins(self._sda_port, 1)
-        self.wait_until(xsi.get_time() + 30000000)
+
+        # Wait for the device to bring up it's tx port, indicating it is ready
+        self.wait((lambda _x: self.xsi.is_port_driving(self._ready_port)))
+        self.wait_until(xsi.get_time() + 50 * 1000 * 1000) # Wait further 50us to ensure I2C slave is initialised and ready
+
         for (typ, addr, d) in self._tsequence:
             if typ == "w":
                 self.start_bit(xsi)

test/lib_i2c/i2c_slave_test/src/main.c

@@ -19,6 +19,7 @@
 
 port_t p_scl = XS1_PORT_1A;
 port_t p_sda = XS1_PORT_1B;
+port_t p_ready = XS1_PORT_1C; // Used to signal FW is ready
 
 static int i = 0;
 static int ack_index = 0;
@@ -71,7 +72,6 @@ int i2c_shutdown(void *app_data) {
     return 0;
 }
 
-
 DECLARE_JOB(burn, (void));
 
 void burn(void) {
@@ -89,6 +89,10 @@ int main(void) {
         .app_data = NULL,
     };
 
+    // Send ready signal to checker
+    port_enable(p_ready);
+    port_out(p_ready, 1);
+
     PAR_JOBS (
         PJOB(i2c_slave, (&i_i2c, p_scl, p_sda, DEVICE_ADDR)),
         PJOB(burn, ()),

test/lib_i2c/test_basic_slave.py

@@ -20,6 +20,7 @@ def test_i2c_basic_slave(build, capfd, request, nightly, speed):
 
     checker = I2CSlaveChecker("tile[0]:XS1_PORT_1A",
                             "tile[0]:XS1_PORT_1B",
+                            "tile[0]:XS1_PORT_1C",
                             tsequence =
                             [("w", 0x3c, [0x33, 0x44, 0x3]),
                             ("r", 0x3c, 3),
@@ -35,6 +36,9 @@ def test_i2c_basic_slave(build, capfd, request, nightly, speed):
 
     sim_args = ['--weak-external-drive']
 
+    # Use this to enable VCD tracing for debug
+    # sim_args = ['--weak-external-drive', '--vcd-tracing', '-tile tile[0] -ports -instructions -o trace.vcd']
+
     # The environment here should be set up with variables defined in the
     # CMakeLists.txt file to define the build. For this test, speed is only
     # used in the Python harness, not in the resultant xe, therefore it is