Documentation updates and fixes

lib_xua/api/xua_conf_default.h

@@ -518,12 +518,11 @@
  * You must also supply your own function to deal with the HID endpoint(s)
  * in this case.
  */
-#if( 0 < HID_CONTROLS )
+#if (HID_CONTROLS) || defined (__DOXYGEN__)
 #define   XUA_HID_ENABLED            (1)
 #define   XUA_OR_STATIC_HID_ENABLED  (1)
 #endif
 
-
 #if defined(__static_hid_report_h_exists__)
 #define   XUA_OR_STATIC_HID_ENABLED  (1)
 #endif

lib_xua/doc/rst/api_user_functions.rst

@@ -1,49 +1,49 @@
-Required User Function Definitions
+|newpage|
-==================================
 
-The following functions need to be defined by an application using `lib_xua`.
+User Function Definitions
+=========================
+
+The following functions can be defined by an application using `lib_xua`.
+
+.. note:: Default, empty, implementations of these functions are provided in `lib_xua`. These are marked
+   as weak symbols so the application can simply define its own version of them.
 
 External Audio Hardware Configuration Functions
 -----------------------------------------------
 
+The following functions can be optionally used by the design to configure external audio hardware.
+As a minimum, in most applications, it is expected that a implementation of `AudioHwConfig()` will need
+to be provided.
+
 .. doxygenfunction:: AudioHwInit
 .. doxygenfunction:: AudioHwConfig
 .. doxygenfunction:: AudioHwConfig_Mute
 .. doxygenfunction:: AudioHwConfig_UnMute
 
 
-Audio Streaming Functions
+Audio Stream Start/Stop Functions
--------------------------
+---------------------------------
 
 The following functions can be optionally used by the design. They can be useful for mute lines etc.
 
-.. c:function:: void AudioStreamStart(void)
+.. doxygenfunction:: UserAudioStreamStart
+.. doxygenfunction:: UserAudioStreamStop
+.. doxygenfunction:: UserAudioInputStreamStart
+.. doxygenfunction:: UserAudioInputStreamStop
+.. doxygenfunction:: UserAudioOutputStreamStart
+.. doxygenfunction:: UserAudioOutputStreamStop
 
-  This function is called when the audio stream from device to host
+Host Active Functions
-  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.
+.. doxygenfunction:: UserHostActive
-
-.. 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).
+The function should write relevant HID bits into this array. The bit ordering and functionality is defined by the HID report descriptor used.
 
-.. c:function:: void UserReadHIDButtons(unsigned char hidData[])
+.. doxygenfunction:: UserHIDGetData
-
-    :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.
-

lib_xua/doc/rst/xdoc.conf

@@ -1,5 +1,5 @@
 XMOSNEWSTYLE = 2
-DOXYGEN_DIRS=../../api
+DOXYGEN_DIRS=../../api ../../src/core/user/audiostream ../../src/core/user/hostactive ../../src/core/user/hid ../../src/core/user/audiohw
 SOURCE_INCLUDE_DIRS=../../../lib_xua
 SPHINX_MASTER_DOC=lib_xua
 

lib_xua/src/core/user/audiostream/audiostream.h

@@ -1,30 +1,51 @@
-// Copyright 2011-2021 XMOS LIMITED.
+// Copyright 2011-2023 XMOS LIMITED.
 // This Software is subject to the terms of the XMOS Public Licence: Version 1.
 #ifndef _AUDIOSTREAM_H_
 #define _AUDIOSTREAM_H_
 
-/* Functions that handle functions that must occur on stream start/stop e.g. DAC mute/un-mute
+/* Functions that handle functionality that occur on stream start/stop e.g. DAC mute/un-mute.
- *
+ * They should be implemented for the external audio hardware arrangement of a specific design.
- * THESE NEED IMPLEMENTING FOR A SPECIFIC DESIGN
+ */
- *
- * */
 
