XN Specification

Network Elements

The network definition is specified as follows:

<?xml version="1.0" encoding="UTF-8"?>
<Network xmlns="http://www.xmos.com"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.xmos.com http://www.xmos.com">

The XN hierarchy of elements is given below:

Node                                   Number       Description
Network                                1            An xCORE network
├── Declarations                       0+
│   └── Declaration                    1+           xCORE Tile declaration
├── Packages                           1+
│   └── Package                        1+           Device package
│       ├── Nodes                      1
│       │   └── Node                   1+           Node declaration
│       │       ├── Tile               1+           An xCORE Tile
│       │       │   └── Port           0+           An xCORE symbolic port name
│       │       ├── Boot               0 or 1       Boot method
│       │       │   ├── Source         1            Binary location
│       │       │   └── Bootee         0+           Nodes booted
│       │       ├── RoutingTable       0 or 1
│       │       │   ├── Bits           1
│       │       │   │   └── Bit        1+           Direction for bit
│       │       │   └── Links          1
│       │       │       └── Link       1+           Direction for link
│       │       └── Service            0+           Service declaration
│       │           └── Chanend        1+           Chanend parameter
│       └── Links                      0 or 1
│           ├── Link                   1+           xCONNECT Link declaration
│           └── LinkEndpoint           2            xCONNECT Link endpoint
├── ExternalDevices                    0 or 1
│   └── Device                         1+           External device
│       └── Attribute                  0+           A device attribute
└── JTAGChain                          0 or 1
    └── JTAGDevice                     1+           A device in the JTAG chain

Declaration

A Declaration element provides a symbolic name for one or more xCORE Tiles. A single name or an array of names is supported with the form:

tileref identifier

tileref identifier [ constant-expression ]

An equivalent declaration is exported to the header file <platform.h> for use in XC programs. A tileref declaration is associated with physical xCORE tiles by the reference attribute of a ~~Tile~~ element.

Example

<Declaration>tileref master</Declaration>
<Declaration>tileref tile[8]</Declaration>

Package

A Package element refers to a package file that describes the mapping from xCORE ports and links to the pins on the package.

XN Package element

Attribute

Required

Type

Description

Id

Yes

String

A name for the package. All package names in the network must be unique.

Type

Yes

String

The name of the XML package. The tools search for the file <type>.pkg in the path specified by XCC_DEVICE_PATH.

Example

<Package id="L2" Type="XS1-L2A-QF124">

The package named L2 is described in the file XS1-L2A-QF124.xml.

Node

A Node element defines a set of xCORE Tiles in a network, all of which are connected to a single switch. XMOS devices such as the G4 or L1 are both examples of nodes.

XN Node element

Attribute

Required

Type

Description

Id

No

String

A name for the node. All node names in the network must be unique.

Type

Yes

String

If type is periph:XS1-SU the node is a XS1-SU peripheral node. Otherwise the type specifies the name of an XML file that describes the node. The tools search for the file config_<type>.xml in the path specified by XCC_DEVICE_PATH.

Reference

Yes

String

Associates the node with a xCORE Tile indentifer specified in a Declaration. This attribute is only valid on nodes with type periph:XS1-SU.

RoutingId

No

Integer

The routing identifier on the xCONNECT Link network.

InPackageId

Yes

String

Maps the node to an element in the package file.

Oscillator

No

String

The PLL oscillator input frequency, specified as a number followed by either MHz, KHz or Hz.

OscillatorSrc

No

String

The name of the node which supplies the PLL oscillator input.

SystemFrequency

No

String

The system frequency, specified as a number followed by either MHz, KHz or Hz. Defaults to 400MHz if not set.

PllFeedbackDivMin

No

Integer

The minimum allowable PLL feedback divider. Defaults to 1 if not set.

ReferenceFrequency

No

String

A reference clock frequency, specified as a number followed by either MHz, KHz or Hz. Defaults to 100MHz if not set.

PllDividerStageOneReg

No

Integer

The PLL divider stage 1 register value.

PllMultiplierStageReg

No

Integer

The PLL multiplier stage register value.

PllDividerStageTwoReg

No

Integer

The PLL divider stage 2 register value.

RefDiv

No

Integer

SystemFrequency / RefDiv = ReferenceFrequency

The PLL registers can be configured automatically using the attributes SystemFrequency, PllFeedbackDivMin and ReferenceFrequency, or can be configured manually using the attributes PllDividerStageOneReg, PllMultiplierStageReg, PllDividerStageTwoReg and RefDiv. If any of the first three attributes are provided, none of the last four attributes may be provided, and vice versa.

The PLL oscillator input frequency may be specifed using the Oscillator or OscillatorSrc attribute. If the Oscillator attribute is provided the OscillatorSrc attribute must not be provided, and vice versa.

If manual configuration is used, the attributes PllDividerStageOneReg, PllMultiplierStageReg, PllDividerStageTwoReg and RefDiv must be provided and the PLL oscillator input frequency must be specifed. The tools use these values to set the PLL registers and reference clock divider. Information on the PLL dividers can be found in xCORE frequency control documents XS1 L Clock Frequency Control.

If the oscillator frequency is specifed and none of the manual PLL attributes are provided, automatic configuration is used. The tools attempt to program the PLL registers such that the target system frequency is achieved, the PLL feedback divider is greater than or equal to the minimum value and the target reference clock frequency is achieved. If any of these constraints cannot be met, the tools issue a warning and report the actual values used.

If the oscillator frequency is not specified, the tools do not attempt to configure the PLL. The PLL registers remain at their initial values as determined by the mode pins.

A network may contain either XS1-L devices or XS1-G devices, but not both.

Example

