Initial TDM docs

doc/programming_guide/reference/i2s/i2s.rst

@@ -4,13 +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. 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
+|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_wire_table:
@@ -19,7 +19,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.
@@ -36,10 +36,44 @@ All |I2S| functions can be accessed via the ``i2s.h`` header:
    
    #include <i2s.h>
 
+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_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 synchronisation. 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.
+
+All |I2S| functions can be accessed via the ``i2s.h`` header:
+
+.. code-block:: c
+   
+   #include "i2s.h"
+
+
+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
    :includehidden:
 
    i2s_common.rst
    i2s_master.rst
    i2s_slave.rst
+   tdm_slave.rst

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/tdm_slave.rst

@@ -0,0 +1,65 @@
+.. 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 <xs1.h>
+   #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:
+