Further doc updates

lib_xua/doc/rst/sw_audio.rst

@@ -91,51 +91,42 @@ 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
+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
-provides the BCLK and LRCLK signals to the audio hardware
 
-XS1 ports and XMOS clocks provide many valuable features for
+xCORE ports and XMOS clocks provide many valuable features for implementing I2S. This section describes how these are configured
-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)
+    Ports and Clocks (xCORE master)
 
 .. only:: html
 
   .. figure:: images/port_config.png
 
-    Ports and Clocks (CODEC slave)
+    Ports and Clocks (xCORE master)
 
-The code to configure the ports and clocks is in the
+The code to configure the ports and clocks is in the ``ConfigAudioPorts()`` function. Developers should not need to modify this.
-``ConfigAudioPorts()`` function. Developers should not need to modify 
-this.
 
-The XMOS device inputs MCLK and divides
+The xCORE inputs MCLK and divides it down to generate BCLK and LRCLK. 
-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``). 
 
-To achieve this MCLK is input
+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``.
-into the device using the 1-bit port ``p_mclk``. This is attached to the clock block ``clk_audio_mclk``, which is in
+The preceding diagram shows the connectivity of ports and clock blocks.
-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
-``p_sdin`` and ``p_sdout`` are configured as
+input in one input statement. This allows the software to input, process and output 32-bit words, whilst the ports serialize and
-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 
+used for ``p_bclk`` and ``p_lrclk``. The bit  clock is generated by performing outputs of a particular pattern to ``p_bclk`` to toggle
-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:
 
@@ -155,12 +146,8 @@ The following table shows the required pattern for different values of this divi
      - ``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``).  
-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``
@@ -176,15 +163,14 @@ Changing Audio Sample Frequency
 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
+First, a change of sample frequency is reported by sending the new frequency over an XC channel. The audio core
-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.
+Once this is complete, the I2S/TDM interface (i.e. the main look in AudioHub) is restarted at the new frequency.