How to guides

1. Log into xmos.com and access My XMOS > Reference Designs
2. Request access to the AVB Endpoint Software by clicking the Request Access link under AVB Audio Endpoint. An email will be sent to your registered email address when access is granted.
3. A Download link will appear where the Request Access link previously appeared. Click and download the firmware zip.

The AVB-LC software requires xTIMEcomposer version 13.0.2 or greater. It can be downloaded at the following URL
http://1m2n3b4v.xmos.com/support/xtools

To import and build the firmware, open xTIMEcomposer Studio 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 firmware .zip file downloaded in section 1.
4. Make sure that all projects are ticked in the
   Projects list.
5. Click Finish.
6. Select the app_avb_lc_demo project in the Project Explorer and click the Build icon in the main toolbar.

1. Connect the xTAG-2 debug adapter (XA-SK-XTAG2) to the first AVB endpoint board.
2. Plug the xTAG-2 into your development system via USB.
3. Plug in the 5V power adapter and connect it to the AVB endpoint board.
4. In xTIMEcomposer, right-click on the binary within the app_avb_lc_demo/bin folder of the project.
5. Choose Flash As > Flash Configurations.
6. Double click xCORE Application in the left panel.
7. Choose hardware in Device options and select the relevant xTAG-2 adapter.
8. Click on Apply if configuration has changed.
9. Click on Flash. Once completed, reset the AVB endpoint board using the reset button.
10. Repeat steps 1 through 8 for the second endpoint.

Refer to the above figure for board controls and connectors.

1. Connect the two development boards into an AVB capable Ethernet switch via the provided Ethernet cables
2. Set the audio input connection jumpers for either RCA input or 3.5 mm jack input.
3. On the first development board, connect the output of a line-level audio source to the audio input connector.
4. On the second development board, connect an audio playback device to the audio output connector.
5. If not already powered, connect the power supplies to the input power jacks of the boards and power them on.
6. A third party 1722.1 Controller application can then be used to connect and disconnect streams between the endpoints.

   See https://github.com/audioscience/avdecc-lib
   for an example command line 1722.1 controller application and library.

Note: The audio output from the board is line level. If using headphones, an external headphone amplifier may be required.

Access more support collatoral from xmos.com Support Reference designs AVB audio endpoint.

Including

• AVB Endpoint Design Guide
• Design files for XR-AVB-LC-BRD board

The XMOS Audio Video Bridging (AVB) endpoint is a reference design that provides time-synchronized, low latency streaming services through IEEE 802 networks. The solution is firmware that is implemented on the XMOS xCORE architecture and can be deployed on a number of different xCORE parts depending on system requirements such as stream and channel count.

XMOS AVB-LC Key Features

802.1AS defines a Precision 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 to phase align audio clocks.

The IEEE 802.1AS-2011 standard document
is available to download free of charge via the IEEE Get Program.

802.1Qav defines a standard for buffering and forwarding of traffic through the network using particular flow control algorithms. It gives predictable latency control on media streams flowing 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.

The 802.1Qav specification is available as a section in the IEEE 802.1Q-2011 standard document
and is available to download free of charge via the IEEE Get Program.

802.1Qat defines a stream reservation protocol that provides end-to-end reservation of bandwidth across an AVB network.

The 802.1Qat specification is available as a section in the IEEE 802.1Q-2011 standard document
.

IEC 61883-6 defines an audio data format that is contained in IEEE 1722 streams. The XMOS AVB solution uses IEC 61883-6 to convey audio sample streams.

The IEC 61883-6:2005 standard document
is available for purchase from the IEC website.

IEEE 1722 defines an encapsulation protocol to transport audio streams over Ethernet. 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 1722. In addition it can use the 802.1AS timestamps to accurately recover the audio master clock from an input stream.

The IEEE 1722-2011 standard document
is available for purchase from the IEEE website.

IEEE 1722.1 is a system control protocol, used for device discovery, connection management and enumeration and control of parameters exposed by the AVB endpoints.

The IEEE 1722.1-2013 standard document
is available for purchase from the IEEE website.

An endpoint consists of five main interacting components:

• The Ethernet MAC
• The Precision Timing Protocol (PTP) engine
• Audio streaming components
• The media clock server
• Configuration and other application components

The following diagram shows the overall structure of an XMOS AVB endpoint.

