diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a9c3906..7668a6e 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 6f7f61e..c155acd 100644 --- a/.github/workflows/docs.yml +++ b/.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 diff --git a/CHANGELOG.rst b/CHANGELOG.rst index ca154a2..4cd75ab 100644 --- a/CHANGELOG.rst +++ b/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 ----- diff --git a/doc/programming_guide/reference/i2c/i2c_master.rst b/doc/programming_guide/reference/i2c/i2c_master.rst index 9cf8266..2e62996 100644 --- a/doc/programming_guide/reference/i2c/i2c_master.rst +++ b/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 - #include + #include "i2c.h" i2c_master_t i2c_ctx; diff --git a/doc/programming_guide/reference/i2c/i2c_slave.rst b/doc/programming_guide/reference/i2c/i2c_slave.rst index 848ceba..60956aa 100644 --- a/doc/programming_guide/reference/i2c/i2c_slave.rst +++ b/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 - #include + #include "i2c.h" port_t p_scl = XS1_PORT_1A; port_t p_sda = XS1_PORT_1B; diff --git a/doc/programming_guide/reference/i2s/i2s.rst b/doc/programming_guide/reference/i2s/i2s.rst index c942e78..dce935e 100644 --- a/doc/programming_guide/reference/i2s/i2s.rst +++ b/doc/programming_guide/reference/i2s/i2s.rst @@ -4,14 +4,13 @@ |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: @@ -19,7 +18,7 @@ in :ref:`i2s_wire_table`. :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 + #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 diff --git a/doc/programming_guide/reference/i2s/i2s_common.rst b/doc/programming_guide/reference/i2s/i2s_common.rst index 87dcf39..22448d1 100644 --- a/doc/programming_guide/reference/i2s/i2s_common.rst +++ b/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: \ No newline at end of file diff --git a/doc/programming_guide/reference/i2s/i2s_master.rst b/doc/programming_guide/reference/i2s/i2s_master.rst index 0b6500a..5c9dc5d 100644 --- a/doc/programming_guide/reference/i2s/i2s_master.rst +++ b/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 - #include + #include "i2s.h" port_t p_i2s_dout[1]; port_t p_bclk; diff --git a/doc/programming_guide/reference/i2s/i2s_slave.rst b/doc/programming_guide/reference/i2s/i2s_slave.rst index 150810f..657aaa5 100644 --- a/doc/programming_guide/reference/i2s/i2s_slave.rst +++ b/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 - #include + #include "i2s.h" // Setup ports and clocks port_t p_bclk = XS1_PORT_1B; diff --git a/doc/programming_guide/reference/i2s/i2s_tdm_slave.rst b/doc/programming_guide/reference/i2s/i2s_tdm_slave.rst new file mode 100644 index 0000000..eba15f6 --- /dev/null +++ b/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 + #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: + diff --git a/doc/programming_guide/reference/spi/spi_master.rst b/doc/programming_guide/reference/spi/spi_master.rst index 22be5d5..954c624 100644 --- a/doc/programming_guide/reference/spi/spi_master.rst +++ b/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 - #include + #include "spi.h" spi_master_t spi_ctx; spi_master_device_t spi_dev; diff --git a/doc/programming_guide/reference/spi/spi_slave.rst b/doc/programming_guide/reference/spi/spi_slave.rst index f3b9f20..440a3b2 100644 --- a/doc/programming_guide/reference/spi/spi_slave.rst +++ b/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 - #include + #include "spi.h" // Setup callbacks // NOTE: See API or SDK examples for more on using the callbacks diff --git a/doc/programming_guide/reference/uart/uart.rst b/doc/programming_guide/reference/uart/uart.rst index 4a8162d..2dd7980 100644 --- a/doc/programming_guide/reference/uart/uart.rst +++ b/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 + #include "uart.h" + .. toctree:: :maxdepth: 2 diff --git a/doc/shared/introduction.rst b/doc/shared/introduction.rst index 35bb5d1..7f50edd 100644 --- a/doc/shared/introduction.rst +++ b/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 diff --git a/modules/uart/api/uart.h b/modules/uart/api/uart.h index d800f5d..46a7480 100644 --- a/modules/uart/api/uart.h +++ b/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 diff --git a/modules/xud/lib_xud b/modules/xud/lib_xud index 50dfe9f..f258656 160000 --- a/modules/xud/lib_xud +++ b/modules/xud/lib_xud @@ -1 +1 @@ -Subproject commit 50dfe9f62f20c7dc752f2bdc2be17e4498e60bc3 +Subproject commit f25865692fde48f39d58ff64139b3f6bcd87884a diff --git a/settings.json b/settings.json index f45574d..16dea7a 100644 --- a/settings.json +++ b/settings.json @@ -1,5 +1,5 @@ { "title": "XCORE Peripheral IO Framework", "project": "fwk_io", - "version": "3.1.0" + "version": "3.3.0" } \ No newline at end of file diff --git a/test/lib_i2c/i2c_slave_checker.py b/test/lib_i2c/i2c_slave_checker.py index 0b8260a..33179bb 100644 --- a/test/lib_i2c/i2c_slave_checker.py +++ b/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) diff --git a/test/lib_i2c/i2c_slave_test/src/main.c b/test/lib_i2c/i2c_slave_test/src/main.c index 3105058..71ea54b 100644 --- a/test/lib_i2c/i2c_slave_test/src/main.c +++ b/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, ()), diff --git a/test/lib_i2c/test_basic_slave.py b/test/lib_i2c/test_basic_slave.py index e34fad0..f14bbd8 100644 --- a/test/lib_i2c/test_basic_slave.py +++ b/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 diff --git a/test/modules/test_support b/test/modules/test_support index 06373a0..011cd8d 160000 --- a/test/modules/test_support +++ b/test/modules/test_support @@ -1 +1 @@ -Subproject commit 06373a0da65f80fcda3e2b754ceb34a4a8b79af6 +Subproject commit 011cd8d9bb4d4cf60625f5b6937a73861c181636 diff --git a/xmos_cmake_toolchain b/xmos_cmake_toolchain index 3a19f02..ea6b9c4 160000 --- a/xmos_cmake_toolchain +++ b/xmos_cmake_toolchain @@ -1 +1 @@ -Subproject commit 3a19f0284c66a92dbb9d5adc9d3d5016aac22646 +Subproject commit ea6b9c4b7bd99044953b7dcdecc9768e737a5635