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

@@ -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,15 +1,15 @@
 
 |newpage|
 
-Synchronisation
-===============
+Synchronisation & Clocking
+==========================
 
 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
 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
@@ -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 
-generation. The codebase expects to drive a synchronisation signal to this external device
+When operating in asynchronous mode xcore.ai based devices will be configured, by default, to use their internal
+"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:
 
@@ -64,3 +71,26 @@ This may be a port of any bit-width, however, connection to bit[0] is assumed::
 
 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.