.. _xn_spec: XN Specification ================ .. _xn_spec_network_elements: Network Elements ---------------- The network definition is specified as follows: :: The XN hierarchy of elements is given below: .. code-block:: 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 .. _xn_spec_declaration: 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 ```` for use in XC programs. A ``tileref`` declaration is associated with physical xCORE tiles by the reference attribute of a :ref:`~~Tile~~ element `. **Example** :: tileref master tileref tile[8] .. _xn_spec_package: 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_spec_package_element_properties: .. list-table:: XN ``Package`` element :header-rows: 1 * - 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 ``.pkg`` in the path specified by ``XCC_DEVICE_PATH``. **Example** :: The package named ``L2`` is described in the file ``XS1-L2A-QF124.xml``. .. _xn_spec_node: 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_spec_node_element_properties: .. list-table:: XN ``Node`` element :header-rows: 1 * - 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_.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** :: The node named ``MyL1`` is an L1 device, as described in the file ``config_XS1-L1A.xml``. .. _xn_spec_core: Tile ~~~~ A ``Tile`` element describes the properties of a single xCORE Tile. .. _xn_spec_core_element_properties: .. list-table:: XN ``Tileref`` element :header-rows: 1 * - 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** :: .. _xn_spec_port: Port ~~~~ A ``Port`` element provides a symbolic name for a port. .. _xn_spec_port_element_properties: .. list-table:: XN ``Port`` element :header-rows: 1 * - Attribute - Required - Type - Description * - Location - Yes - String - A port identifier defined in the standard header file ````. The ports are described in the `XC Programming Guide `. * - Name - Yes - String - A valid C preprocessor identifier. All port names declared in the network must be unique. **Example** :: .. _xn_spec_boot: Boot ~~~~ A ``Boot`` element defines the how the node is booted. It contains one :ref:`~~Source~~ element ` and zero or more :ref:`~~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 :ref:`boot programs from flash memory `. .. _xn_spec_source: Source ~~~~~~ A ``Source`` element specifies the location from which the node boots. It has the following attributes. .. _xn_spec_source_element_properties: .. list-table:: XN ``Source`` element :header-rows: 1 * - 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** :: .. _xn_spec_bootee: 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 :ref:`xn_spec_link` and :ref:`xn_spec_linkendpoint`), the tools pick one to use for booting. .. _xn_spec_bootee_element_properties: .. list-table:: XN ``Bootee`` element :header-rows: 1 * - Attribute - Required - Type - Description * - NodeId - Yes - String - A valid identifier for another node. **Example** :: .. _xn_spec_bit: Bit ~~~ A ``Bit`` element specifies the direction for messages whose first mismatching bit matches the specified bit number. .. _xn_spec_bit_element_properties: .. list-table:: XN ``Bit`` element :header-rows: 1 * - 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** :: .. _xn_spec_routinglink: Link ~~~~ When it appears within a ``RoutingTable`` element, a ``Link`` element specifies the direction of an xCONNECT Link. .. _xn_spec_routinglink_element_properties: .. list-table:: XN ``Link`` element :header-rows: 1 * - Attribute - Required - Type - Description * - name - Yes - String - A link identifier in the form XL where denotes a tile number and the link letter. See the corresponding package datasheet for available link pinouts. * - direction - Yes - Integer - The direction of the link. **Example** :: .. _xn_spec_service: Service ~~~~~~~ A ``Service`` element specifies an XC service function provided by a node. .. _xn_spec_service_element_properties: .. list-table:: XN ``Service`` element :header-rows: 1 * - 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 ```` for use in XC programs. **Example** :: .. _xn_spec_chanend: Chanend ~~~~~~~ A ``Chanend`` element describes a channel end parameter to an XC service function. .. _xn_spec_chanend_element_properties: .. list-table:: XN ``Service`` element :header-rows: 1 * - 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** :: .. _xn_spec_link: 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 :ref:`~~LinkEndpoint~~ children `. .. _xn_spec_link_element_properties: .. list-table:: XN ``Link`` element :header-rows: 1 * - Attribute - Required - Type - Description * - Encoding - Yes - String - Must be either ``2wire`` or ``5wire``. * - Delays - Yes - String - Of the form ``,`` where specifies the inter delay value for the endpoint, and specifies the intra delay value for the endpoint. If a value for is omitted, value is used. * - Flags - No - String - Specifies additional properties of the link. Use the value ``XSCOPE`` to specify a link used to send xSCOPE trace information. **Example** :: .. _xn_spec_linkendpoint: 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. .. _xn_spec_linkendpoint_element_properties: .. list-table:: XN ``LinkEndpoint`` element :header-rows: 1 * - Attribute - Required - Type - Description * - NodeID - No - String - A valid node identifier. * - Link - No - String - A link identifier in the form ``XL`` where denotes a tile number and the link letter. See the corresponding package datasheet for available link pinouts. * - 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:: 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:: 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:: .. _xn_spec_device: Device ------ A ``Device`` element describes a device attached to an xCORE Tile that is not connected directly to an xCONNECT Link. .. _xn_spec_device_element_properties: .. list-table:: XN ``Device`` element :header-rows: 1 * - 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. .. _xn_spec_attribute: Attribute ~~~~~~~~~ An ``Attribute`` element describes one aspect of a :ref:`~~Device~~ `. .. _xn_spec_attribute_element_properties: .. list-table:: XN ``Attribute`` element :header-rows: 1 * - 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** :: 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** :: .. _xn_spec_jtag_device: JTAGChain --------- The JTAGChain element describes a device in the JTAG chain. The order of these elements defines their order in the JTAG chain. .. _xn_spec_jtagchain_element_properties: .. list-table:: XN ``JTAGChain`` element :header-rows: 1 * - Attribute - Required - Type - Description * - JTAGSpeed - No - String - Sets the JTAG clock speed. JTAGDevice ~~~~~~~~~~ .. _xn_spec_jtagdevice_element_properties: .. list-table:: XN ``JTAGDevice`` element :header-rows: 1 * - Attribute - Required - Type - Description * - NodeID - Yes - String - A valid node identifier. **Example** ::