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

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

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