diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 51af7784..4e76454a 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,6 +1,15 @@ lib_xua Change Log ================== +3.3.1 +----- + + * CHANGED: Documentation updates + + * Changes to dependencies: + + - lib_spdif: 4.1.0 -> 4.2.1 + 3.3.0 ----- diff --git a/Jenkinsfile b/Jenkinsfile index bd0503cb..7dc08510 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -1,4 +1,4 @@ -@Library('xmos_jenkins_shared_library@v0.18.0') _ +@Library('xmos_jenkins_shared_library@v0.21.0') _ getApproval() @@ -24,7 +24,7 @@ pipeline { } stage('Library checks') { steps { - xcoreLibraryChecks("${REPO}") + xcoreLibraryChecks("${REPO}", false) } } stage('Testing') { diff --git a/README.rst b/README.rst index 7068b3c8..fb10166f 100644 --- a/README.rst +++ b/README.rst @@ -1,5 +1,5 @@ lib_xua -======= +####### :Latest release: 3.3.0 @@ -7,14 +7,14 @@ lib_xua :Scope: General Use Summary -------- +******* lib_xua contains shared components for use in the XMOS USB Audio (XUA) Reference Designs. These components enable the development of USB Audio devices on the XMOS xCORE architecture. Features -~~~~~~~~ +======== Key features of the various components in this repository are as follows @@ -56,7 +56,7 @@ Note, not all features may be supported at all sample frequencies, simultaneousl Some features may also require specific host driver support. Host System Requirements -~~~~~~~~~~~~~~~~~~~~~~~~ +======================== USB Audio devices built using `lib_xua` have the following host system requirements. @@ -69,27 +69,27 @@ USB Audio devices built using `lib_xua` have the following host system requireme Older versions of Windows are not guaranteed to operate as expected. Devices are also expected to operate with various Linux distributions including mobile variants. Related Application Notes -~~~~~~~~~~~~~~~~~~~~~~~~~ +========================= The following application notes use this library: - * AN000246 - Simple USB Audio Device using lib_xua - * AN000247 - Using lib_xua with lib_spdif (transmit) - * AN000248 - Using lib_xua with lib_mic_array + * AN000246 - Simple USB Audio Device using lib_xua + * AN000247 - Using lib_xua with lib_spdif (transmit) + * AN000248 - Using lib_xua with lib_mic_array -Required software (dependencies) +Required Software (dependencies) ================================ - * lib_locks (git@github.com:xmos/lib_locks.git) - * lib_logging (git@github.com:xmos/lib_logging.git) - * lib_mic_array (git@github.com:xmos/lib_mic_array.git) - * lib_xassert (git@github.com:xmos/lib_xassert.git) - * lib_dsp (git@github.com:xmos/lib_dsp) - * lib_i2c (git@github.com:xmos/lib_i2c.git) - * lib_i2s (git@github.com:xmos/lib_i2s.git) - * lib_gpio (git@github.com:xmos/lib_gpio.git) - * lib_mic_array_board_support (git@github.com:xmos/lib_mic_array_board_support.git) - * lib_spdif (git@github.com:xmos/lib_spdif.git) - * lib_xud (git@github.com:xmos/lib_xud.git) - * lib_adat (git@github.com:xmos/lib_adat) + * lib_locks (www.github.com/xmos/lib_locks) + * lib_logging (www.github.com/xmos/lib_logging) + * lib_mic_array (www.github.com/xmos/lib_mic_array) + * lib_xassert (www.github.com/xmos/lib_xassert) + * lib_dsp (www.github.com/xmos/lib_dsp) + * lib_i2c (www.github.com/xmos/lib_i2c) + * lib_i2s (www.github.com/xmos/lib_i2s) + * lib_gpio (www.github.com/xmos/lib_gpio) + * lib_mic_array_board_support (www.github.com/xmos/lib_mic_array_board_support) + * lib_spdif (www.github.com/xmos/lib_spdif) + * lib_xud (www.github.com/xmos/lib_xud) + * lib_adat (www.github.com/xmos/lib_adat) diff --git a/lib_xua/doc/rst/api.rst b/lib_xua/doc/rst/api.rst index 201d694c..4285cd53 100644 --- a/lib_xua/doc/rst/api.rst +++ b/lib_xua/doc/rst/api.rst @@ -1,9 +1,8 @@ .. _sec_api: - API Reference -------------- +************* .. toctree:: diff --git a/lib_xua/doc/rst/api_component.rst b/lib_xua/doc/rst/api_component.rst index c04f7d0f..47c73eb3 100644 --- a/lib_xua/doc/rst/api_component.rst +++ b/lib_xua/doc/rst/api_component.rst @@ -1,7 +1,7 @@ .. _sec_api_component: Component API -------------- +============= The following functions can be called from the top level main of an application and implement the various components described in diff --git a/lib_xua/doc/rst/api_defines.rst b/lib_xua/doc/rst/api_defines.rst index 9a9b0a30..76904020 100644 --- a/lib_xua/doc/rst/api_defines.rst +++ b/lib_xua/doc/rst/api_defines.rst @@ -2,7 +2,7 @@ .. _sec_api_defines: Configuration Defines ---------------------- +===================== An application using the USB audio framework needs to have defines set for configuration. Defaults for these defines are found in ``xua_conf_default.h``. @@ -13,7 +13,7 @@ for a relevant build configuration. This section fully documents all of the settable defines and their default values (where appropriate). Code Location (tile) -~~~~~~~~~~~~~~~~~~~~ +-------------------- .. doxygendefine:: AUDIO_IO_TILE .. doxygendefine:: XUD_TILE @@ -23,7 +23,7 @@ Code Location (tile) .. doxygendefine:: PLL_REF_TILE Channel Counts -~~~~~~~~~~~~~~ +-------------- .. doxygendefine:: NUM_USB_CHAN_OUT .. doxygendefine:: NUM_USB_CHAN_IN @@ -31,7 +31,7 @@ Channel Counts .. doxygendefine:: I2S_CHANS_ADC Frequencies and Clocks -~~~~~~~~~~~~~~~~~~~~~~ +---------------------- .. doxygendefine:: MAX_FREQ .. doxygendefine:: MIN_FREQ @@ -40,24 +40,24 @@ Frequencies and Clocks .. doxygendefine:: MCLK_48 Audio Class -~~~~~~~~~~~ +----------- .. doxygendefine:: AUDIO_CLASS .. doxygendefine:: AUDIO_CLASS_FALLBACK .. doxygendefine:: FULL_SPEED_AUDIO_2 -System Feature Configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Feature Configuration +--------------------- MIDI -.... +^^^^ .. doxygendefine:: MIDI .. doxygendefine:: MIDI_RX_PORT_WIDTH S/PDIF -...... +^^^^^^ .. doxygendefine:: XUA_SPDIF_TX_EN .. doxygendefine:: SPDIF_TX_INDEX @@ -65,37 +65,37 @@ S/PDIF .. doxygendefine:: SPDIF_RX_INDEX ADAT -.... +^^^^ .. doxygendefine:: XUA_ADAT_RX_EN .. doxygendefine:: ADAT_RX_INDEX PDM Microphones -............... +^^^^^^^^^^^^^^^ .. doxygendefine:: XUA_NUM_PDM_MICS DFU -... +^^^ .. doxygendefine:: XUA_DFU_EN .. .. doxygendefine:: DFU_FLASH_DEVICE HID -... +^^^ .. doxygendefine:: HID_CONTROLS CODEC Interface -............... +^^^^^^^^^^^^^^^ .. doxygendefine:: CODEC_MASTER USB Device Configuration -~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------ .. doxygendefine:: VENDOR_STR .. doxygendefine:: VENDOR_ID @@ -108,10 +108,10 @@ USB Device Configuration Stream Formats -~~~~~~~~~~~~~~ +-------------- Output/Playback -............... +^^^^^^^^^^^^^^^ .. doxygendefine:: OUTPUT_FORMAT_COUNT @@ -132,7 +132,8 @@ Output/Playback .. doxygendefine:: STREAM_FORMAT_OUTPUT_3_DATAFORMAT Input/Recording -............... +^^^^^^^^^^^^^^^ + .. doxygendefine:: INPUT_FORMAT_COUNT .. doxygendefine:: STREAM_FORMAT_INPUT_1_RESOLUTION_BITS @@ -144,7 +145,7 @@ Input/Recording .. doxygendefine:: STREAM_FORMAT_INPUT_1_DATAFORMAT Volume Control -~~~~~~~~~~~~~~ +-------------- .. doxygendefine:: OUTPUT_VOLUME_CONTROL .. doxygendefine:: INPUT_VOLUME_CONTROL @@ -152,8 +153,8 @@ Volume Control .. doxygendefine:: MAX_VOLUME .. doxygendefine:: VOLUME_RES -Mixing Parameters -~~~~~~~~~~~~~~~~~ +Mixing +------ .. doxygendefine:: MIXER .. doxygendefine:: MAX_MIX_COUNT @@ -163,8 +164,7 @@ Mixing Parameters .. doxygendefine:: VOLUME_RES_MIXER Power -~~~~~ +----- -.. doxygendefine:: SELF_POWERED -.. doxygendefine:: BMAX_POWER +.. doxygendefine:: XUA_POWERMODE diff --git a/lib_xua/doc/rst/api_user_functions.rst b/lib_xua/doc/rst/api_user_functions.rst index 5da0c0ae..e0728647 100644 --- a/lib_xua/doc/rst/api_user_functions.rst +++ b/lib_xua/doc/rst/api_user_functions.rst @@ -1,10 +1,10 @@ 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) @@ -38,7 +38,7 @@ External Audio Hardware Configuration Functions Audio Streaming Functions -~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------- The following functions can be optionally used by the design. They can be useful for mute lines etc. @@ -52,7 +52,7 @@ The following functions can be optionally used by the design. They can be useful 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. @@ -64,10 +64,11 @@ This is called on a change in state. 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. + diff --git a/lib_xua/doc/rst/arch.rst b/lib_xua/doc/rst/arch.rst index 109c79ac..448fa55a 100644 --- a/lib_xua/doc/rst/arch.rst +++ b/lib_xua/doc/rst/arch.rst @@ -2,7 +2,7 @@ .. _usb_audio_sec_architecture: Software Architecture ---------------------- +********************* This section describes the required software architecture of a USB Audio device implemented using `lib_xua`, its dependencies and other supporting libraries. diff --git a/lib_xua/doc/rst/feat.rst b/lib_xua/doc/rst/feat.rst index f4b3a4d7..3dbeb2d8 100644 --- a/lib_xua/doc/rst/feat.rst +++ b/lib_xua/doc/rst/feat.rst @@ -1,8 +1,8 @@ -Features & Options ------------------- +Additional Features +******************* -The previous section describes the use of core functionality contained within ``lib_xua`` +The previous chapter describes the use of core functionality contained within ``lib_xua`` This seciton details enabling additional features with supported external dependencies, for example, ``lib_xua`` can provide S/PDIF output though the used of ``lib_spdif`` diff --git a/lib_xua/doc/rst/feat_spdif_rx.rst b/lib_xua/doc/rst/feat_spdif_rx.rst index d4475395..00dd249d 100644 --- a/lib_xua/doc/rst/feat_spdif_rx.rst +++ b/lib_xua/doc/rst/feat_spdif_rx.rst @@ -1,6 +1,6 @@ S/PDIF Receive -~~~~~~~~~~~~~~ +============== ``lib_xua`` supports the development of devices with S/PDIF receive functionality through the use of ``lib_spdif``. The XMOS S/PDIF receiver runs in a single core and supports rates up to 192kHz. diff --git a/lib_xua/doc/rst/feat_spdif_tx.rst b/lib_xua/doc/rst/feat_spdif_tx.rst index 8e42611d..b8cf9c5d 100644 --- a/lib_xua/doc/rst/feat_spdif_tx.rst +++ b/lib_xua/doc/rst/feat_spdif_tx.rst @@ -1,6 +1,6 @@ S/PDIF Transmit -~~~~~~~~~~~~~~~ +=============== ``lib_xua`` supports the development of devices with S/PDIF transmit functionality through the use of ``lib_spdif``. The XMOS S/PDIF transmitter runs in a single core and supports rates up to 192kHz. diff --git a/lib_xua/doc/rst/issues.rst b/lib_xua/doc/rst/issues.rst index e4f86ff1..f7dd8f01 100644 --- a/lib_xua/doc/rst/issues.rst +++ b/lib_xua/doc/rst/issues.rst @@ -2,7 +2,7 @@ |appendix| Known Issues ------------- +************ - Quad-SPI DFU will corrupt the factory image with tools version < 14.0.4 due to an issue with libquadflash diff --git a/lib_xua/doc/rst/lib_xua.rst b/lib_xua/doc/rst/lib_xua.rst index 609d86d3..5bf5bf42 100644 --- a/lib_xua/doc/rst/lib_xua.rst +++ b/lib_xua/doc/rst/lib_xua.rst @@ -2,8 +2,7 @@ .. include:: ../../../README.rst About This Document -~~~~~~~~~~~~~~~~~~~ - +=================== This document describes the structure of ``lib_xua``, its use and resources required. It also covers some implementation detail. @@ -18,7 +17,7 @@ the XMOS tool chain and XC language. Options Advanced Usage Additional Features - Software Detail + Implementation Detail API Known Issues diff --git a/lib_xua/doc/rst/opt.rst b/lib_xua/doc/rst/opt.rst index a303c570..089553b1 100644 --- a/lib_xua/doc/rst/opt.rst +++ b/lib_xua/doc/rst/opt.rst @@ -2,7 +2,7 @@ .. _sec_options: Options -------- +******* This section describes key options of ``lib_xua``. These are typically controlled using build time defines. Where something must be defined, it is recommended this is done in `xua_conf.h` but could also be done in the application Makefile. diff --git a/lib_xua/doc/rst/opt_audio_class.rst b/lib_xua/doc/rst/opt_audio_class.rst index 9afc055c..9c16a2f9 100644 --- a/lib_xua/doc/rst/opt_audio_class.rst +++ b/lib_xua/doc/rst/opt_audio_class.rst @@ -1,7 +1,7 @@ |newpage| USB Audio Class Version -~~~~~~~~~~~~~~~~~~~~~~~ +======================= The codebase supports USB Audio Class versions 1.0 and 2.0. @@ -15,22 +15,22 @@ Additional improvements, amongst others, include: - Extensive support for interrupts to inform the host about dynamic changes that occur to different entities such as Clocks etc Driver Support -.............. +-------------- Audio Class 1.0 -+++++++++++++++ +^^^^^^^^^^^^^^^ Audio Class 1.0 is fully supported in Apple OSX. Audio Class 1.0 is fully supported in all modern Microsoft Windows operating systems (i.e. Windows XP and later). Audio Class 2.0 -+++++++++++++++ +^^^^^^^^^^^^^^^ Audio Class 2.0 is fully supported in Apple OSX since version 10.6.4. Starting with Windows 10, release 1703, a USB Audio 2.0 driver is shipped with Windows. Third party Windows drivers are also available, however, documentation of these is beyond the scope of this document, please contact XMOS for further details. Audio Class 1.0 Mode and Fall-back -.................................. +---------------------------------- The default for XMOS USB Audio applications is to run as a high-speed Audio Class 2.0 device. However, some products may prefer to run in Audio Class 1.0 mode, this is normally to @@ -64,7 +64,7 @@ Due to bandwidth limitations of full-speed USB the following sample-frequency re Related Defines -................ +--------------- :ref:`opt_audio_class_defines` descibes the defines that effect audio class selection. diff --git a/lib_xua/doc/rst/opt_audio_formats.rst b/lib_xua/doc/rst/opt_audio_formats.rst index 18cbbc4c..9be1e17c 100644 --- a/lib_xua/doc/rst/opt_audio_formats.rst +++ b/lib_xua/doc/rst/opt_audio_formats.rst @@ -3,7 +3,7 @@ .. _sec_opt_audio_formats: Audio Stream Formats -~~~~~~~~~~~~~~~~~~~~ +==================== The design currently supports up to three different stream formats for playback, selectable at run time. This is implemented using standard Alternative Settings to the Audio Streaming interfaces. @@ -32,7 +32,7 @@ By default the design exposes two sets of Alternative Settings for the playback 24-bit playback. When DSD is enabled an additional (32-bit) alternative is exposed. Audio Subslot -............. +------------- An audio subslot holds a single audio sample. See `USB Device Class Definition for Audio Data Formats `_ for full details. @@ -73,7 +73,7 @@ Values other than 4 may be used for the following reasons: Audio Sample Resolution -....................... +----------------------- An audio sample is represented using a number of bits (`bBitResolution`) less than or equal to the number of total bits available in the audio subslot i.e. `bBitResolution` <= `bSubslotSize` * 8). The design @@ -99,7 +99,7 @@ supports values 16, 24 and 32. Audio Format -............ +------------ The design supports two audio formats, PCM and, when "Native" DSD is enabled, Direct Stream Digital (DSD). A DSD capable DAC is required for the latter. @@ -122,7 +122,6 @@ The following options are supported: * UAC_FORMAT_TYPEI_PCM - .. note:: Currently DSD is only supported on the output/playback stream diff --git a/lib_xua/doc/rst/opt_channels.rst b/lib_xua/doc/rst/opt_channels.rst index d097fa5c..0385518c 100644 --- a/lib_xua/doc/rst/opt_channels.rst +++ b/lib_xua/doc/rst/opt_channels.rst @@ -1,7 +1,7 @@ |newpage| Channel Counts and Sample Rates -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=============================== The codebase is fully configurable in relation to channel counts and sample rates. Practical limitations of these are normally based on USB packet size restrictions and I/O diff --git a/lib_xua/doc/rst/opt_dsd.rst b/lib_xua/doc/rst/opt_dsd.rst index 3d6ef4f7..756cec96 100644 --- a/lib_xua/doc/rst/opt_dsd.rst +++ b/lib_xua/doc/rst/opt_dsd.rst @@ -1,7 +1,7 @@ |newpage| Direct Stream Digital (DSD) -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=========================== Direct Stream Digital (DSD) is used for digitally encoding audio signals on Super Audio CDs (SACD). It uses pulse-density modulation (PDM) encoding. @@ -48,7 +48,7 @@ If only DoP functionality is desired the Native implementation can be disabled w DSD over PCM (DoP) -.................. +------------------ DoP support follows the method described in the `DoP Open Standard 1.1 `_. @@ -81,14 +81,14 @@ of rate. DoP requires bit-perfect transmission - therefore any audio/volume processing will break the stream. "Native" vs DoP -~~~~~~~~~~~~~~~ +--------------- Since the DoP specification requires header bytes this eats into the data bandwidth. The "Native" implementation has no such overhead and can therefore transfer the same DSD rate and half the effective PCM rate of DoP. Such a property may be desired when upporting DSD128 without exposing a 352.8kHz PCM rate, for example. Ports -..... +----- The codebase expects 1-bit ports to be defined in the application XN file for the DSD data and clock lines for example:: diff --git a/lib_xua/doc/rst/opt_i2s.rst b/lib_xua/doc/rst/opt_i2s.rst index 894764e8..681626d9 100644 --- a/lib_xua/doc/rst/opt_i2s.rst +++ b/lib_xua/doc/rst/opt_i2s.rst @@ -1,7 +1,7 @@ |newpage| I2S/TDM -~~~~~~~ +======= I2S/TDM is typically fundamental to most products and is built into the ``XUA_AudioHub()`` core. diff --git a/lib_xua/doc/rst/opt_location.rst b/lib_xua/doc/rst/opt_location.rst index 60047363..45a5d1ee 100644 --- a/lib_xua/doc/rst/opt_location.rst +++ b/lib_xua/doc/rst/opt_location.rst @@ -1,7 +1,7 @@ |newpage| Code Location -~~~~~~~~~~~~~ +============= When designing a system there is a choice as to which hardware resources to use for each interface. In a multi-tile system the codebase needs to be informed as to which tiles to use for these hardware diff --git a/lib_xua/doc/rst/opt_midi.rst b/lib_xua/doc/rst/opt_midi.rst index 97c732aa..8b9fe96a 100644 --- a/lib_xua/doc/rst/opt_midi.rst +++ b/lib_xua/doc/rst/opt_midi.rst @@ -2,7 +2,7 @@ |newpage| MIDI -~~~~ +==== The codebase supports MIDI input/output over USB as per `Universal Serial Bus Device Class Definition for MIDI Devices `_. diff --git a/lib_xua/doc/rst/opt_mixer.rst b/lib_xua/doc/rst/opt_mixer.rst index 17f3f6a3..fde57569 100644 --- a/lib_xua/doc/rst/opt_mixer.rst +++ b/lib_xua/doc/rst/opt_mixer.rst @@ -1,7 +1,7 @@ |newpage| Mixer -~~~~~ +===== The codebase supports audio mixing functionality with highly flexible routing options. diff --git a/lib_xua/doc/rst/opt_other.rst b/lib_xua/doc/rst/opt_other.rst index 72a84f92..5cfcecad 100644 --- a/lib_xua/doc/rst/opt_other.rst +++ b/lib_xua/doc/rst/opt_other.rst @@ -1,11 +1,10 @@ |newpage| Other Options -~~~~~~~~~~~~~ +============= There are a few other, lesser used, options available. - .. _opt_other_defines: .. list-table:: Other defines diff --git a/lib_xua/doc/rst/opt_pdm.rst b/lib_xua/doc/rst/opt_pdm.rst index e1ceaeb3..4e4dbab5 100644 --- a/lib_xua/doc/rst/opt_pdm.rst +++ b/lib_xua/doc/rst/opt_pdm.rst @@ -1,7 +1,7 @@ |newpage| PDM Microphones -~~~~~~~~~~~~~~~ +=============== The codebase supports input from up to 8 PDM microphones. diff --git a/lib_xua/doc/rst/opt_spdif_rx.rst b/lib_xua/doc/rst/opt_spdif_rx.rst index 2f94d659..1000ef20 100644 --- a/lib_xua/doc/rst/opt_spdif_rx.rst +++ b/lib_xua/doc/rst/opt_spdif_rx.rst @@ -1,7 +1,7 @@ |newpage| S/PDIF Receive -~~~~~~~~~~~~~~ +============== The codebase supports a single, stereo, S/PDIF receiver. This can be input via 75 Ω coaxial or optical fibre. In order to provide S/PDIF functionality ``lib_xua`` uses ``lib_spdif`` (https://www.github.com/xmos/lib_spdif). diff --git a/lib_xua/doc/rst/opt_spdif_tx.rst b/lib_xua/doc/rst/opt_spdif_tx.rst index 9a080754..7d4bf7e0 100644 --- a/lib_xua/doc/rst/opt_spdif_tx.rst +++ b/lib_xua/doc/rst/opt_spdif_tx.rst @@ -1,7 +1,7 @@ |newpage| S/PDIF Transmit -~~~~~~~~~~~~~~~ +=============== The codebase supports a single, stereo, S/PDIF transmitter. This can be output over 75 Ω coaxial or optical fibre. In order to provide S/PDIF transmit functionality ``lib_xua`` uses ``lib_spdif`` (https://www.github.com/xmos/lib_spdif). diff --git a/lib_xua/doc/rst/opt_strings.rst b/lib_xua/doc/rst/opt_strings.rst index 2a0c60a5..dab165b6 100644 --- a/lib_xua/doc/rst/opt_strings.rst +++ b/lib_xua/doc/rst/opt_strings.rst @@ -1,6 +1,6 @@ Strings and ID's -~~~~~~~~~~~~~~~~ +================ The codebase includes various strings and ID's that should be customised to match the product requirements. These are listed in ::ref:`opt_strings_defines`. diff --git a/lib_xua/doc/rst/opt_sync.rst b/lib_xua/doc/rst/opt_sync.rst index 4fa794a5..dce27bab 100644 --- a/lib_xua/doc/rst/opt_sync.rst +++ b/lib_xua/doc/rst/opt_sync.rst @@ -2,7 +2,7 @@ |newpage| Synchronisation -~~~~~~~~~~~~~~~ +=============== The codebase supports "Synchronous" and "Asynchronous" modes for USB transfer as defined by the USB specification(s). diff --git a/lib_xua/doc/rst/overview.rst b/lib_xua/doc/rst/overview.rst index 0eccdf19..8be7bae7 100644 --- a/lib_xua/doc/rst/overview.rst +++ b/lib_xua/doc/rst/overview.rst @@ -1,6 +1,5 @@ Overview --------- - +******** .. table:: :class: vertical-borders @@ -75,5 +74,3 @@ Overview | Reference code is maintained by XMOS Limited. | +-------------------------------------------------------------------------------------------------------------------------------+ - - diff --git a/lib_xua/doc/rst/sw.rst b/lib_xua/doc/rst/sw.rst index 8f48241f..f3629a65 100644 --- a/lib_xua/doc/rst/sw.rst +++ b/lib_xua/doc/rst/sw.rst @@ -1,8 +1,8 @@ Implementation Detail ---------------------- +********************* -This section examines the implementation of the various components that make up ``lib_xua``. It also examines the integration of dependencies and supporting libraries. +This chapter examines the implementation of the various components that make up ``lib_xua``. It also examines the integration of dependencies and supporting libraries. .. toctree:: @@ -10,8 +10,8 @@ This section examines the implementation of the various components that make up sw_ep0 sw_xud sw_clocking - sw_spdif sw_mixer + sw_spdif sw_spdif_rx sw_adat_rx sw_midi diff --git a/lib_xua/doc/rst/sw_adat_rx.rst b/lib_xua/doc/rst/sw_adat_rx.rst index dbcb9c77..5472a4e6 100644 --- a/lib_xua/doc/rst/sw_adat_rx.rst +++ b/lib_xua/doc/rst/sw_adat_rx.rst @@ -1,7 +1,7 @@ |newpage| ADAT Receive ------------- +============ The ADAT receive component receives up to eight channels of audio at a sample rate of 44.1kHz or 48kHz. The API for calling the receiver functions is diff --git a/lib_xua/doc/rst/sw_audio.rst b/lib_xua/doc/rst/sw_audio.rst index 13ae57ca..a98b7c19 100755 --- a/lib_xua/doc/rst/sw_audio.rst +++ b/lib_xua/doc/rst/sw_audio.rst @@ -3,7 +3,7 @@ .. _usb_audio_sec_audio: Audio Hub -......... +========= The Audio Hub task performs many functions. It receives and transmits samples from/to the Decoupler or Mixer core over a channel. @@ -96,9 +96,8 @@ Two master clock frequencies to support 44.1kHz and 48kHz audio frequencies (e.g and 12.288/24.576MHz respectively). This master clock input is then provided to the external audio hardware and the xCORE device. - Port Configuration (xCORE Master) -+++++++++++++++++++++++++++++++++ +--------------------------------- The default software configuration is xCORE is I2S master. That is, the XMOS device provides the BCLK and LRCLK signals to the external audio hardware @@ -143,7 +142,7 @@ before the data (as required by the I2S standard) and alternates between high an and right channels of audio. Changing Audio Sample Frequency -+++++++++++++++++++++++++++++++ +------------------------------- .. _usb_audio_sec_chang-audio-sample: @@ -159,5 +158,3 @@ functions. Once this is complete, the I2S/TDM interface (i.e. the main loop in AudioHub) is restarted at the new frequency. - - diff --git a/lib_xua/doc/rst/sw_clocking.rst b/lib_xua/doc/rst/sw_clocking.rst index 9afde000..65880cb5 100755 --- a/lib_xua/doc/rst/sw_clocking.rst +++ b/lib_xua/doc/rst/sw_clocking.rst @@ -4,7 +4,7 @@ .. _usb_audio_sec_clock_recovery: External Clock Recovery (Clock Gen) ------------------------------------ +=================================== To provide an audio master clock an application may use selectable oscillators, clock generation IC or, in the case of xCORE.ai devices, integrated secondary PLL, to generate fixed @@ -14,7 +14,7 @@ It may also use an external PLL/Clock Multiplier to generate a master clock base the xCORE. Using an external PLL/Clock Multiplier allows an Asynchronous mode design to lock to an external -clock source from a digital stream (e.g. S/PDIF or ADAT input). The code-base supports the Cirrus +clock source from a digital stream (e.g. S/PDIF or ADAT input). The codebase supports the Cirrus Logic CS2100 device for this purpose. Other devices may be supported via code modification. .. note:: diff --git a/lib_xua/doc/rst/sw_ep0.rst b/lib_xua/doc/rst/sw_ep0.rst index 642f7b27..39e90a06 100644 --- a/lib_xua/doc/rst/sw_ep0.rst +++ b/lib_xua/doc/rst/sw_ep0.rst @@ -3,14 +3,14 @@ .. _usb_audio_sec_usb: Endpoint 0: Management and Control -.................................. +================================== All USB devices must support a mandatory control endpoint, Endpoint 0. This controls the management tasks of the USB device. These tasks can be generally split into enumeration, audio configuration and firmware upgrade requests. Enumeration -~~~~~~~~~~~ +----------- When the device is first attached to a host, enumeration occurs. This process involves the host interrogating the device as to its functionality. The device does this by presenting several interfaces to the host via a set of descriptors. @@ -41,12 +41,13 @@ The function may also return ``XUD_RES_RST`` if a bus-reset has been issued onto Since the ``USB_StandardRequests()`` function STALLs an unknown request, the endpoint 0 code must first parse the ``USB_SetupPacket_t`` structure to handle device specific requests and then call ``USB_StandardRequests()`` as required. Over-riding Standard Requests -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------- The USB Audio design "over-rides" some of the requests handled by ``USB_StandardRequests()``, for example it uses the SET_INTERFACE request to indicate if the host is streaming audio to the device. In this case the setup packet is parsed, the relevant action taken, the ``USB_StandardRequests()`` is still called to handle the response to the host. Class Requests -~~~~~~~~~~~~~~ +-------------- + Before making the call to ``USB_StandardRequests()`` the setup packet is parsed for Class requests. These are handled in functions such as ``AudioClassRequests_1()``, ``AudioClassRequests_2``, ``DFUDeviceRequests()`` etc depending on the type of request. Any device specific requests are handled - in this case Audio Class, MIDI class, DFU requests etc. @@ -54,7 +55,7 @@ Any device specific requests are handled - in this case Audio Class, MIDI class, Some of the common Audio Class requests and their associated behaviour will now be examined. Audio Requests -++++++++++++++ +^^^^^^^^^^^^^^ When the host issues an audio request (e.g. sample rate or volume change), it sends a command to Endpoint 0. Like all requests this is returned from ``USB_GetSetupPacket()``. After some parsing (namely as Class Request to an Audio Interface) the request is handled by either the ``AudioClassRequests_1()`` or ``AudioClassRequests_2()`` function (based on whether the device is running in Audio Class 1.0 or 2.0 mode). @@ -63,7 +64,7 @@ Note, Audio Class 1.0 Sample rate changes are send to the relevant endpoint, rat The ``AudioClassRequests_X()`` functions further parses the request in order to ascertain the correct audio operation to execute. Audio Request: Set Sample Rate -++++++++++++++++++++++++++++++ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``AudioClassRequests_2()`` function parses the passed ``USB_SetupPacket_t`` structure for a ``CUR`` request of type ``SAM_FREQ_CONTROL`` to a Clock Unit in the devices topology (as described in the devices descriptors). @@ -72,7 +73,7 @@ The new sample frequency is extracted and passed via channel to the rest of the .. _usb_audio_sec_audio-requ-volume: Audio Request: Volume Control -+++++++++++++++++++++++++++++ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When the host requests a volume change, it sends an audio interface request to Endpoint 0. An array is @@ -102,10 +103,10 @@ to the mixer to change the volume. Mixer commands are described in :ref:`usb_audio_sec_mixer`. Audio Endpoints (Endpoint Buffer and Decoupler) -............................................... +=============================================== Endpoint Buffer -~~~~~~~~~~~~~~~ +--------------- All endpoints other that Endpoint 0 are handled in one core. This core is implemented in the file ``ep_buffer.xc``. This core communicates directly with the XUD library. @@ -114,7 +115,7 @@ The USB buffer core is also responsible for feedback calculation based on USB St (SOF) notification and reads from the port counter of a port connected to the master clock. Decouple -~~~~~~~~ +-------- The decoupler supplies the USB buffering core with buffers to transmit/receive audio data to/from the host. It marshals these buffers into @@ -125,7 +126,7 @@ matching the audio rate to the USB packet rate). The decoupler is implemented in the file ``decouple.xc``. Audio Buffering Scheme -~~~~~~~~~~~~~~~~~~~~~~~ +---------------------- This scheme is executed by co-operation between the buffering core, the decouple core and the XUD library. @@ -133,7 +134,6 @@ core, the decouple core and the XUD library. For data going from the device to the host the following scheme is used: - #. The Decouple core receives samples from the Audio Hub core and puts them into a FIFO. This FIFO is split into packets when data is entered into it. Packets are stored in a format consisting of their @@ -152,11 +152,9 @@ used: Decouple core that the buffer has been sent and the Decouple core moves the read pointer of the FIFO. - For data going from the host to the device the following scheme is used: - #. The Decouple core passes a pointer to the Endpoint Buffer core pointing into a FIFO of data and signals to the XUD library that the Endpoint Buffer core is ready to receive. @@ -171,9 +169,8 @@ used: #. Upon request from the Audio Hub core, the Decouple core sends samples to the Audio Hub core by reading samples out of the FIFO. - Decoupler/Audio Core interaction -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------- To meet timing requirements of the audio system (i.e Audio Hub/Mixer), the Decoupler core must respond to requests from the audio system to @@ -200,7 +197,6 @@ in channel count sized chunks (i.e. ``NUM_USB_CHAN_OUT`` and The complete communication scheme is shown in the table below (for non sample frequency change case): - .. table:: Decouple/Audio System Channel Communication +-----------------+-----------------+-----------------------------------------+ @@ -242,7 +238,7 @@ frequency change case): (this is especially advantageous in the DSD over PCM (DoP) case) Asynchronous Feedback -+++++++++++++++++++++ +--------------------- When built to operate in Asynchronous mode the device uses a feedback endpoint to report the rate at which audio is output/input to/from external audio interfaces/devices. This feedback is in accordance with @@ -265,7 +261,7 @@ sent to the host. In practice this an explicit feedback endpoint is normally use in Microsoft Windows operating systems (see ``UAC_FORCE_FEEDBACK_EP``). USB Rate Control -++++++++++++++++ +---------------- .. _usb_audio_sec_usb-rate-control: diff --git a/lib_xua/doc/rst/sw_hid.rst b/lib_xua/doc/rst/sw_hid.rst index b8157127..48480c5a 100755 --- a/lib_xua/doc/rst/sw_hid.rst +++ b/lib_xua/doc/rst/sw_hid.rst @@ -1,5 +1,5 @@ Audio Controls via Human Interface Device (HID) ------------------------------------------------- +=============================================== The design supports simple audio controls such as play/pause, volume up/down etc via the USB Human Interface Device Class Specification. diff --git a/lib_xua/doc/rst/sw_midi.rst b/lib_xua/doc/rst/sw_midi.rst index 700db3c5..dea78378 100755 --- a/lib_xua/doc/rst/sw_midi.rst +++ b/lib_xua/doc/rst/sw_midi.rst @@ -1,11 +1,11 @@ |newpage| MIDI ----- +==== -The MIDI core implements a 31250 baud UART for both input and output. On receiving 32-bit USB MIDI events +The MIDI core implements a 31250 baud UART for both input and output. On receiving 32=bit USB MIDI events from the Endpoint Buffer core, it parses these and translates them to 8-bit MIDI messages which are sent -over UART. Similarly, incoming 8-bit MIDI messages are aggregated into 32-bit USB-MIDI events and +over UART. Similarly, incoming 8-bit MIDI messages are aggregated into 32-bit USB MIDI events and passed on to the Endpoint Buffer core. The MIDI core is implemented in the file ``usb_midi.xc``. The Endpoint Buffer core implements the two Bulk endpoints (one In and one Out) as well as interacting diff --git a/lib_xua/doc/rst/sw_pdm.rst b/lib_xua/doc/rst/sw_pdm.rst index 795d7d57..91e3a174 100755 --- a/lib_xua/doc/rst/sw_pdm.rst +++ b/lib_xua/doc/rst/sw_pdm.rst @@ -1,7 +1,7 @@ |newpage| PDM Microphones ---------------- +=============== The XMOS USB Audio Reference Design firmware is capable of integrating with PDM microphones. The PDM stream from the microphones is converted to PCM and output to the host via USB. @@ -46,9 +46,8 @@ After the decimation to the output sample-rate various other steps take place e. and compensation etc. Please refer to the documentation provided with ``lib_mic_array`` for further implementation detail and complete feature set. - PDM Microphone Hardware Characteristics -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------------- The PDM microphones require a *clock input* and provide the PDM signal on a *data output*. All of the PDM microphones must share the same clock signal (buffered on the PCB as appropriate), and @@ -78,7 +77,7 @@ divide down 12.288 MHz master clock. Or, if clock accuracy is not important, the reference can be divided down to provide an approximate clock. Usage & Integration -~~~~~~~~~~~~~~~~~~~ +------------------- A PDM microphone wrapper is called from ``main()`` and takes one channel argument connecting it to the rest of the system: @@ -113,3 +112,4 @@ sends the frame of audio back over this channel. Note, it is assumed that the system shares a global master-clock, therefore no additional buffering or rate-matching/conversion is required. + diff --git a/lib_xua/doc/rst/sw_resource.rst b/lib_xua/doc/rst/sw_resource.rst index 8945f7c7..dafa5d10 100755 --- a/lib_xua/doc/rst/sw_resource.rst +++ b/lib_xua/doc/rst/sw_resource.rst @@ -3,7 +3,7 @@ .. _usb_audio_sec_resource_usage: Resource Usage --------------- +============== The following table details the resource usage of each component of the reference design software. Note, memory usage is approximate and varies based on device used, compiler settings etc. @@ -50,3 +50,4 @@ Note, memory usage is approximate and varies based on device used, compiler sett Unlike other interfaces, since the USB PHY is internal the USB ports are a fixed set of ports and cannot be modified. See ``lib_xud`` documentation for full details. + diff --git a/lib_xua/doc/rst/sw_spdif.rst b/lib_xua/doc/rst/sw_spdif.rst index 8366b6d1..12518c56 100755 --- a/lib_xua/doc/rst/sw_spdif.rst +++ b/lib_xua/doc/rst/sw_spdif.rst @@ -2,7 +2,7 @@ |newpage| S/PDIF Transmit -............... +=============== ``lib_xua`` supports the development of devices with S/PDIF transmit throught the use of ``lib_spdif``. The XMOS S/SPDIF transmitter component runs in a single core and supports sample-rates upto 192kHz. @@ -21,7 +21,7 @@ bits) and transmitted in biphase-mark encoding (BMC) with respect to an *externa Note that a minor change to the ``SpdifTransmitPortConfig`` function would enable *internal* master clock generation (e.g. when clock source is already locked to desired audio clock). -.. list-table:: S/PDIF Capabilities +.. list-table:: S/PDIF Capabilities * - **Sample frequencies** - 44.1, 48, 88.2, 96, 176.4, 192 kHz @@ -31,7 +31,7 @@ clock generation (e.g. when clock source is already locked to desired audio cloc - ``lib_spdif`` Clocking -++++++++ +-------- .. only:: latex @@ -54,7 +54,7 @@ This resamples the master clock to its clock domain (oscillator), which introduc A typical jitter-reduction scheme is an external D-type flip-flop clocked from the master clock (as shown in the preceding diagram). Usage -+++++ +----- The interface to the S/PDIF transmitter core is via a normal channel with streaming built-ins (``outuint``, ``inuint``). Data format should be 24-bit left-aligned in a 32-bit word: ``0x12345600`` @@ -84,9 +84,8 @@ The following protocol is used on the channel: This communication is wrapped up in the API functions provided by ``lib_spdif``. - -Output stream structure -+++++++++++++++++++++++ +Output Stream Structure +----------------------- The stream is composed of words with the following structure shown in :ref:`usb_audio_spdif_stream_structure`. The channel status bits are diff --git a/lib_xua/doc/rst/sw_spdif_rx.rst b/lib_xua/doc/rst/sw_spdif_rx.rst index 9ba652f6..790c4d7c 100644 --- a/lib_xua/doc/rst/sw_spdif_rx.rst +++ b/lib_xua/doc/rst/sw_spdif_rx.rst @@ -1,7 +1,7 @@ |newpage| S/PDIF Receive ---------------- +============== XMOS devices can support S/PDIF receive up to 192kHz - see ``lib_spdif`` for full specifications. @@ -45,7 +45,7 @@ The tag has one of three values: See S/PDIF, IEC 60958-3:2006, specification for further details on format, user bits etc. Usage and Integration -+++++++++++++++++++++ +--------------------- Since S/PDIF is a digital steam the devices master clock must be synchronised to it. This is typically done with an external device. See `Clock Recovery` (:ref:`usb_audio_sec_clock_recovery`). diff --git a/lib_xua/doc/rst/sw_xud.rst b/lib_xua/doc/rst/sw_xud.rst index 11a65c92..618ea70f 100644 --- a/lib_xua/doc/rst/sw_xud.rst +++ b/lib_xua/doc/rst/sw_xud.rst @@ -2,7 +2,7 @@ |newpage| XMOS USB Device (XUD) Library -............................. +============================= All low level communication with the USB host is handled by the XMOS USB Device (XUD) library - `lib_xud` diff --git a/lib_xua/doc/rst/using.rst b/lib_xua/doc/rst/using.rst index 8ac6e5cb..3293c470 100644 --- a/lib_xua/doc/rst/using.rst +++ b/lib_xua/doc/rst/using.rst @@ -1,12 +1,12 @@ Basic Usage ------------ +*********** This sections describes the basic usage of `lib_xua` and provides a guide on how to program USB Audio Devices. Library Structure -~~~~~~~~~~~~~~~~~ +================= The code is split into several directories. @@ -26,7 +26,7 @@ Note, the midi and dfu directories are potential candidates for separate libs in Using in a Project -~~~~~~~~~~~~~~~~~~ +================== All `lib_xua` functions can be accessed via the ``xua.h`` header file:: @@ -39,7 +39,7 @@ It is also required to add ``lib_xua`` to the ``USED_MODULES`` field of your app .. _sec_basic_usage_codeless: "Codeless" Programming Model -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============================ Whilst it is possible to code a USB Audio device using the building blocks provided by `lib_xua` it is realised that this might not be desirable for many classes of customers or products. @@ -71,7 +71,7 @@ set ``EXCLUDE_USB_AUDIO_MAIN`` to 1 in the application makefile or ``xua_conf.h` ::ref:`sec_advanced_usage`. Configuring lib_xua -~~~~~~~~~~~~~~~~~~~ +=================== Configuration of the various build time options of ``lib_xua`` is done via the optional header `xua_conf.h`. To allow the build scripts to locate this file it should reside somewhere in the application `src` directory. @@ -93,9 +93,8 @@ should continue to include `xua.h` as previously directed. A simple example is s #endif - User Functions -~~~~~~~~~~~~~~ +============== To enable custom functionality, such as configuring external audio hardware, bespoke behaviour on stream start/stop etc, various functions can be overridden by the user. (see ::ref:`sec_api` for diff --git a/lib_xua/doc/rst/using_adv.rst b/lib_xua/doc/rst/using_adv.rst index 15a11e57..e1909fc5 100644 --- a/lib_xua/doc/rst/using_adv.rst +++ b/lib_xua/doc/rst/using_adv.rst @@ -1,7 +1,7 @@ .. _sec_advanced_usage: Advanced Usage --------------- +************** Whilst it is possible to program USB Audio devices using ``lib_xua`` by only setting defines (see :ref:`sec_basic_usage_codeless`) some developers may want to code a USB Audio device from diff --git a/lib_xua/doc/rst/using_adv_core_comp.rst b/lib_xua/doc/rst/using_adv_core_comp.rst index b7189ba4..1d692b35 100644 --- a/lib_xua/doc/rst/using_adv_core_comp.rst +++ b/lib_xua/doc/rst/using_adv_core_comp.rst @@ -1,5 +1,5 @@ Running the Core Components -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=========================== In their most basic form the core components can be run as follows:: diff --git a/lib_xua/doc/rst/using_adv_core_hw.rst b/lib_xua/doc/rst/using_adv_core_hw.rst index 401b6477..012fe45c 100644 --- a/lib_xua/doc/rst/using_adv_core_hw.rst +++ b/lib_xua/doc/rst/using_adv_core_hw.rst @@ -1,5 +1,5 @@ Core Hardware Resources -~~~~~~~~~~~~~~~~~~~~~~~ +======================= The user must declare and initialise relevant hardware resources (globally) and pass them to the relevant function of `lib_xua`. diff --git a/lib_xua/doc/rst/using_adv_i2s.rst b/lib_xua/doc/rst/using_adv_i2s.rst index 4fceffa8..12d5029c 100644 --- a/lib_xua/doc/rst/using_adv_i2s.rst +++ b/lib_xua/doc/rst/using_adv_i2s.rst @@ -1,7 +1,7 @@ |newpage| I2S/TDM -~~~~~~~ +======= I2S/TDM is typically fundamental to most products and is built into the ``XUA_AudioHub()`` core. diff --git a/lib_xua/doc/rst/using_adv_mixer.rst b/lib_xua/doc/rst/using_adv_mixer.rst index e5b9cc11..6317b971 100644 --- a/lib_xua/doc/rst/using_adv_mixer.rst +++ b/lib_xua/doc/rst/using_adv_mixer.rst @@ -1,7 +1,7 @@ |newpage| Mixer -~~~~~ +===== Since the mixer has no I/O the instantiation is straight forward. Communication wises, the mixer cores are inserted between the `AudioHub` and Buffering core(s) diff --git a/lib_xua/module_build_info b/lib_xua/module_build_info index 6c1e9361..9351ad3f 100644 --- a/lib_xua/module_build_info +++ b/lib_xua/module_build_info @@ -1,4 +1,4 @@ -VERSION = 3.3.0 +VERSION = 3.3.1 DEBUG ?= 0 @@ -11,7 +11,7 @@ endif DEPENDENT_MODULES = lib_locks(>=2.1.0) \ lib_logging(>=3.1.1) \ lib_mic_array(>=4.5.0) \ - lib_spdif(>=4.1.0) \ + lib_spdif(>=4.2.1) \ lib_xassert(>=4.1.0) \ lib_xud(>=2.2.1) \ lib_adat(>=1.0.0)