-/* Any actions required for stream start e.g. DAC un-mute - run every stream start */
+/**
+ * @brief   User stream start code
+ *
+ * User code to perform any actions required at every stream start - either input or output
+ */
 void UserAudioStreamStart(void);
 
-/* Any actions required on stream stop e.g. DAC mute - run every steam stop  */
+/**
+ * @brief   User stream stop code
+ *
+ * User code to perform any actions required on every stream stop - either input or output*/
 void UserAudioStreamStop(void);
 
-/* Any actions required on input stream start */
+/**
+ * @brief   User input stream stop code
+ *
+ * User code to perform any actions required on input stream start i.e. device to host
+ */
 void UserAudioInputStreamStart(void);
 
-/* Any actions required on input stream stop */
+/**
+ * @brief   User input stream stop code
+ *
+ * User code to perform any actions required on input stream stop i.e. device to host
+ */
 void UserAudioInputStreamStop(void);
 
-/* Any actions required on output stream start */
+/**
+ * @brief   User output stream start code
+ *
+ * User code to perform any actions required on output stream start i.e. host to device
+ */
 void UserAudioOutputStreamStart(void);
 
-/* Any actions required on output stream stop */
+/**
+ * @brief   User output stream stop code
+ *
+ * User code to perfrom any actions required on output stream stop i.e. host to device
+ */
 void UserAudioOutputStreamStop(void);
 
 #endif

lib_xua/src/core/user/hid/user_hid.h

@@ -5,13 +5,13 @@
  * @brief Human Interface Device (HID) API
  *
  * This file defines the Application Programming Interface (API) used to record HID
- *   events and retrieve a HID Report for sending to a host.
+ * events and retrieve a HID Report for sending to a host.
  * The using application has the responsibility to fulfill this API.
  * Document section numbers refer to the HID Device Class Definition, version 1.11.
  */
 
-#ifndef __USER_HID_H__
+#ifndef _USER_HID_H_
-#define __USER_HID_H__
+#define _USER_HID_H_
 
 #include <stddef.h>
 
@@ -34,22 +34,16 @@ typedef struct hidEvent_t {
 #define HID_MAX_DATA_BYTES ( 4 )
 #define HID_EVENT_INVALID_ID ( 0x100 )
 
-#if XUA_HID_ENABLED
-
 /**
  *  \brief  Get the data for the next HID Report
  *
- *  \note This function returns the HID data as a list of unsigned char because the
- *        \c XUD_SetReady_In() accepts data for transmission to the USB Host using
- *        this type.
- *
  *  \param[in]  id       The HID Report ID (see 5.6, 6.2.2.7, 8.1 and 8.2)
  *                       Set to zero if the application provides only one HID Report
- *                         which does not include a Report ID
+ *                       which does not include a Report ID
  *  \param[out] hidData  The HID data
  *                       If using Report IDs, this function places the Report ID in
- *                         the first element; otherwise the first element holds the
+ *                       the first element; otherwise the first element holds the
- *                         first byte of HID event data.
+ *                       first byte of HID event data.
  *
  *  \returns  The length of the HID Report in the \a hidData argument
  *  \retval   Zero means no new HID event data has been recorded for the given \a id
@@ -61,5 +55,4 @@ size_t UserHIDGetData( const unsigned id, unsigned char hidData[ HID_MAX_DATA_BY
  */
 void UserHIDInit( void );
 
-#endif /* ( 0 < HID_CONTROLS ) */
+#endif /* _USER_HID_H_ */
-#endif /* __USER_HID_H__ */

lib_xua/src/core/user/hostactive/hostactive.h

@@ -1,4 +1,12 @@
-// Copyright 2013-2021 XMOS LIMITED.
+// Copyright 2013-2023 XMOS LIMITED.
 // This Software is subject to the terms of the XMOS Public Licence: Version 1.
 
+/**
+ * @brief   User host active code
+ *
+ * This function can be used to perform user defined actions based on host present/not-present events.
+ * This function is called on a change in state.
+ *
+ * \param active  Indicates if the host is active or not. 1 for active, else 0
+ */
 void UserHostActive(int active);