lib_board_support#

Introduction#

This repo contains board specific hardware configuration code for various XMOS evaluation and development kits. By keeping the board-specific code in a dedicated repository various applications need not replicate commonly used code such as initialisation of on-board peripherals and in addition any updates or fixes can easily be rolled out to all dependent applications.

Supported Boards#

The following boards are supported in this repo with interfaces provided in the languages shown in the table below.

Board	Supported Languages
XK_EVK_XU316	XC / C
XK_AUDIO_316_MC_AB	XC / C
XK_AUDIO_216_MC_AB	XC / C
XK_EVK_XE216	XC
XK_ETH_XU316_DUAL_100M	XC

Note

The XK_ETH_XU316_DUAL_100M board is currently unreleased and does not have official documentation. Please contact XMOS Support for futher information.

The following sections provide specific details of the features for each of the boards supported by this library.

Usage#

This repo supports the XMOS build system; XCommon CMake. To use the library add lib_board_support to an applications CMakeLists.txt file using the APP_DEPENDENT_MODULES entry. The application must provide a relevant xn file, although example xn files are provided in alongside this library (see xn_files directory).

The application must use the APIs for the specific board that it is using. To ensure that only the correct sources for the board in use get compiled in, it is necessary to set the preprocessor value BOARD_SUPPORT_BOARD in the project to one of the available boards listed in api/boards/boards_utils.h. This can be done in the app with the following snippet of cmake:

set(APP_COMPILER_FLAGS
    -DBOARD_SUPPORT_BOARD=XK_AUDIO_316_MC_AB  # Change value to select board, see api/boards/boards_utils.h for available boards
)

From the application where board initialisation of configuration is done it is necessary to include the relevant header file. For example:

#include "xk_audio_316_mc_ab/board.h"

From then onwards the code may call the relevant API functions to setup and configure the board hardware. Examples are provided in the examples directory of this repo.

Note that in some cases, the xcore tile that calls the configuration function (usually from I²S initialisation) is different from the tile where I²C master is placed. Since I²C master is required by most audio CODECs for configuration and xcore tiles can only communicate with each other via channels, a remote server is needed to provide the I²C setup. This usually takes the form of a task which is run on a thread placed on the I²C tile and is controlled via a channel from the other tile where I²S resides. The cross-tile channel must be declared at the top-level XC main function. The included examples provide a reference for this using both XC and C.

Note

Sample XN files (hardware description for compiler) are provided in /xn_files in the cases where the compiler doesn’t support the platform directly. These can be copied into your application directory where needed. See /examples for usage.

Application Programmer Interface#

This section contains the details of the API support by lib_board_support. The API is broken down into 2 sections:

Boards: This includes subdirectories for each supported board which need to be included in your application.
Drivers: This includes sources for configuring peripheral devices which may be on one or more of the supported boards.

Common API#

This section contains the list of supported boards, one of which needs to be globally defined as BOARD_SUPPORT_BOARD in the project.

NULL_BOARD#: Define representing Null board i.e. no board in use

XK_AUDIO_216_MC_AB#: Define representing XK-AUDIO-216-MC Board

XK_AUDIO_316_MC_AB#: Define representing XK-AUDIO-316-MC Board

XK_EVK_XU316#: Define representing XK-EVK-XU316 board

XK_EVK_XE216#: Define representing XK-EVK-XU216 board

XK_ETH_XU316_DUAL_100M#: Define representing XK-ETH-XU316-DUAL-100M board

BOARD_SUPPORT_N_BOARDS#: Total number of boards supported by the library

BOARD_SUPPORT_BOARD#

Define that should be set to the current board type in use

Default value: NULL_BOARD

XK_AUDIO_316_MC_AB API#

struct xk_audio_316_mc_ab_config_t#

Configuration struct type for setting the hardware profile.

Public Members

xk_audio_316_mc_ab_mclk_modes_t clk_mode#: See xk_audio_316_mc_ab_mclk_modes_t for available clock mode options.

char dac_is_clock_master#: Boolean setting for whether the DAC or the xcore.ai is I2S clock master. Set to 0 to make the xcore.ai master.

unsigned default_mclk#: Nominal clock frequency in MHz. Standard rates are supported between 11.2896 MHz and 49.152 MHz.

