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
│       │       ├── Extmem             0 or 1       External memory configuration
│       │       │   ├── Lpddr          1            Pad control for LPDDR device outputs
│       │       │   └── Padctrl        1            Pad control for xcore.ai outputs
│       │       ├── 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.

Table 22 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="0" Type="XS3-UnA-1024-QF60A">

This package is described in the file XS3-UnA-1024-QF60A.pkg.

Node#

A Node element defines a set of xCORE Tiles in a network, all of which are connected to a single switch. The XMOS xcore.ai device XU316-1024-FB265 is an example of a node.

Table 23 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.
SecondaryPllInputDiv	No	Integer	The secondary PLL input divider register value
SecondaryPllOutputDiv	No	Integer	The secondary PLL output divider register value
SecondaryPllFeedbackDiv	No	Integer	The secondary PLL feedback divider 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 the device datasheets.

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 PLLs. The PLL registers remain at their initial values as determined by the mode pins.

The secondary PLL can only be configured manually by supplying SecondaryPllInputDiv, SecondaryPllOutputDiv and SecondaryPllFeedbackDiv.

Example

<Node Id=”0” InPackageId=”0” Type=”XS3-L16A-1024” Oscillator=”24MHz” SystemFrequency=”600MHz” ReferenceFrequency=”100MHz”>

Tile#

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

Table 24 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.

Table 25 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 relevant device architecture manual and datasheet.
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.

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.

Table 26 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.
BootMode	No	Integer	Required for `Location` of type `LINK`, and maps to an entry in the “boot source pins” table in the “boot procedure” chapter of the datasheet. Valid values are 4 through 7.

Example

<Source Location="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.

Table 27 XN `Bootee` element#
Attribute	Required	Type	Description
NodeId	Yes	String	A valid identifier for another node.

Example

<Bootee NodeId="Secondary">

Bit#

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

Table 28 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"/>

Link#

When it appears within a RoutingTable element, a Link element specifies the direction of an xCONNECT Link (xLINK).

Table 29 XN `Link` element#
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.

Table 30 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)">

xSCOPE Example

The text below is required to support xSCOPE and must reside under a <Network> element (at the same level as <Links>):

<Nodes>
  <Node Id="2" Type="device:" RoutingId="0x8000">
    <Service Id="0" Proto="xscope_host_data(chanend c);">
      <Chanend Identifier="c" end="3"/>
    </Service>
  </Node>
</Nodes>

Chanend#

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

Table 31 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"/>

Link#

A Link element describes the characteristics of an xCONNECT Link. It must contain exactly two ~~LinkEndpoint~~ children.

Table 32 XN `Link` element#
Attribute	Required	Type	Description
Encoding	Yes	String	Must be either `2wire` or `5wire`.
Delays	Yes	String	Of the form `<x>clk,<y>clk` where <x> specifies the inter-token delay value for the endpoint, and <y> specifies the intra-token delay value for the endpoint. <x> and <y> are specified as a number of `SystemFrequency` cycles. If `,<y>clk` is omitted, the <x>clk value is used for the intra-token delay value.
Flags	No	String	Specifies additional properties of the link. Use the value `XSCOPE` to specify a link used to send xSCOPE trace information.

Example

<Link Encoding="2wire" Delays="4clk,4clk">

LinkEndpoint#

A LinkEndpoint describes one end of an xCONNECT Link, the details of which can be found in the device datasheet. Each endpoint associates a node identifier to a physical xCONNECT Link.

Table 33 XN `LinkEndpoint` element#
Attribute	Required	Type	Description
NodeID	No	String	A valid node identifier.
Link	No	String	A link identifier in the form `XL<n>` where <n> denotes a link index. See the corresponding device datasheet for available link pinouts.
RoutingId	No	Integer	The routing identifier on the xCONNECT Link network.
Chanend	No	Integer	A channel end.

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="XL0"/>
<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	Link specifier
0	XL0
1	XL1
2	XL2
3	XL3
4	XL4
5	XL5
6	XL6
7	XL7
8	XL8

The following example demonstrates how Node 0 Link number 4 is connected to Node 1 Link number 7:

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

Table 34 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)
PageSize	Yes	Integer	The program page size of the device
SectorSize	Yes	Integer	The erase sector size of the device
NumPages	Yes	Integer	The number of pages in the device

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

SPIFlash: Device is SPI flash memory
SQIFlash: Device is QuadSPI flash memory

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

Attribute#

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

Table 35 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.
QE_REGISTER: This is optional and only required for devices which do not support JEDEC SFDP. Valid values are flash_qe_location_status_reg_0 and flash_qe_location_status_reg_1.
QE_BIT: This is optional and only required for devices which do not support JEDEC SFDP. Valid values are flash_qe_bit_0 through to flash_qe_bit_7.

Example

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

Flash device example

The following example shows the complete description of a flash device.

<ExternalDevices>
  <Device NodeId="0" Tile="0" Class="SQIFlash" Name="bootFlash" Type="S25FL116K" PageSize="256" SectorSize="4096" NumPages="16384">
    <Attribute Name="PORT_SQI_CS"   Value="PORT_SQI_CS"/>
    <Attribute Name="PORT_SQI_SCLK" Value="PORT_SQI_SCLK"/>
    <Attribute Name="PORT_SQI_SIO"  Value="PORT_SQI_SIO"/>
  </Device>
</ExternalDevices>

JTAGChain#

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

Table 36 XN `JTAGChain` element#
Attribute	Required	Type	Description
JTAGSpeed	No	String	Sets the JTAG clock speed.

JTAGDevice#

Table 37 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">