Component API

The following functions can be called from the top level main of an application and implement the various components described in Software architecture.

When using the USB audio framework the c_ep_in array is always composed in the following order:

  • Endpoint 0 (in)

  • Audio Feedback endpoint (if output enabled)

  • Audio IN endpoint (if input enabled)

  • MIDI IN endpoint (if MIDI enabled)

  • Clock Interrupt endpoint

The array c_ep_out is always composed in the following order:

  • Endpoint 0 (out)

  • Audio OUT endpoint (if output enabled)

  • MIDI OUT endpoint (if MIDI enabled)

void XUA_Endpoint0(
chanend c_ep0_out,
chanend c_ep0_in,
NULLABLE_RESOURCE(chanend, c_aud_ctl),
NULLABLE_RESOURCE(chanend, c_mix_ctl),
NULLABLE_RESOURCE(chanend, c_clk_ctl),
NULLABLE_CLIENT_INTERFACE(i_dfu, dfuInterface),
)

Endpoint 0 task for USB Audio devices

Function implementing Endpoint 0 for enumeration, control and configuration of USB audio devices. It uses the descriptors defined in xua_ep0_descriptors.h.

Parameters:

  • c_ep0_out – Chanend connected to the XUD_Main() out endpoint array

  • c_ep0_in – Chanend connected to the XUD_Main() in endpoint array

  • c_aud_ctl – 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

  • c_mix_ctl – Optional chanend to be connected to the mixer core(s) if present

  • c_clk_ctl – Optional chanend to be connected to the clockgen core if present

  • dfuInterface – Interface to DFU task (this task must be run on a tile connected to boot flash.

void XUA_Buffer(
chanend c_aud_out,
chanend c_aud_in,
chanend c_aud_fb,
chanend c_midi_from_host,
chanend c_midi_to_host,
chanend c_midi,
NULLABLE_RESOURCE(chanend, c_int),
NULLABLE_RESOURCE(chanend, c_clk_int),
chanend c_sof,
chanend c_aud_ctl,
NULLABLE_RESOURCE(in_port_t, p_off_mclk),
chanend c_hid,
chanend c_aud,
chanend c_audio_rate_change,
CLIENT_INTERFACE(pll_ref_if, i_pll_ref),
chanend c_swpll_update,
)

USB Audio Buffering Core(s).

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.

Parameters:

  • c_aud_out – Audio OUT endpoint channel connected to the XUD

  • c_aud_in – Audio IN endpoint channel connected to the XUD

  • c_aud_fb – Audio feedback endpoint channel connected to the XUD

  • c_midi_from_host – MIDI OUT endpoint channel connected to the XUD

  • c_midi_to_host – MIDI IN endpoint channel connected to the XUD

  • c_midi – Channel connected to MIDI thread

  • c_int – Audio clocking interrupt endpoint channel connected to the XUD

  • c_clk_int – Optional chanend connected to the clockGen() thread if present

  • c_sof – Start of frame channel connected to the XUD

  • c_aud_ctl – Audio control channel connected to Endpoint0()

  • p_off_mclk – A port that is clocked of the MCLK input (not the MCLK input itself)

  • c_hid – Channel connected to the HID handler thread

  • c_aud – Channel connected to XUA_AudioHub() thread

  • c_audio_rate_change – Channel to notify and synchronise on audio rate change

  • i_pll_ref – Interface to task that toggles reference pin to CS2100

  • c_swpll_update – Channel connected to software PLL task. Expects master clock counts based on USB frames.

void XUA_AudioHub(
NULLABLE_RESOURCE(chanend, c_aud),
NULLABLE_RESOURCE(clock, clk_audio_mclk),
NULLABLE_RESOURCE(clock, clk_audio_bclk),
NULLABLE_RESOURCE(in_port_t, p_mclk_in),
NULLABLE_RESOURCE(i2s_clk_port_type, p_lrclk),
NULLABLE_RESOURCE(i2s_clk_port_type, p_bclk),
NULLABLE_ARRAY_OF_SIZE(out_buffered_port_32_t, p_i2s_dac, I2S_WIRES_DAC),
NULLABLE_ARRAY_OF_SIZE(in_buffered_port_32_t, p_i2s_adc, I2S_WIRES_ADC),
chanend c_spdif_tx,
chanend c_dig,
chanend c_audio_rate_change,
NULLABLE_SERVER_INTERFACE(i_dfu, dfuInterface),
chanend c_pdm_in,
)

The audio driver thread.

This function drives I2S ports and handles samples to/from other digital I/O threads.

Parameters:

  • c_aud – Audio sample channel connected to the mixer() thread or the decouple() thread

  • clk_audio_mclk – Nullable clockblock to be clocked from master clock

  • clk_audio_bclk – Nullable clockblock to be clocked from i2s bit clock

  • p_mclk_in – Master clock inport port (must be 1-bit). Use null when xcore is slave

  • p_lrclk – Nullable port for I2S sample clock

  • p_bclk – Nullable port for I2S bit clock

  • p_i2s_dac – Nullable array of ports for I2S data output lines

  • p_i2s_adc – Nullable array of ports for I2S data input lines

  • i_SoftPll – Interface to software PLL task

  • c_spdif_tx – Channel connected to S/PDIF transmitter core from lib_spdif

  • c_dig – Channel connected to the clockGen() thread for receiving/transmitting samples

  • c_audio_rate_change – Channel notifying ep_buffer of an mclk frequency change and sync for stable clock

  • dfuInterface – Interface supporting DFU methods

  • c_pdm_in – Channel for receiving decimated PDM samples

void mixer(chanend c_to_host, chanend c_to_audio, chanend c_mix_ctl)

Digital sample mixer.

This thread mixes audio streams between the decouple() thread and the audio() thread.

Parameters:

  • c_to_host – a chanend connected to the decouple() thread for receiving/transmitting samples

  • c_to_audio – a chanend connected to the audio() thread for receiving/transmitting samples

  • c_mix_ctl – a chanend connected to the Endpoint0() thread for receiving control commands

void clockGen(
NULLABLE_RESOURCE(streaming_chanend_t, c_spdif_rx),
NULLABLE_RESOURCE(streaming_chanend_t, c_adat_rx),
CLIENT_INTERFACE(pll_ref_if, i_pll_ref),
chanend c_audio,
chanend c_clk_ctl,
chanend c_clk_int,
chanend c_audio_rate_change,
)

Clock generation and digital audio I/O handling.

Parameters:

  • c_spdif_rx – channel connected to S/PDIF receive thread

  • c_adat_rx – channel connect to ADAT receive thread

  • i_pll_ref – interface to taslk that outputs clock signal to drive external frequency synthesizer

  • c_audio – channel connected to the audio() thread

  • c_clk_ctl – channel connected to Endpoint0() for configuration of the clock

  • c_clk_int – channel connected to the decouple() thread for clock interrupts

  • c_audio_rate_change – channel to notify of master clock change

  • p_for_mclk_count_aud – port used for counting mclk and providing a timestamp

  • c_sw_pll – channel used to communicate with software PLL task

void usb_midi(
NULLABLE_RESOURCE(in_buffered_port_1_t, p_midi_in),
NULLABLE_RESOURCE(port, p_midi_out),
NULLABLE_RESOURCE(clock, clk_midi),
NULLABLE_RESOURCE(chanend, c_midi),
unsigned cable_number,
)

USB MIDI I/O task.

This function passes MIDI data between XUA_Buffer and MIDI UART I/O.

Parameters:

  • p_midi_in – 1-bit input port for MIDI

  • p_midi_out – 1-bit output port for MIDI

  • clk_midi – Clock block used for clockin the UART; should have a rate of 100MHz

  • c_midi – Chanend connected to the decouple() thread

  • cable_number – The cable number of the MIDI implementation. This should be set to 0.