The MAC component provides Ethernet connectivity to the AVB
solution. To use the component, a Ethernet PHY must be attached
to the XCore ports via MII. The XS1
device is also capable of implementing a dual 100 Mbps interface – see the AVB Daisy Chain product for reference.

The XMOS Ethernet 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).
• Time sensitive traffic shaping – allows traffic bandwidth to be reserved and shaped on egress to provide a steady and guaranteed 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 Mbps component consists of five logcial cores, each
running at 50 MIPS or more, that must be run on the same tile. These logcial cores handle both the receipt and transmission of
Ethernet frames. The MAC component can be linked via channels to other components/logcial cores in the system. Each link can set a filter to
control which packets are conveyed to it via that channel.

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 documentation
. 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
AVB API
).

1722 packet routing

The Precision Timing Protocol (PTP) component enables a system with a
notion of global time on a network. The component implements the IEEE
802.1AS protocol. It allows synchronization of the
presentation and playback rate of media streams across a network.

The timing component consists of two logcial cores. It connects to the Ethernet MAC 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 potential PTP grandmaster or a PTP slave only. If the component is configured as a grandmaster, it supplies a clock source to the network. If the network has several grandmasters, the potential grandmasters 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 tasks 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 tasks can communicate with the server using the API described
in Section PTP client API
.

• 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 audio word clock, although it can be used to derive it. 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.

AVB streams, channels, talkers and listeners

Internal routing, media FIFOs

As described in the previous section, an IEEE 1722 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:

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 AVB API
.

Media FIFOs use shared memory to move data between tasks, thus the
filling and emptying of the FIFO must be on the same tile.

Talker units

A talker unit consists of one logcial core which creates IEEE 1722 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 task implementing the audio hardware interface. The Talker task removes the samples and combines them into IEEE 1722 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 the same tile as the talker. The instantiating of
talker units is performed via the API described in Section
Component tasks and functions
. Once the talker unit starts, it registers
with the main control task and is controlled via the main AVB API
described in Section AVB API
.

Listener units

A Listener unit takes IEEE 1722 packets from the MAC
and converts them into a sample stream to be fed into a media FIFO.
Each audio Listener component can listen to several IEEE 1722
streams.

A system may have several Listener units. The instantiating of
Listener units is performed via the API described in Section
Component tasks and functions
. Once the Listener unit starts, it registers
with the main control task and is controlled via the main AVB API
described in Section AVB API
.

Media FIFOs to XC channels

Audio hardware interfaces

A media clock controls the rate at which information is passed to an
external media playing device. For example, an audio word 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 two sources:

• An incoming clock signal on a port.
• The word clock of a remote endpoint, derived from an incoming IEEE 1722 audio stream.

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 component 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 1722 streams. It then sends control information back to
ensure the listening component honors the presentation time of the
incoming stream.

Multiple media clocks require multiple hardware PLLs. AVB-LC hardware supports a single media clock.

Driving an external clock generator

The control task

1722.1

AVB Endpoint Design Guide Read More »

The print library provides support for formatted output.

• int printchar(char value)

  Prints a character.

  Parameters

  • value

    The character to print.

  Returns

  The number of characters printed, or -1 on error.

• int printcharln(char value)

  Prints a character followed by a new line.

  Parameters

  • value

    The character to print.

  Returns

  The number of characters printed, or -1 on error.

• int printint(int value)

  Prints a value as a signed decimal.

  Parameters

  • value

    The value to print.

  Returns

  The number of characters printed, or -1 on error.

• int printintln(int value)

  Prints a value as a signed decimal followed by a newline.

  Parameters

  • value

    The value to print.

  Returns

  The number of characters printed, or -1 on error.

• int printuint(unsigned value)

  Prints a value as a unsigned decimal.

  Parameters

  • value

    The value to print.

  Returns

  The number of characters printed, or -1 on error.

• int printuintln(unsigned value)

  Prints a value as a unsigned decimal followed by a newline.

  Parameters

  • value

    The value to print.

  Returns

  The number of characters printed, or -1 on error.

• int printllong(long long value)

  Prints a long long value as a signed decimal.

  Parameters

  • value

    The value to print.

  Returns

  The number of characters printed, or -1 on error.

• int printllongln(long long value)

  Prints a long long value as a signed decimal followed by a newline.

  Parameters

  • value

    The value to print.

  Returns

  The number of characters printed, or -1 on error.

• int printullong(unsigned long long value)

  Prints a long long value as a unsigned decimal.

  Parameters

  • value

    The value to print.

  Returns

  The number of characters printed, or -1 on error.

