Skip to content

Commit

Permalink
Merge pull request #24 from xmos/develop
Browse files Browse the repository at this point in the history
Release v1.1.0 to main
  • Loading branch information
ed-xmos authored Oct 10, 2024
2 parents d194de9 + 70703de commit 8972ed8
Show file tree
Hide file tree
Showing 33 changed files with 236 additions and 378 deletions.
25 changes: 22 additions & 3 deletions CHANGELOG.rst
Original file line number Diff line number Diff line change
@@ -1,18 +1,37 @@
lib_board_support change log
============================

1.1.0
-----

* FIXED: DAC setup on channels 0 to 5 (DACs 0, 1 & 2) when dac_is_clock_master
set to 1 (XMOS is slave) which caused distortion at higher frequencies

* Changes to dependencies:

- lib_i2c: 6.2.0 -> 6.3.0

- lib_sw_pll: 2.2.0 -> 2.3.0

- lib_xassert: 4.2.0 -> 4.3.0

1.0.1
-----

* CHANGED: Documentation improvements

1.0.0
-----

* ADDED: Board documentation
* ADDED: Example apps showing use of library
* FIXED: Missing lib_sw_pll dependency
* ADDED: Callable from C
* ADDED: I2C master exit API for XK-AUDIO-316-MC
* FIXED: Uninitialised global interface for XK-AUDIO-216-MC setup
* ADDED: Explicit xk_evk_xu316_AudioHwChanInit() API
* ADDED: NULL_BOARD default option so library can be included in a project
without being used.
without being used
* FIXED: Missing lib_sw_pll dependency
* FIXED: Uninitialised global interface for XK-AUDIO-216-MC setup

* Changes to dependencies:

Expand Down
6 changes: 0 additions & 6 deletions CMakeLists.txt

This file was deleted.

73 changes: 32 additions & 41 deletions Jenkinsfile
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
@Library('[email protected]') _
// This file relates to internal XMOS infrastructure and should be ignored by external users

@Library('[email protected]') _

getApproval()


pipeline {
agent none

Expand All @@ -23,10 +23,15 @@ pipeline {
defaultValue: '15.3.0',
description: 'The XTC tools version'
)
string(
name: 'XMOSDOC_VERSION',
defaultValue: '6.1.0',
description: 'The xmosdoc version'
)
}
environment {
REPO = 'lib_board_support'
PYTHON_VERSION = "3.10"
PYTHON_VERSION = "3.12.1"
VENV_DIRNAME = ".venv"
}

