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

Documentation updates

Browse Source
This commit is contained in:
Ross Owen
2023-07-17 14:23:09 +01:00
parent 50966dda90
commit 77fad35497
3 changed files with 67 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
lib_xua/api/xua_conf_default.h
View File

@@ -227,21 +227,27 @@
*/
/**
* @brief Max supported sample frequency for device (Hz). Default: 192000
* @brief Max supported sample frequency for device (Hz).
*
* Default: 192000Hz
*/
#ifndef MAX_FREQ
#define MAX_FREQ (192000)
#endif
/**
* @brief Min supported sample frequency for device (Hz). Default 44100
* @brief Min supported sample frequency for device (Hz).
*
* Default: 44100Hz
*/
#ifndef MIN_FREQ
#define MIN_FREQ (44100)
#endif
/**
* @brief Master clock defines for 44100 rates (in Hz). Default: NONE (Must be defined by app)
* @brief Master clock defines for 44100 rates (in Hz).
*
* Default: NONE (Must be defined by app)
*/
#ifndef MCLK_441
#error MCLK_441 not defined
@@ -249,7 +255,9 @@
#endif
/**
* @brief Master clock defines for 48000 rates (in Hz). Default: NONE (Must be defined by app)
* @brief Master clock defines for 48000 rates (in Hz).
*
* Default: NONE (Must be defined by app)
*/
#ifndef MCLK_48
#error MCLK_48 not defined
@@ -257,7 +265,7 @@
#endif
/**
* @brief Enable/disable the use of the secondary/application PLL for generating master-clock.
* @brief Enable/disable the use of the secondary/application PLL for generating master-clocks.
* Only available on xcore.ai devices.
*
* Default: Enabled (for xcore.ai devices)
@@ -276,7 +284,9 @@
#endif
/**
* @brief Default device sample frequency. A safe default should be used. Default: MIN_FREQ
* @brief Default device sample frequency. A safe default should be used.
*
* Default: MIN_FREQ
*/
#ifndef DEFAULT_FREQ
#define DEFAULT_FREQ (MIN_FREQ)

15
lib_xua/doc/rst/api_defines.rst
View File

@@ -8,9 +8,9 @@ An application using the USB audio framework needs to have defines set for confi
Defaults for these defines are found in ``xua_conf_default.h``.
These defines should be over-ridden in an optional header file ``xua_conf.h`` file or in the ``Makefile``
for a relevant build configuration.
for a relevant build configuration.
This section fully documents all of the settable defines and their default values (where appropriate).
This section fully documents all of the settable defines and their default values (where appropriate).
Code Location (tile)
--------------------
@@ -25,12 +25,12 @@ Code Location (tile)
Channel Counts
--------------
.. doxygendefine:: NUM_USB_CHAN_OUT
.. doxygendefine:: NUM_USB_CHAN_IN
.. doxygendefine:: I2S_CHANS_DAC
.. doxygendefine:: I2S_CHANS_ADC
.. doxygendefine:: NUM_USB_CHAN_OUT
.. doxygendefine:: NUM_USB_CHAN_IN
.. doxygendefine:: I2S_CHANS_DAC
.. doxygendefine:: I2S_CHANS_ADC
Frequencies and Clocks
Frequencies and Clocks
----------------------
.. doxygendefine:: MAX_FREQ
@@ -38,6 +38,7 @@ Frequencies and Clocks
.. doxygendefine:: DEFAULT_FREQ
.. doxygendefine:: MCLK_441
.. doxygendefine:: MCLK_48
.. doxygendefine:: XUA_USE_APP_PLL
Audio Class
-----------

56
lib_xua/doc/rst/opt_sync.rst
View File