• int printullongln(unsigned long long value)

  Prints a long long value as a unsigned decimal followed by a newline.

  Parameters

  • value

    The value to print.

  Returns

  The number of characters printed, or -1 on error.

• int printhex(unsigned value)

  Prints a value as a unsigned hexadecimal.

  The upper-case letters are used for the conversion.

  Parameters

  • value

    The value to print.

  Returns

  The number of characters printed, or -1 on error.

• int printhexln(unsigned value)

  Prints a value as a unsigned hexadecimal followed by a newline.

  The upper-case letters are used for the conversion.

  Parameters

  • value

    The value to print.

  Returns

  The number of characters printed, or -1 on error.

• int printllonghex(unsigned long long value)

  Prints a long long value as a unsigned hexadecimal.

  The upper-case letters are used for the conversion.

  Parameters

  • value

    The value to print.

  Returns

  The number of characters printed, or -1 on error.

• int printllonghexln(unsigned long long value)

  Prints a long long value as a unsigned hexadecimal followed by a newline.

  The upper-case letters are used for the conversion.

  Parameters

  • value

    The value to print.

  Returns

  The number of characters printed, or -1 on error.

• int printstr(const char s[])

  Prints a null terminated string.

  Parameters

  • s

    The string to print.

  Returns

  The number of characters printed, or -1 on error.

• int printstrln(const char s[])

  Prints a null terminated string followed by a newline.

  Parameters

  • s

    The string to print.

  Returns

  The number of characters printed, or -1 on error.

The safestring library provides safe versions of the string functions found in string.h of the C standard library. All functions are callable from XC. When called from XC any attempt to perform an out of bounds array access will cause an exception to be raised.

• void safestrcpy(char s1[], const char s2[])

  Copies a string (including the terminating null character) to an array.

  Parameters

  • s1

    The array to copy to.

  • s2

    The string to copy.

• void safestrncpy(char s1[], const char s2[], unsigned n)

  Copies no more than n characters of the string s1 to the array s2.

  If the length of s2 is less than n then null characters will be appended to the copied characters until n bytes are written.

  Parameters

  • s1

    The array to copy to.

  • s2

    The string to copy.

  • n

    The number of characters to copy.

• void safestrcat(char s1[], const char s2[])

  Appends a copy of a string (including the terminating null character) to the end of another string.

  Parameters

  • s1

    The string to append to.

  • s2

    The string to append.

• void safestrncat(char s1[], const char s2[], unsigned n)

  Appends no more than n characters of the string s2 to the string s1.

  The null characters at the end of s1 is overwritten by the first character of s2. A terminating null character is always appended to the result.

  Parameters

  • s1

    The string to append to.

  • s2

    The string to append.

  • n

    The number of characters to append.

• int safestrcmp(const char s1[], const char s2[])

  Compares two strings.

  If the strings are equal 0 is returned. If the strings are not equal a non-zero value is returned, the sign of which is determined by the sign of the difference between the first pair of characters which differ in the strings being compared.

  Parameters

  • s1

    The first string to compare.

  • s2

    The second string to compare.

  Returns

  A integer greater than, equal to, or less than 0, if s1 is respectively greater than, equal to, or less than s2.

• int safestrncmp(const char s1[], const char s2[], unsigned n)

  Compares up to the first n character of two strings.

  If the strings are equal up to the first n characters, 0 is returned. Otherwise a non-zero value is returned, the sign of which is determined by the sign of the difference between the first pair of characters which differ.

  Parameters

  • s1

    The first string to compare.

  • s2

    The second string to compare.

  • n

    The maximum number of characters to compare.

  Returns

  A integer greater than, equal to, or less than 0, if s1 is respectively greater than, equal to, or less than s2.

• int safestrlen(const char s[])

  Returns the length of a string.

  The length is given by the number of characters in the string not including the terminating null character.

  Parameters

  • s

    The string.

  Returns

  The length of the string.

• int safestrchr(const char s[], int c)

  Returns the index of the first occurrence of c (converted to a char) in s.

  If c does not occur in s, -1 is returned. The terminating null character is considered to be part of s.

  Parameters

  • s

    The string to scan.

  • c

    The character to scan for.

  Returns

  The index of c.

• int safestrrchr(const char s[], int c)

  Returns the index of the last occurrence of c (converted to a char) in s, or -1 if c does not occur in s.

  The terminating null character is considered to be part of s.

  Parameters

  • s

    The string to scan.

  • c

    The character to scan for.

  Returns

  The index of c.