unsigned pll_sync_freq#: When the CLK_CS2100 is used, this defines the nominal reference clock frequency for multiplication by the PLL. This value is ignored when the CS2100 is not used.

xk_audio_316_mc_ab_pcm_format_t pcm_format#: See xk_audio_316_mc_ab_pcm_format_t for available data frame options.

unsigned i2s_n_bits#: Number of bits per data frame in I2S.

unsigned i2s_chans_per_frame#: This defines the number of audio channels per frame (a frame is a complete cycle of FSYNC or LRCLK).

enum xk_audio_316_mc_ab_mclk_modes_t#

Type of clock to be instantiated. This may be a fixed clock using the application PLL, an adjustable clock using the CS2100 external PLL or an adjustable or fixed clock using the on-chip application PLL.

Values:

enumerator CLK_FIXED#

enumerator CLK_CS2100#

enumerator CLK_PLL#

enum xk_audio_316_mc_ab_pcm_format_t#

Formats supported by the DAC and ADC. Either I2S using multiple data lines or TDM supporting multi-channel using a single data line.

Values:

enumerator AUD_316_PCM_FORMAT_I2S#

enumerator AUD_316_PCM_FORMAT_TDM#

port p_scl#: I2C interface ports

port p_sda#

void xk_audio_316_mc_ab_i2c_master(SERVER_INTERFACE(i2c_master_if, i2c[1]))#

Starts an I2C master task. Must be started from tile[0] after xk_audio_316_mc_ab_board_setup() and before and tile[1] HW calls.

Parameters:

i2c – client side of I2C master interface connection.

void xk_audio_316_mc_ab_board_setup(const REFERENCE_PARAM(xk_audio_316_mc_ab_config_t, config))#

Performs the required port operations to enable and the audio hardware on the platform. Must be called from tile[0] and before xk_audio_316_mc_ab_AudioHwInit() is called.

Parameters:

config – Reference to the xk_audio_316_mc_ab_config_t configuration struct.

void xk_audio_316_mc_ab_AudioHwInit(CLIENT_INTERFACE(i2c_master_if, i2c), const REFERENCE_PARAM(xk_audio_316_mc_ab_config_t, config))#

Initialises the audio hardware ready for a configuration. Must be called once after xk_audio_316_mc_ab_board_setup().

Parameters:

i2c – Client side of I2C master interface connection.
config – Reference to the xk_audio_316_mc_ab_config_t hardware configuration struct.

void xk_audio_316_mc_ab_AudioHwConfig(CLIENT_INTERFACE(i2c_master_if, i2c), const REFERENCE_PARAM(xk_audio_316_mc_ab_config_t, config), unsigned samFreq, unsigned mClk, unsigned dsdMode, unsigned sampRes_DAC, unsigned sampRes_ADC)#

Configures the audio hardware following initialisation. This is typically called each time a sample rate or stream format change occurs.

Parameters:

i2c – Client side of I2C master interface connection.
config – Reference to the xk_audio_316_mc_ab_config_t hardware configuration struct.
samFreq – The sample rate in Hertz.
mClk – The master clock rate in Hertz.
dsdMode – Controls whether the DAC is to be set into DSD mode (1) or PCM mode (0).
sampRes_DAC – The sample resolution of the DAC output in bits. Typically 16, 24 or 32.
sampRes_ADC – The sample resolution of the ADC input in bits. Typically 16, 24 or 32.

void xk_audio_316_mc_ab_i2c_master_exit(CLIENT_INTERFACE(i2c_master_if, i2c))#

Causes the tile[0] to exit, freeing up a thread. Must be called from tile[1]. Once called, HW config calls from tile[1] will block forever. It is possible to re-start xk_audio_316_mc_ab_i2c_master() on tile[0] if needed to re-enable this service.

Parameters:

i2c – Client side of I2C master interface connection.

XK_AUDIO_216_MC_AB API#

struct xk_audio_216_mc_ab_config_t#

Configuration struct type for setting the hardware profile.

Public Members

xk_audio_216_mc_ab_clk_mode_t clk_mode#: See xk_audio_216_mc_ab_clk_mode_t for clock mode available options.

