Updates to documentation (#280)

Documentation updates (including moving of header files
This commit is contained in:
Ross Owen
2022-09-30 16:11:53 +01:00
committed by GitHub
parent 0c368e0356
commit eb86a72882
66 changed files with 2294 additions and 955 deletions

View File

@@ -1,20 +1,22 @@
// Copyright 2017-2021 XMOS LIMITED.
// Copyright 2017-2022 XMOS LIMITED.
// This Software is subject to the terms of the XMOS Public Licence: Version 1.
#ifndef _XUA_H_
#define _XUA_H_
#ifndef __XUA_H__
#define __XUA_H__
#include <xs1.h>
#include "xua_conf_full.h"
#if __XC__ || __STDC__
#include "xua_audiohub.h"
#include "xua_endpoint0.h"
#include "xua_buffer.h"
#include "xua_mixer.h"
#endif
#if __XC__
#include "xua_clocking.h"
#include "xua_midi.h"
#if XUA_NUM_PDM_MICS > 0
#include "xua_pdm_mic.h"
#endif

View File

@@ -22,7 +22,7 @@
*
* \param clk_audio_mclk Nullable clockblock to be clocked from master clock
*
* \param clk_audio_mclk Nullable clockblock to be clocked from i2s clock
* \param clk_audio_bclk Nullable clockblock to be clocked from i2s bit clock
*
* \param p_mclk_in Master clock inport port (must be 1-bit)
*
@@ -34,7 +34,9 @@
*
* \param p_i2s_adc Nullable array of ports for I2S data input lines
*
* \param c_dig channel connected to the clockGen() thread for
* \param c_spdif_tx Channel connected to S/PDIF transmiter core from lib_spdif
*
* \param c_dig Channel connected to the clockGen() thread for
* receiving/transmitting samples
*/
void XUA_AudioHub(chanend ?c_aud,
@@ -45,10 +47,10 @@ void XUA_AudioHub(chanend ?c_aud,
buffered _XUA_CLK_DIR port:32 ?p_bclk,
buffered out port:32 (&?p_i2s_dac)[I2S_WIRES_DAC],
buffered in port:32 (&?p_i2s_adc)[I2S_WIRES_ADC]
#if (XUA_SPDIF_TX_EN) //&& (SPDIF_TX_TILE != AUDIO_IO_TILE)
#if (XUA_SPDIF_TX_EN) || defined(__DOXYGEN__)
, chanend c_spdif_tx
#endif
#if (XUA_SPDIF_RX_EN || XUA_ADAT_RX_EN)
#if (XUA_SPDIF_RX_EN || XUA_ADAT_RX_EN || defined(__DOXYGEN__))
, chanend c_dig
#endif
#if (XUD_TILE != 0) && (AUDIO_IO_TILE == 0) && (XUA_DFU_EN == 1)

View File

@@ -5,58 +5,59 @@
#if __XC__
#include "xua.h"
#include "clocking.h"
#include "xua_clocking.h" /* Required for pll_ref_if */
/** USB Audio Buffering Core.
/** USB Audio Buffering Core(s).
*
* This function buffers USB audio data between the XUD layer and the decouple
* thread. Most of the chanend parameters to the function should be connected to
* XUD_Manager()
* This function buffers USB audio data between the XUD and the audio subsystem.
* Most of the chanend parameters to the function should be connected to
* XUD_Manager(). The uses two cores.
*
* \param c_aud_out Audio OUT endpoint channel connected to the XUD
* \param c_aud_in Audio IN endpoint channel connected to the XUD
* \param c_aud_fb Audio feedback endpoint channel connected to the XUD
* \param c_midi_from_host MIDI OUT endpoint channel connected to the XUD
* \param c_midi_to_host MIDI IN endpoint channel connected to the XUD
* \param c_int Audio clocking interrupt endpoint channel connected to the XUD
* \param c_clk_int Optional chanend connected to the clockGen() thread if present
* \param c_sof Start of frame channel connected to the XUD
* \param c_aud_ctl Audio control channel connected to Endpoint0()
* \param p_off_mclk A port that is clocked of the MCLK input (not the MCLK input itself)
* \param c_aud_out Audio OUT endpoint channel connected to the XUD
* \param c_aud_in Audio IN endpoint channel connected to the XUD
* \param c_aud_fb Audio feedback endpoint channel connected to the XUD
* \param c_midi_from_host MIDI OUT endpoint channel connected to the XUD
* \param c_midi_to_host MIDI IN endpoint channel connected to the XUD
* \param c_midi Channel connected to MIDI core
* \param c_int Audio clocking interrupt endpoint channel connected to the XUD
* \param c_clk_int Optional chanend connected to the clockGen() thread if present
* \param c_sof Start of frame channel connected to the XUD
* \param c_aud_ctl Audio control channel connected to Endpoint0()
* \param p_off_mclk A port that is clocked of the MCLK input (not the MCLK input itself)
* \param c_aud Channel connected to XUA_AudioHub() core
* \param i_pll_ref Interface to task that toggles reference pin to CS2100
*/
void XUA_Buffer(
chanend c_aud_out,
#if (NUM_USB_CHAN_IN > 0)
#if (NUM_USB_CHAN_IN > 0) || defined(__DOXYGEN__)
chanend c_aud_in,
#endif
#if (NUM_USB_CHAN_IN == 0) || defined (UAC_FORCE_FEEDBACK_EP)
#if (NUM_USB_CHAN_IN == 0) || defined (UAC_FORCE_FEEDBACK_EP)
chanend c_aud_fb,
#endif
#ifdef MIDI
#if defined(MIDI) || defined(__DOXYGEN__)
chanend c_midi_from_host,
chanend c_midi_to_host,
chanend c_midi,
#endif
#if (XUA_SPDIF_RX_EN) || (XUA_ADAT_RX_EN)
#if XUA_SPDIF_RX_EN || XUA_ADAT_RX_EN || defined(__DOXYGEN__)
chanend ?c_int,
chanend ?c_clk_int,
#endif
chanend c_sof,
chanend c_aud_ctl,
in port p_off_mclk
#if (HID_CONTROLS )
#if (HID_CONTROLS)
, chanend c_hid
#endif
, chanend c_aud
#if (XUA_SYNCMODE == XUA_SYNCMODE_SYNC)
#if (XUA_SYNCMODE == XUA_SYNCMODE_SYNC) || defined(__DOXYGEN__)
, client interface pll_ref_if i_pll_ref
#endif
);
void XUA_Buffer_Ep(chanend c_aud_out,
#if (NUM_USB_CHAN_IN > 0)
#if (NUM_USB_CHAN_IN > 0) || defined(__DOXYGEN__)
chanend c_aud_in,
#endif
#if (NUM_USB_CHAN_IN == 0) || defined (UAC_FORCE_FEEDBACK_EP)
@@ -80,7 +81,7 @@ void XUA_Buffer_Ep(chanend c_aud_out,
#ifdef CHAN_BUFF_CTRL
, chanend c_buff_ctrl
#endif
#if (XUA_SYNCMODE == XUA_SYNCMODE_SYNC)
#if (XUA_SYNCMODE == XUA_SYNCMODE_SYNC) || defined(__DOXYGEN__)
, client interface pll_ref_if i_pll_ref
#endif
);

View File

@@ -0,0 +1,32 @@
// Copyright 2011-2022 XMOS LIMITED.
// This Software is subject to the terms of the XMOS Public Licence: Version 1.
#ifndef _CLOCKING_H_
#define _CLOCKING_H_
#include <xs1.h>
interface pll_ref_if
{
void toggle();
void init();
void toggle_timed(int relative);
};
[[distributable]]
void PllRefPinTask(server interface pll_ref_if i_pll_ref, out port p_sync);
/** Clock generation and digital audio I/O handling.
*
* \param c_spdif_rx channel connected to S/PDIF receive thread
* \param c_adat_rx channel connect to ADAT receive thread
* \param i_pll_ref interface to taslk that outputs clock signal to drive external frequency synthesizer
* \param c_audio channel connected to the audio() thread
* \param c_clk_ctl channel connected to Endpoint0() for configuration of the
* clock
* \param c_clk_int channel connected to the decouple() thread for clock
interrupts
*/
void clockGen(streaming chanend ?c_spdif_rx, chanend ?c_adat_rx, client interface pll_ref_if i_pll_ref, chanend c_audio, chanend c_clk_ctl, chanend c_clk_int);
#endif

View File

@@ -17,21 +17,14 @@
* @brief Location (tile) of audio I/O. Default: 0
*/
#ifndef AUDIO_IO_TILE
#define AUDIO_IO_TILE 0
#define AUDIO_IO_TILE (0)
#endif
/**
* @brief Location (tile) of audio I/O. Default: 0
*/
#ifndef XUD_TILE
#define XUD_TILE 0
#endif
/**
* @brief Location (tile) of IAP. Default: AUDIO_IO_TILE
*/
#ifndef IAP_TILE
#define IAP_TILE AUDIO_IO_TILE
#define XUD_TILE (0)
#endif
/**
@@ -66,7 +59,7 @@
* @brief Disable USB functionalty just leaving AudioHub
*/
#ifndef XUA_USB_EN
#define XUA_USB_EN 1
#define XUA_USB_EN (1)
#endif
/**
@@ -438,7 +431,8 @@
#define HID_CONTROLS (0)
#endif
/* @brief Defines whether XMOS device runs as master (i.e. drives LR and Bit clocks)
/**
* @brief Defines whether XMOS device runs as master (i.e. drives LR and Bit clocks)
*
* 0: XMOS is I2S master. 1: CODEC is I2s master.
*
@@ -457,7 +451,6 @@
#define SERIAL_STR ""
#endif
/**
* @brief Vendor String used by the device. This is also pre-pended to various strings used by the design.
*
@@ -1154,6 +1147,26 @@
#undef UAC_FORCE_FEEDBACK_EP
#endif
/* Synchronisation defines */
#define XUA_SYNCMODE_ASYNC (1) // USB_ENDPOINT_SYNCTYPE_ASYNC
#define XUA_SYNCMODE_ADAPT (2) // USB_ENDPOINT_SYNCTYPE_ADAPT
#define XUA_SYNCMODE_SYNC (3) // USB_ENDPOINT_SYNCTYPE_SYNC
#ifndef XUA_SYNCMODE
#define XUA_SYNCMODE XUA_SYNCMODE_ASYNC
#endif
#if (XUA_SYNCMODE == XUA_SYNCMODE_SYNC)
#if (XUA_SPDIF_RX_EN|| ADAT_RX)
#error "Digital input streams not supported in Sync mode"
#endif
#endif
/*********************************************************/
/*** Internal defines below here. NOT FOR MODIFICATION ***/
/*********************************************************/
#ifndef __ASSEMBLER__
/* Endpoint addresses enums */
enum USBEndpointNumber_In
@@ -1200,40 +1213,37 @@ enum USBEndpointNumber_Out
XUA_ENDPOINT_COUNT_OUT /* End marker */
};
#ifndef XUA_ENDPOINT_COUNT_CUSTOM_OUT
#define XUA_ENDPOINT_COUNT_CUSTOM_OUT 0
#define XUA_ENDPOINT_COUNT_CUSTOM_OUT (0)
#endif
#ifndef XUA_ENDPOINT_COUNT_CUSTOM_IN
#define XUA_ENDPOINT_COUNT_CUSTOM_IN 0
#define XUA_ENDPOINT_COUNT_CUSTOM_IN (0)
#endif
#define ENDPOINT_COUNT_IN (XUA_ENDPOINT_COUNT_IN + XUA_ENDPOINT_COUNT_CUSTOM_IN)
#define ENDPOINT_COUNT_OUT (XUA_ENDPOINT_COUNT_OUT + XUA_ENDPOINT_COUNT_CUSTOM_OUT)
#define ENDPOINT_COUNT_IN (XUA_ENDPOINT_COUNT_IN + XUA_ENDPOINT_COUNT_CUSTOM_IN)
#define ENDPOINT_COUNT_OUT (XUA_ENDPOINT_COUNT_OUT + XUA_ENDPOINT_COUNT_CUSTOM_OUT)
#endif
#endif /* __ASSEMBLER__ */
/*** Internal defines below here. NOT FOR MODIFICATION ***/
#define AUDIO_STOP_FOR_DFU (0x12345678)
#define AUDIO_START_FROM_DFU (0x87654321)
#define AUDIO_REBOOT_FROM_DFU (0xa5a5a5a5)
#define AUDIO_STOP_FOR_DFU (0x12345678)
#define AUDIO_START_FROM_DFU (0x87654321)
#define AUDIO_REBOOT_FROM_DFU (0xa5a5a5a5)
#define MAX_VOL (0x20000000)
#define MAX_VOL (0x20000000)
#if defined(LEVEL_METER_LEDS) && !defined(LEVEL_UPDATE_RATE)
#define LEVEL_UPDATE_RATE 400000
#define LEVEL_UPDATE_RATE (400000)
#endif
/* The number of clock ticks to wait for the audio feeback to stabalise
* Note, feedback always counts 128 SOFs (16ms @ HS, 128ms @ FS) */
#ifndef FEEDBACK_STABILITY_DELAY_HS
#define FEEDBACK_STABILITY_DELAY_HS (2000000)
#define FEEDBACK_STABILITY_DELAY_HS (2000000)
#endif
#ifndef FEEDBACK_STABILITY_DELAY_FS
#define FEEDBACK_STABILITY_DELAY_FS (20000000)
#define FEEDBACK_STABILITY_DELAY_FS (20000000)
#endif
/* Length of clock unit/clock-selector units */
@@ -1458,16 +1468,3 @@ enum USBEndpointNumber_Out
#error CODEC_MASTER with DSD is currently unsupported
#endif
#define XUA_SYNCMODE_ASYNC (1) // USB_ENDPOINT_SYNCTYPE_ASYNC
#define XUA_SYNCMODE_ADAPT (2) // USB_ENDPOINT_SYNCTYPE_ADAPT
#define XUA_SYNCMODE_SYNC (3) // USB_ENDPOINT_SYNCTYPE_SYNC
#ifndef XUA_SYNCMODE
#define XUA_SYNCMODE XUA_SYNCMODE_ASYNC
#endif
#if (XUA_SYNCMODE == XUA_SYNCMODE_SYNC)
#if (XUA_SPDIF_RX_EN || XUA_ADAT_RX_EN)
#error "Digital input streams not supported in Sync mode"
#endif
#endif

View File

@@ -1,36 +1,41 @@
// Copyright 2011-2021 XMOS LIMITED.
// Copyright 2011-2022 XMOS LIMITED.
// This Software is subject to the terms of the XMOS Public Licence: Version 1.
#ifndef _XUA_ENDPOINT0_H_
#define _XUA_ENDPOINT0_H_
#include "xua.h"
#include "dfu_interface.h"
#include "vendorrequests.h"
#if __XC__
/** Function implementing Endpoint 0 for enumeration, control and configuration
* of USB audio devices. It uses the descriptors defined in ``descriptors_2.h``.
*
* \param c_ep0_out Chanend connected to the XUD_Manager() out endpoint array
* \param c_ep0_in Chanend connected to the XUD_Manager() in endpoint array
* \param c_audioCtrl Chanend connected to the decouple thread for control
* audio (sample rate changes etc.). Note when nulled, the
* audio device only supports single sample rate/format and
* DFU is not supported either since this channel is used
* to carry messages about format, rate and DFU state
* \param c_mix_ctl Optional chanend to be connected to the mixer thread if
* present
* \param c_clk_ctl Optional chanend to be connected to the clockgen thread if
* present.
* \param c_usb_test Optional chanend to be connected to XUD if test modes required.
* of USB audio devices. It uses the descriptors defined in ``xua_ep0_descriptors.h``.
*
* \param c_ep0_out Chanend connected to the XUD_Manager() out endpoint array
* \param c_ep0_in Chanend connected to the XUD_Manager() in endpoint array
* \param c_audioCtrl Chanend connected to the decouple thread for control
* audio (sample rate changes etc.). Note when nulled, the
* audio device only supports single sample rate/format and
* DFU is not supported either since this channel is used
* to carry messages about format, rate and DFU state
* \param c_mix_ctl Optional chanend to be connected to the mixer core(s) if
* present
* \param c_clk_ctl Optional chanend to be connected to the clockgen core if
* present
* \param dfuInterface Interface to DFU task (this task must be run on a tile
* connected to boot flash.
* \param c_EANativeTransport_ctrl Optional chanend to be connected to EA Native
* endpoint manager if present
*/
void XUA_Endpoint0(chanend c_ep0_out, chanend c_ep0_in, chanend ?c_audioCtrl,
chanend ?c_mix_ctl,chanend ?c_clk_ctl, chanend ?c_EANativeTransport_ctr, client interface i_dfu ?dfuInterface
VENDOR_REQUESTS_PARAMS_DEC_);
void XUA_Endpoint0(chanend c_ep0_out,
chanend c_ep0_in, chanend ?c_audioCtrl,
chanend ?c_mix_ctl, chanend ?c_clk_ctl,
chanend ?c_EANativeTransport_ctrl,
client interface i_dfu ?dfuInterface
#if !defined(__DOXYGEN__)
VENDOR_REQUESTS_PARAMS_DEC_
#endif
);
/** Function to set the Vendor ID value
*

81
lib_xua/api/xua_midi.h Normal file
View File

@@ -0,0 +1,81 @@
// Copyright 2011-2022 XMOS LIMITED.
// This Software is subject to the terms of the XMOS Public Licence: Version 1.
#ifndef _XUA_MIDI_H_
#define _XUA_MIDI_H_
#include "xua.h"
#ifndef MIDI_SHIFT_TX
#define MIDI_SHIFT_TX (0)
#endif
/** USB MIDI I/O task.
*
* This function passes MIDI data between XUA_Buffer and MIDI UART I/O.
*
* \param p_midi_in 1-bit input port for MIDI
* \param p_midi_out 1-bit output port for MIDI
* \param clk_midi Clock block used for clockin the UART; should have
* a rate of 100MHz
* \param c_midi Chanend connected to the decouple() thread
* \param cable_number The cable number of the MIDI implementation.
* This should be set to 0.
**/
void usb_midi(
#if (MIDI_RX_PORT_WIDTH == 4)
buffered in port:4 ?p_midi_in,
#else
buffered in port:1 ?p_midi_in,
#endif
port ?p_midi_out,
clock ?clk_midi,
chanend ?c_midi,
unsigned cable_number
#ifdef IAP
, chanend ?c_iap, chanend ?c_i2c, // iOS stuff
port ?p_scl, port ?p_sda
#endif
);
#define MAX_USB_MIDI_PACKET_SIZE 1024
#define MIDI_USB_BUFFER_FROM_HOST_FIFO_SIZE (512+1024)
#define MIDI_USB_BUFFER_TO_HOST_SIZE (256)
#define MIDI_ACK 20
#define USB_MIDI_DEVICE_OUT_FIFO_SIZE (1024)
#ifdef __MIDI_IMPL
#define INLINE
#else
#define INLINE inline
#endif
#ifdef NO_INLINE_MIDI_SELECT_HANDLER
#pragma select handler
void midi_get_ack_or_data(chanend c, int &is_ack, unsigned int &datum);
#else
#pragma select handler
INLINE void midi_get_ack_or_data(chanend c, int &is_ack, unsigned int &datum) {
if (testct(c)) {
is_ack = 1;
(void) inct(c); // read 1-bytes control token
(void) inuchar(c);
(void) inuchar(c);
(void) inuchar(c);
}
else {
is_ack = 0;
datum = inuint(c);
}
}
#endif
INLINE void midi_send_ack(chanend c) {
outct(c, MIDI_ACK);
outuchar(c, 0);
outuchar(c, 0);
outuchar(c, 0);
}
#define MIDI_RATE (31250)
#define MIDI_BITTIME (XS1_TIMER_MHZ * 1000000 / MIDI_RATE)
#define MIDI_BITTIME_2 (MIDI_BITTIME>>1)
#endif // _XUA_MIDI_H_

34
lib_xua/api/xua_mixer.h Normal file
View File

@@ -0,0 +1,34 @@
// Copyright 2011-2022 XMOS LIMITED.
// This Software is subject to the terms of the XMOS Public Licence: Version 1.
#ifndef _XUA_MIXER_H_
#define _XUA_MIXER_H_
enum mix_ctl_cmd {
SET_SAMPLES_TO_HOST_MAP,
SET_SAMPLES_TO_DEVICE_MAP,
SET_MIX_MULT,
SET_MIX_MAP,
SET_MIX_IN_VOL,
SET_MIX_OUT_VOL,
GET_INPUT_LEVELS,
GET_STREAM_LEVELS,
GET_OUTPUT_LEVELS
};
/** Digital sample mixer.
*
* This thread mixes audio streams between the decouple() thread and
* the audio() thread.
*
* \param c_to_host a chanend connected to the decouple() thread for
* receiving/transmitting samples
* \param c_to_audio a chanend connected to the audio() thread for
* receiving/transmitting samples
* \param c_mix_ctl a chanend connected to the Endpoint0() thread for
* receiving control commands
*
*/
void mixer(chanend c_to_host, chanend c_to_audio, chanend c_mix_ctl);
#endif