Documentation updates

lib_xua/api/xua_conf_default.h

@@ -227,21 +227,27 @@
  */
 
 /**
- * @brief Max supported sample frequency for device (Hz). Default: 192000
+ * @brief Max supported sample frequency for device (Hz).
+ *
+ * Default: 192000Hz
  */
 #ifndef MAX_FREQ
 #define MAX_FREQ                 (192000)
 #endif
 
 /**
- * @brief Min supported sample frequency for device (Hz). Default 44100
+ * @brief Min supported sample frequency for device (Hz).
+ *
+ * Default: 44100Hz
  */
 #ifndef MIN_FREQ
 #define MIN_FREQ                 (44100)
 #endif
 
 /**
- * @brief Master clock defines for 44100 rates (in Hz). Default: NONE (Must be defined by app)
+ * @brief Master clock defines for 44100 rates (in Hz).
+ *
+ * Default: NONE (Must be defined by app)
  */
 #ifndef MCLK_441
     #error MCLK_441 not defined
@@ -249,7 +255,9 @@
 #endif
 
 /**
- * @brief Master clock defines for 48000 rates (in Hz). Default: NONE (Must be defined by app)
+ * @brief Master clock defines for 48000 rates (in Hz).
+ *
+ * Default: NONE (Must be defined by app)
  */
 #ifndef MCLK_48
     #error MCLK_48 not defined
@@ -257,7 +265,7 @@
 #endif
 
 /**
- * @brief Enable/disable the use of the secondary/application PLL for generating master-clock.
+ * @brief Enable/disable the use of the secondary/application PLL for generating master-clocks.
  *        Only available on xcore.ai devices.
  *
  * Default: Enabled (for xcore.ai devices)
@@ -276,7 +284,9 @@
 #endif
 
 /**
- * @brief Default device sample frequency. A safe default should be used. Default: MIN_FREQ
+ * @brief Default device sample frequency. A safe default should be used.
+ *
+ * Default: MIN_FREQ
  */
 #ifndef DEFAULT_FREQ
 #define DEFAULT_FREQ             (MIN_FREQ)

lib_xua/doc/rst/api_defines.rst

@@ -8,9 +8,9 @@ An application using the USB audio framework needs to have defines set for confi
 Defaults for these defines are found in ``xua_conf_default.h``.
 
 These defines should be over-ridden in an optional header file  ``xua_conf.h`` file or in the ``Makefile``
-for a relevant build configuration. 
+for a relevant build configuration.
 
-This section fully documents all of the settable defines and their default values (where appropriate).  
+This section fully documents all of the settable defines and their default values (where appropriate).
 
 Code Location (tile)
 --------------------
@@ -25,12 +25,12 @@ Code Location (tile)
 Channel Counts
 --------------
 
-.. doxygendefine:: NUM_USB_CHAN_OUT 
+.. doxygendefine:: NUM_USB_CHAN_OUT
-.. doxygendefine:: NUM_USB_CHAN_IN 
+.. doxygendefine:: NUM_USB_CHAN_IN
-.. doxygendefine:: I2S_CHANS_DAC 
+.. doxygendefine:: I2S_CHANS_DAC
-.. doxygendefine:: I2S_CHANS_ADC 
+.. doxygendefine:: I2S_CHANS_ADC
 
-Frequencies and Clocks 
+Frequencies and Clocks
 ----------------------
 
 .. doxygendefine:: MAX_FREQ
@@ -38,6 +38,7 @@ Frequencies and Clocks
 .. doxygendefine:: DEFAULT_FREQ
 .. doxygendefine:: MCLK_441
 .. doxygendefine:: MCLK_48
+.. doxygendefine:: XUA_USE_APP_PLL
 
 Audio Class
 -----------

lib_xua/doc/rst/opt_sync.rst

@@ -1,27 +1,27 @@
 
 |newpage|
 
-Synchronisation
+Synchronisation & Clocking
-===============
+==========================
 
-The codebase supports "Synchronous" and "Asynchronous" modes for USB transfer as defined by the 
+The codebase supports "Synchronous" and "Asynchronous" modes for USB transfer as defined by the
 USB specification(s).
 
