dengweijie/lib_xua
1
0
Fork 0
forked from PAWPAW-Mirror/lib_xua
Code Pull Requests Activity

Documentation updates and fixes

Browse Source
This commit is contained in:
Ross Owen
2023-07-14 15:58:54 +01:00
parent 7f72c4b842
commit e7b5faed66
6 changed files with 76 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
lib_xua/api/xua_conf_default.h
View File

@@ -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

50
lib_xua/doc/rst/api_user_functions.rst
View File

@@ -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

2
lib_xua/doc/rst/xdoc.conf
View File

@@ -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

45
lib_xua/src/core/user/audiostream/audiostream.h
View File

@@ -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

21
lib_xua/src/core/user/hid/user_hid.h
View File

@@ -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 <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
* 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_ */

10
lib_xua/src/core/user/hostactive/hostactive.h
View File

@@ -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);