char codec_is_clk_master#: Boolean setting for whether the DAC or the xcore-200 is I2S clock master. Set to 0 to make the xcore-200 master.

xk_audio_216_mc_ab_usb_sel_t usb_sel#: USB port slection - see xk_audio_216_mc_ab_usb_sel_t for options.

xk_audio_216_mc_ab_pcm_format_t pcm_format#: See xk_audio_216_mc_ab_pcm_format_t for available pmc_format options.

unsigned pll_sync_freq#: When the external PLL is used, this defines the nominal reference clock frequency for multiplication by the PLL.

enum xk_audio_216_mc_ab_clk_mode_t#

Type of clock to be instantiated. This may be a fixed clock using an external generator or an adjustable clock using an external PLL (CS2100) in either digital Rx clock recovery or USB clock recovery using synchronous mode.

Values:

enumerator AUD_216_CLK_FIXED#

enumerator AUD_216_CLK_EXTERNAL_PLL#

enumerator AUD_216_CLK_EXTERNAL_PLL_USB#

enum xk_audio_216_mc_ab_pcm_format_t#

Formats supported by the DAC and ADC. Either I2S using multiple data lines or TDM supporting multi-channel using a single data line.

Values:

enumerator AUD_216_PCM_FORMAT_I2S#

enumerator AUD_216_PCM_FORMAT_TDM#

enum xk_audio_216_mc_ab_usb_sel_t#

Selects which USB port to use - either type A or type B.

Values:

enumerator AUD_216_USB_A#

enumerator AUD_216_USB_B#

void xk_audio_216_mc_ab_AudioHwInit(const REFERENCE_PARAM(xk_audio_216_mc_ab_config_t, config))#

Initialises the audio hardware ready for a configuration. Must be called once after xk_audio_316_mc_ab_board_setup().

Parameters:

config – Reference to the xk_audio_216_mc_ab_config_t hardware configuration struct.

void xk_audio_216_mc_ab_AudioHwConfig(const REFERENCE_PARAM(xk_audio_216_mc_ab_config_t, config), unsigned samFreq, unsigned mClk, unsigned dsdMode, unsigned sampRes_DAC, unsigned sampRes_ADC)#

Configures the audio hardware following initialisation. This is typically called each time a sample rate or stream format change occurs.

Parameters:

config – Reference to the xk_audio_216_mc_ab_config_t hardware configuration struct.
samFreq – The sample rate in Hertz.
mClk – The master clock rate in Hertz.
dsdMode – Controls whether the DAC is to be set into DSD mode (1) or PCM mode (0).
sampRes_DAC – The sample resolution of the DAC output in bits. Typically 16, 24 or 32.
sampRes_ADC – The sample resolution of the ADC input in bits. Typically 16, 24 or 32.

XK_EVK_XU316 API#

struct xk_evk_xu316_config_t#

Configuration struct type for setting the hardware profile.

Public Members

unsigned default_mclk#: xk_audio_316_mc_ab_config_t::clk_mode See xk_audio_316_mc_ab_mclk_modes_t for available clock mode options.

enum audioHwCmd_t#

Command enumeration for channel based commands to I2C master server on other tile.

Values:

enumerator AUDIOHW_CMD_REGWR#

enumerator AUDIOHW_CMD_REGRD#

enumerator AUDIOHW_CMD_EXIT#

void xk_evk_xu316_AudioHwRemote(chanend c)#

Starts an I2C master server task. Must be started before the tile[1] xk_evk_xu316_AudioHwInit calls. In the background this also starts a combinable channel to interface translation task so the API may be used over a channel end however it still only occupies one thread. May be exited after config by sending AUDIOHW_CMD_EXIT if dynamic configuration is not required.

Parameters:

c – Server side of channel connecting I2C master server and HW config functions.

void xk_evk_xu316_AudioHwChanInit(chanend c)#

Initialises the client side channel for remote communications with I2C. Must be called on tile[1] before xk_evk_xu316_AudioHwInit().

Parameters:

c – Client side of channel connecting I2C master server and HW config functions.

void xk_evk_xu316_AudioHwInit(const REFERENCE_PARAM(xk_evk_xu316_config_t, config))#