-Asynchronous mode (``XUA_SYNCMODE_ASYNC``) has the advantage that the device is clock-master. This means that 
+Asynchronous mode (``XUA_SYNCMODE_ASYNC``) has the advantage that the device is clock-master. This means that
-a high-quality local master-clock source can be utilised. It also has the benefit that the device may 
+a high-quality local master-clock source can be utilised. It also has the benefit that the device may
-synchronise it's master clock to an external digital input stream e.g. S/PDIF and thus avoiding sample-rate
+synchronise it's master clock to an external digital input stream e.g. S/PDIF thus avoiding sample-rate
 conversion.
 
-The drawback of this mode is that it burdens the host with syncing to the device which some hosts 
+The drawback of this mode is that it burdens the host with syncing to the device which some hosts
 may not support. This is especially pertinent to embedded hosts, however, most PC's and mobile devices
 will indeed support this mode.
 
 Synchronous mode (``XUA_SYNCMODE_SYNC``) is an option if the target host does not support asynchronous mode
-or if it is desirable to synchronise many devices to a single host. It should be noted, however, that input 
+or if it is desirable to synchronise many devices to a single host. It should be noted, however, that input
 from digital streams, such as S/PDIF, are not currently supported in this mode.
 
 .. note::
-    
+
    The selection of synchronisation mode is done at build time and cannot be changed dynamically.
 
 Setting the synchronisation mode of the device is done using the define in :ref:`opt_sync_defines`
@@ -39,10 +39,17 @@ Setting the synchronisation mode of the device is done using the define in :ref:
      - USB synchronisation mode
      - ``XUA_SYNCMODE_ASYNC``
 
-When operating in synchronous mode an external Cirrus Logic CS2100 device is required for master clock 
+When operating in asynchronous mode xcore.ai based devices will be configured, by default, to use their internal
-generation. The codebase expects to drive a synchronisation signal to this external device
+"Applications" PLL to generated an appropriate master-clock signal.  To disable this ``XUA_USE_APP_PLL`` should be
+set to ``0``. For all other devices the developer is expected to supply external master-clock generation circuitry.
 
-The programmer should ensure the define in :ref:`opt_sync_ref_defines` is set appropriately.
+When operating in synchronous mode an xcore.ai based device, by default, will be configured to used it's internal
+"application" PLL to generate a master-clock synchronised to the USB host.
+
+xcore-200 based devices do not have this application PLL and so an external Cirrus Logic CS2100 device is required
+for master clock generation. The codebase expects to drive a synchronisation signal to this external device.
+
+In this case the developer should ensure the define in :ref:`opt_sync_ref_defines` is set appropriately.
 
 .. _opt_sync_ref_defines:
 
@@ -57,10 +64,33 @@ The programmer should ensure the define in :ref:`opt_sync_ref_defines` is set ap
      - Tile location of reference to CS2100 device
      - ``AUDIO_IO_TILE``
 
-The codebase expects this reference signal port to be defined in the application XN file as ``PORT_PLL_REF``. 
+The codebase expects this reference signal port to be defined in the application XN file as ``PORT_PLL_REF``.
 This may be a port of any bit-width, however, connection to bit[0] is assumed::
 
     <Port Location="XS1_PORT_1A"  Name="PORT_PLL_REF"/>
 
 Configuration of the external CS2100 device (typically via I2C) is beyond the scope of this document.
 
+Note, in all cases the master-clocks are generated (when using the xcore.ai Application PLL) or should be generated
+(if using external circuitry) to match the defines in :ref:`opt_sync_mclk_defines`.
+
+.. _opt_sync_mclk_defines:
+
+.. list-table:: Master clock frequencies
+   :header-rows: 1
+   :widths: 20 80 20
+
+   * - Define
+     - Description
+     - Default
+   * - ``MCLK_48``
+     - Master clock frequency (in Hz)used for sample-rates related to 48KHz
+     - NOTE
+   * - ``MCLK_441``
+     - Master clock frequency (in Hz) used for sample-rates related to 44.1KHz
+     - NONE
+
+.. note::
+
+   The master clock defines above are critical for proper operation and default values are not provided.
+   If they are not defined by the devloper a build error will be emmited.