<Node Id="MyL1" Type="XS1-L1A" Oscillator="20Mhz"
      SystemFrequency="410MHz" ReferenceFrequency="98.5Mhz">

The node named MyL1 is an L1 device, as described in the file config_XS1-L1A.xml.

Tile

A Tile element describes the properties of a single xCORE Tile.

XN Tileref element

Attribute

Required

Type

Description

Number

Yes

Integer

The unique number for the tile in the node. A value between 0 and n-1 where n is the number of tiles as defined in the node’s XML file.

Reference

No

String

Associates the tile with an identifier with the form tile[n] in a Declaration. A tile may be associated with at most one identifier.

Example

<Tile Number="0" Reference="tile[0]">

Port

A Port element provides a symbolic name for a port.

XN Port element

Attribute

Required

Type

Description

Location

Yes

String

A port identifier defined in the standard header file <xs1.h>. The ports are described in the XC Programming Guide <https://www.xmos.ai/developer/doc/XM-000223-UG>.

Name

Yes

String

A valid C preprocessor identifier. All port names declared in the network must be unique.

Example

<Port Location="XS1_PORT_1I" Name="PORT_UART_TX"/>
<Port Location="XS1_PORT_1J" Name="PORT_UART_RX"/>

Boot

A Boot element defines the how the node is booted. It contains one ~~Source~~ element and zero or more ~~Bootee~~ elements that are booted over xCONNECT Links. If the source specifies an xCONNECT Link, no Bootee elements may be specified. In a line of XS1-L devices, bootees must be contiguous to the device booting from SPI.

Tip

The XMOS tools require a Boot element to be able to boot programs from flash memory.

Source

A Source element specifies the location from which the node boots. It has the following attributes.

XN Source element

Attribute

Required

Type

Description

Location

Yes

String

Has the form SPI: or LINK. The device-name must be declared in the set of Device elements.

Important

Only XMOS XS1-L devices can be configured to boot over xCONNECT Links.

Example

<Source Location="SPI:bootFlash"/>

Bootee

A Bootee element specifies another node in the system that this node boots via an xCONNECT Link. If more than one xCONNECT Link is configured between this node and one of its bootees (see Link and LinkEndpoint), the tools pick one to use for booting.

XN Bootee element

Attribute

Required

Type

Description

NodeId

Yes

String

A valid identifier for another node.

Example

<Bootee NodeId="Slave">

Bit

A Bit element specifies the direction for messages whose first mismatching bit matches the specified bit number.

XN Bit element

Attribute

Required

Type

Description

number

Yes

Integer

The bit number, numbered from the least significant bit.

direction

Yes

Integer

The direction to route messages.

Example

<Bit number="1" direction="0"/>

Service

A Service element specifies an XC service function provided by a node.

XN Service element

Attribute

Required

Type

Description

Proto

Yes

String

The prototype for the service function, excluding the service keyword. This prototype is exported to the header file <platform.h> for use in XC programs.

Example

<Service Proto="service_function(chanend c1, chanend c2)">

Chanend

A Chanend element describes a channel end parameter to an XC service function.

XN Service element

Attribute

Required

Type

Description

Indentifier

Yes

String

The identifier for the chanend argument in the service function prototype.

end

Yes

Integer

The number of the channel end on the current node.

remote

Yes

Integer

The number of the remote channel end that is connected to the channel end on the current node.

Example

<Chanend Identifier="c" end="23" remote="5"/>

Device

A Device element describes a device attached to an xCORE Tile that is not connected directly to an xCONNECT Link.

XN Device element

Attribute

Required

Type

Description

Name

Yes

String

An identifier that names the device.

NodeId

Yes

String

The identifier for the node that the device is connected to.

Tile

Yes

Integer

The tile in the node that the device is connected to.

Class

Yes

String

The class of the device.

Type

No

String

The type of the device (class dependent).

The following attribute values for the attribute name are recognised: Class:

SPIFlash

Device is SPI flash memory

SQIFlash

Device is QuadSPI flash memory

FastSQI

Device is QuadSPI flash memory and is using fast boot driver

ARMBridge

Device is ARM flash memory

Use the Type attribute to identify the model of the flash device.

Attribute

An Attribute element describes one aspect of a ~~Device~~.

XN Attribute element

Attribute

Required

Type

Description

Name

Yes

String

Specifies an attribute of the device.

Value

Yes

String

Specifies a value associated with the attribute.

The following attribute names for the device are supported: class SPIFlash:

PORT_SPI_MISO

SPI Master In Slave Out signal.

PORT_SPI_SS

SPI Slave Select signal.

PORT_SPI_CLK

SPI Clock signal.

PORT_SPI_MOSI

SPI Master Out Slave In signal.

Example

<Attribute Name="PORT_SPI_MISO" Value="PORT_SPI_MISO"/>

The following attribute names for the device are supported: class SQIFlash:

PORT_SQI_CS

QuadSPI Chip Select signal.

PORT_SQI_SCLK

QuadSPI Clock signal.

PORT_SQI_SIO

QuadSPI In/Out signal.

Example

<Attribute Name="PORT_SQI_SIO" Value="PORT_SQI_SIO"/>

JTAGChain

The JTAGChain element describes a device in the JTAG chain. The order of these elements defines their order in the JTAG chain.

XN JTAGChain element

Attribute

Required

Type

Description

JTAGSpeed

No

String

Sets the JTAG clock speed.

JTAGDevice

XN JTAGDevice element

Attribute

Required

Type

Description

NodeID

Yes

String

A valid node identifier.

Example

<!-- N1 comes before N2 in the JTAG chain -->
<JTAGDevice NodeId="N1">
<JTAGDevice NodeId="N2">