From 28682cf8086b5da416b537a4988c6a2929f08801 Mon Sep 17 00:00:00 2001 From: Ed Date: Wed, 4 Oct 2023 08:12:13 +0100 Subject: [PATCH] Further TDM doc updates --- doc/programming_guide/reference/i2s/i2s.rst | 12 ++-- .../reference/i2s/i2s_common.rst | 7 +- .../reference/i2s/i2s_master.rst | 2 +- .../reference/i2s/i2s_tdm_slave.rst | 59 +++++++++++++++++ .../reference/i2s/tdm_slave.rst | 65 ------------------- 5 files changed, 71 insertions(+), 74 deletions(-) create mode 100644 doc/programming_guide/reference/i2s/i2s_tdm_slave.rst delete mode 100644 doc/programming_guide/reference/i2s/tdm_slave.rst diff --git a/doc/programming_guide/reference/i2s/i2s.rst b/doc/programming_guide/reference/i2s/i2s.rst index 8fe007d..8198994 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. TDM is a special case of |I2S| which supports transport of more than two audio channels and is partially included in the library. The components in the library are controlled via C and can either act as |I2S| master, |I2S| slave or TDM 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:: 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* which determines which side drives the clock lines. 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: @@ -36,8 +35,7 @@ All |I2S| functions can be accessed via the ``i2s.h`` header: #include -TDM is a protocol between two devices similar where one is the *master* and one is the *slave* which determines which side drives the clock lines. The protocol is made up of four signals shown -in :ref:`tdm_wire_table`. +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: @@ -50,7 +48,7 @@ in :ref:`tdm_wire_table`. - Bit clock. This is a fixed divide of the *MCLK* and is driven by the master. * - *FSYCNH* - - Frame synchronisation. Toggles at the start of the TDM data frame. This is driven by the master. + - 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 @@ -76,4 +74,4 @@ Currently supported TDM functions can be accessed via the ``i2s_tdm_slave.h`` he i2s_common.rst i2s_master.rst i2s_slave.rst - tdm_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..fc9c9db 100644 --- a/doc/programming_guide/reference/i2s/i2s_common.rst +++ b/doc/programming_guide/reference/i2s/i2s_common.rst @@ -1,4 +1,4 @@ -.. include:: ../../../substitutions.rst +v.. include:: ../../../substitutions.rst **************** |I2S| Common API @@ -8,3 +8,8 @@ The following structures and functions are used by an |I2S| master or slave inst .. doxygengroup:: hil_i2s_core :content-only: + +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_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/i2s/tdm_slave.rst b/doc/programming_guide/reference/i2s/tdm_slave.rst deleted file mode 100644 index 951ec32..0000000 --- a/doc/programming_guide/reference/i2s/tdm_slave.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. include:: ../../../substitutions.rst - -********* -TDM Slave -********* - -TDM Slave Usage -=============== - -The following code snippet demonstrates the basic usage of a TDM slave device. - -.. code-block:: c - - #include - #include "i2s_tdm_slave.h" - - // Setup ports and clocks - port_t p_bclk = XS1_PORT_1B; - port_t p_lrclk = XS1_PORT_1C; - port_t p_din [4] = {XS1_PORT_1D, XS1_PORT_1E, XS1_PORT_1F, XS1_PORT_1G}; - port_t p_dout[4] = {XS1_PORT_1H, XS1_PORT_1I, XS1_PORT_1J, XS1_PORT_1K}; - xclock_t bclk = XS1_CLKBLK_1; - - port_t p_bclk = TDM_SLAVEPORT_BCLK; - port_t p_fsync = TDM_SLAVEPORT_FSYNCH; - port_t p_dout = TDM_SLAVEPORT_OUT; - - xclock_t bclk = TDM_SLAVEPORT_CLK_BLK; - - port_enable(p_bclk); - // NOTE: p_lrclk does not need to be enabled by the caller - - - 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 = (void*)read_buffer_ptr, - }; - - // Setup callbacks - // NOTE: See API or SDK examples for more on using the callbacks - i2s_callback_group_t i_i2s = { - .init = (i2s_init_t) i2s_init, - .restart_check = (i2s_restart_check_t) i2s_restart_check, - .receive = (i2s_receive_t) i2s_receive, - .send = (i2s_send_t) i2s_send, - .app_data = 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_slave(&i_i2s, p_dout, 4, p_din, 4, p_bclk, p_lrclk, bclk); - -|I2S| Slave API -=============== - -The following structures and functions are used to initialize and start an |I2S| slave instance. - -.. doxygengroup:: hil_i2s_slave - :content-only: -