AVB Design Guide

XMOS AVB Design Guide
Document Revision 5.1.0
Publication Date: 2011/09/12
Copyright © 2011 XMOS Limited, All Rights Reserved.

---

XMOS AVB Design Guide
2/71
Overview
Summary
The XMOS Audio Visual Bridging (AVB) reference design can be used to stream
synchronized audio over an ethernet network. The XMOS solution is based on event-
driven programmable devices, which can transmit and receive multiple audio streams,
and implement both talker and listener functionality.
TALKER
TALKER
Audio Source
Audio Source
XMOS
XMOS
PHY
PHY
(I2S, S/PDIF, USB)
(I2S, S/PDIF, USB)
Device
Device
AVB
Network
LISTENER
LISTENER
Audio Output
XMOS
(I2S, S/PDIF, USB)
Device PHY
Audio Output
XMOS PHY
(I2S, S/PDIF, USB)
Device
XMOS AVB Features
· Supports all endpoint requirements: ethernet interface, packet processing,
timing synchronization, configuration/stream setup and media rate recovery
can all be handled on device.
· Supports emerging AVB standards such as IEEE 802.1as, IEEE 801.1Qav and
IEEE P1722.
· Flexible software based design implements both hardware interfaces and
protocol layers in the same environment allowing flexibility in system design
and easy modification.
Document Revision 5.1.0

---

XMOS AVB Design Guide
3/71
·
Multiple audio hardware interfaces supported, for instance I2S, TDM and
S/PDIF.
XMOS AVB Specification
Functionality
Provides hardware interfaces, audio transport, precise timing pro-
tocol clock synchronization and media clock recovery to streamed
audio over ethernet.
Supported Standards
Ethernet
IEEE 802.3 (via MII)
AVB QoS
IEEE 802.1Qav, 802.1Qat
Precise Timing Protocol
IEEE 802.1as
AVB Audio Over Ethernet
IEEE P1722
Audio Streaming
IEC 61883-6
Control Protocol
IEEE P1722.1
Supported Devices
XMOS Devices
XS1-G4
XS1-L2
Requirements
Development Tools
XMOS Desktop Tools v11.2 or
later
Ethernet
1 x MII compatible 100Mbit PHY
Audio
Audio input/output device
(e.g. ADC/DAC audio CODEC)
PLL/Frequency synthesizer
chip to generate CODEC system
clock
Boot/Storage
Compatible SPI Flash Device
Licensing and Support
Reference code provided without charge under license from XMOS.
Support via http://www.xmos.com/secure/tickets.
Reference code is maintained by XMOS Limited.
Document Revision 5.1.0

---

XMOS AVB Design Guide
4/71
Ethernet AVB Standards
Ethernet AVB consists of a collection of different standards that together allow
audio and video to be streamed over ethernet. The standards allow synchronized,
uninterrupted streaming with multiple talkers and listeners on a switched network
infrastructure.
802.1as
802.1as defines a precise timing protocol based on the IEEE 1558v2 protocol. It
allows every device connected to the network to share a common global clock.
The protocol allows devices to have a synchronized view of this clock to within
microseconds of each other, aiding media stream clock recovery and coordinated
AVB traffic control.
802.1Qav
802.1Qav defines a standard for buffering and forwarding of traffic through the
network using particular flow control algorithms. It uses the global clock provided
by 802.1as to synchronize traffic forwarding and gives predictable latency control
on media streams going through the network.
The XMOS AVB solution implements the requirements for endpoints defined by
802.1Qav. This is done by traffic flow control in the transmit arbiter of the ethernet
MAC component.
802.1Qat
802.1Qat defines a stream reservation protocol that provides end-to-end reservation
of bandwidth across an AVB network.
IEC 61883-6
IEC 61883-6 defines an audio data format that is contained in IEEE P1722 streams.
The XMOS AVB solution uses IEC 61883-6 to convey audio sample streams. Alterna-
tively, the solution can use the Simple Audio Format.
Document Revision 5.1.0

---

XMOS AVB Design Guide
5/71
IEEE P1722
IEEE P1722 defines an encapsulation protocol to transport audio streams over ether-
net. It is complementary to the AVB standards and in particular allows timestamping
of a stream based on the 802.1as global clock.
The XMOS AVB solution handles both transmission and receipt of audio streams
using IEEE P1722. In addition it can use the 802.1as timestamps to accurately recover
the sample rate clock of the audio to match on the listener side.
IEEE P1722.1
IEEE P1722.1 is a system control protocol, used for discovery of AVB endpoints, con-
nection management between endpoints, and enumeration and control of parameters
exposed by the endpoints.
The XMOS AVB solution supports this emerging standard.
Document Revision 5.1.0

---

XMOS AVB Design Guide
6/71
Hardware development platforms
For initial development of AVB applications the following XMOS development plat-
forms are recommended for any low channel count application (using the XS1-L2
device):
· XK-AVB-LC-SYS AVB Audio Endpoint
In addition the following kit can be used for development:
· XDK XS1-G Development Kit
To develop with this kit is is recommended to also use the following add on board:
· XAI Multichannel Audio Interface
Finally, the following board can also be used:
· XC-2 Ethernet Kit
This board has no audio hardware built in; a CODEC and frequency generator must
be added to the board.
It is recommended to have at least two boards for developing streaming audio
applications.
For developing an application specific board for AVB please refer to the hardware
guides for the above boards which contain example schematics, BOMs, design
guidelines etc.
It is also recommended that an AVB compatible network switch be obtained and used
while developing the system. While the XMOS AVB solution can use a non-AVB switch,
some of the features will need to be disabled.
Document Revision 5.1.0

---

XMOS AVB Design Guide
7/71
System Description
The following sections describe the system architecture of the XMOS AVB software
platform.
This software design guide assumes the reader is familiar with the XC language and
XMOS XS1 devices.
System Architecture
The following diagram shows the overall structure of an XMOS AVB endpoint.
Audio subsystem(s)
1722
MAC
talker
Audio
PHY
Codec
Audio
interface
1722
listener
PLL
PTP
Media
PLL driver
server
clock
server
IP/
Config
UDP/TCP
GPIO
Figure 1: AVB System Software Architecture
An endpoint consists of five main interacting components:
· The ethernet MAC
· The precise timing engine (PTP)
· Audio streaming components
· The media clock server
· Configuration and other application components
Document Revision 5.1.0

---

XMOS AVB Design Guide
8/71
Demo Applications
The software platform comes with four demo applications:
Directory
Platform
app_xr_avb_lc_demo
XR-AVB-LC-BRD reference design kit
(including a demo control protocol im-
plementation that can be controlled by
a Windows configuration application)
app_xdk_avb_demo
XDK development kit
app_xdk_xai_avb_demo
XDK development kit with XAI audio
interface board
app_xc2_avb_demo
XC-2 development kit
Ethernet MAC Component
The MAC component provides ethernet connectivity to the AVB solution. To use the
component, a physical interface must be attached to the XCore ports to provide an
100 Mbps MII interface. The XS1 device is also capable of implementing a dual 100
Mbps interface and a gigabit GMII interface 1.
The MAC component supports two features that are necessary to implement AVB
standards with precise timing and quality constraints.
· Timestamping - allows receipt and transmission of ethernet frames to be
timestamped with respect to a clock (for example a 100 MHz reference clock
can provide a resolution of 10 ns).
· Bandwidth control - allows different channels to have different priorities and
bandwidth restrictions to allow steady flow of outgoing media stream packets.
The implementation provides flow control to satisfy the requirements of an AVB
endpoint as specified in the IEEE 802.1Qav standard.
The single port 100 MBit component consists of five threads (each running at 50
MIPS or more) that must be run on the same core. These threads handle both the
receiving and transmission of ethernet frames. The MAC component can be linked
(via channels) to other components/threads in the system. Each link can set a filter
to control which packets are conveyed to it via that channel.
1 Dual MII and gigabit GMII code is not included with the 5v1 software release. Contact XMOS for
more information about the device capability and software.
Document Revision 5.1.0

---

XMOS AVB Design Guide
9/71
All configuration of the channel is managed by a client C/XC API, which configures
and registers the filters. Details of the API used to configure MAC channels can be
found in the ethernet MAC component design guide. This API is used for direct
(layer-2) access to the MAC. For AVB applications it is more likely that interaction
with the ethernet stack will be via the main AVB API (see Section ).
1722 Packet Routing
In the AVB stack the MAC also includes a IEEE P1722 packet router that routes audio
packets to the listener components in the system. It controls the routing by stream ID.
This requires no configuration and is controlled implicitly via the AVB API described
in Section .
Precise Timing Protocol Component
The precise timing protocol component (PTP) provides a system with a notion of
global time on a network. The component supports the AVB 802.1as timing protocol.
It allows synchronization of the presentation and playback rate of media streams
across a network.
to MAC
to client threads
PTP server
The timing component consists of two threads. It connects to the ethernet MAC
Document Revision 5.1.0

---

XMOS AVB Design Guide
10/71
component and provides channel ends for clients to query for timing information.
The component interprets PTP packets from the MAC and maintains a notion of
global time. The maintenance of global time requires no application interaction with
the component.
The PTP component can be configured at runtime to be a PTP grandmaster or a PTP
slave. If the component is configured as a grandmaster, it supplies a clock source
to the network. If the network has several grandmasters, the potential grandmas-
ters negotiate between themselves to select a single grandmaster. Once a single
grandmaster is selected, all units on the network synchronize a global time from this
source and the other grandmasters stop providing timing information. Depending
on the intermediate network, this synchronization can be to sub-microsecond level
resolution.
Client threads connect to the timing component via channels. The relationship
between the local reference counter and global time is maintained across this
channel, allowing a client to timestamp with a local timer very accurately and then
convert it to global time, giving highly accurate global timestamps.
Client threads can communicate with the server using the API described in Section .
· The PTP system in the endpoint is self-configuring, it runs automatically and
gives each endpoint an accurate notion of a global clock.
· The global clock is not the same as the sample rate clock used to time audio
(though it can be used to create the sample clock). An audio stream may be at
a rate that is independent of the PTP clock but will contain timestamps that use
the global PTP clock domain as a reference domain.
Audio Components
AVB Streams, Channels, Talkers and Listeners
Audio is transported in streams of data, where each stream may have multiple
channels. Endpoints producing streams are called Talkers and those receiving them
are called Listeners. Each stream on the network has a unique 64-bit stream ID. A
single endpoint can be a Talker, a Listener or both. In general each endpoint will
have a number of sinks with the capacity to receive a number of incoming streams
and a number of sources with the capacity to transmit a number of streams.
Routing is done using layer 2 ethernet addresses. Each stream is sent from a partic-
ular source MAC address to a particular destination MAC address. The destination
MAC address may be a multicast address (that is several Listeners may receive it). In
Document Revision 5.1.0

---

