Initial doc add

2018-03-08 17:39:15 +00:00
parent a7678f8916
commit 2729d9a34a
50 changed files with 11736 additions and 9 deletions
--- a/lib_xua/doc/rst/sw_audio.rst
+++ b/lib_xua/doc/rst/sw_audio.rst
@@ -0,0 +1,194 @@
+.. _usb_audio_sec_audio:
+
+Audio Driver
+............
+
+The audio driver receives and transmits samples from/to the decoupler
+or mixer core over an XC channel. 
+It then drives several in and out I2S/TDM channels. If
+the firmware is configured with the CODEC as slave, it will also
+drive the word and bit clocks in this core as well. The word
+clocks, bit clocks and data are all derived from the incoming
+master clock (typically the output of the external oscillator or PLL). The audio
+driver is implemented in the file ``audio.xc``.
+
+The audio driver captures and plays audio data over I2S. It also
+forwards on relevant audio data to the S/PDIF transmit core.  
+
+The audio core must be connected to a CODEC that supports I2S (other
+modes such as "left justified" can be supported with firmware changes). In
+slave mode, the XMOS device acts as the master generating the Bit
+Clock (BCLK) and Left-Right Clock (LRCLK, also called Word Clock)
+signals. Any CODEC or DAC/ADC combination that supports I2S and can be used.
+
+:ref:`usb_audio_codec_signals` shows the signals used to communicate audio between
+the XMOS device and the CODEC.
+
+.. _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 CODEC. 
+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 CODEC.
+
+:ref:`usb_audio_l1_clock_divides` shows some example clock frequencies and divides
+for different sample rates (note that this reflects the single tile L-Series reference board configuration):
+
+.. _usb_audio_l1_clock_divides:
+
+.. list-table:: Clock Divides used in single tile L-Series Ref Design
+  :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.576MHz
+respectively).  This master clock input is then provided to the CODEC and
+the XMOS device. 
+
+
+Port Configuration (xCORE Master)
+++++++++++++++++++++++++++++++++
+
+The default software configuration is CODEC Slave (xCORE master).  That is, the XMOS device
+provides the BCLK and LRCLK signals to the CODEC.
+
+XS1 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 (CODEC slave)
+
+.. only:: html
+
+  .. figure:: images/port_config.png
+
+    Ports and Clocks (CODEC slave)
+
+The code to configure the ports and clocks is in the
+``ConfigAudioPorts()`` function. Developers should not need to modify 
+this.
+
+The XMOS device 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 is restarted at the new frequency.
+
+
+