Expand All @@ -36,60 +41,33 @@ pipeline {
label 'linux&&64'
}
stages{
stage('Checkout and lib checks'){
stage('Checkout'){
steps {
println "Stage running on: ${env.NODE_NAME}"
sh "git clone -b v1.2.1 [email protected]:xmos/infr_scripts_py"
sh "git clone -b v1.6.0 [email protected]:xmos/infr_apps"

dir("${REPO}") {
checkout scm
createVenv()
withVenv {
sh "pip install -e ../infr_scripts_py"
sh "pip install -e ../infr_apps"

// Grab dependancies before changelog check
withTools(params.TOOLS_VERSION) {
withTools(params.TOOLS_VERSION) {
dir("examples") {
sh "cmake -G \"Unix Makefiles\" -B build"
}

// installPipfile(false)
withTools(params.TOOLS_VERSION) {
withEnv(["REPO=${REPO}", "XMOS_ROOT=.."]) {
xcoreLibraryChecks("${REPO}", false)
// junit "junit_lib.xml"
} // withEnv
} // withTools
} // Venv
}
} // dir
} // steps
}
stage('Docs') {
environment { XMOSDOC_VERSION = "v5.0" }
stage('Library checks') {
steps {
dir("${REPO}") {
sh "docker pull ghcr.io/xmos/xmosdoc:$XMOSDOC_VERSION"
sh """docker run -u "\$(id -u):\$(id -g)" \
--rm \
-v \$(pwd):/build \
ghcr.io/xmos/xmosdoc:$XMOSDOC_VERSION -v html latex"""

// Zip and archive doc files
zip dir: "doc/_build/html", zipFile: "${REPO}_docs_html.zip"
archiveArtifacts artifacts: "${REPO}_docs_html.zip"
archiveArtifacts artifacts: "doc/_build/pdf/${REPO}_*.pdf"
}
}
}
stage('Build'){
runLibraryChecks("${WORKSPACE}/${REPO}", "v2.0.1")
} // steps
} // Library checks
stage('Build examples'){
steps {
dir("${REPO}") {
dir("${REPO}/examples") {
withVenv {
withTools(params.TOOLS_VERSION) {
sh "cmake -G \"Unix Makefiles\" -B build"
archiveArtifacts artifacts: "build/manifest.txt", allowEmptyArchive: false
sh "xmake -C build -j"
sh "xmake -C build -j 16"
archiveArtifacts artifacts: "**/*.xe", allowEmptyArchive: false
stash name: "xe_files", includes: "**/*.xe"
}
Expand All @@ -108,10 +86,23 @@ pipeline {
}
}
}
stage('Documentation') {
steps {
dir("${REPO}") {
withVenv {
sh "pip install git+ssh://[email protected]/xmos/xmosdoc@v${params.XMOSDOC_VERSION}"
sh 'xmosdoc'
zip zipFile: "${REPO}_docs.zip", archive: true, dir: 'doc/_build'
} // withVenv
} // dir
} // steps
} // Documentation

}
post {
always{
dir("${REPO}/tests") {
// No test yet so this is a placeholder
// junit 'results.xml'
}
}
Expand Down
11 changes: 5 additions & 6 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ lib_board_support
#################

:vendor: XMOS
:version: 1.0.0
:version: 1.0.1
:scope: General Use
:description: Support library for XMOS development kits
:category: General Purpose
Expand All @@ -15,16 +15,17 @@ lib_board_support
Summary
*******

``lib_board_support`` contains board specific hardware configuration code for various XMOS
``lib_board_support`` contains board specific hardware configuration code for various `XMOS`
evaluation and development kits.

Features
********

* Support for the following boards
* Support for the following boards:
* ``XK_EVK_XU316``
* ``XK_AUDIO_316_MC``
* ``XK_AUDIO_216_MC``
* Simple examples to demonstrating usage from both `XC` and `C`.

Known Issues
************
Expand All @@ -48,10 +49,8 @@ Related Application Notes

The following application notes use this library:

* `AN02003: SPDIF/ADAT/I²S Receive to I²S Slave Bridge with ASRC <https://www.xmos.com/file/an02003>`_
* `AN02016: Integrating Audio Weaver (AWE) Core into USB Audio <https://www.xmos.com/file/an02016>`_
* `AN02003: SPDIF/ADAT/I2S Receive to |I2S| Slave Bridge with ASRC <https://www.xmos.com/file/an02003>`_

A number of simple examples are also included in this library under the `examples` directory to demonstrate usage of lib_board_support from XC and C.

Support
*******
Expand Down
Binary file added doc/images/xk_316_audio_mc.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
File renamed without changes
Binary file added doc/images/xk_evk_xu316_block_diagram.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
87 changes: 71 additions & 16 deletions doc/rst/lib_board_support.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ lib_board_support
Introduction
************

This repo contains board specific hardware configuration code for various ``XMOS`` evaluation and development kits.
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.

****************
Expand All @@ -33,45 +33,58 @@ The following section provides specific details of the features for each of the
xk_audio_216_mc_ab/hw_216_mc
xk_evk_xu316/hw_evk_xu316


*****
Usage
*****

This repo supports XCommon CMake. Simply add ``lib_board_support`` to an applications cmake file using the `APP_DEPENDENT_MODULES` entry. The application
must provide the ``xn`` file although example ``xn`` files are provided in this repo in the `xn_files` directory.
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
libray (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 your 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::
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::
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 in your code you may call the relevant API functions to setup and configure the board hardware. Examples of doing this are provided in the `examples` directory of this repo.

Note that in some cases, the XCORE tile that calls the configuration function (usually from |I2S| initilaisation) is different from the tile where |I2C| master is placed. Since |I2C| 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 |I2C| setup. This usually takes the form of a task which is run on a thread placed on the |I2C| tile and is controlled via a channel from the other tile where |I2S| resides. The cross-tile channel must be declared at the top-level XC main function. The included examples show examples of this using both XC and C.
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 |I2S|
initialisation) is different from the tile where |I2C| master is placed. Since |I2C| 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 |I2C| setup. This usually takes the
form of a task which is run on a thread placed on the |I2C| tile and is controlled via a channel
from the other tile where |I2S| 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.

********************************
Application Programmer Interface
********************************

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

1. Boards: This includes subdirectories for each supported board which need to be included in your application.
2. Drivers: This includes sources for configuring peripheral devices which may be on one or more of
1. `Boards`: This includes subdirectories for each supported board which need to be included in your application.
2. `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 your project.
This section contains the list of supported boards, one of which needs to be globally defined as
``BOARD_SUPPORT_BOARD`` in the project.

.. doxygengroup:: bs_common
:content-only:
Expand Down Expand Up @@ -110,15 +123,57 @@ XK_EVK_XU316 API
Example Applications
********************

Example applications are provided to show how to use lib_board_support.
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 <https://github.com/xmos/lib_board_support/tree/develop/examples/app_evk_316_simple_c>`_ and `app_xu316_mc_simple_c <https://github.com/xmos/lib_board_support/blob/develop/examples/app_xu316_mc_simple_c/README.rst>`_ provide a bare-bones application where the hardware setup is called from C. They show how to use the cross-tile communications in conjunction with the |I2C| master server. The applications only setup the hardware and then exit the |I2C| server.
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 |I2C| master server.
The applications only setup the hardware and then exit the |I2C| server.

XC Usage Example
================

A more sophisticated example is provided, written in XC, by `app_xu316_i2s_loopback <https://github.com/xmos/lib_board_support/tree/develop/examples/app_xu316_i2s_loopback>`_. This application sets up the hardware on the `XK_AUDIO_316_MC_AB` board and then runs an |I2S| loopback application to take samples from the on-board ADCs and send the signals out through the DACs. It keeps the |I2C| master server running in case the application wants to change sample rate which requires |I2C| configuration of the audio CODECs.
A more sophisticated example is also provided, written in XC, by `app_xk_audio_316_mc_loopback`.

This application sets up the hardware on the `XK-AUDIO-316-MC` board and then runs an |I2S|
loopback application to take samples from the on-board ADCs and send the signals out through the
DACs. It keeps the |I2C| master server running in case the application wants to change sample rate
which requires |I2C| configuration of the audio CODECs.

Two build configurations are included:

- `XMOS_MASTER` - This configures the ADCs and DACs to |I2S| slave and the xcore.ai device
drives the |I2S| clocks. The on-chip application PLL is configured to drive the master clock
to the mixed signal devices.
- `XMOS_SLAVE` - This configures one the DACs to |I2S| master and the remaining DAC, all ADCs
and the `xcore.ai` device to |I2S| slave. The on-chip application PLL is configured to drive
the master clock to the mixed signal devices.

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

cd examples/app_xk_audio_316_mc_loopback
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 bin/XMOS_MASTER/app_xk_audio_316_mc_loopback_XMOS_MASTER.xe

or::

xrun bin/XMOS_SLAVE/app_xk_audio_316_mc_loopback_XMOS_SLAVE.xe

Connect an analog audio source to the chosen ADC input channels and then monitor the looped back
output on the chosen DAC output channels.

Loading

0 comments on commit 8972ed8

Please sign in to comment.