Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
Toggle table of contents sidebar

# 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,
  port p_for_mclk_count_aud,
  chanend c_sw_pll,

)

  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.

void mic_array_task(

  chanend c_mic_to_audio,
  unsigned channel_map[MIC_ARRAY_CONFIG_MIC_COUNT],

)

  USB PDM microphone task.

  Starts the mic-array processing thread(s)

  Supported sample rates: 16 kHz, 32 kHz, and 48 kHz.

  The task runs in a continuous while(1) loop until `ma_shutdown()` is invoked. When `ma_shutdown()` is called, the internal mic thread terminates (`mic_array_start()` returns). After that, a new sampling-rate value may be received on the same channel, and the mic-array thread is then started again at the new rate.

  c_mic_to_audio channel usage:

  - While the mic thread is running, decimated PCM frames are sent from the mic array to the application over this channel.

  - Before the mic thread is started, the PCM sampling rate is received over this channel.

  Parameters:

    - c_mic_to_audio – Channel over which decimated PCM frames are produced by the mic array and delivered to the application.

    - channel_map – Array mapping the logical microphone indices to PDM input channels. The ith entry is the pdm-data port pin that is routed to microphone output channel i