Initialises the audio hardware ready for a configuration. Must be called once after xk_evk_xu316_AudioHwRemote() and xk_evk_xu316_AudioHwChanInit().

Parameters:

config – Reference to the xk_audio_316_mc_ab_config_t hardware configuration struct.

void xk_evk_xu316_AudioHwConfig(unsigned samFreq, unsigned mClk, unsigned dsdMode, unsigned sampRes_DAC, unsigned sampRes_ADC)#

Configures the audio hardware following initialisation. This is typically called each time a sample rate or stream format change occurs.

Parameters:

samFreq – The sample rate in Hertz.
mClk – The master clock rate in Hertz.
dsdMode – Controls whether the DAC is to be set into DSD mode (1) or PCM mode (0).
sampRes_DAC – The sample resolution of the DAC output in bits. Typically 16, 24 or 32.
sampRes_ADC – The sample resolution of the ADC input in bits. Typically 16, 24 or 32.

XK_EVK_XU216 API#

void ar8035_phy_driver(CLIENT_INTERFACE(smi_if, i_smi), CLIENT_INTERFACE(ethernet_cfg_if, i_eth))#

Task that connects to the SMI master and MAC to configure the ar8035 PHY and monitor the link status. Note this task is combinable (typically with SMI) and therefore does not need to take a whole thread. This task must be run from tile[1].

Parameters:

i_smi – Client register read/write interface
i_eth – Client MAC configuration interface

XK_ETH_XU316_DUAL_100M API#

void dual_dp83826e_phy_driver(CLIENT_INTERFACE(smi_if, i_smi), NULLABLE_CLIENT_INTERFACE(ethernet_cfg_if, i_eth_phy_0), NULLABLE_CLIENT_INTERFACE(ethernet_cfg_if, i_eth_phy_1))#

Task that connects to the SMI master and MAC to configure the DP83826E PHYs and monitor the link status. Note this task is combinable (typically with SMI) and therefore does not need to take a whole thread.

Note it may be necessary to modify R3 and R23 according to which PHY is used. Populate R23 and remove R3 for PHY_0 only populated otherwise populate R3 and remove R23 for all other settings.

Parameters:

i_smi – Client register read/write interface
i_eth_phy_0 – Client MAC configuration interface for PHY_0. Set to NULL if unused.
i_eth_phy_1 – Client MAC configuration interface for PHY_1. Set to NULL if unused.

void reset_eth_phys(void)#: Sends hard reset to both PHYs. Both PHYs will be ready for SMI communication once this function has returned. This function must be called from Tile[1].

rmii_port_timing_t get_port_timings(int phy_idx)#

Returns a timing struct tuned to the xk_eth_xu316_dual_100m hardware. This struct should be passed to the call to rmii_ethernet_rt_mac() and will ensure setup and hold times are maximised at the pin level of the PHY connection. rmii_port_timing_t is defined in lib_ethernet.

Parameters:

phy_idx – The index of the PHY to get timing data about (0 or 1).

Returns:

The timing struct to be passed to the PHY.

Example Applications#

Some simple example applications are provided in order to show how to use lib_board_support.

Simple C Usage#

The applications app_evk_316_simple_c and app_xk_audio_316_mc_simple_c provide a bare-bones application where the hardware setup is called from C.

These applications run on the XK-EVK-XU316 and XK-AUDIO-316-MC boards respectively.

They show how to use the cross-tile communications in conjunction with the I²C master server. The applications only setup the hardware and then exit the I²C server.

XC Usage Example#

The application app_xk_audio_316_mc_simple_xc demonstrates calling the hardware setup API from C. It runs on the XK-AUDIO-316-MC board.

Building and running#

To build and run an example, run the following from an XTC tools terminal to configure the build:

cd examples/<app_name>
cmake -G "Unix Makefiles" -B build

Any missing dependencies will be downloaded by the build system at this point.

The application binaries can be built using xmake:

xmake -C build

To run the application use the following command:

xrun --io bin/<app_name>.xe

For example:

cd examples/app_xk_audio_316_mc_simple_xc
cmake -G "Unix Makefiles" -B build
xmake -C build
xrun --io bin/app_xk_audio_316_mc_simple_xc.xe