XMOS AVB Design Guide
11/71
addition, AVB switches can reserve an end-to-end path with guaranteed bandwidth
for a stream. This is done by the Talker endpoint advertising the stream to the
switches and the Listener registering to receive it. If sufficient bandwidth is not
available, this registration may fail.
Streams carry their own presentation time (the time that samples are due to be
output) allowing multiple Listeners that receive the same stream to output in sync.
· Streams are encoded using the 1722 AVB transport protocol.
· All channels in a stream must be synchronized to the same sample clock.
· All the channels in a stream must come from the same Talker.
· Routing of audio streams uses ethernet layer 2 routing, which can be either
unicast (one-to-one) or multicast (one-to-many).
· Routing is done at the stream level. All channels within a stream must be
routed to the same place. However, a stream can be multicast to several
Listeners, each of which picks out different channels.
· A single end point can be both a Talker and Listener.
· The stream ID is the only information you can obtain about a stream before
registering to listen to it. Any other information about the stream must be
communicated by a higher level protocol (see Section ).
Internal Routing, Media FIFOs
1722 Stream
media output FIFOs
audio out
1722 Stream
media input FIFOs
audio in
As described in the previous section, an IEEE P1722 audio stream may consist of
many channels. These channels need to be routed to particular audio I/Os on the
endpoint. To achieve maximum flexibility the XMOS design uses intermediate media
FIFOs to route audio. Each FIFO contains a single channel of audio.
The above figure shows the breakdown of 1722 streams into local FIFOs. The figure
shows four points where transitions to and from media FIFOs occur. For audio being
received by an endpoint:
Document Revision 5.1.0

---

XMOS AVB Design Guide
12/71
1. When a 1722 stream is received, its channels are mapped to output media
FIFOs. This mapping can be configured dynamically so that it can be changed
at runtime by the configuration component.
2. The digital hardware interface maps media FIFOs to audio outputs. This
mapping is fixed and is configured statically in the software.
For audio being transmitted by an endpoint:
1. The digital hardware interface maps digital audio inputs to local media FIFOs.
This mapping is fixed and cannot be changed at runtime.
2. Several input FIFOs can be combined into a 1722 stream. This mapping is
dynamic.
The configuration of the mappings is handled through the API describe in .
Media FIFOs uses shared memory to move data between threads. So the filling and
emptying of the FIFO must be on the same core.
Talker Units
to MAC
input FIFOs
Talker
A talker unit consists of one thread which creates IEEE P1722 packets and passes
the audio samples onto the MAC. Audio samples are passed to this component
via input media FIFOs. Samples are pushed into this FIFO from a different thread
implementing the audio hardware interface. The packetizer thread removes the
samples and combines them into IEEE P1722 ethernet packets to be transmitted via
the MAC component.
When the packets are created the timestamps are converted to the time domain of
the global clock provided by the PTP component, and a fixed offset is added to the
timestamps to provide the presentation time of the samples (i.e the time at which
the sample should be played by a listener).
A system may have several talker units. However, since samples are passed via a
shared memory interface a talker can only combine input FIFOs that are created on
Document Revision 5.1.0

---

XMOS AVB Design Guide
13/71
the same core as the talker. The instantiating of talker units is performed via the API
described in Section . Once the talker unit starts, it registers with the main control
thread and is control via the main AVB API described in Section .
Listener Units
from MAC
output FIFOs
Listener
A listener units takes IEEE P1722 packets from the MAC and converts them into a
sample stream to be fed into a media FIFOs. Each audio listener component can
listen to several IEEE P1722 streams.
A system may have several listener units. The instantiating of listener units is
performed via the API described in Section . Once the listener unit starts, it registers
with the main control thread and is controlled via the main AVB API described in
Section .
Media FIFOs to XC Channels
Sometimes it is useful to convert the audio stream in a media FIFO into a sample
stream over an XC channel. This may be needed to move samples off core or if
the audio interface thread requires samples over a channel. Several functions are
provided to do this and are described in Section .
Audio Hardware Interfaces
The audio hardware interface components drive external audio hardware, pull audio
out of media output FIFOs and push into media input FIFOs.
Different interfaces interact in different ways, some directly push and pull from
the media FIFOs, whereas some (for performance reasons) require samples to be
provided of an XC channel.
The following diagram shows the thread layout of the I2S component which pushes
its input directly to media input FIFOs but takes output FIFOs from an XC channel.
Document Revision 5.1.0

---

XMOS AVB Design Guide
14/71
The diagram shows the supporting thread that takes samples out of the media output
FIFOs and serializes them over an XC channel:
output_fifo_to_xc_channel
output FIFOs
input FIFOs
I2S
Details on the available audio components can be found in Section .
Media Clocks
A media clock controls the rate at which information is passed to an external media
playing device. For example, an audio sample clock that governs the rate at which
samples should be passed to an audio CODEC. An XMOS AVB endpoint can keep
track of several media clocks.
A media clock can be synchronized to one of three sources:
· An incoming clock signal on a port.
· The rate of the incoming samples (provided by the IEEE P1722 timestamps) on
an incoming IEEE P1722 audio stream.
· The global PTP clock.
A hardware interface can be tied to a particular media clock, allowing the media
output from the XMOS device to be synchronized with other devices on the network.
All media clocks are maintained by the media clock server component. This com-
ponent takes one thread of processing and maintains the current state of all the
media clocks in the system. It then periodically updates other components with clock
change information to keep the system synchronized. The set of media clocks is
determined by an array passed to the server at startup.
The media clock server component also receives information from the audio listener
component to track timing information of incoming IEEE P1722 streams. It then sends
Document Revision 5.1.0

---

XMOS AVB Design Guide
15/71
control information back to ensure the listening component honors the presentation
time of the incoming stream.
Driving an external clock generator
A high quality, low jitter master clock, which is required to drive an audio CODEC,
must be synchronized with an AVB media clock. The XS1 chip cannot provide this
clock directly but can provide a lower frequency source for a frequency synthesizer
chip or external PLL chip. The frequency synthesizer chip must be able to generate a
high frequency clock based on a lower frequency signal (e.g a chip such as the Cirrus
Logic CS2300 or similar). The recommended configuration is as in the block diagram
below:
XS1
bclk, lrclk
CODEC
Device
mclk
FREQ
rate, ctl
SYNTH
The XS1 device provides control to the frequency synthesizer (which is often a divided
down clock to drive the higher required rate) and the frequency synthesizer provides
the master clock to the CODEC. The sample bit clocks and word clocks are then
provided to the CODEC by the XS1 device.
To drive an external clock generator requires one thread connected to the media
clock server. See src/audio/media_clocks/external for details.
Configuration and application threads
The Control Thread
As well as the components described in previous sections, an AVB endpoint applica-
tion needs a thread to control and configure the system. This control thread varies
across application and must be implemented by the application designer. To assist
in this task a unified control API is presented in Section . The control thread can
pass XC channels connected to other components into the avb_init() function and
subsequently use the control API calls to configure the other components.
Document Revision 5.1.0

---

XMOS AVB Design Guide
16/71
For an example of how an application can use this API, see the example code
walkthrough presented in Section .
Legacy Mode
AVB protocols require an AVB compatible switch to function correctly.
For testing/demonstration purposes the software platform provides a "legacy" mode
which alters the protocols to be non standard but function through non-AVB switches.
In this mode the destination addresses of the protocols change to become legacy
traffic and some of the PTP protocol behavior changes. In this case:
· The protocols are non-longer AVB standard so do not work with any other AVB
hardware. They will work with other endpoints set to this mode.
· There is no longer any quality of service guarantee so audio may be disrupted.
Furthermore the traffic from the endpoint may disrupt other non-AVB ethernet
devices on the network.
Remote Configuration
The AVB standard protocols control the time synchronization, streaming and routing
of audio data. However, it is likely that a higher level configuration protocol will be
required to configure an AVB endpoint.
Such a protocol needs two parts: discovery and control. The discovery part must
determine higher level information about other endpoints on the network. For
example:
· Discover which other Talkers/Listeners are on the network.
· Discover which streams are available and meta-information about them (sample
rate, description, global clock synchronization participation etc.).
The XMOS TCP/IP implementation canbe used with the AVB solution to provide
services such as MDNS.
The control part controls the device. For example it controls:
· The streams the Talker outputs/Listener inputs.
· Audio input/output (including sample rate, gain, dsp).
· Other non-audio aspects.
Document Revision 5.1.0

---

XMOS AVB Design Guide
17/71
A control stack will link into the control thread to provide a bridge to the local
control API. To aid implementation of this, a the XMOS TCP/IP stack can be used. A
demonstration control API is provided for the XR-AVB-LC-BRD, for more details see
the AtteroTech/XMOS XR-AVB-LC-BRD Quickstart Guide.
TCP/IP Stack
The AVB software solution includes a port of the uIP protocol stack which is a
small memory footprint stack that can be used for UDP/TCP communication to aid
implementation of an upper layer configuration protocol. For details on this stack
see the XTCP Component Guide.
Zeroconf
The Zeroconf stack (sometimes known as "Bonjour") provides:
· Multicast DNS - Allows endpoints to have a local name related to their IP
address.
· DNS Service Discovery - Allows endpoints to advertize a particular service
(such as a configuration/control service over TCP/IP) for other entities on the
network to discover.
The stack is configured via the API described in Section .
Resource Usage
Available Chip Resources
Each XMOS device has a set of resources detailed in the following table. The resources
are split amongst different cores on the device which may affect how resources can
be used:
Document Revision 5.1.0

---

XMOS AVB Design Guide
18/71
Device
Threads
MIPS
Memory (KB)
Ports
XS1-G4-512BGA
32
1600
256
64 x 1bit
16 x 4bit
8 x 16bit
4 x 32bit
XS1-L2-124QFN-C5 16
500
128
16 x 1bit
6 x 4bit
4 x 8bit
2 x 16bit
XS1-L2-124QFN-C4 16
400
128
16 x 1bit
6 x 4bit
4 x 8bit
2 x 16bit
Note that some ports overlap on the device so, for example, using a 32 bit port
makes some 1 bit ports unavailable. See the device datasheets for details.
The following sections detail the resource required for each component. Please note
that the memory requirements for code size should be taken as a rough guide since
exact memory usage depends on the integration of components (which components
are on which core etc.) in the final build of the application.
Ethernet Component
Each endpoint requires a driver for the ethernet PHY.
Component
Threads
MIPS/Thread
Memory (KB)
Ports
Ethernet
5
50
15 code
6 x 1bit
1.5 per buffer
2 x 4bit
PTP Component
Every AVB endpoint must include a PTP component.
Component
Threads
MIPS/Thread
Memory (KB)
Ports
PTP
1
50
7
None
Document Revision 5.1.0

---

XMOS AVB Design Guide
19/71
Media Clock Server
Every AVB endpoint must include a media clock server.
Component
Threads
MIPS/Thread
Memory (KB)
Ports
Media
Clock 1
50
1
None
Server
If the endpoint drives an external PLL, a PLL driver component is required.
Component
Threads
MIPS/Thread
Memory (KB)
Ports
PLL driver
1
50
0.5
1 x 1bit
+ ports to con-
figure PLL
Audio Component(s)
Each endpoint may have several listener and talker components. Each listener/talker
component is capable of handling eight IEEE P1722 streams and up to 24 channels
of audio.
Component
Threads
MIPS/Thread
Memory (KB)
Ports
1722 listener unit
1
50
5
None
1722 talker unit
1
50
5
None
The amount of resource required for audio processing depends on the interface and
the number of audio channels required. The overheads for the interface are:
Component
Threads
MIPS/Thread
Memory(KB)
Ports
I2S
1
50
0.5
3 x 1bit
1 x 1bit per stereo chan-
nel
TDM
1
50
0.5
3 x 1bit
1 x 1bit per 8 channels
The following table shows that number of channels an interface can handle per
thread:
Document Revision 5.1.0