• unsigned safestrspn(const char s1[], const char s2[])

  Returns the length of the longest initial segment of s1 which consists entirely of characters from s2.

  Parameters

  • s1

    The string to scan.

  • s2

    The string containing characters to scan for.

  Returns

  The length of the initial segment.

• unsigned safestrcspn(const char s1[], const char s2[])

  Returns the length of the longest initial segment of s1 which consists entirely of characters not from s2.

  Parameters

  • s1

    The string to scan.

  • s2

    The string containing characters to scan for.

  Returns

  The length of the initial segment.

• int safestrpbrk(const char s1[], const char s2[])

  Returns the index of the first occurrence in s1 of any character in s2.

  If no character in s2 occurs in s1, -1 is returned.

  Parameters

  • s1

    The string to scan.

  • s2

    The string containing characters to scan for.

  Returns

  The index of first matching character.

• int safestrstr(const char s1[], const char s2[])

  Returns the index of the first occurrence of s1 as a sequence of characters (excluding the terminating null character) in s2.

  If s1 is not contained in s2, -1 is returned. If s2 is a zero length string then 0 is returned.

  Parameters

  • s1

    The string to scan.

  • s2

    The string to scan for.

  Returns

  The index of first matching subsequence.

• void safememcpy(unsigned char dst[], const unsigned char src[], unsigned length)

  Copies length bytes from the array src to the array dst.

  Parameters

  • dst

    The destination array.

  • src

    The source array.

  • length

    The number of bytes to copy.

• void safememmove(unsigned char data[], unsigned dst, unsigned src, unsigned length)

  Copies length bytes from offset src of array data to offset dst of array data.

  If the source and destination areas overlap then copying takes place as if the bytes are first copied from the source into a temporary array and then copied to the destination.

  Parameters

  • data

    The array to move data in.

  • dst

    The offset of the destination area.

  • src

    The offset of the source area.

  • length

    The number of bytes to copy.

• void safememset(unsigned char dst[], int value, unsigned length)

  Copies value (converted to an unsigned char) to each of the first length bytes of the array dst.

  Parameters

  • dst

    The destination array.

  • value

    The value to copy.

  • length

    The number of bytes to copy.

• int safememcmp(const unsigned char s1[], const unsigned char s2[], unsigned length)

  Compares the first length bytes of the arrays s1 and s2.

  If there is no difference 0 is returned, otherwise a non-zero value is returned, the sign of which is determined by the sign of the difference between the first pair of bytes which differ.

  Parameters

  • s1

    The first array.

  • s2

    The second array.

  • length

    The number of bytes to compare.

  Returns

  A integer greater than, equal to, or less than 0, if the first length bytes of s1 are respectively greater than, equal to, or less than the first length bytes of s2.

• int safememchr(const unsigned char s[], int c, unsigned length)

  Returns the index of the first occurrence of c (converted to an unsigned char) in the first length bytes of s.

  If c does not occur in s, -1 is returned.

  Parameters

  • s

    The array to scan.

  • c

    The character to scan for.

  • length

    The number of bytes to scan.

  Returns

  The index of c.

The xccommpat header file provides type definitions that simplify the task of writing functions that may be called from both C/C++ and XC.

• chanend

  chanend typedef for use in C/C++ code.

  This typedef is only supplied if xccompat.h is included from C/C++ code. This enables a XC function prototyped as taking a parameter of type chanend to be called from C and vice versa.

• timer

  timer typedef for use in C/C++ code.

  This typedef is only supplied if xccompat.h is included from C/C++ code. This enables a XC function prototyped as taking a parameter of type timer to be called from C and vice versa.

• port

  port typedef for use in C/C++ code.

  This typedef is only supplied if xccompat.h is included from C/C++ code. This enables a XC function prototyped as taking a parameter of type port to be called from C and vice versa.

The XN file format lets you optionally specify the network configuration to use
with the target device. If the target device has a network topology that can’t
be automatically routed by the xTIMEcomposer tools you must specify the network
configuration in the XN file. You can add the network configuration as follows:

1. Add the RoutingId attribute to each Node element:

   <Node Id="0" InPackageId="0" Type="XS1-L8A-64" SystemFrequency="500MHz" RoutingId="1">
   

