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.
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 |
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.
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 |
Reference |
Yes |
String |
Associates the node with a xCORE Tile indentifer specified in a
|
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 |
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 |
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
|
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 |
|
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.
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 |
Example
<Tile Number="0" Reference="tile[0]">
Port¶
A Port
element provides a symbolic name for a port.
Attribute |
Required |
Type |
Description |
---|---|---|---|
Location |
Yes |
String |
A port identifier defined in the standard header file |
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.
Attribute |
Required |
Type |
Description |
---|---|---|---|
Location |
Yes |
String |
Has the form |
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.
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.
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"/>
Link¶
When it appears within a RoutingTable
element, a Link
element specifies
the direction of an xCONNECT Link.
Attribute |
Required |
Type |
Description |
---|---|---|---|
name |
Yes |
String |
A link identifier in the form X<n>L<m> where <n> denotes a tile number and <m> the link letter. See the corresponding package datasheet for available link pinouts. |
direction |
Yes |
Integer |
The direction of the link. |
Example
<Link number="XLA" direction="2"/>
Service¶
A Service
element specifies an XC service function provided by a node.
Attribute |
Required |
Type |
Description |
---|---|---|---|
Proto |
Yes |
String |
The prototype for the service function, excluding the |
Example
<Service Proto="service_function(chanend c1, chanend c2)">
Chanend¶
A Chanend
element describes a channel end parameter to an XC service
function.
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"/>
Link¶
xCONNECT Links are described in the system specification documents (XS1 L System Specification) and link performance documents (XS1 L Link Performance/Design Guidelines).
A Link element describes the characteristics of an xCONNECT Link. It must contain exactly two ~~LinkEndpoint~~ children.
Attribute |
Required |
Type |
Description |
---|---|---|---|
Encoding |
Yes |
String |
Must be either |
Delays |
Yes |
String |
Of the form |
Flags |
No |
String |
Specifies additional properties of the link. Use the value |
Example
<Link Encoding="2wire" Delays="4,4">
LinkEndpoint¶
A LinkEndpoint
describes one end of an xCONNECT Link, the details of
which can be found in the system specification documents (XS1 L System Specification .
Each endpoint associates a node identifier to a physical xCONNECT Link.
Attribute |
Required |
Type |
Description |
---|---|---|---|
NodeID |
No |
String |
A valid node identifier. |
Link |
No |
String |
A link identifier in the form |
RoutingId |
No |
Integer |
The routing identifier on the xCONNECT Link network. |
Chanend |
No |
Integer |
A channel end. |
BootRomEnabled |
No |
Integer |
Link is enabled at boot and can therefore be considered for use within the spanning network. |
An endpoint is usually described as a combination of a node identifier and link identifier. For a streaming debug link, one of the endpoints must be described as a combination of a routing identifier and a channel end. For example:
<LinkEndpoint NodeId="0" Link="X0LD"/>
<LinkEndpoint RoutingId="0x8000" Chanend="1">
The table below highlights the correct link name to use for the Link
attribute within the LinkEndpoint
element.
xConnect link Number |
xCORE “L” series link name |
xCORE-200 link name |
0 |
XLC |
XL0 |
1 |
XLD |
XL1 |
2 |
XLA |
XL2 |
3 |
XLB |
XL3 |
4 |
XLG |
XL4 |
5 |
XLH |
XL5 |
6 |
XLE |
XL6 |
7 |
XLF |
XL7 |
8 |
N/A |
XL8 |
An xCORE “L” series link name cannot be used within an xCORE-200 XN specification.
An xCORE-200 link name cannot be used within an xCORE “L” series XN specification.
The following example demonstrates how Node 0 Link number 4 is connected to Node 1 Link number 7 in an xCORE “L” series XN specification:
<Links>
<Link Encoding="5wire" Delays="0,1">
<LinkEndpoint NodeId="0" Link="XLG"/>
<LinkEndpoint NodeId="1" Link="XLF"/>
</Link>
</Links>
The following example demonstrates how Node 0 Link number 4 is connected to Node 1 Link number 7 in an xCORE-200 series XN specification:
<Links>
<Link Encoding="5wire" Delays="4,4">
<LinkEndpoint NodeId="0" Link="XL4"/>
<LinkEndpoint NodeId="1" Link="XL7"/>
</Link>
</Links>
Device¶
A Device
element describes a device attached to an xCORE Tile
that is not connected directly to an xCONNECT Link.
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~~.
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"/>