Updates to documentation (#280)

Documentation updates (including moving of header files

lib_xua/doc/rst/api_user_functions.rst

@@ -0,0 +1,73 @@
+Required User Function Definitions
+----------------------------------
+
+The following functions need to be defined by an application using the XMOS USB Audio framework.
+
+External Audio Hardware Configuration Functions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. c:function:: void AudioHwInit(chanend ?c_codec)
+
+   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
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following functions can be optionally used by the design. They can be useful for mute lines etc.
+
+.. c:function:: void AudioStreamStart(void)
+
+  This function is called when the audio stream from device to host
+  starts. 
+
+.. c:function:: void AudioStreamStop(void)
+
+  This function is called when the audio stream from device to host stops.
+
+Host Active
+~~~~~~~~~~~
+
+The following function can be used to signal that the device is connected to a valid host.
+
+This is called on a change in state.
+
+.. c:function:: void AudioStreamStart(int active)
+
+   :param active: Indicates if the host is active or not. 1 for active else 0.
+
+
+HID Controls
+~~~~~~~~~~~~
+
+The following function is called when the device wishes to read physical user input (buttons etc).
+
+.. c:function:: void UserReadHIDButtons(unsigned char hidData[])
+
+    :param hidData: The function should write relevant HID bits into this array. The bit ordering and functionality is defined by the HID report descriptor used.