Documentation updates relating to TDM/I2S

CHANGELOG.rst

@@ -4,9 +4,10 @@ lib_xua Change Log
 UNRELEASED
 ----------
 
+  * ADDED:     Configurable word-length for I2S/TDM via XUA_I2S_N_BITS 
   * FIXED:     Memory corruption due to erroneous initialisation of mixer weights when not in use (#152) 
   * FIXED:     UserHostActive() not being called as expected (#326)
-  * FIXED:     Exception when entering DSD mode
+  * FIXED:     Exception when entering DSD mode (#327)
 
 3.4.0
 -----

lib_xua/api/xua_conf_default.h

@@ -93,7 +93,11 @@
 
 #define XUA_PCM_FORMAT_I2S      (0)
 #define XUA_PCM_FORMAT_TDM      (1)
-
+/**
+ * @brief Format of PCM audio interface. Should be set to XUA_PCM_FORMAT_I2S or XUA_PCM_FORMAT_TDM
+ *
+ * Default: XUA_PCM_FORMAT_I2S
+ */
 #ifdef XUA_PCM_FORMAT
     #if (XUA_PCM_FORMAT != XUA_PCM_FORMAT_I2S) && (XUA_PCM_FORMAT != XUA_PCM_FORMAT_TDM)
         #error Bad value for XUA_PCM_FORMAT
@@ -194,7 +198,7 @@
 #endif
 
 /**
- * @Brief Number of bits per channel for I2S/TDM
+ * @brief Number of bits per channel for I2S/TDM. Supported values: 16/24/32-bit.
  *
  * Default: 32 bits
  */

lib_xua/doc/rst/api_defines.rst

@@ -50,6 +50,15 @@ Audio Class
 Feature Configuration
 ---------------------
 
+I2S/TDM
+^^^^^^^
+
+.. doxygendefine:: I2S_CHANS_DAC
+.. doxygendefine:: I2S_CHANS_ADC
+.. doxygendefine:: CODEC_MASTER
+.. doxygendefine:: XUA_I2S_N_BITS
+.. doxygendefine:: XUA_PCM_FORMAT
+
 MIDI
 ^^^^
 

lib_xua/doc/rst/opt_i2s.rst

@@ -23,11 +23,14 @@ The defines in :ref:`opt_i2s_defines` effect the I2S implementation.
      - The desired number of input channels via I2S (0 for disabled)
      - N/A (Must be defined)
    * - ``XUA_PCM_FORMAT``
-     - Enabled either TDM or I2S mode
+     - Enables either TDM or I2S mode
      - ``XUA_PCM_FORMAT_I2S``
    * - ``CODEC_MASTER``
-     - Sets is xCORE is I2S master or slave
+     - Sets if xCORE is I2S master or slave
      - ``0`` (xCORE is master)
+   * - ``XUA_I2S_N_BITS``
+     - I2S/TDM word length (16, 24 or 32bit supported)
+     - ``32``
 
 The I2S code expects that the ports required for I2S (master clock, LR-clock, bit-clock and data lines) are be defined in the application XN file in the relevant `Tile``.  
 For example::
@@ -42,8 +45,16 @@ For example::
         <Port Location="XS1_PORT_1G"  Name="PORT_I2S_ADC1"/>
     </Tile>
 
-All of the I2S related ports must be 1-bit ports.
+All of the I2S/TDM related ports must be 1-bit ports.
 
 .. note:: 
 
-    TDM mode allows 8 channels (rather than 2) to be supplied on each dataline.
+    TDM mode allows 8 channels (rather than 2) to be supplied on each data-line.
+
+.. note:: 
+
+    Data output/input is in "I2S" format, rather than, say "left-justified" or "right-justified" formats. 
+    I2S format specifies a single bit-clock delay after the LR-clock transition before sample-data is driven/received.
+    This also applies to TDM mode. TDM support in ADC/DAC hardware is quite varied, an "offset" value may need to be programmed into 
+    the external device for compatible operation.
+

lib_xua/doc/rst/opt_location.rst

@@ -21,7 +21,7 @@ full listing of these ``TILE`` defines.
      - Description
      - Default
    * - ``AUDIO_IO_TILE``
-     - Tile on which I2S, ADAT Rx, S/PDIF Rx & mixer resides
+     - Tile on which I2S/TDM, ADAT Rx, S/PDIF Rx & mixer resides
      - ``0``
    * - ``XUD_TILE``
      - Tile on which USB resides, including buffering for all USB interfaces/endppoints

lib_xua/doc/rst/overview.rst

@@ -25,7 +25,7 @@ Overview
  |                                 +---------------------------------------------------------------------------------------------+
  |                                 | `USB Midi Device Class 1.0 <http://www.usb.org/developers/devclass_docs/midi10.pdf>`_       |
  +---------------------------------+---------------------------------------------------------------------------------------------+
- |   Audio                         |   I2S/TDM                                                                                   |
+ |   Audio                         |   I2S/TDM (16/24/32-bit)                                                                    |
  |                                 +---------------------------------------------------------------------------------------------+
  |                                 |   S/PDIF                                                                                    |
  |                                 +---------------------------------------------------------------------------------------------+

lib_xua/doc/rst/using_adv_i2s.rst

@@ -5,7 +5,7 @@ I2S/TDM
 
 I2S/TDM is typically fundamental to most products and is built into the ``XUA_AudioHub()`` core.
 
-In order to enable I2S on must declare an array of ports for the data-lines (one for each direction)::
+In order to enable I2S/TDM on must declare an array of ports for the data-lines (one for each direction)::
 
     /* Port declarations. Note, the defines come from the XN file */
     buffered out port:32 p_i2s_dac[] = {PORT_I2S_DAC0}; /* I2S Data-line(s) */
@@ -22,7 +22,7 @@ Ports for the sample and bit clocks are also required::
 
 These ports must then be passed to the ``XUA_AudioHub()`` task appropriately.
 
-I2S functionality also requires two clock-blocks, one for bit and sample clock e.g.::
+I2S/TDM functionality also requires two clock-blocks, one for bit-clock and another for the master clock e.g.::
 
     /* Clock-block declarations */
     clock clk_audio_bclk = on tile[0]: XS1_CLKBLK_4; /* Bit clock */