.. _usb_audio_sec_audio:

AudioHub/I2S
............

The AudioHub task performs many functions. It receives and transmits samples from/to the decoupler or mixer core over an XC channel.

It also drives several in and out I2S/TDM channels to/from a CODEC, DAC, ADC etc - from now on termed "audio hardware".

If the firmware is configured with the xCORE as I2S master the requred clock lines will also be driven out from this task also. 

It also has the task of formwarding on and reciving samples to/from other audio related tasks such as S/PDIF tasks, ADAT tasks etc.

The AudioHub task must be connected to external audio hardware that supports I2S (other modes such as "left justified" can be supported with firmware changes). 

In master mode, the XMOS device acts as the master generating the I2S "Continous Serial Clock (SCK)" typically called the Bit-Clock (BCLK) and the "Word Select (WS)" line typically called left-right clock (LRCLK) signals. Any CODEC or DAC/ADC combination that supports I2S and can be used.

The LR-clock, bit-clock and data are all derived from the incoming master clock (typically the output of the external oscillator or PLL) 
- This is not part of the I2S standard but is commonly included for synchronizing the internal operation of the analog/digital converters.

The AudioHub task is implemented in the file ``xua_audiohub.xc``.

:ref:`usb_audio_codec_signals` shows the signals used to communicate audio between the XMOS device and the external audio hardware.

.. _usb_audio_codec_signals:

.. list-table:: I2S Signals
   :header-rows: 1
   :widths: 20 80
  
   * - Signal
     - Description
   * - LRCLK 
     - The word clock, transition at the start of a sample
   * - BCLK     
     - The bit clock, clocks data in and out
   * - SDIN
     - Sample data in (from CODEC/ADC to the XMOS device)
   * - SDOUT 
     - Sample data out (from the XMOS device to CODEC/DAC)
   * - MCLK
     - The master clock running the CODEC/DAC/ADC

The bit clock controls the rate at which data is transmitted to and from the external audio hardware.

In the case where the XMOS device is the master, it divides the MCLK to generate the required signals for both BCLK and LRCLK,
with BCLK then being used to clock data in (SDIN) and data out (SDOUT) of the external audio hardware.

:ref:`usb_audio_example_clock_divides` shows some example clock frequencies and divides for different sample rates:

.. _usb_audio_example_clock_divides:

.. list-table:: Clock Divide examples
  :header-rows: 1
  :widths: 30 25 25 20

  * - Sample Rate (kHz)    
    - MCLK (MHz)
    - BCLK (MHz)
    - Divide
  * - 44.1  
    - 11.2896 
    - 2.819 
    - 4
  * - 88.2 
    - 11.2896
    - 5.638 
    - 2
  * - 176.4 
    - 11.2896
    - 11.2896 
    - 1
  * - 48 
    - 24.576 
    - 3.072 
    - 8
  * - 96 
    - 24.576 
    - 6.144 
    - 4
  * - 192 
    - 24.576 
    - 12.288 
    - 2

The master clock must be supplied by an external source e.g. clock generator, fixed oscillators, PLL etc to generate the two frequencies to support
44.1kHz and 48kHz audio frequencies (e.g. 11.2896/22.5792MHz and 12.288/24.576MHzrespectively).  This master clock input is then provided to the 
external audio hardware and the xCORE device. 


Port Configuration (xCORE Master)
+++++++++++++++++++++++++++++++++

The default software configuration is xCORE is I2S master.  That is, the XMOS device provides the BCLK and LRCLK signals to the external audio hardware

xCORE ports and XMOS clocks provide many valuable features for implementing I2S. This section describes how these are configured
and used to drive the I2S interface.

.. only:: latex

  .. figure:: images/port_config.pdf

    Ports and Clocks (xCORE master)

.. only:: html

  .. figure:: images/port_config.png

    Ports and Clocks (xCORE master)

The code to configure the ports and clocks is in the ``ConfigAudioPorts()`` function. Developers should not need to modify this.

The xCORE inputs MCLK and divides it down to generate BCLK and LRCLK. 

To achieve this MCLK is input into the device using the 1-bit port ``p_mclk``. This is attached to the clock block ``clk_audio_mclk``, which is in
turn used to clock the BCLK port, ``p_bclk``. BCLK is used to clock the LRCLK (``p_lrclk``) and data signals SDIN (``p_sdin``) and SDOUT (``p_sdout``). 

Again, a clock block is used (``clk_audio_bclk``) which has ``p_bclk`` as its input and is used to clock the ports ``p_lrclk``, ``p_sdin`` and ``p_sdout``.
The preceding diagram shows the connectivity of ports and clock blocks.

``p_sdin`` and ``p_sdout`` are configured as buffered ports with a transfer width of 32, so all 32 bits are
input in one input statement. This allows the software to input, process and output 32-bit words, whilst the ports serialize and
deserialize to the single I/O pin connected to each port.

xCORE-200 series devices have the ability to divide an extenal clock in a clock-block.

However, XS1 based devices do not have this functionality. In order achieve the reqired master-clock
to bit-clock/LR-clock divicd on XS1 devices, buffered ports with a transfer width of 32 are also 
used for ``p_bclk`` and ``p_lrclk``. The bit  clock is generated by performing outputs of a particular pattern to ``p_bclk`` to toggle
the output at the desired rate. The pattern depends on the divide between the master-clock and bit-clock. 
The following table shows the required pattern for different values of this divide:

.. list-table:: Output patterns
   :header-rows: 1

   * - Divide 
     - Output pattern 
     - Outputs per sample
   * - 2 
     - ``0xAAAAAAAA`` 
     - 2
   * - 4 
     - ``0xCCCCCCCC`` 
     - 4
   * - 8 
     - ``0xF0F0F0F0`` 
     - 8

In any case, the bit clock outputs 32 clock cycles per sample. In the special case where the divide is 1 (i.e. the bit clock frequency equals 
the master clock frequency), the ``p_bclk`` port is set to a special mode where it simply outputs its clock input (i.e. ``p_mclk``).  
See ``configure_port_clock_output()`` in ``xs1.h`` for details.

``p_lrclk`` is clocked by ``p_bclk``. In I2S mode the port outputs the pattern ``0x7fffffff``
followed by ``0x80000000`` repeatedly. This gives a signal that has a transition one bit-clock
before the data (as required by the I2S standard) and alternates between high and low for the
left and right channels of audio.

Changing Audio Sample Frequency
+++++++++++++++++++++++++++++++

.. _usb_audio_sec_chang-audio-sample:

When the host changes sample frequency, a new frequency is sent to
the audio driver core by Endpoint 0 (via the buffering cores and mixer).

First, a change of sample frequency is reported by sending the new frequency over an XC channel. The audio core
detects this by checking for the presence of a control token on the channel channel 

Upon receiving the change of sample frequency request, the audio
core stops the I2S/TDM interface and calls the CODEC/port configuration 
functions. 

Once this is complete, the I2S/TDM interface (i.e. the main look in AudioHub) is restarted at the new frequency.



