From 0932ca0ccca91fe165f213990a1b6df18f615325 Mon Sep 17 00:00:00 2001 From: Ross Owen Date: Wed, 7 Jun 2023 11:53:42 +0100 Subject: [PATCH] Documentation updates relating to TDM/I2S --- CHANGELOG.rst | 3 ++- lib_xua/api/xua_conf_default.h | 8 ++++++-- lib_xua/doc/rst/api_defines.rst | 9 +++++++++ lib_xua/doc/rst/opt_i2s.rst | 19 +++++++++++++++---- lib_xua/doc/rst/opt_location.rst | 2 +- lib_xua/doc/rst/overview.rst | 2 +- lib_xua/doc/rst/using_adv_i2s.rst | 4 ++-- 7 files changed, 36 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index d95b28c8..65af1b55 100644 --- a/CHANGELOG.rst +++ b/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 ----- diff --git a/lib_xua/api/xua_conf_default.h b/lib_xua/api/xua_conf_default.h index dd9287dc..8876372c 100644 --- a/lib_xua/api/xua_conf_default.h +++ b/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 */ diff --git a/lib_xua/doc/rst/api_defines.rst b/lib_xua/doc/rst/api_defines.rst index 76904020..a67b08fd 100644 --- a/lib_xua/doc/rst/api_defines.rst +++ b/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 ^^^^ diff --git a/lib_xua/doc/rst/opt_i2s.rst b/lib_xua/doc/rst/opt_i2s.rst index 681626d9..7547f419 100644 --- a/lib_xua/doc/rst/opt_i2s.rst +++ b/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:: -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. + diff --git a/lib_xua/doc/rst/opt_location.rst b/lib_xua/doc/rst/opt_location.rst index 45a5d1ee..0f3b210b 100644 --- a/lib_xua/doc/rst/opt_location.rst +++ b/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 diff --git a/lib_xua/doc/rst/overview.rst b/lib_xua/doc/rst/overview.rst index 8be7bae7..d014a45d 100644 --- a/lib_xua/doc/rst/overview.rst +++ b/lib_xua/doc/rst/overview.rst @@ -25,7 +25,7 @@ Overview | +---------------------------------------------------------------------------------------------+ | | `USB Midi Device Class 1.0 `_ | +---------------------------------+---------------------------------------------------------------------------------------------+ - | Audio | I2S/TDM | + | Audio | I2S/TDM (16/24/32-bit) | | +---------------------------------------------------------------------------------------------+ | | S/PDIF | | +---------------------------------------------------------------------------------------------+ diff --git a/lib_xua/doc/rst/using_adv_i2s.rst b/lib_xua/doc/rst/using_adv_i2s.rst index 12d5029c..89dd025c 100644 --- a/lib_xua/doc/rst/using_adv_i2s.rst +++ b/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 */