diff --git a/lib_xua/api/xua_conf_default.h b/lib_xua/api/xua_conf_default.h index ca857ab7..9a54e840 100644 --- a/lib_xua/api/xua_conf_default.h +++ b/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 diff --git a/lib_xua/doc/rst/api_user_functions.rst b/lib_xua/doc/rst/api_user_functions.rst index 7a7f527e..e9c1ed61 100644 --- a/lib_xua/doc/rst/api_user_functions.rst +++ b/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 - starts. - -.. c:function:: void AudioStreamStop(void) - - This function is called when the audio stream from device to host stops. - -Host Active ------------ +Host Active Functions +--------------------- 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. - +.. doxygenfunction:: UserHostActive 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[]) - - :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. - +.. doxygenfunction:: UserHIDGetData diff --git a/lib_xua/doc/rst/xdoc.conf b/lib_xua/doc/rst/xdoc.conf index 4d522c83..ae22d5a0 100644 --- a/lib_xua/doc/rst/xdoc.conf +++ b/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 diff --git a/lib_xua/src/core/user/audiostream/audiostream.h b/lib_xua/src/core/user/audiostream/audiostream.h index 1f27774e..e9aa7b67 100644 --- a/lib_xua/src/core/user/audiostream/audiostream.h +++ b/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 - * - * THESE NEED IMPLEMENTING FOR A SPECIFIC DESIGN - * - * */ +/* 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. + */ -/* 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 diff --git a/lib_xua/src/core/user/hid/user_hid.h b/lib_xua/src/core/user/hid/user_hid.h index d5b2b425..778676d8 100644 --- a/lib_xua/src/core/user/hid/user_hid.h +++ b/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__ -#define __USER_HID_H__ +#ifndef _USER_HID_H_ +#define _USER_HID_H_ #include @@ -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 - * first byte of HID event data. + * the first element; otherwise the first element holds the + * 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_ */ diff --git a/lib_xua/src/core/user/hostactive/hostactive.h b/lib_xua/src/core/user/hostactive/hostactive.h index fa100d10..d3231297 100644 --- a/lib_xua/src/core/user/hostactive/hostactive.h +++ b/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);