---

XMOS AVB Design Guide
20/71
Component
Sample Rate (kHz)
Channels
I2S
44.1/48
8 in and 8 out
I2S
88.2/96
4 in and 4 out
TDM
48
8 in and 8 out
Note that several instances of the audio interface component can be made e.g. you
could use 2 threads to handle 16 channels of I2S. The following table shows how
much buffering memory is required depending on the number of audio channels.
Sample Rate (kHz)
Audio Channels
Memory (KB)
44.1
n in/m out
0.5 x (n+m)
48
n in/m out
0.5 x (n+m)
88.2
n in/m out
1 x (n+m)
96
n in/m out
1 x (n+m)
TCP Stack
The uIP IP/UDP/TCP stack requires the following resource.
Component
Threads
MIPS/Thread
Memory (KB)
Ports
uIP server
1
50
30
None
Configuration/Control
In addition to the other components there are application dependant threads that
control other I/O. For general configuration and slow I/O a minimum of 1 thread (50
MIPS) should be reserved.
Choosing the right chip
An XMOS AVB endpoint provides the ability to take IEEE 1722 audio streams from
ethernet and output the audio data.
The number of audio channels the device can handle depends on the XMOS device
used. The XS1 platform is very flexible and can provide other functions alongside
audio (depending on how much audio is used) including DSP functionality, controlling
inputs and displays on a device or controlling non-AVB ethernet communication.
Document Revision 5.1.0

---

XMOS AVB Design Guide
21/71
The amount of audio available for the XS1-G4 and XS1-L2 devices is detailed in the
following sections. See Section for more information on chip resource usage and
how these figures were determined.
Please note that in a final application the exact capability depends on the type of
digital audio interface, the mapping between 1722 and local streams, the complexity
of the routing etc. and these figures are meant only as a rough guide.
· The maximum channel count figures assume that more than two channels are
used per AVB stream to maximize channel count.
· The maximum channel count assumes I2S or similar (e.g you cannot get
maximum number of channels if all are S/PDIF).
· At 100MBit/s, the capability on the XS1 for higher bit-rates are bounded by
bandwidth and buffering in line with the AVB standard.
· For very high channel counts, it is assumed that a multi-channel multiplexed
1-wire protocol (e.g. TDM) is used to reduce the required pin count.
There exist combinations for using the AVB software with higher channel counts
and a gigabit interface on a G4 (or multi-G4) configuration. For details of these
configurations please contact XMOS.
XS1-G4 Device - 100Mbit/s
Sample Rate (kHz)
AVB Streams
Audio Channels
48
9in/9out
32 in/32 out
96
6in/6out
16 in/16 out
XS1-L2 Device - 100Mbit/s
Sample Rate (kHz)
AVB Streams
Audio Channels
48
4in/4out
8 in/8 out
96
2in/2out
4 in/4 out
Document Revision 5.1.0

---

XMOS AVB Design Guide
22/71
Programming Guide
Getting Started
The following instructions show how to build the demo for the XR-AVB-LC-BRD
endpoint. The same method holds for the other applications.
To install the software, open the XDE (XMOS Development Tools) and follow these
steps:
1. Choose File · Import.
2. Choose General · Existing Projects into Workspace and click Next.
3. Click Browse next to Select archive file and select the file firmware ZIP file.
4. Make sure the projects you want to import are ticked in the Projects list. Import
all the components and whichever applications you are interested in.
5. Click Finish.
To build, select the app_xr_avb_lc_demo project in the Project Explorer and click the
Build icon.
From the command line, you can follow these steps:
1. To install, unzip the pacakge zipfile
2. To build, change into the app_xr_avb_lc_demo directory and execute the
command:
xmake all
Makefiles
The main Makefile for the project is in the app_xr_avb_lc_demo directory. This file
specifies build options and used modules. The Makefile uses the common build
infrastructure in module_xmos_common. This system includes the source files from the
relevant modules and is documented within module_xmos_common.
Running the application
To upgrade the firmware you must, firstly connect the
XTAG-2 to the relevant development board and plug the XTAG-2 into your PC or Mac.
Document Revision 5.1.0

---

XMOS AVB Design Guide
23/71
Using the XMOS Development Environment
Using the 11.2.0 development tools or later and AVB version 5v0.1 or later, from
within the XDE:
1. Right click on the binary within the project.
2. Choose Run As · Run Configurations
3. Choose hardware and select the relevant XTAG-2 adapter
4. Select the Run UART server check box.
5. Click on Apply if configuration has changed
6. Click on Run
Using the Command Line Tools
1. Open the XMOS command line tools (Desktop Tools Prompt) and execute the
following command:
xrun --uart <binary>.xe
Installing the application onto flash
1. Connect the XTAG-2 debug adapter to the relevant development board, then
plug the XTAG-2 into your PC or Mac.
Using the XMOS Development Environment
To upgrade the flash from the XDE, follow these steps:
1. Start the XMOS Development Environment and open a workspace.
2. Choose File · Import · C/XC · C/XC Executable
3. Click Browse and select the new firmware (XE) file.
4. Click Next and Finish.
5. A Debug Configurations window is displayed. Click Close.
Document Revision 5.1.0

---

XMOS AVB Design Guide
24/71
6. Choose Run · Run Configurations.
7. Double-click Flash Programmer to create a new configuration.
8. Browse for the XE file in the Project and C/XC Application boxes.
9. Ensure the XTAG-2 device appears in the adapter list.
10. Click Run.
Using Command Line Tools
1. Open the XMOS command line tools (Desktop Tools Prompt) and execute the
following command:
xflash <binary>.xe
Source code structure
Directory Structure
The source code is split into several top-level directories (which are presented as
separate projects in Eclipse). These are split into modules and applications. The
applications build into a single executable using the source code from the modules.
The modules used by an application are specified using the USED_MODULES variable in
the application Makefile. For more details on this module structure please see the
documentation in the module_xmos_common directory.
The source package contains demonstration applications for different hardware:
Document Revision 5.1.0

---

XMOS AVB Design Guide
25/71
Directory
Platform
app_xr_avb_lc_demo
XR-AVB-LC-BRD reference design kit
app_xdk_avb_demo
XDK development kit
app_xdk_xai_avb_demo
XDK development kit with XAI audio
interface board
app_xc2_avb_demo
XC-2 development kit
app_1722_1_listner
An LC board listener that uses the
1722.1 protocol for control
app_1722_1_talker
An LC board talker that uses the
1722.1 protocol for control
app_two_channel_listener
An LC board test application with a lis-
tener that combines two single chan-
nel streams
app_two_channel_talker
An LC board test application with a
talker that produces two single chan-
nel streams
test_api_listener
A simple LC board stereo channel lis-
tener
test_api_talker
A simple LC board stereo channel
talker
Each of these applications uses different modules.
Some support modules originate in other repositories:
Directory
Description
Repository
module_ethernet
Ethernet MAC
sc_ethernet
module_xtcp
XTCP TCP/IP stack
sc_xtcp
module_zeroconf
Zeroconf/Multicast=DNS sc_xtcp
stack.
module_i2c
Two wire configuration sc_i2c
protocol code.
module_xlog
A logging server for redi- sc_xlog
recting prints over UART
or an XC channel.
module_xmos_common
Common build infrastruc- xcommon
ture.
The following modules contain the core AVB code and are needed by every applica-
tion:
Document Revision 5.1.0

---

XMOS AVB Design Guide
26/71
Directory
Description
module_avb
Main AVB code for control and config-
uration.
module_avb_1722
IEEE P1722 transport (listener and
talker functionality).
module_avb_1722_maap
IEEE P1722 MAAP - Multicast address
allocation code.
module_avb_1722_1
IEEE P1722.1 AVB control protocol.
module_avb_srp
802.1Qat stream reservation code.
module_osc
A module providing an Open Sound
Control style tree hierarchy for set-
tings. Note that no OSC protocol is
currently implemented.
module_gptp
802.1as code.
module_avb_audio
Code for media FIFOs and audio hard-
ware interfaces (I2S/TDM etc).
module_avb_media_clock
Media clock server code.
module_avb_util
General utility functions used by all
modules.
module_locks
A generic module for concurrency
locking.
module_avb_attero_cfg
Module containing UDP configuration
code for communicating with the ex-
ample Atterotech control application.
In addition to the core AVB code the following modules are used by the demos for
other functionality:
Directory
Description
module_xdk_avb_common
A selection of code used in XDK AVB
demos.
Document Revision 5.1.0

---

XMOS AVB Design Guide
27/71
Key Files
File
Description
avb.h
Header file containing declarations for
all AVB component functions and the
AVB control API.
xtcp_client.h
Header file for clients of the TCP/IP
stack.
ethernet_rx_client.h
Header file for clients that require di-
rect access to the ethernet MAC (RX).
ethernet_tx_client.h
Header file for clients that require di-
rect access to the ethernet MAC (TX).
gptp.h
Header file for access to the PTP
server.
mdns.h
Header file for clients wishing to reg-
ister Zeroconf names/services.
audio_i2s.h
Header file containing the I2S audio
component.
audio_tdm.h
Header file containing the TDM audio
component.
An XMOS AVB application (tutorial)
This tutorial walks through the application code for the XR-AVB-LC-BRD demonstration
application. This application provides both a talker transmitting a single eight channel
stream and a listener that can receive an eight channel stream.
The code for this demo is found in the app_xr_avb_lc_demo/src directory.
avb_conf.h
The avb_conf.h file sets the required defines for configuring the AVB system. Every
application must include this file and the required and optional that can be set in
this file are described in Section .
First, the file sets up the ethernet buffering. This is a balance between the required
memory for the rest of the application and the amount of buffering needed for the
audio.
Document Revision 5.1.0

---

