View source for Writing apps for Xena

==Writing apps for Xena==

====Overview====
An XMOS XS1-L2 paralell processing chip is included in each A-EON X1000 
computer. Amigas have a history of naming their unique chips, and the 
XMOS chip in the X1000 has been named Xena.

The XS1-L2 is actually two XS1 cores in a single package. In the X1000,
about 1/3 of the I/O pins are connected back to a "localbus" interface,
with the rest brought out to a "Xorro" slot for connections to whatever
the user wants to connect.

The Xena chip has many unique attributes. It can be programmed in "C",
or in a variant called "XC" that better embraces the stream oriented
architecture of the chip.

Each of the two cores in Xena supports up to eight threads. Each thread
operates at a internal clock of 100,000,000 Hz. When programmed in XC,
each threads memory is private to that thread. There are no "common" data
areas between threads, and all inter-thread data is moved through
Channels. These channels can carry data between threads, cores, and even
between XMOS chips.

From the software side, each channel is declared, then used from exactly
two places. Any data written to one end can be read from the other. 
Channels are bi-directional, so data can move in both directions.

Channels are BLOCKING. A read will stall until a matching write is made
to satisfy it. Likewise a write will stall until a matching read is made
at the other end of the channel. This will require some organization from
the programmer.

The "streaming" modifier may be added to a channel declaration. This will
dedicate a hardware channel exclusively to this connection. This may be
required for higher bandwidth connections.

From the hardware side, channels may be three or five wire types. Cores are
interconnected by a switching "fabric" that consists of these channels. Part
of each *.xc file created configures the switches for the particular needs
of an application.

==Programming the Xena chip==
We have a set of "XTools" for delivery of the executable to the Xena chip.
At this time, the compiler suite is available only for X86 platforms.
So all development is currently done from a Windows or X86 linux platform,
and the resulting *.xe files are moved over to the X1000 by flash drive
or network share. The XMOS development tools were recently updated to 
version 12, but since my existing projects were started under version 11,
I'll provide platform definition files for both.

At the creation of each new project in the XMOS IDE, the target board must
be selected. If you are using version 11 of the XDE, create directory
C:\Program FIles\XMOS\DevelopmentTools\11.11.1\targets\A-EON X-1000 Xena Device
and copy the following text into a file in that directory
<syntaxhighlight>
<?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">
  <Type>Device</Type>
  <Name>A-EON X-1000 Xena Device</Name>

  <Declarations>
    <Declaration>core stdcore[2]</Declaration>
  </Declarations>

  <Packages>
    <Package ID="0" Type="XS1-L2A-QF124">
      <Nodes>
        <Node Id="0" InPackageId="0" Type="XS1-L1A" Oscillator="25MHz" SystemFrequency="500MHz">
          <Core Number="0" Reference="stdcore[0]"/>
        </Node>
        <Node Id="1" InPackageId="1" Type="XS1-L1A" Oscillator="25MHz" SystemFrequency="500MHz">
          <Core Number="0" Reference="stdcore[1]"/>
        </Node>
      </Nodes>
    </Package>
  </Packages>

  <Links>
    <Link Encoding="5wire" Delays="0,1">
      <LinkEndpoint NodeId="0" Link="XLG"/>
      <LinkEndpoint NodeId="1" Link="XLF"/>
    </Link>
    <Link Encoding="5wire" Delays="0,1">
      <LinkEndpoint NodeId="0" Link="XLH"/>
      <LinkEndpoint NodeId="1" Link="XLE"/>
    </Link>
    <Link Encoding="5wire" Delays="0,1">
      <LinkEndpoint NodeId="0" Link="XLE"/>
      <LinkEndpoint NodeId="1" Link="XLH"/>
    </Link>
    <Link Encoding="5wire" Delays="0,1">
      <LinkEndpoint NodeId="0" Link="XLF"/>
      <LinkEndpoint NodeId="1" Link="XLG"/>
    </Link>
  </Links>

  <JTAGChain>
     <JTAGDevice NodeId="0"/>
     <JTAGDevice NodeId="1"/>
  </JTAGChain>
 