@@ -1,27 +1,27 @@
|newpage|
Synchronisation
===============
Synchronisation & Clocking
==========================
The codebase supports "Synchronous" and "Asynchronous" modes for USB transfer as defined by the
The codebase supports "Synchronous" and "Asynchronous" modes for USB transfer as defined by the
USB specification(s).
Asynchronous mode (``XUA_SYNCMODE_ASYNC``) has the advantage that the device is clock-master. This means that
a high-quality local master-clock source can be utilised. It also has the benefit that the device may
synchronise it's master clock to an external digital input stream e.g. S/PDIF and thus avoiding sample-rate
Asynchronous mode (``XUA_SYNCMODE_ASYNC``) has the advantage that the device is clock-master. This means that
a high-quality local master-clock source can be utilised. It also has the benefit that the device may
synchronise it's master clock to an external digital input stream e.g. S/PDIF thus avoiding sample-rate
conversion.
The drawback of this mode is that it burdens the host with syncing to the device which some hosts
The drawback of this mode is that it burdens the host with syncing to the device which some hosts
may not support. This is especially pertinent to embedded hosts, however, most PC's and mobile devices
will indeed support this mode.
Synchronous mode (``XUA_SYNCMODE_SYNC``) is an option if the target host does not support asynchronous mode
or if it is desirable to synchronise many devices to a single host. It should be noted, however, that input
or if it is desirable to synchronise many devices to a single host. It should be noted, however, that input
from digital streams, such as S/PDIF, are not currently supported in this mode.
.. note::
The selection of synchronisation mode is done at build time and cannot be changed dynamically.
Setting the synchronisation mode of the device is done using the define in :ref:`opt_sync_defines`
@@ -39,10 +39,17 @@ Setting the synchronisation mode of the device is done using the define in :ref:
- USB synchronisation mode
- ``XUA_SYNCMODE_ASYNC``
When operating in synchronous mode an external Cirrus Logic CS2100 device is required for master clock
generation. The codebase expects to drive a synchronisation signal to this external device
When operating in asynchronous mode xcore.ai based devices will be configured, by default, to use their internal
"Applications" PLL to generated an appropriate master-clock signal. To disable this ``XUA_USE_APP_PLL`` should be
set to ``0``. For all other devices the developer is expected to supply external master-clock generation circuitry.
The programmer should ensure the define in :ref:`opt_sync_ref_defines` is set appropriately.
When operating in synchronous mode an xcore.ai based device, by default, will be configured to used it's internal
"application" PLL to generate a master-clock synchronised to the USB host.
xcore-200 based devices do not have this application PLL and so an external Cirrus Logic CS2100 device is required
for master clock generation. The codebase expects to drive a synchronisation signal to this external device.
In this case the developer should ensure the define in :ref:`opt_sync_ref_defines` is set appropriately.
.. _opt_sync_ref_defines:
@@ -57,10 +64,33 @@ The programmer should ensure the define in :ref:`opt_sync_ref_defines` is set ap
- Tile location of reference to CS2100 device
- ``AUDIO_IO_TILE``
The codebase expects this reference signal port to be defined in the application XN file as ``PORT_PLL_REF``.
The codebase expects this reference signal port to be defined in the application XN file as ``PORT_PLL_REF``.
This may be a port of any bit-width, however, connection to bit[0] is assumed::
<Port Location="XS1_PORT_1A" Name="PORT_PLL_REF"/>
Configuration of the external CS2100 device (typically via I2C) is beyond the scope of this document.
Note, in all cases the master-clocks are generated (when using the xcore.ai Application PLL) or should be generated
(if using external circuitry) to match the defines in :ref:`opt_sync_mclk_defines`.
.. _opt_sync_mclk_defines:
.. list-table:: Master clock frequencies
:header-rows: 1
:widths: 20 80 20
* - Define
- Description
- Default
* - ``MCLK_48``
- Master clock frequency (in Hz)used for sample-rates related to 48KHz
- NOTE
* - ``MCLK_441``
- Master clock frequency (in Hz) used for sample-rates related to 44.1KHz
- NONE
.. note::
The master clock defines above are critical for proper operation and default values are not provided.
If they are not defined by the devloper a build error will be emmited.