XMOS AVB Design Guide
28/71
#define PHY_ADDRESS 0x0
#define MAX_ETHERNET_PACKET_SIZE (1518)
#define NUM_MII_RX_BUF 6
#define NUM_MII_TX_BUF 3
#define ETHERNET_RX_HP_QUEUE 1
#define MAX_ETHERNET_CLIENTS
5
#define MII_RX_BUFSIZE_HIGH_PRIORITY (700)
#define MII_RX_BUFSIZE_LOW_PRIORITY (300)
#define MII_TX_BUFSIZE_HIGH_PRIORITY (300)
#define MII_TX_BUFSIZE_LOW_PRIORITY (200)
#define ETHERNET_MAX_TX_HP_PACKET_SIZE (300)
Some general settings are needed for memory allocation across the whole AVB code
base. Here the maximum name length (use for remote control identification) and the
maximum channels per stream are set:
#define AVB_MAX_NAME_LEN 25
#define AVB_MAX_CHANNELS_PER_STREAM 8
The application can listen to a single eight channel stream. This requires a single
sink that can be handled by a single listener unit:
#define AVB_NUM_SINKS 1
#define AVB_NUM_LISTENER_UNITS 1
The application will produce a single eight channel stream. This requires a single
source that can be handled by a single talker unit:
#define AVB_NUM_SOURCES 1
#define AVB_NUM_TALKER_UNITS 1
The audio I/O side of the application must be configured. The board has eight digital
I/Os in and out so this determines the number of input/output FIFOs. In addition the
maximum sample rate of these inputs is set. A media unit is one that controls media
FIFOs. Due to the way the I2S component works, two media units are required (one
for input and one for output).
#define AVB_NUM_MEDIA_OUTPUTS 8
#define AVB_NUM_MEDIA_INPUTS 8
#define AVB_NUM_MEDIA_UNITS 2
The demo is synchronous in that it has one clock for both the input and output (this
Document Revision 5.1.0

---

XMOS AVB Design Guide
29/71
will end up being a clock divided down from the PTP clock).
#define AVB_NUM_MEDIA_CLOCKS 1
Finally, the XR-AVB-LC-BRD has eight digital inputs but only two of them are connected
to an ADC on board. For this demo another setting is added, which causes the I2S
component to ignore the input on every stereo pair but the first, and instead adds
synthesized sine waves to these inputs:
#define I2S_SYNTH_FROM 1
// Defining this makes SRP auto-start and auto-stop a stream when listeners come and go
#define SRP_AUTO_TALKER_STREAM_CONTROL
The toplevel main
The main file for the demo is xr_avb_demo.xc. This file contains three main parts:
· First, the file declares the ports needed by the application.
· Second, the top-level main() function runs the main components that make up
the application.
· Finally, the demo() function implements the main control thread that imple-
ments the demo.
The demo runs at a particular sample rate. This affects the AVB control thread and
also the thread that drives the external PLL. To co-ordinate this, the program sets
some #defines relating to the sample rate:
#define SAMPLE_RATE 48000
// This is the number of master clocks in a word clock
#define MASTER_TO_WORDCLOCK_RATIO 512
Here, MASTER_TO_WORDCLOCK_RATIO controls the ratio between the master clock and
the wordclock, which must match the setting in the clock generation PLL.
The next part of the file (not shown) declares the ports for ethernet, audio CODECs
and the PLL.
Document Revision 5.1.0

---

XMOS AVB Design Guide
30/71
The next part of the file contains the top-level main that runs the components of the
application. It is of the form:
int main(void) {
channel declarations
...
par {
...
component functions
...
}
}
The first component functions are the ethernet components: the ethernet MAC and
the TCP/IP stack server. The ethernet component section reads the MAC address out
of OTP and then runs the ethernet server based on this. The channel arrays rx_link,
tx_link and xtcp are connected to other parts of the system that use the ethernet
and TCP/IP stack:
Document Revision 5.1.0

---

XMOS AVB Design Guide
31/71
on stdcore[1]:
{
int mac_address[2];
ethernet_getmac_otp(otp_data,
otp_addr,
otp_ctrl,
(mac_address, char[]));
phy_init(clk_smi, p_mii_resetn,
smi,
mii);
ethernet_server(mii, mac_address,
rx_link, 4,
tx_link, 5,
smi, connect_status);
}
// TCP/IP stack
on stdcore[1]:
{
uip_server(rx_link[1],
tx_link[2],
xtcp, 1,
null,
connect_status);
}
The next components that are run are also core components of an AVB application,
namely the PTP server and the media clock server. Note that the initialization of the
PLL is run before the PTP server simply because it must be initialized on core 1. The
actual code that drives the PLL is on core 0. In order to save threads, the GPIO and
the PTP servers are combined into a single thread.
Document Revision 5.1.0

---

XMOS AVB Design Guide
32/71
on stdcore[1]:
{
// We need to initiate the PLL from core 1, so do it here before
// launching
the main function of the thread
audio_clock_CS2300CP_init(r_i2c, MASTER_TO_WORDCLOCK_RATIO);
ptp_server_and_gpio(rx_link[0], tx_link[0], ptp_link, 3,
PTP_GRANDMASTER_CAPABLE,
c_gpio_ctl);
}
on stdcore[1]:
{
media_clock_server(media_clock_ctl,
ptp_link[1],
buf_ctl,
1,
clk_ctl,
1);
}
As mentioned previously, the application has one outgoing stream which is han-
dled by a single talker unit. The talker unit is instantiated next with a call to
avb_1722_talker():
on stdcore[0]: avb_1722_talker(ptp_link[0],
tx_link[1],
talker_ctl[0],
AVB_NUM_SOURCES);
There is also a single listener unit, which takes incoming packets and splits them
into media FIFOs. However, the I2S component takes samples to play over an
XC channel. So media_output_to_xc_channel_split_lr() is called to take samples
from the shared memory media FIFOs and output them over an XC channel.
Document Revision 5.1.0

---