</Network>
</syntaxhighlight>

to allow selection of Xena projects. There were some
changes when version 12 released, so if you are using
the new "Tooltips" IDE, create the directory
C:\Program FIles\XMOS\xTIMEcomposer\12.0.0beta\targets\A-EON X-1000 Xena Device
and create a file there with these contents
<syntaxhighlight>
<?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">
  <Type>Device</Type>
  <Name>A-EON X-1000 Xena Device</Name>

  <Declarations>
    <Declaration>tileref tile[2]</Declaration>
  </Declarations>

  <Packages>
    <Package ID="0" Type="XS1-L2A-QF124">
      <Nodes>
        <Node Id="0" InPackageId="0" Type="XS1-L1A" Oscillator="25MHz" SystemFrequency="500MHz">
          <Tile Number="0" Reference="tile[0]"/>
        </Node>
        <Node Id="1" InPackageId="1" Type="XS1-L1A" Oscillator="25MHz" SystemFrequency="500MHz">
          <Tile Number="0" Reference="tile[1]"/>
        </Node>
      </Nodes>
    </Package>
  </Packages>

  <Links>
    <Link Encoding="5wire" Delays="0,1">
      <LinkEndpoint NodeId="0" Link="XLG"/>
      <LinkEndpoint NodeId="1" Link="XLF"/>
    </Link>
    <Link Encoding="5wire" Delays="0,1">
      <LinkEndpoint NodeId="0" Link="XLH"/>
      <LinkEndpoint NodeId="1" Link="XLE"/>
    </Link>
    <Link Encoding="5wire" Delays="0,1">
      <LinkEndpoint NodeId="0" Link="XLE"/>
      <LinkEndpoint NodeId="1" Link="XLH"/>
    </Link>
    <Link Encoding="5wire" Delays="0,1">
      <LinkEndpoint NodeId="0" Link="XLF"/>
      <LinkEndpoint NodeId="1" Link="XLG"/>
    </Link>
  </Links>

  <JTAGChain>
     <JTAGDevice NodeId="0"/>
     <JTAGDevice NodeId="1"/>
  </JTAGChain>
 
</Network>
</syntaxhighlight>
In both cases, these are just the normal XS1-L2 header files, with the
addition of "OSCILLATOR=25MHZ" to each core/tile to specify the clock
used for the X1000 Xena chip.

==Unique to XC:==

XC does not support pointers.
Any RAM used by a thread may NOT be accessed by any other thread.
Any I/O pins declared by a thread may not be used by any other thread.

main() in an XC program may only declare channels, and launch other
threads with par() statement(s)

multiple core projects may only have one par() in main().

This may take some getting used to. Where normal "C" programs may
gather data into a block of memory, then pass a pointer to it, XC
threads cannot share access to the memory block, nor pass pointers.

So far, this has made my main() a simple "map" of the threads I am
using, and the channels that connect them. It also makes code modules
MUCH more easily re-used, since inter-thread dependencies are much 
better documented.

In some cases, (like the re-use of existing code), we simply MUST have
pointers. Standard C can be mixed with XC, though you'll lose some of
the elegance that XC provides. One example is the FAT file system support
used in the logger application.

==Connecting to the hardware==
As delivered, the Xena chip in an X1000 includes the localbus connections,
a built-in JTAG port for programming and debugging, and an LED from
each XCORE. To make any connections to the chip, a XORRO card will be
required. The Xorro card provides access to all the open pins, and to
the JTAG pins in case you want to add additional XMOS chips.

To get much done, you'll probably need to add some accessories. The
logger project adds a serial port, and an SD card interface. 

