Documentation updates

lib_xua/api/xua_audiohub.h

@@ -67,20 +67,17 @@ void SpdifTxWrapper(chanend c_spdif_tx);
  * Note, default (empty) implementations of these are provided in audiohub_user.c
  */
 
-/** User code for any required audio hardwarte initialisation - run once at start up */
+/** This function is called when the device starts up and should contain user code to perform any required audio hardware initialisation */
 void AudioHwInit(void);
 
-/** User code to mute audio hardware before a sample rate change - run every sample frequency change */
-void AudioHwConfig_Mute(void);
 
-/** User code to un-mute audio hardware after a sample rate change - run every sample frequency change */
-void AudioHwConfig_UnMute(void);
 
-/** User code Configure audio hardware (clocking, CODECs etc) for a specific mClk/Sample frquency - run on every sample frequency change
+/** This function is called when on sample rate change and should contain user code to configure audio hardware
+ *  (clocking, CODECs etc) for a specific mClk/Sample frequency
  *
  * \param samFreq       The new sample frequency (in Hz)
  *
- * \param mclk          The new master clock frequency (in Hz)
+ * \param mClk          The new master clock frequency (in Hz)
  *
  * \param dsdMode       DSD mode, DSD_MODE_NATIVE, DSD_MODE_DOP or DSD_MODE_OFF
  *
@@ -90,6 +87,19 @@ void AudioHwConfig_UnMute(void);
  */
 void AudioHwConfig(unsigned samFreq, unsigned mClk, unsigned dsdMode, unsigned sampRes_DAC, unsigned sampRes_ADC);
 
+/** This function is called before AudioHwConfig() and should contain user code to mute audio hardware before a
+ *  sample rate change in order to reduced audible pops/clicks
+ *
+ *  Note, if using the application PLL of a xcore.ai device this function will be called before the master-clock is
+ *  changed
+ */
+void AudioHwConfig_Mute(void);
+
+/** This function is called after AudioHwConfig() and should contain user code to un-mute audio hardware after a
+ *  sample rate change
+ */
+void AudioHwConfig_UnMute(void);
+
 #endif // __XC__
 
 void UserBufferManagementInit();

lib_xua/doc/rst/api_user_functions.rst

@@ -1,41 +1,16 @@
 Required User Function Definitions
 ==================================
 
-The following functions need to be defined by an application using the XMOS USB Audio framework.
+The following functions need to be defined by an application using `lib_xua`.
 
 External Audio Hardware Configuration Functions
 -----------------------------------------------
 
-.. c:function:: void AudioHwInit(chanend ?c_codec)
+.. doxygenfunction:: AudioHwInit
+.. doxygenfunction:: AudioHwConfig
+.. doxygenfunction:: AudioHwConfig_Mute
+.. doxygenfunction:: AudioHwConfig_UnMute
 
-   This function is called when the audio core starts after the
-   device boots up and should initialize the external audio harware e.g. clocking, DAC, ADC etc
-
-   :param c_codec: An optional chanend that was original passed into
-                   :c:func:`audio` that can be used to communicate 
-                   with other cores.
-  
-
-.. c:function:: void AudioHwConfig(unsigned samFreq, unsigned mclk, chanend ?c_codec, unsigned dsdMode, unsigned sampRes_DAC, unsigned sampRes_ADC)
-
-   This function is called when the audio core starts or changes
-   sample rate. It should configure the extenal audio hardware to run at the specified
-   sample rate given the supplied master clock frequency.
-
-   :param samFreq: The sample frequency in Hz that the hardware should be configured to (in Hz).
-                   
-   :param mclk: The master clock frequency that is required in Hz.
-   
-   :param c_codec: An optional chanend that was original passed into
-                   :c:func:`audio` that can be used to communicate 
-                   with other cores.
-
-   :param dsdMode: Signifies if the audio hardware should be configured for DSD operation
-
-   :param sampRes_DAC: The sample resolution of the DAC stream
-   
-   :param sampRes_ADC: The sample resolution of the ADC stream
-  
 
 Audio Streaming Functions
 -------------------------
@@ -45,7 +20,7 @@ The following functions can be optionally used by the design. They can be useful
 .. c:function:: void AudioStreamStart(void)
 
   This function is called when the audio stream from device to host
-  starts. 
+  starts.
 
 .. c:function:: void AudioStreamStop(void)