XMOS AVB Design Guide
33/71
on stdcore[0]: avb_1722_listener(rx_link[3],
tx_link[3],
buf_ctl[0],
listener_ctl[0],
AVB_NUM_SINKS);
on stdcore[0]:
{
init_media_output_fifos(ofifos, ofifo_data, AVB_NUM_MEDIA_OUTPUTS);
media_output_fifo_to_xc_channel_split_lr(media_ctl[1],
c_samples_to_codec,
0, // clk_ctl index
ofifos,
AVB_NUM_MEDIA_OUTPUTS);
}
The above components comprise the core of the AVB system. In addition there is
a debugging thread and a couple of control threads. The debugging thread calls
the XLog server which redirects print statements across the system to pass over the
UART port to the XTAG2. The resulting print statements can be viewed using xrun
with the --uart option.
on stdcore[0]:
{
xlog_server_uart(p_uart_tx);
}
Finally, the application has an application specific control thread.
First the AVB system must be initialized with a call to avb_init(). This call is needed
before any other AVB API calls.
This function takes channels connected to all the different components of the system
to be able to control them.
on stdcore[0]:
{
// First initialize avb higher level protocols
avb_init(media_ctl, listener_ctl, talker_ctl, media_clock_ctl, rx_link[2], tx_link[4], ptp_link[2]);
demo(xtcp[0], rx_link[2], tx_link[4], c_gpio_ctl);
Document Revision 5.1.0

---

XMOS AVB Design Guide
34/71
The main control thread
The main control thread is implemented in the function demo:
void demo(chanend tcp_svr, chanend c_rx, chanend c_tx, chanend c_gpio_ctl) {
This demo uses Zeroconf to advertise a configuration protocol. The name is reg-
istered as xmos_attero_endpoint, so on the local network it will have a DNS name
of xmos_attero_endpoint.local. The server attero-cfg which is a configuration
service over UDP on port ATTERO_CFG_PORT (with the value 40404) is also advertised.
This service can be discovered by the AtteroTech host configuration utility (see the
AtteroTech/XMOS XR-AVB-LC-BRD Quickstart Guide). The control API server itself
must be initialized so that it can handle requests to this port.
mdns_init(tcp_svr);
// Register all the zeroconf names
mdns_register_canonical_name("xmos_attero_endpoint");
mdns_register_service("XMOS/Attero AVB", "_attero-cfg._udp",
ATTERO_CFG_PORT, "");
// Initialize the control api server
c_api_server_init(tcp_svr);
The next section of code configures the clocking and the source streams the demo
will transmit. Firstly, as mentioned earlier in the walkthrough, this demo has one
media clock which is derived from the global PTP clock. This allows all endpoints to
run a talker and listener on the same clock with a minimum of configuration. Another
possible scheme would be for every endpoint to have a media clock that is derived
from the same AVB stream.
Document Revision 5.1.0

---

XMOS AVB Design Guide
35/71
//printstr("Media clock: LOCAL\n");
//set_device_media_clock_type(0, MEDIA_FIFO_DERIVED);
set_device_media_clock_type(0, LOCAL_CLOCK);
//set_device_media_clock_type(0, PTP_DERIVED);
set_device_media_clock_rate(0, SAMPLE_RATE);
set_device_media_clock_state(0, DEVICE_MEDIA_CLOCK_STATE_ENABLED);
// Configure the source stream
set_avb_source_name(0, "8 channel stream out");
set_avb_source_channels(0, 8);
for (int i = 0; i < 8; i++)
map[i] = i;
set_avb_source_map(0, map, 8);
set_avb_source_format(0, AVB_SOURCE_FORMAT_MBLA_24BIT, SAMPLE_RATE);
set_avb_source_sync(0, 0); // use the media_clock defined above
After the initial configuration the application enters its main control loop. This is
in the standard XC form of a "while (1), select" loop. The loop iterates and at each
point selects one of the case statements to handle. The cases may be activated by
an incoming packet, a timer event for periodic processing or some communication
from the gpio thread.
while (1) {
...
select {
case ...
break;
case ...
break;
...
}
}
The first case handled is an incoming AVB control packet from the MAC. The
avb_get_control_packet() function fires to this case and places the packet in the
array buf.
case avb_get_control_packet(c_rx, buf, nbytes):
This packet may be an 802.1Qat packet or a 1722 MAAP packet. First we pass it to
the AVB packet handler (it will ignore the packet if it is not a relevant protocol).
Document Revision 5.1.0

---

XMOS AVB Design Guide
36/71
avb_status = avb_process_control_packet(buf, nbytes, c_tx);
switch (avb_status)
{
case AVB_SRP_TALKER_ROUTE_FAILED:
avb_srp_get_failed_stream(streamId);
// handle a routing failure here
break;
case AVB_SRP_LISTENER_ROUTE_FAILED:
avb_srp_get_failed_stream(streamId);
// handle a routing failure here
break;
case AVB_MAAP_ADDRESSES_LOST:
// oh dear, someone else is using our multicast address
for (int i=0;i<AVB_NUM_SOURCES;i++)
set_avb_source_state(i, AVB_SOURCE_STATE_DISABLED);
// request a different address
avb_1722_maap_request_addresses(AVB_NUM_SOURCES, null);
break;
default:
break;
This result of this processing may be a report of a failed route which in this application
is just ignored. Alternatively, the result may be that we have lost our reserved
addresses (since some other node on the network has a claim to them). In this case
we request new address for our streams.
The next event the main loop responds to is an incoming TCP/IP packet.
Document Revision 5.1.0

---

XMOS AVB Design Guide
37/71
case xtcp_event(tcp_svr, conn):
if (conn.event == XTCP_IFUP) {
avb_start();
// Request a multicast addresses for stream transmission
avb_1722_maap_request_addresses(AVB_NUM_SOURCES, null);
}
{
mdns_event res;
res = mdns_xtcp_handler(tcp_svr, conn);
if (res & mdns_entry_lost)
{
printstr("Media clock: FIFO\n");
set_device_media_clock_type(0, MEDIA_FIFO_DERIVED);
}
}
c_api_xtcp_handler(tcp_svr, conn);
// add any special tcp/ip packet handling here
break;
Here, two handlers are called. One to handle any Zeroconf packets and one to handle
any control protocol packets. The control protocol packets are used to communicate
with the Atterotech PC control application. The code used to do this within the
firmware is in the module module_avb_attero_cfg.
The gpio thread controls the buttons on the device. It can signal the main control
thread of certain events. The next case handles this:
Document Revision 5.1.0

---

XMOS AVB Design Guide
38/71
case c_gpio_ctl :> int cmd:
switch (cmd)
{
case STREAM_SEL:
change_stream = 1;
break;
case CHAN_SEL:
{
enum avb_sink_state_t cur_state;
c_gpio_ctl :> selected_chan;
get_avb_sink_state(0, cur_state);
set_avb_sink_state(0, AVB_SINK_STATE_DISABLED);
for (int j=0;j<8;j++)
map[j] = (j+selected_chan*2) & 0x7;
set_avb_sink_map(0, map, 8);
if (cur_state != AVB_SINK_STATE_DISABLED)
set_avb_sink_state(0, AVB_SINK_STATE_POTENTIAL);
}
break;
}
break;
One possibility is that the STREAM_SEL button is pressed to change the stream being
listened to. This just sets the change_stream variable to be passed to the stream
manager of the application later.
The other possibility is that the CHAN_SEL button is pressed which changes the chan-
nels being listened to within the stream. This disables the listener sink, reconfigures
the mapping between the incoming stream and the output FIFOs and then re-enables
the stream.
The final event that can be responded to is a periodic event that occurs via an XCore
timer. This event happens once every 50us.
Document Revision 5.1.0

---

XMOS AVB Design Guide
39/71
case tmr when timerafter(timeout) :> void:
timeout += PERIODIC_POLL_TIME;
do {
avb_status = avb_periodic();
switch (avb_status)
{
case AVB_MAAP_ADDRESSES_RESERVED:
for(int i=0;i<AVB_NUM_SOURCES;i++) {
avb_1722_maap_get_offset_address(macaddr, i);
// activate the source
set_avb_source_dest(i, macaddr, 6);
set_avb_source_state(i, AVB_SOURCE_STATE_POTENTIAL);
}
break;
}
} while (avb_status != AVB_NO_STATUS);
The avb_periodic() function performs general AVB periodic processing and may
return a report that the MAAP addresses that were requested have been allocated. At
this point we can set the destination of the talker stream and enable it.
The other piece of periodic processing is to call the demo's stream manager. This is
a function contained in demo_stream_manager.xc, which manages the streams that
have been seen and the stream that is being listened to.
demo_manage_listener_stream(change_stream, selected_chan);
The demo stream manager
The demo stream manager is contained in the file demo_stream_manager.xc. It
maintains a table of streams that have been seen in the array stream_table. A
stream is first seen via the function avb_check_for_new_stream().
res = avb_check_for_new_stream(streamId, vlan, addr);
If there is no current stream and a new stream is seen, or if the change_stream
variable is set (due to a button press, see the preceding Section), then the current
listened to stream is updated. This is done by reconfiguring the sink in this section
of code:
Document Revision 5.1.0

---

XMOS AVB Design Guide
40/71
curStreamId[0] = new_hi;
curStreamId[1] = new_lo;
simple_printf("Mapping %x%x ---> %d\n",
curStreamId[0],
curStreamId[1],
0);
for (int j=0;j<8;j++)
map[j] = (j+selected_chan*2) & 0x7;
set_avb_sink_sync(0, 0);
set_avb_sink_channels(0, 8);
set_avb_sink_map(0, map, 8);
set_avb_sink_state(0, AVB_SINK_STATE_DISABLED);
set_avb_sink_id(0, curStreamId);
set_avb_sink_vlan(0, new_vlan);
set_avb_sink_addr(0, addr, 6);
set_avb_sink_state(0, AVB_SINK_STATE_POTENTIAL);
change_stream = 0;
Creating custom applications
To create your own AVB application, the general steps are:
1. Make a copy of the Eclipse project or application directory (the directory
starting with app_) you wish to base your code on, to a separate directory with
a different name.
2. Make a copy of any modules you wish to alter, and update the Makefile of your
new application to use these new custom modules.
3. Make appropriate changes to the code, rebuild and reflash the device for
testing.
If you are using a custom board and have made a copy, you need to:
1. Provide a .xn file for your board (updating the TARGET variable in the Makefile
appropriately).
2. Update avb_conf.h with the specific defines you wish to set.
Document Revision 5.1.0

---

XMOS AVB Design Guide
41/71
3. Update avb_device_defines.h and avb_device_defines.c to provide device
specific information to the AVB control API.
4. Update the top level main.
5. Add any custom code in other files you need.
Board Design
The key PCB components for an XMOS AVB solution are:
1. XS1-G4 or XS1-L2 chip
2. 100 Mbit/s MII ethernet phy (100 Mbit)
3. SPI flash for boot image loading and persistent storage
4. PLL/frequency synthesizer chip
5. An audio CODEC or processor
To aid board design please refer to the schematics that can be found at:
http://www.xmos.com/support/documentation.
This page includes reference designs for XMOS chips (including BOM costs). The
following schematics show examples connecting to additional hardware:
Schematic
Component
XR-AVB-LC-BRD
XS1-L2, Ethernet, Flash, PLL, Audio
CODECs
XC-2
XS1-G4, Ethernet, Flash
XAI Audio Interface
PLL, Audio CODEC, S/PDIF
It is highly recommend to add an XSYS connector for an XTAG2 device onto a board
for debugging.
Document Revision 5.1.0

---

XMOS AVB Design Guide
42/71
API Reference
Configuration Defines
Each application using the AVB modules must include a file called avb_conf.h and
this file must set the following values with #defines.
Define
Description
MAX_ETHERNET_PACKET_SIZE
The maximum ethernet packet size that can
be received by the endpoint. Packets larger
than this are truncated (default 1518).
NUM_MII_RX_BUF
Number of packet buffers for incoming pack-
ets.
NUM_MII_TX_BUF
Number of packet buffers for outgoing pack-
ets.
MAX_ETHERNET_CLIENTS
Maximum number of ethernet clients (i.e.
threads connected to the ethernet server).
Define
Description
AVB_MAX_NAME_LEN
The maximum length in characters of any
text name used in the endpoint (e.g. the
name of a source).
AVB_MAX_CHANNELS_PER_STREAM
The maximum allowed number of channels
per AVB stream (incoming or outgoing).
Define
Description
AVB_NUM_SINKS
The total number of AVB sinks (incoming
streams that can be listened to).
AVB_NUM_LISTENER_UNITS
The total number or listener components
(i.e. the number of threads running the
avb_1722_listener() function).
AVB_NUM_SOURCES
The total number of AVB sources (streams
that are to be transmitted).
AVB_NUM_TALKER_UNITS
The total number or talker components
(i.e. the number of threads running the
avb_1722_talker() function).
Document Revision 5.1.0

---

XMOS AVB Design Guide
43/71
Define
Description
AVB_NUM_MEDIA_OUTPUTS
The total number of media outputs (i.e. the
number of media output FIFOs).
AVB_NUM_MEDIA_INPUTS
The total number of media inputs (i.e. the
number of media input FIFOs).
AVB_NUM_MEDIA_UNITS
The number of components in the endpoint
that will register and initialize media FIFOs
(e.g. an audio interface component).
AVB_NUM_MEDIA_CLOCKS
The number of media clocks in the endpoint.
Component functions
The following functions provide components that can be combined in the top-
level main. For details on the ethernet and TCP/IP components see the Ethernet
Component Guide and the XTCP Component Guide.
Core Components
void ptp_server(chanend mac_rx,
chanend mac_tx,
chanend client[],
int num_clients,
enum ptp_server_type server_type)
This function runs the PTP server.
It takes one thread and runs indefinitely
Parameters
· mac_rx ­ chanend connected to the ethernet server (receive)
· mac_tx ­ chanend connected to the ethernet server (transmit)
· client ­ an array of chanends to connect to clients of the ptp server
· num_clients ­ The number of clients attached
· server_type ­ The type of the server (PTP_GRANDMASTER_CAPABLE or
PTP_SLAVE_ONLY)
Document Revision 5.1.0

---

XMOS AVB Design Guide
44/71
void media_clock_server(chanend media_clock_ctl,
chanend ptp_svr,
chanend ?buf_ctl[],
int buf_ctl_size,
chanend ?clk_ctl[],
int clk_ctl_size)
The media clock server.
Parameters
· media_clock_ctl ­ chanend connected to the main control thread and
passed into avb_init()
· ptp_svr ­ chanend connected to the PTP server
· buf_ctl[] ­ array of links to listener components requiring buffer manage-
ment
· buf_ctl_size ­ size of the buf_ctl array
· clk_ctl[] ­ array of links to components requiring a media clock
· clk_ctl_size ­ size of the clk_ctl array
void avb_1722_listener(chanend ethernet_rx_svr,
chanend ethernet_tx_svr,
chanend buf_ctl,
chanend listener_ctl,
int num_streams)
An AVB IEEE 1722 audio listener thread.
This thread implements a listener. It takes IEEE 1722 packets from the ethernet
MAC and splits them into output FIFOs. The buffer fill level of these streams is
set in conjunction with communication to the media clock server. This thread
is dynamically configured using the AVB control API.
Parameters
· ethernet_rx_svr ­ receive link to the ethernet MAC
· ethernet_tx_svr ­ transmit link to the ethernet MAC
· buf_ctl ­ buffer control link to the media clock server
· listener_ctl ­ channel to configure the listener (given to avb_init())
· num_streams ­ the number of streams the unit will handle
void avb_1722_talker(chanend ptp_svr,
chanend ethernet_tx_svr,
chanend talker_ctl,
int num_streams)
An AVB IEEE 1722 audio talker thread.
Document Revision 5.1.0

---

XMOS AVB Design Guide
45/71
This thread implements a talker, taking media input FIFOs and combining them
into 1722 packets to be sent to the ethernet component. It is dynamically
configured using the AVB control API.
Parameters
· ptp_svr ­ link to the PTP timing server
· ethernet_tx_svr ­ transmit link to the ethernet MAC
· talker_ctl ­ channel to configure the talker (given to avb_init())
· num_streams ­ the number of streams the unit controls
Audio Components
The following types are used by the AVB audio components:
media_output_fifo_t
This type provides a handle to a media output FIFO.
media_output_fifo_data_t
This type provides the data structure used by a media output FIFO.
media_input_fifo_t
This type provides a handle to a media input fifo.
media_input_fifo_data_t
This type provides the data structure used by a media input fifo.
The following functions implement AVB audio components:
void init_media_input_fifos(media_input_fifo_t ififos[],
media_input_fifo_data_t ififo_data[],
int n)
Initialize media input fifos.
This function intializes media input FIFOs and ties the handles to their associ-
ated data structures. It should be called before the main component function
on a thread to setup the FIFOs.
Parameters
· ififos ­ an array of media input FIFO handles to initialize
· ififo_data ­ an array of associated data structures
· n ­ the number of FIFOs to initialize
Document Revision 5.1.0

---

XMOS AVB Design Guide
46/71
void init_media_output_fifos(media_output_fifo_t ofifos[],
media_output_fifo_data_t ofifo_data[],
int n)
Initialize media output FIFOs.
This function initializes media output FIFOs and ties the handles to their associ-
ated data structures. It should be called before the main component function
on a thread to setup the FIFOs.
Parameters
· ofifos ­ an array of media output FIFO handles to initialize
· ofifo_data ­ an array of associated data structures
· n ­ the number of FIFOs to initialize
void i2s_master(const clock mclk,
clock bclk,
out buffered port:32 p_bclk,
out buffered port:32 p_lrclk,
out buffered port:32 p_dout[],
int num_out,
in buffered port:32 p_din[],
int num_in,
int master_to_word_clock_ratio,
streaming chanend ?c_listener,
media_input_fifo_t ?input_fifos[],
chanend media_ctl,
int clk_ctl_index)
Input and output audio data using I2S format with the XCore acting as master.
This function implements a thread that can handle several synchronous I2S
interfaces. It inputs and outputs 24-bit data.
The function will take input from the I2S interface and put the samples directly
into shared memory media input FIFOs. The output samples are received over
a channel. Every two word clock periods (i.e. once a sample) a timestamp is
sent from this thread over the channel and num_out samples are taken from
the channel.
This function can handle up to 8in and 8out at 48KHz.
Parameters
· mclk ­ clock block that clocks the system clock of the codec; needs to be
configured before the function call
· bclk ­ clock block that clocks the bit clock; configured within the
i2s_master function
· p_bclk ­ the port to output the bit clock to
Document Revision 5.1.0

---

XMOS AVB Design Guide
47/71
· p_lrclk ­ the port to output the word clock to
· p_dout ­ array of ports to output data to
· num_out ­ number of output ports
· p_din ­ array of ports to input data from
· num_in ­ number of input ports
· master_to_word_clock_ratio ­ the ratio of the master clock to the word
clock; must be one of 128, 256 or 512
· c_listener ­ chanend connector to a listener component
· input_fifos ­ a map from the inputs to local talker streams. The channels
of the inputs are interleaved, for example, if you have two input ports, the
map {0,1,0,1} would map to the two stereo local talker streams 0 and 1.
· media_ctl ­ the media fifo control channel
· clk_ctl_index ­ the index of the clk_ctl channel array that controls the
master clock fo the codec
void media_output_fifo_to_xc_channel(chanend media_ctl,
streaming chanend samples_out,
int clk_ctl_index,
media_output_fifo_t ofifos[],
int num_channels)
Output audio streams from media fifos to an XC channel.
This function outputs samples from several media output FIFOs over an XC
channel over the streaming chanend samples_out.
The protocol over the channel is that the thread expects a timestamp to be sent
to it and then it will output num_channels samples, pulling from the ofifos
array. It will then expect another timestamp before the next set of samples.
Parameters
· media_ctl ­ chanend connected to the main control thread
· samples_out ­ the chanend on which samples are output
·
clk_ctl_index
­ the index in the clk_ctl array passed to
media_clock_server() that controls the rate of the FIFOs (i.e.
the
rate at which samples are pulled from the other end of the channel). This
should be -1 if the pull rate is not controlled by the media clock server.
· ofifos ­ array of media output FIFOs to pull from
· num_channels ­ the number of channels (or FIFOs)
Document Revision 5.1.0

---

XMOS AVB Design Guide
48/71
void media_output_fifo_to_xc_channel_split_lr(chanend media_ctl,
streaming
chanend samples_out,
int clk_ctl_index,
media_output_fifo_t out-
put_fifos[],
int num_channels)
Output audio streams from media FIFOs to an XC channel, splitting left and
right pairs.
This function outputs samples from several media output FIFOs over an XC chan-
nel over the streaming chanend samples_out. The media FIFOs are assumed to
be grouped in left/right stereo pairs which are then split.
The protocol over the channel is that the thread expects a timestamp to be
sent to it and then it will first output num_channels/2 samples, pulling from
all the even indexed elements of the ofifos array and then output all the odd
elements. It will then expect another timestamp before the next set of samples.
Parameters
· media_ctl ­ chanend connected to the main control thread
· samples_out ­ the chanend on which samples are output
·
clk_ctl_index
­ the index in the clk_ctl array passed to
media_clock_server() that controls the rate of the FIFOs (i.e.
the
rate at which samples are pulled from the other end of the channel). This
should be -1 if the pull rate is not controlled by the media clock server.
· output_fifos ­ array of media output fifos to pull from
· num_channels ­ the number of channels (or FIFOs)
AVB API
General Control Functions
avb_status_t
AVB Status Report Type.
This type is returned by avb_periodic(), avb_srp_process_packet() and
avb_1722_maap_process_packet(). and indicates any change in state of the
AVB system.
Enum Values:
AVB_NO_STATUS
-1
Document Revision 5.1.0

---

XMOS AVB Design Guide
49/71
No status to report.
AVB_SRP_OK
0
Status is ok (no change).
AVB_SRP_TALKER_ROUTE_FAILED
A route from one of the devices sources has failed to reach an
intended listener (probably due to lack of bandwidth).
Use avb_srp_get_failed_stream() to find the streamID of the
failed stream.
AVB_SRP_LISTENER_ROUTE_FAILED
A route from to one of the devices sinks has failed to reach from
an intended talker (probably due to lack of bandwidth).
Use avb_srp_get_failed_stream() to find the streamID of the
failed stream.
AVB_SRP_INDICATION
One of the SRP indications has occured.
The stream flags will be marked appropriately.
AVB_MAAP_ADDRESSES_RESERVED
Multicast addresses have been successfully been reserved after a
called to avb_1722_maap_request_addresses().
Use
avb_1722_maap_get_base_address()
or
avb_1722_maap_get_offset_address() to access the reserved
addresses.
AVB_MAAP_ADDRESSES_LOST
Previously reserved multicast addresses have been lost.
After
this
event
the
control
thread
should
dis-
able
any
streams
using
MAAP
addresses
and
recall
avb_1722_maap_request_addresses()
AVB_1722_1_OK
1722.1 status ok
AVB_1722_1_ENTITY_ADDED
An entity has been added to the database by the discovery proto-
col.
AVB_1722_1_ENTITY_REMOVED
An entity has been removed from the database by the discovery
protocol.
AVB_1722_1_CONNECT_TALKER
A connection management protocol message has been received
indicating that a talker component should initiate a connection.
AVB_1722_1_DISCONNECT_TALKER
An SCM message indicates that a talker should release a connec-
tion.
Document Revision 5.1.0

---

XMOS AVB Design Guide
50/71
AVB_1722_1_CONNECT_LISTENER
An SCM message indicates that a listener should initiate a connec-
tion.
AVB_1722_1_DISCONNECT_LISTENER
An SCM message indicates that a listener should release a con-
nection.
void avb_init(chanend media_ctl[],
chanend ?listener_ctl[],
chanend ?talker_ctl[],
chanend media_clock_ctl,
chanend c_mac_rx,
chanend c_mac_tx,
chanend c_ptp)
Initialize the AVB control thread.
This function initializes the AVB system. It needs to be called in the main user
control thread before any other AVB control call. The function takes chanends
connected to other parts of the system and registers all of these components.
At this point the sinks, sources and media FIFOs are allocated numbers. The al-
location is performed by registering numbers from 0 upwards working through
the listener_ctl/talker_ctl/media_ctl arrays. Each component in this array may
register several sink/sources/FIFOs. For example, if the listener_ctl array con-
nects to two listener units each registering 3 sinks then the first unit will be
allocated sink numbers 0,1,2 and the second 3,4,5.
Note that this call does not start any protocols communicating over the network
(e.g. advertising talkers via IEEE 802.1Qat). That is deferred until the call to
avb_start().
Parameters
· media_ctl ­ array of chanends connected to components that register/-
control media FIFOs
· listener_ctl ­ array of chanends connected to components that register/-
control IEEE 1722 sinks
· talker_ctl ­ array of chanends connected to components that register/-
control IEEE 1722 sources
· media_clock_ctl ­ chanend connected to the media clock server
· c_mac_rx ­ chanend connected to the ethernet server (RX)
· c_mac_tx ­ chanend connected to the ethernet server (TX)
· c_ptp ­ chanend connected to the ptp server
void avb_start(void)
Start any AVB protocol state machines.
Document Revision 5.1.0

---

XMOS AVB Design Guide
51/71
This call starts any AVB protocol state machines running. It should be called
after the ethernet link goes up.
avb_status_t avb_periodic(void)
Perform AVB periodic processing.
This function performs AVB periodic processing. It should be called from the
main control thread at least once each ms. If it returns a state other than
AVB_NO_STATUS then it should be called again immediately.
Returns A status update from the periodic processing to indicate an event due
to a timeout etc. (see avb_status_t)
void avb_get_control_packet(chanend c_rx,
unsigned int buf[],
unsigned int &nbytes)
Receives an 802.1Qat SRP packet or an IEEE P1722 MAAP packet.
This function receives an AVB control packet from the ethernet MAC. It is
selectable so can be used in a select statement as a case.
Parameters
· c_rx ­ chanend connected to the ethernet component
· buf ­ buffer to retrieve the packet into; buffer must have length at least
MAX_AVB_CONTROL_PACKET_SZIE bytes
· nbytes ­ a reference parameter that is filled with the length of the received
packet
avb_status_t avb_process_control_packet(unsigned int buf[],
int len,
chanend c_tx)
Process an AVB control packet.
This function processes an ethernet packet and if it is a 802.1Qat or IEEE 1722
MAAP packet will handle it.
This
function
should
always
be
called
on
the
buffer
filled
by
avb_get_control_packet().
Parameters
· buf ­ the incoming message buffer
· len ­ the length (in bytes) of the incoming buffer
· c_tx ­ chanend connected to the ethernet mac (TX)
Returns AVB_SRP_TALKER_ROUTE_FAILED if the incoming packet reports a talker
routing failure (i.e. a failure in getting an outgoing stream to its intended
listener). AVB_SRP_LISTENER_ROUTE_FAILED if the incoming packet reports a
listener routing failure (i.e. a failure in listening to a stream). If the packet
Document Revision 5.1.0

---

XMOS AVB Design Guide
52/71
causes a previously asked for, or reserved, multicast address range to be no
longer available, then AVB_MAAP_ADDRESSES_LOST is returned.
int avb_check_for_new_stream(unsigned streamId[2],
unsigned &vlan,
unsigned char addr[6])
Check whether a new incoming AVB stream has been detected.
This function checks whether a new IEEE 1722 stream has been detected. A
new stream will be detected if an 802.1Qat talker advertise packet is received
by the endpoint.
Each new stream seen will be reported once by this function. Internally the AVB
system keeps a history up to the size AVB_STREAM_HISTORY_SIZE which has a
default value of 128 and can be set in avb_conf.h
Parameters
· streamId ­ an array to be filled with the new stream id
· vlan ­ a reference param to be filled with the vlan the detected stream is
on
Returns a non-zero value if a new stream is detected, zero otherwise
void avb_set_legacy_mode(int mode)
Set the endpoint into "legacy mode".
This function sets the endpoint into "legacy mode" to work with non-AVB
switches for testing or demonstration purposes. In this mode the destination
address of certain protocols change to become legacy (non-AVB) traffic and the
PTP 802.1as protocol behaves in a slightly different manner. In this case:
· The protocols are non-longer AVB standard so will not work with any other
AVB hardware. They will only work with other endpoints set to this mode.
· There is no longer any quality of service guarantee so audio may be
disrupted. Furthermore the traffic from the endpoint may disrupt other
non-AVB ethernet devices on the network.
Parameters
· mode ­ non-zero to set legacy mode, zero to unset it
Multicast Address Allocation
void avb_1722_maap_request_addresses(int num_addresses,
char ?start_address[])
Request a range of multicast addresses.
Document Revision 5.1.0

---

XMOS AVB Design Guide
53/71
This function requests a range of multicast addresses to use as destination
addresses for IEEE 1722 streams. It starts the reservation process according to
the 1722 MAAP protocol. If the reservation is successful it is reported via the
status return value of avb_periodic().
Parameters
· num_addresses ­ number of addresses to try and reserve; will be reserved
in a contiguous range
· start_address ­ an optional six byte array specifying the required start
address of the range; if argument is null then the start address will be
picked at random
void avb_1722_maap_get_base_address(unsigned char addr[6])
Get the base address of the reserved range.
This function returns the first address of the reserved multicast address range.
Parameters
· addr ­ array to be filled with the 6-byte MAC address
void avb_1722_maap_get_offset_address(unsigned char addr[6],
int offset)
Get the address offset into the reserved range.
This function returns a specific address within the reserved multicast address
range.
Parameters
· addr ­ array to be filled with the 6-byte MAC address
· offset ­ the offset into that range required
Stream Reservation
void avb_srp_get_failed_stream(unsigned int streamId[2])
Get the stream id of a failed reservation.
This
should
be
called
after
getting
AVB_SRP_ROUTE_FAILED
from
avb_srp_process_packet().
Parameters
· streamId ­ the 64 bit stream id array to fill with the failed stream
Document Revision 5.1.0

---

XMOS AVB Design Guide
54/71
Device Control
These functions need to be supplied by the application.
int get_device_name(char device_name_string[])
Get the name of the device.
Parameters
· device_name_string ­ array to be filled with the device name
int get_device_system(char device_name_string[])
Get the name of the system the device is part of.
Parameters
· device_name_string ­ array to be filled with the system name
int get_device_identity_vendor_id(char vendor_id_string[])
Get the id of the vendor.
Parameters
· vendor_id_string ­ array to be filled with the vendor id
int get_device_identity_vendor(char vendor_name_string[])
Get the name of the device vendor.
Parameters
· vendor_name_string ­ array to be filled with the vendor name
int get_device_identity_product(char product_string[])
Get the name of the product.
Parameters
· product_string ­ array to be filled with the product name
int get_device_identity_version(char version_string)
Get the version of the product.
Parameters
· version_string ­ array to be filled with the version
int get_device_identity_serial(char serial_no_string[])
Get the serial number of the device.
Parameters
· serial_no_string ­ array to be filled with the serial number
Document Revision 5.1.0

---

XMOS AVB Design Guide
55/71
Media Clock Control
device_media_clock_type_t
Enum Values:
DEVICE_MEDIA_CLOCK_TYPE_PTP
DEVICE_MEDIA_CLOCK_TYPE_STREAM
int get_device_media_clock_type(int clock_num,
device_media_clock_type_t &clock_type)
Get the type of a media clock.
Parameters
· clock_num ­ the number of the media clock
· clock_type ­ the type of the clock
int set_device_media_clock_type(int clock_num,
device_media_clock_type_t clock_type)
Set the type of a media clock.
Parameters
· clock_num ­ the number of the media clock
· clock_type ­ the type of the clock
int get_device_media_clock_rate(int clock_num,
int &rate)
Get the rate of a media clock.
Parameters
· clock_num ­ the number of the media clock
· rate ­ the rate of the clock in Hz
int set_device_media_clock_rate(int clock_num,
int rate)
Set the rate of a media clock.
Sets the rate of the media clock.
Parameters
· clock_num ­ the number of the media clock
· rate ­ the rate of the clock in Hz
int get_device_media_clock_source(unsigned clock_num,
device_media_clock_state_t &source)
Get the source of a media clock.
Parameters
Document Revision 5.1.0

---

XMOS AVB Design Guide
56/71
· clock_num ­ the number of the media clock
· source ­ the output FIFO number to base the clock on
int set_device_media_clock_source(unsigned clock_num,
device_media_clock_state_t source)
Set the source of a media clock.
For clocks that are derived from an output FIFO. This function gets/sets which
FIFO the clock should be derived from.
Parameters
· clock_num ­ the number of the media clock
· source ­ the output FIFO number to base the clock on
device_media_clock_state_t
Enum Values:
DEVICE_MEDIA_CLOCK_STATE_DISABLED
DEVICE_MEDIA_CLOCK_STATE_ENABLED
int get_device_media_clock_state(int clock_num,
device_media_clock_state_t &state)
Get the state of a media clock.
Parameters
· clock_num ­ the number of the media clock
· state ­ the state of the clock
int set_device_media_clock_state(int clock_num,
device_media_clock_state_t state)
Set the state of a media clock.
This function can be used to enabled/disable a media clock.
Parameters
· clock_num ­ the number of the media clock
· state ­ the state of the clock
AVB Source Control
avb_source_format_t
Enum Values:
AVB_SOURCE_FORMAT_MBLA_24BIT
Document Revision 5.1.0

---

XMOS AVB Design Guide
57/71
void get_avb_source_format(unsigned source_num,
unsigned format,
unsigned &rate)
Get the format of an AVB source.
Parameters
· source_num ­ the local source number
· format ­ the format of the stream
· rate ­ the sample rate of the stream in Hz
void set_avb_source_format(unsigned source_num,
unsigned format,
unsigned rate)
Set the format of an AVB source.
The AVB source format covers the encoding and sample rate of the source.
Currently the format is limited to a single encoding MBLA 24 bit signed integers.
This setting will not take effect until the next time the source state moves from
disabled to potential.
Parameters
· source_num ­ the local source number
· format ­ the format of the stream
· rate ­ the sample rate of the stream in Hz
void get_avb_source_channels(unsigned source_num,
unsigned &n)
Get the channel count of an AVB source.
Parameters
· source_num ­ the local source number
· n ­ the number of channels
void set_avb_source_channels(unsigned source_num,
unsigned n)
Set the channel count of an AVB source.
Sets the number of channels in the stream.
This setting will not take effect until the next time the source state moves from
disabled to potential.
Parameters
· source_num ­ the local source number
· n ­ the number of channels
Document Revision 5.1.0

---

XMOS AVB Design Guide
58/71
void get_avb_source_map(unsigned source_num,
unsigned map[],
unsigned &len)
Get the channel map of an avb source.
Parameters
· source_num ­ the local source number to set
· map ­ the map, an array of integers giving the input FIFOs that make up
the stream
· len ­ the length of the map; should be equal to the number of channels
in the stream
void set_avb_source_map(unsigned source_num,
unsigned map[],
unsigned len)
Set the channel map of an avb source.
Sets the channel map of a source i.e. the list of input FIFOs that constitute the
stream.
This setting will not take effect until the next time the source state moves from
disabled to potential.
Parameters
· source_num ­ the local source number to set
· map ­ the map, an array of integers giving the input FIFOs that make up
the stream
· len ­ the length of the map; should be equal to the number of channels
in the stream
void get_avb_source_sync(unsigned source_num,
unsigned &mclock)
Get the media clock of an AVB source.
Parameters
· source_num ­ the local source number
· mclock ­ the media clock number
void set_avb_source_sync(unsigned source_num,
unsigned mclock)
Set the media clock of an AVB source.
Sets the media clock of the stream.
Parameters
· source_num ­ the local source number
Document Revision 5.1.0

---

XMOS AVB Design Guide
59/71
· mclock ­ the media clock number
void get_avb_source_presentation(unsigned source_num,
unsigned &offset)
Get the presentation time offset of an AVB source.
Parameters
· source_num ­ the local source number to set
· offset ­ the presentation offset in ms
void set_avb_source_presentation(unsigned source_num,
unsigned offset)
Set the presentation time offset of an AVB source.
Sets the presentation time offset of a source i.e. the time after sampling that
the stream should be played. The default value for this is 2ms.
This setting will not take effect until the next time the source state moves from
disabled to potential.
Parameters
· source_num ­ the local source number to set
· offset ­ the presentation offset in ms
void get_avb_source_name(unsigned source_num,
char name[])
Get the name of an AVB source.
Parameters
· source_num ­ the local source number
· name ­ the string containing the name
void set_avb_source_name(unsigned source_num,
char name[])
Set the name of an AVB source.
Sets a human readable name for the stream. This name must be fewer than
AVB_MAX_NAME_LEN which can be set in avb_conf.h.
Parameters
· source_num ­ the local source number
· name ­ the string containing the name
void get_avb_source_dest(unsigned source_num,
char addr[],
unsigned &len)
Get the destination address of an avb source.
Parameters
Document Revision 5.1.0

---

XMOS AVB Design Guide
60/71
· source_num ­ the local source number
· addr ­ the destination address as an array of 6 bytes
· len ­ the length of the address, should always be equal to 6
void set_avb_source_dest(unsigned source_num,
char addr[],
unsigned len)
Set the destination address of an avb source.
Sets the destination MAC address of a source. This setting will not take effect
until the next time the source state moves from disabled to potential.
Parameters
· source_num ­ the local source number
· addr ­ the destination address as an array of 6 bytes
· len ­ the length of the address, should always be equal to 6
void get_avb_source_vlan(unsigned source_num,
unsigned &vlan)
Get the destination vlan of an AVB source.
Parameters
· source_num ­ the local source number
· vlan ­ the destination vlan id, The media clock number
void set_avb_source_vlan(unsigned source_num,
unsigned vlan)
Set the destination vlan of an AVB source.
Sets the vlan that the source will transmit on. This defaults to 2.
This setting will not take effect until the next time the source state moves from
disabled to potential.
Parameters
· source_num ­ the local source number
· vlan ­ the destination vlan id, The media clock number
avb_source_state_t
The state of an AVB source.
Enum Values:
AVB_SOURCE_STATE_DISABLED
The source is disabled and will not transmit.
AVB_SOURCE_STATE_POTENTIAL
The source is enabled and will transmit if a listener requests it.
Document Revision 5.1.0

---

XMOS AVB Design Guide
61/71
AVB_SOURCE_STATE_ENABLED
The source is enabled and transmitting.
void get_avb_source_state(unsigned source_num,
avb_source_state_t &state)
Get the current state of an AVB source.
Parameters
· source_num ­ the local source number
· state ­ the state of the source
void set_avb_source_state(unsigned source_num,
avb_source_state_t state)
Set the current state of an AVB source.
Sets the current state of an AVB source. You cannot set the state to ENABLED.
Changing the state to POTENTIAL turns the stream on and it will automatically
change to ENABLED when connected to a listener and streaming.
Parameters
· source_num ­ the local source number
· state ­ the state of the source
AVB Sink Control
void get_avb_sink_channels(unsigned sink_num,
unsigned &n)
Get the number of channels of an AVB sink.
Parameters
· sink_num ­ the number of the sink
· n ­ the number of channels
void set_avb_sink_channels(unsigned sink_num,
unsigned n)
Set the number of channels of an AVB sink.
Sets the number of channels of an AVB sink.
This setting will not take effect until the next time the sink state moves from
disabled to potential.
Parameters
· sink_num ­ the number of the sink
· n ­ the number of channels
Document Revision 5.1.0

---

XMOS AVB Design Guide
62/71
void get_avb_sink_map(unsigned sink_num,
unsigned map[],
unsigned &len)
Get the map of an AVB sink.
Parameters
· sink_num ­ the number of the sink
· map ­ array containing the media output FIFOs that the stream will be
split into
· len ­ the length of the map; should equal to the number of channels in
the stream
void set_avb_sink_map(unsigned sink_num,
unsigned map[],
unsigned len)
Set the map of an AVB sink.
Sets the map i.e. the mapping from the 1722 stream to output FIFOs.
This setting will not take effect until the next time the sink state moves from
disabled to potential.
Parameters
· sink_num ­ the number of the sink
· map ­ array containing the media output FIFOs that the stream will be
split into
· len ­ the length of the map; should equal to the number of channels in
the stream
void get_avb_sink_sync(unsigned sink_num,
unsigned &sync)
Get the media clock sync of an AVB sink.
Parameters
· sink_num ­ the number of the sink
· sync ­ the media clock number of the sink
void set_avb_sink_sync(unsigned sink_num,
unsigned sync)
Set the media clock sync of an AVB sink.
Sets which media clock is used to synchronize the incoming stream.
This setting will not take effect until the next time the sink state moves from
disabled to potential.
Parameters
Document Revision 5.1.0

---

XMOS AVB Design Guide
63/71
· sink_num ­ the number of the sink
· sync ­ the media clock number of the sink
void get_avb_sink_name(unsigned sink_num,
char name[])
Get the name of an AVB sink.
Parameters
· sink_num ­ the number of the sink
· name ­ the name string
void set_avb_sink_name(unsigned sink_num,
char name[])
Set the name of an AVB sink.
Sets the name of the sink (to be reported by higher level protocols).
Parameters
· sink_num ­ the number of the sink
· name ­ the name string
void get_avb_sink_id(unsigned sink_num,
unsigned streamId[])
Get the stream id that an AVB sink listens to.
Parameters
· sink_num ­ the number of the sink
· streamId ­ int array containing the 64-bit of the stream
void set_avb_sink_id(unsigned sink_num,
unsigned streamId[])
Set the stream id that an AVB sink listens to.
Sets the stream id that an AVB sink listens to.
This setting will not take effect until the next time the sink state moves from
disabled to potential.
Parameters
· sink_num ­ the number of the sink
· streamId ­ int array containing the 64-bit of the stream
void get_avb_sink_addr(unsigned sink_num,
char addr[],
unsigned &len)
Get the incoming destination mac address of an avb sink.
Parameters
Document Revision 5.1.0

---

XMOS AVB Design Guide
64/71
· sink_num ­ The local sink number
· addr ­ The mac address as an array of 6 bytes.
· len ­ The length of the address, should always be equal to 6.
void set_avb_sink_addr(unsigned sink_num,
char addr[],
unsigned len)
Set the incoming destination mac address of an avb sink.
Set the incoming destination mac address of a sink. This needs to be set if the
address is a multicast address so the endpoint can register for that multicast
group with the switch.
This setting will not take effect until the next time the sink state moves from
disabled to potential.
Parameters
· sink_num ­ The local sink number
· addr ­ The mac address as an array of 6 bytes.
· len ­ The length of the address, should always be equal to 6.
void get_avb_sink_vlan(unsigned sink_num,
unsigned &vlan)
Get the virtual lan id of an AVB sink.
Parameters
· sink_num ­ the number of the sink
· vlan ­ the vlan id of the sink
void set_avb_sink_vlan(unsigned sink_num,
unsigned vlan)
Set the virtual lan id of an AVB sink.
Sets the vlan id of the incoming stream.
This setting will not take effect until the next time the sink state moves from
disabled to potential.
Parameters
· sink_num ­ the number of the sink
· vlan ­ the vlan id of the sink
avb_sink_state_t
Enum Values:
AVB_SINK_STATE_DISABLED
Document Revision 5.1.0

---

XMOS AVB Design Guide
65/71
AVB_SINK_STATE_POTENTIAL
AVB_SINK_STATE_ENABLED
void get_avb_sink_state(unsigned sink_num,
avb_sink_state_t state)
Get the state of an AVB sink.
Parameters
· sink_num ­ the number of the sink
· state ­ the state of the sink
void set_avb_sink_state(unsigned sink_num,
avb_sink_state_t state)
Set the state of an AVB sink.
Sets the current state of an AVB sink. You cannot set the state to ENABLED.
Changing the state to POTENTIAL turns the stream on and it will automatically
change to ENABLED when connected to a talker and receiving samples.
Parameters
· sink_num ­ the number of the sink
· state ­ the state of the sink
PTP Client API
The PTP client API can be used if you want extra information about the PTP time
domain. An application does not need to directly use this to control the AVB endpoint
since the talker, listener and media clock server units communicate with the PTP
server directly.
Time Data Structures
ptp_timestamp
This type represents a timestamp in the gptp clock domain.
Structure Members:
unsigned int seconds
unsigned int nanoseconds
Document Revision 5.1.0

---

XMOS AVB Design Guide
66/71
Getting PTP Time Information
ptp_time_info
This type is used to relate local XCore time with gptp time.
It can be retrieved from the PTP server using the ptp_get_time_info() function.
ptp_time_info_mod64
This structure is used to relate local XCore time with the least significant 64
bits of gptp time.
It can be retrieved from the PTP server using the ptp_get_time_info_mod64()
function.
void ptp_get_time_info(chanend ptp_server,
ptp_time_info &info)
Retrieve time information from the ptp server.
This function gets an up-to-date structure of type ptp_time_info to use to
convert local time to PTP time.
Parameters
· ptp_server ­ chanend connected to the ptp_server
· info ­ structure to be filled with time information
void ptp_get_time_info_mod64(chanend ptp_server,
ptp_time_info_mod64 &info)
Retrieve time information from the ptp server.
This function gets an up-to-date structure of type ptp_time_info_mod64 to use
to convert local time to ptp time (modulo 64 bits).
Parameters
· ptp_server ­ chanend connected to the ptp_server
· info ­ structure to be filled with time information
void ptp_request_time_info(chanend ptp_server)
This function requests a ptp_time_info structure from the PTP server.
This is an asynchronous call so needs to be completed later with a call to
ptp_get_requested_time_info().
Parameters
· ptp_server ­ chanend connecting to the ptp server
void ptp_request_time_info_mod64(chanend ptp_server)
This function requests a ptp_time_info_mod64 structure from the PTP server.
Document Revision 5.1.0

---

XMOS AVB Design Guide
67/71
This is an asynchronous call so needs to be completed later with a call to
ptp_get_requested_time_info_mod64().
Parameters
· ptp_server ­ chanend connecting to the PTP server
void ptp_get_requested_time_info(chanend ptp_server,
ptp_time_info &info)
This function receives a ptp_time_info structure from the PTP server.
This completes an asynchronous transaction initiated with a call to
ptp_request_time_info(). The function can be placed in a select case which
will activate when the PTP server is ready to send.
Parameters
· ptp_server ­ chanend connecting to the PTP server
· info ­ a reference parameter to be filled with the time information struc-
ture
void ptp_get_requested_time_info_mod64(chanend ptp_server,
ptp_time_info_mod64 &info)
This function receives a ptp_time_info_mod64 structure from the PTP server.
This completes an asynchronous transaction initiated with a call to
ptp_request_time_info_mod64(). The function can be placed in a select case
which will activate when the PTP server is ready to send.
Parameters
· ptp_server ­ chanend connecting to the PTP server
· info ­ a reference parameter to be filled with the time information struc-
ture
Converting Timestamps
void local_timestamp_to_ptp(ptp_timestamp &ptp_ts,
unsigned local_ts,
ptp_time_info &info)
Convert a timestamp from the local XCore timer to PTP time.
This function takes a 32-bit timestamp taken from an XCore timer and converts
it to PTP time.
Parameters
· ptp_ts ­ the PTP timestamp structure to be filled with the converted time
· local_ts ­ the local timestamp to be converted
Document Revision 5.1.0

---

XMOS AVB Design Guide
68/71
· info ­ a time information structure retrieved from the ptp server
unsigned local_timestamp_to_ptp_mod32(unsigned local_ts,
ptp_time_info_mod64 &info)
Convert a timestamp from the local XCore timer to the least significant 32 bits
of PTP time.
This function takes a 32-bit timestamp taken from an XCore timer and converts
it to the least significant 32 bits of global PTP time.
Parameters
· local_ts ­ the local timestamp to be converted
· info ­ a time information structure retrieved from the PTP server
Returns the least significant 32-bits of ptp time in nanoseconds
unsigned ptp_timestamp_to_local(ptp_timestamp &ts,
ptp_time_info &info)
Convert a PTP timestamp to a local XCore timestamp.
This function takes a PTP timestamp and converts it to a local 32-bit timestamp
that is related to the XCore timer.
Parameters
· ts ­ the PTP timestamp to convert
· info ­ a time information structure retrieved from the PTP server.
Returns the local timestamp
MDNS/Bonjour API
void mdns_init(chanend tcp_svr)
Initialize Zeroconf.
This function should be called before any other mdns functions.
Parameters
· tcp_svr ­ chanend connected to the xtcp server
mdns_event mdns_xtcp_handler(chanend tcp_svr,
xtcp_connection_t &conn)
Handle a mdns TCP/IP event.
This function will process a tcp/ip event (following a call to xtcp_event()). If
the related connection is an MDNS connection it will handle the packet and set
the connection event to ALREADY_HANDLED.
Parameters
Document Revision 5.1.0

---

XMOS AVB Design Guide
69/71
· tcp_svr ­ chanend connected to the TCP/IP server.
· conn ­ the connection data structure filled in by xtcp_event()
Returns one of several constants describing events that have occurred
void mdns_register_name(char name[])
Register a name for the host.
This function registers a name for the host. After this call the zeroconf protocol
will try and reserve this name. After that point you can refer to the host on the
network with this name.
If the name is already reserved by another node on the network, a unique
number will be added to the name. For example, if the name "xc2.local" was
requested and already exists on the network. The library will try and reserver
"xc2-1.local" and then "xc2-2.local" etc.
Parameters
· name ­ the name to register
void mdns_register_canonical_name(char name[])
Register the canonical name for the host.
This function registers the canonical name (i.e. the name returned as response
to PTR requests) for the host.
Parameters
· name ­ the name to register
void mdns_register_service(char name[],
char srv_type[],
int srv_port,
char txt[])
Register a Zeroconf service.
This function registers a service to advertise.
Parameters
· name ­ a human readable name of the service instance e.g. "My Web
Server"
· srv_type ­ the type of the service "_http._tcp"
· srv_port ­ the port the service is to be advertised on
· txt ­ the associated TXT record of the service.
Document Revision 5.1.0

---

XMOS AVB Design Guide
70/71
IEEE 1722 Bandwidth Usage
The AVB standard requires audio data to be split into packets to be transmitted over
ethernet along with meta-information specified by the IEEE 1722 transport protocol.
This meta-information incurs an overhead on the bandwidth of each stream of data.
The protocol overhead is detailed in the following table:
Protocol
Overhead (bytes)
Interframe gap
20
Ethernet header
18
IEEE 1722 header
24
61883-6 header
8
CRC
4
Each stream of audio data can contain several multiplexed channels of audio. The
higher the number of channels per stream, the more efficient the audio transport is
in terms of bandwidth. Note that the IEC 61883-6 standard recommends transmitting
single channel streams as stereo with the right channel blank.
After the header in each packet, audio data is stored in AM824 format which pads
24-bit data to 4 byte quadlets. The frame rate is 8kHz so a 48kHz stream has 6
samples per packet, a 96kHz has 12 samples per packet and so on.
The following table shows the bandwidth for streams at different sample rates with
different number of channels per stream.
Sample Rate (kHz)
Channels/Stream
Mbps
48
1
7.81
48
2
7.81
48
4
10.88
48
8
17.02
48
16
29.31
48
32
53.89
96
1
10.88
96
2
10.88
96
4
17.02
96
8
29.31
96
16
53.89
Document Revision 5.1.0

---