WARNING: wiring your own circuit boards can be fun, but it does require
certain skills. If you are not comfortable with a soldering iron, or
familiar with electronics assembly, you might want to find someone who
IS skilled in these things to assemble your Xorro project for you.

AmigaKit may provide Xorro assembly for pre-compiled projects like the
Logger if requested to do so. Please contact them for price and 
availability.

The Xorro card provides 3.3, 5, and 12 volts for your projects. The I/O
voltage of the chips is 3.3 volts. DO NOT apply voltages above 3.3 or
below 0 volts to any input. DO use output buffers for any outputs coming
from the XORRO slot. pins that are always INPUT or OUTPUT should be
declared as such in your code. Bi-Directional pins will switch to output
when any output statement is executed, (pin <: value) and will switch
back to input when any read is made of that pin (pin :> state).


====Project Description, The Logger====
The goal is to create a debug logger that will reside entirely on a 
Xorro card. It will connect directly to SER0: of the Nemo board, and will 
capture the debug stream and store it on an SD card for later retrieval.

==Hardware requirements==
A Xorro card for access to the Xena signals.
A serial "level shifter" chip, 3.3 volt. (MAX3232)
An SD card socket will all pins available (4 bit "fast" mode)
An SD card. Faster is better, I'm using Class 10.

Please note that the MAX3232 and the SD Card are both 3.3 volt devices,
so voltage translation is not necessary.

Software threads used, and their role.
Fast serial Receive: from XCORE
Fast serial Transmit: from XCORE
SD card handler(with FAT FS): from XCORE
Smart buffer: Code HERE
Localbus, Xena side: code HERE
Localbus, Nemo side: code HERE

As described earlier, main() in an XC project is limited to
launching the threads and the channels that interconnect them.
This seems a good time for an example.


The modules used:
The fast serial routines, TX and RX, each require a single pin to
be defined as the input or output. Each also requires a streaming
channel end to supply or sink the data being handled. These "fast"
serial routines are 8N1, no handshaking, and can use baud rates up
to about 10 Megabaud, assuming the channels will be serviced 
quickly enough.

The SD Card code supports reading and writing files to a Secure
Digital card. Either SPI or 4Wire modes may be chosen, and software
to support FAT file system is included. There are a bunch of options
that determine support for multiple devices, long file names, and
other stuff. It should be noted that the FATFS code is written in C,
not in XC as most other modules are.

The buffer code is my own, and was written to collect incoming
bytes, until a large enough block is ready to pass on to the SD card
thread. The code itself is quite simple, with the following design
goals:
The highest priority is to receive and buffer incoming bytes from
the streaming input (from the Serial IN pin, in this case).
When a block of data is requested, IF there is enough data, it is
sent out the output streaming channel.
Finally, one or optionally two control channels are checked for
commands and handled as needed. There are commands to get the
current buffer quantity, get the amount if idle time since the
last received character, get the number of buffer overruns (this
counter will reset on read), and to request n Bytes of data.
There is an optional second control channel if requested.

The localbus code is two separate programs. One is a thread in
CORE1, and the other is an app running on the X1000. This provides
addressable communication between Xena and Nemo. The code presented
here is early working code. I hope the community will work together
to decide what features might be added to this example.

It should be noted that the XMOS localbus thread might block if any
channel read or write is not ready. If this happens while the Data
Bus output buffer is enabled, permanent damage can be caused to
the Xena chip and/or the localbus. For this reason the localbus
thread will wait on a timer while the bus output is enabled. This 
section of code is clearly marked as "KEEP OUT", and I suggest that
you leave it alone unless you are SURE of what you are doing.

The localbus code currently moves uint16 data words at all times.
It is possible to support 8, 16, and 32 bit values, but I wanted the
first example to be as simple as possible.

Addresses for the localbus are 16 bits wide, and only even addresses
are supported. Odd addresses will be decremented. So far I am using
addresses to select which threads the localbus might exchange data with.