2. Add a RoutingTable element to each Node element:

   <RoutingTable>
     <Bits>
       <Bit number="0" direction="1"/>
     </Bits>
     <Links>
       <Link name="XLB" direction="1"/>
     </Links>
   </RoutingTable>
   

The tools use this information to generate code that sets up the following
control registers before your application runs:

• Switch node identifier
• Direction registers
• Link direction field of the link status, direction, and network control register

See xCONNECT Architecture
for a description of the xCONNECT
interconnect.

When an XN file containing a network configuration is passed to the
xTIMEcomposer tools, they check the network configuration is fully
routable, i.e. they check it is possible to route a packet between every pair of
nodes on the network. Routing problems are reported as errors.

If no network configuration is present in the XN file the xTIMEcomposer tools
automatically choose a suitable set routing IDs and routing tables based on the
network topology. To inspect this network configuration you can use the command
line utility xntools to write it to the XN file.

1. Start the command-line tools
2. Run the following command:

   xntools –add-routing target.xn

See Example XN with custom routing information.
for an example XN file for
a network of two XS1-L8-64 devices.

<?xml version="1.0" encoding="UTF-8"?>
<Network xmlns="http://1m2n3b4v.xmos.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://1m2n3b4v.xmos.com">
  <Declarations>
    <Declaration>tileref tile[2]</Declaration>
  </Declarations>
  <Packages>
    <Package id="0" Type="XS1-LnA-64-TQ128">
      <Nodes>
        <Node Id="0" InPackageId="0" Type="XS1-L8A-64" SystemFrequency="500MHz" RoutingId="1">
          <Tile Number="0" Reference="tile[0]"/>
          <RoutingTable>
            <Bits>
              <Bit number="0" direction="1"/>
            </Bits>
            <Links>
              <Link name="XLB" direction="1"/>
            </Links>
          </RoutingTable>
        </Node>
      </Nodes>
    </Package>
    <Package id="1" Type="XS1-LnA-64-TQ128">
      <Nodes>
        <Node Id="1" InPackageId="0" Type="XS1-L8A-64" SystemFrequency="500MHz" RoutingId="0">
          <Tile Number="0" Reference="tile[1]"/>
          <RoutingTable>
            <Bits>
              <Bit number="0" direction="0"/>
            </Bits>
            <Links>
              <Link name="XLB" direction="0"/>
            </Links>
          </RoutingTable>
        </Node>
      </Nodes>
    </Package>
  </Packages>
  <Links>
    <Link Encoding="5wire" Delays="0,1">
      <LinkEndpoint NodeId="0" Link="XLB"/>
      <LinkEndpoint NodeId="1" Link="XLB"/>
    </Link>
  </Links>
  <JTAGChain>
    <JTAGDevice NodeId="0"/>
    <JTAGDevice NodeId="1"/>
  </JTAGChain>
</Network>

The user must load a compiled binary into the XTA, then define the timing-critical sections of code within the application and specify the timing constraints for each section of code. The tool supports timing functions, timing loops and the execution between two endpoints. The tool verifies that all possible paths of execution meet the specified timing constraints. If all paths meet their timing requirements then the minimum xCORE tile frequency the xCORE device can be run at to meet timing requirements is also output.

The tool can be used interactively on the command-line or through a graphical user interface (GUI) in xTIMEcomposer Studio.

When working within xTIMEcomposer Studio, loading a binary into the XTA is done by creating a new Time configuration. These work in the same way as the Run and Debug configurations. Once the configuration exists, the binary can be loaded into the XTA using the Time button in the toolbar. To load a binary that does not have an associated xTIMEcomposer project, see Files View .

To load a binary from the console, type:

load <FILE NAME>

A route is a timing-critical section of code. It consists of the set of all paths through which control can flow between two points in a program (endpoints). A route can be created by timing a function, timing a loop or by timing between endpoints.

An endpoint is any source line that, during the compilation process, must be preserved, and its order with respect to other endpoints must be maintained. In the GUI the locations of valid endpoints are marked in the editor.

To show a list of all endpoints type the following command on the console:

list allendpoints

If specifying a route with respect to assembly code then any valid label/program counter (PC) can be used as an endpoint. However, program counters are classed as non-portable endpoints as they are likely to change between compilations and their use in scripts is therefore discouraged.

Source lines can be labeled with endpoint pragmas in order to ensure that the endpoints are portable. For example, Putting an endpoint pragma into XC. shows a function that has been annotated with endpoint pragmas called start and stop.

int g(in port p) {
    int x, y;

    # pragma xta endpoint " start "
    p :> x;

    # pragma xta endpoint " stop "
    p :> y;

    return (y - x);
}

The endpoints defined in source are listed in the Info View.

On the console, type:

list endpoints

In xTIMEcomposer Studio set the from and to endpoint and then click the Analyze endpoints button. Endpoints are set by right-clicking on the marker showing where valid endpoints are in the source.

On the console, type:

analyze endpoints <from ENDPOINT> <to ENDPOINT>

The tool does not time code across multiple xCORE tiles so both endpoints must be on the same tile.

One analysis can result in multiple routes being generated (see Multiple Route Creation for further details).

In xTIMEcomposer Studio select the function name from the list of available functions using the Analyze function button.

On the console, type:

analyze function <FUNCTION>

This will create a route which describes the set of all possible paths from the function entry point to all the function return points.

In xTIMEcomposer Studio set the looppoint and then click the Analyze loop button. Looppoints are set by right-clicking in the margin and selecting the Set loop point option.

On the console, type:

analyze loop <ANY>

This creates a route that describes all possible paths through the loop. It it effectively a shortcut for timing between endpoints where the start and stop endpoint is the same, the point is within a loop and an exclusion has been placed such that everything outside the loop is excluded.

One analysis can result in multiple routes being generated (see Multiple Route Creation for further details).

For each route created it is necessary to define its timing requirements. In xTIMEcomposer Studio right-click on the route in the upper panel of the Routes View and select Set timing requirements in the context menu.

On the console, type:

set required <route id> <value> <MODE>

The supported timing modes are defined in Timing Modes .

The route IDs can be found in the console by typing:

print summary

Alternatively, the - character can be used on the command-line or in a script to refer to the last route analyzed.

All analyzed routes are given a unique route ID. However, when referring to routes in a script, using the route ID may not always result in portable or robust scripts. In many cases, the only route that needs to be referenced is the one that was last analyzed. This can be achieved by using the ‘-‘ character as the route ID. If the last command created multiple routes then the ‘-‘ character refers to all of the routes created.

Within a single route, all nodes are assigned a unique ID number. This is required as input for some of the console commands. The ‘-‘ character can be used in this context to refer to the top level node of the route.

In the GUI all routes created are shown in the upper pane of the Routes View in the xTIMEcomposer. More detailed information on each route can be found by hovering over the route in this list.

On the console, type:

print summary

Details for a specific route are shown using the command:

print routeinfo <route id>

Violation

Slack

The structure of a route can be examined in xTIMEcomposer Studio in two ways. The lower pane of the Routes View shows the structure of the selected route as a tree and the Structure Panel of the Visualizations View renders it graphically.

In the console, to display the the structure of a route type:

print structure <route id>

The structure used by the tool is described in Structural Nodes .

In xTIMEcomposer Studio the editors highlight code which is executed by the section of a route that has been selected. The selection is done using the lower pane of the Routes View.

In the console, to display the source code which is executed by a route type:

		
  XMOS Timing Analyzer Manual Read More »
		

					

	

The format of the routing id’s and routing tables has changed. The flash loader
is written to flash at the time as the factory image and it is the flash loader
that is responsible for setting up the network. All upgrade images must
therefore use the same routing id’s and routing tables that were specified by the
factory image.

The image header used to identify images within flash has changed. It is
therefore not possible for a flash loader built by xTIMEcomposer 12 to
identify an xTIMEcomposer 13 upgrade image header in flash. When creating an upgrade
image using the xTIMEcomposer 13 tools you must specify the the version of tools
used to create the factory image that will be upgraded.

No overlay memory regions can be supported within the xTIMEcomposer
12 compatible upgrade images.

Firstly, the old routing id’s and routing tables must be defined within
the XN file. To do this, use the following command to populate your XN file
with xTIMEcomposer version 12 compatible routing id’s and routing tables:

xntools --add-routing-12 myfile.xn

The output file myfile.xn will now contain the routing id’s and routing tables as
xTIMEcomposer 12 would have defined. This XN file can now be compiled
within an xTIMEcomposer 13 project.

Secondly, the command line argument --factory-version must be included in the
call to xFLASH to generate the xTIMEcomposer 12 compatible upgrade image.

xflash --upgrade 1 upgrade.xe --factory-version 12 -o upgrade.bin

This upgrade.bin image can then be successfully used to upgrade an xTIMEcomposer 12 factory image.