XCore Exchange - New pages [en]

VDP-1 by yzoer

Yzoer — Wed, 18 Aug 2010 18:01:01 GMT

Yzoer: Created page with ''''VDP - Video Display Processor''' VDP-1 is the first in a series of Video Display Processors, primarily modelled after console / handheld hardware such as the Sega Genesis and …'

'''VDP - Video Display Processor'''
VDP-1 is the first in a series of Video Display Processors, primarily modelled after console / handheld hardware such as the Sega Genesis and Nintendo's Gameboy Advance.

With only a handful of resistors to form an R2R DAC, a single-core XS1 using VDP-1 can output either VGA or NTSC. Given the nature of a tile- and spritebased architecture, the memory footprint for applications is surprisingly small and allows for applications to be loaded concurrently.

'''Overview'''

As mentioned before, VDP-1 uses a tile- and spritebased architecture. What this boils down to is that the system doesn't use a frame-buffer but instead uses a scanline based rendering approach, saving significant amounts of memory. VDP-1 can render 2 independently controlled Backgrounds that can be moved both horizontally and vertically, on a per-pixel basis.

Similarly, the system allows for 32 independently controlled objects, called sprites. Sprites can be compared to 'mini-backgrounds' and range from 8x8 to 64x64 pixels. Like backgrounds, the can be positioned on a per-pixel basis.

In order to use VDP-1 efficiently, a brief description of the system will be described below.

'''Tiles'''

Tiles are the foundation of VDP-1. A tile is the base unit for both backgrounds and sprites and consists of 8x8 pixels. Each pixel in a tile can take one of 16 colors. Each color is therefore encoded as a 4-bit nibble. With 4-bits per pixel and 64 pixels per tile, the total memory footprint for a tile is 32 bytes.

'''Palettes'''

VDP-1 supports 16 palettes of 16 colors each, giving a grand total of 256 colors on-screen at once. Each palette entry consists of 5 bits for red,green and blue respectively ( 5:5:5 ) and therefore occupies 2 bytes per entry. The total palette foot-print therefore comes in at 512 bytes ( 16 palettes x 16 entries x 2 bytes per entry = 512 ).

Palettes are closely related to tiles ( and sprites ) in that each 4-bit pixels in a tile serves as a look-up into a specified palette. In order to see the relationship between pixels on-screen, tiles and palettes, consider the following scenario:

Tile pattern definition in hexadecimal:

unsigned int tiledata[] = {
0x11111111,
0x10000001,
0x10000001,
0x10022001,
0x10022001,
0x10000001,
0x10000001,
0x11111111,
};

and a corresponding palette:

unsigned short palette[16] = {
RGB(0,0,0), // black
RGB(31,0,0), // red,
RGB(0,31,0), // blue
};

For each nibble in the tile, a corresponding color is fetched from its referenced palette. So for each pixel that is serialized out of the tile, a 15-bit RGB value is displayed on-screen. By limiting the number of colors in a tile to 16, we saved ourselves 4 times the amount of memory!

'''Backgrounds'''

Now that we know how a tile gets defined in memory and how each pixels gets a color from its specified palette, we need to figure out a way to organize the tiles together so we can create more interesting images. This is where backgrounds come in. Backgrounds are yet another level of indirection, which is often somewhat confusing.

A background is a rectangular area in memory that specifies which tiles get rendered where and with what palette. Each background is made up of 64x32 'cells', creating a 512x256 image.

Cells contain the index and palette number of the tile to be rendered as well as two additional bits to allow for tiles to be flipped horizontally and vertically. Since tiles are always of a fixed size, each index is internally multiplied by 32.

- more to come -

Boot and initialisation

Jamie — Mon, 02 Aug 2010 11:44:41 GMT

Jamie: /* Synchronisation */

This page gives a brief description of the boot and initialisation process for single chip or networks of XS1 processors and how these may be replaced.

The boot and initialisation process is generated automatically by the mapper and included in the final multi-core program binary. It works in three phases, and it is possible to disable any of these enabling the use of a different method. Each of these phases are described below.

==Network bringup==

Network bringup is only necessary in systems with externally linked chips, such as the XMP-64, in order to establish node labelings and Xlink and routing table setup. When booting from JTAG, this phase is performed by loading an executing a separate binary (Loadable 1) for each core in the system. Once the execution of this has finished, the second program binary for each code (Loadable 2) is loaded and executed. When booting from flash the automatically generated second stage loader performs network bringup and loading. For more details see the XE file format section of the [http://www.xmos.com/published/tools-development-guide?ver=1.0 Tools Developer Guide].

The network bringup phase can excluded from a multi-core binary either by using xobjdujmp to manually construct it with ELF images for each core, or to extract it, again using xobjdump.

==C/XC runtime startup==

The runtime startup initialises the environment for C and XC programs to run, which includes setting up pointers, threads and channels. This is included in the program binary and is executed before the main function in the program. The inclusion of this can be disabled with the '-nostdlib' compiler flag. When this is disabled, the ELF symbol '_start' must be defined, as execution will start from that address.

==Synchronisation==

Channels, possibly over Xlinks, are used to ensure that all cores are in a known state and ready and some additional cleanup is performed. The top-level channel ends are allocated and the values communicated between cores. Then, on each core the correct top-level functions are called. This phase can be disabled by using the '--nochaninit' mapper flag.

Synchronisation is performed using a spare register in the switch (register number 3) of node 0. This is referred to at the scratch register. On power up the scratch register has value 0. When node 0, core 0 is ready to synchronise it writes 1 to it then polls, waiting for it to reach num_cores.

Each of the other cores is assigned a unique number in the range 1..num_cores-1 (let's call it boot_id) in the linker-generated code. At startup each core polls the scratch register waiting for it to reach boot_id. When it does, it sets it to boot_id+1.

In order to reach num_cores each of the cores must have detected its own number and written the next. Thus they are all known to have reached a known point in the boot.

Interrupts

Jamie — Mon, 02 Aug 2010 11:05:23 GMT

Segher: /* Its stack */

This page gives some description of, and example code showing how to use interrupts in the XS1 ISA. The details are all included in the [http://www.xmos.com/published/xmos-xs1-architecture-0?ver=xs1_en.pdf XS1 Architecture] manual, but this is intended to be a higher-level and more practical description.

Interrupts are a special kind of event that trigger entry to a predefined point of the program whilst saving the program counter (pc), status register (sr) and exception data (ed) registers in the saved pc (spc), sr (ssr) and ed (sed) registers respectively. This allows execution to resume at the point of interruption once the cause has been dealt with.

=Generating interrupts=

Interrupts can be generated in three ways: by exceptions, kernel calls and resources. An exception may be raised automatically by an illegal operation, such as an unaligned memory access, or explicitly by an ECALL instruction. In both cases, pc, sr and ed are saved, and control is transferred to the kernel entry point (kep). A kernel call can be made by executing the KCALL instruction, which again saves state and sets the pc to kep+64. Resources can also be setup to generate interrupts, and each can be assigned its own interrupt handler: the event vector (ev). The following example code shows how to setup a channel resource to generate interrupts on receiving a message.
<pre>
getr r11, XS1_RES_TYPE_CHANEND # Get a channel
eeu res[r11] # Enable events and interrupts on the channel
setc res[r11], XS1_SETC_IE_MODE_INTERRUPT # Set the resource control bits to generate interrupts
ldap r10, intrhandler # Load the address of the interrupt handler
setv res[r11], r10 # Set the event vector to the interrupt handler
</pre>

=The kernel=

Interrupts are intended to ''interrupt'' the normal execution of the program, possibly at an unexpected moment. This is in contrast with events which are waited on to occur. Whether the interrupt is caused by an exception, kernel call or resource action, the general idea is to deal with the cause and then return to the original location and state of execution. This can be achieved with the use of a ''kernel'' to save ''all'' of the execution state, handle the interrupt and then restore it to resume.

==Its stack==

The kep can be initialised using the SETKEP instruction. Once in the interrupt handler, the kernel may operate using the program stack or with a seperate ''kernel stack'', by executing KENTSP instead of ENTSP. There is no specific instruction to set the kernel stack pointer (ksp), but it can be set using the following sequence:
<pre>
set sp, r11 # Set the stack pointer
stw r11, sp[0] # Copy this into the location krestsp expects to find sp
krestsp 0 # Execute KRESTSP to set ksp = sp
</pre>

==Preserving execution state==

On entering the kernel in the event of an interrupt, the state of the executing program (i.e. the registers available to it), must be preserved so none are overwritten by the execution of the handler. There are several instructions provided to store/load special saved regsiters: spc, ssr, sed, to/from the stack. As an example, on entry to the kernel, we can store all the registers that might be used by the handler:
<pre>
kentsp 17 # Switch to kernel stack and allocate 17 words
stw spc, sp[1]
stw ssr, sp[2]
stw sed, sp[3]
stw r0, sp[4]
stw r1, sp[5]
stw r2, sp[6]
stw r3, sp[7]
stw r4, sp[8]
stw r5, sp[9]
stw r6, sp[10]
stw r7, sp[11]
stw r8, sp[12]
stw r9, sp[13]
stw r10, sp[14]
stw r11, sp[15]
stw lr, sp[16]
</pre>
And then restore them, when we exit the kernel:
<pre>
ldw spc, sp[1]
ldw ssr, sp[2]
ldw sed, sp[3]
ldw r0, sp[4]
ldw r1, sp[5]
ldw r2, sp[6]
ldw r3, sp[7]
ldw r4, sp[8]
ldw r5, sp[9]
ldw r6, sp[10]
ldw r7, sp[11]
ldw r8, sp[12]
ldw r9, sp[13]
ldw r10, sp[14]
ldw r11, sp[15]
ldw lr, sp[16]
krestsp 17 # Contract the kernel stack and switch to user stack
kret # Return from interrupt
</pre>

==Resuming execution==

Interrupts can be renabled at the point of returning from the kernel by modifying ssr in sp[2]:
<pre>
ldw r11, sp[2] # Load ssr into r11
ldc r10, SR_IEBLE # (0x2)
or r11, r11, r10 # Set SR_IEBLE bit
stw r11, sp[2] # Save the modified value
</pre>

Although the pc is pre-incremented, so that it always holds the address of the next instruciton to execute, when an interrupt occurs, it remains at the address of the current instruction. Because of this, the program counter needs to be manually incremented before returning from an interrupt, except in two cases.

The first is when the interrupted instruction was paused for some reason such as waiting on a channel input. This can be check by inspecting the WAITING bit in the thread's status register (now in ssr or on the stack):
<pre>
ldw r10, sp[2] # Load ssr into r10
ldc r9, SR_WAITING # (0x40)
and r10, r10, r9 # Mask off the WAITING bit
eq r10, r10, r9 # Check if it was set
</pre>

The second case is when another interrupt is generated and waiting while a previous one is beging handled, so that on exit from the handler, the next interrupt is immediately generated and entry to the handler caused before the original waiting instruction is executed. In this case, it is not necessary to increment the pc again before returining from the handler. One way to solve this problem is to compare the spc value to another saved pc vlaue (at dp[_pc]), which is updated only when there is a change:
<pre>
ldw r11, sp[1]
ldw r10, dp[_pc]
eq r11, r11, r10
</pre>

==Enabling interrupts==

When the source has been configured, the interrupt handler set and you are ready to receive interrupts, the status register of the thread must be set using SETSR:
<pre>
clrsr SR_EEBLE # If events are enabled, clear this bit
setsr SR_IEBLE # Enable interrupts
</pre>

=Things to be aware of=

* Receiving on a channel with interrupts or events enabled will cause an ILLEGAL_RESOURCE exception. Disable events and interrupts before attempting to use a channel for input.

PiXC

Jhrose — Sat, 26 Jun 2010 14:37:46 GMT

Jhrose: Add PiXC version 0.3 source

= A proposal for Pi-calculus extensions to XC (PiXC) =
Copyright © XMOSlinkers jhrose, 2009-2010. Version 0.3. These notes are distributed with the [http://www.gnu.org/copyleft/fdl.html FSF Free Documentation License version 1.3] as a community work.

= Introduction =
<nowiki>XC [</nowiki>2] is a general purpose programming language, for expressing parallel algorithms. PiXC is a proposal to extend XC with mobility, using Milner's p<nowiki>i-calculus [</nowiki>12] as a model. Mobility enables the program function and data control flow to evolve in response to run-time input.

== Aims ==
The aims of PiXC are:

* <nowiki>To use the pi-calculus [</nowiki>12<nowiki>] as a model to extend XC [</nowiki>2] with mobility
* To formalise (extensions to) a compiler for PiXC that targets XMOS processors<nowiki> [</nowiki>1]

== Version Control ==

{| class="prettytable"
| 0.1
| Initial proposal for mobile channels and mobile processes (to target a dynamic Operating System).

|-
| 0.2
| Added initial bindings (mobile:b) and endpoint qualifiers (mobile:01) for mobile channels; added initial bindings for mobile processes. Took design patterns into a new section. Added section for semantics. Added section for case studies.

|-
| 0.2.1
| Reposition PiXC as a general purpose programming language (well-positioned to implement a dynamic Operating System).

|-
| 0.3
| Described protocols.

|}
== Summary ==
<nowiki>XMOS processors such as the XS-1 core [</nowiki>1<nowiki>] equip system designers with process-oriented hardware and software building blocks, not unlike the INMOS Transputer [</nowiki>7<nowiki>] cores which predated them. An XMOS XS-1 is a multi-core processor, each core with its own memory and i/o links [</nowiki>1<nowiki>]. The cores embed support for a number of services commonly provided by an operating system on general purpose processors, including multi-threading, communication, general purpose i/o, and timers. And like INMOS with Occam [</nowiki>5<nowiki>], XMOS provide a parallel programming language in XC [</nowiki>2].

<nowiki>Milner writes [</nowiki>12<nowiki>], "[pi is]...a calculus for analysing properties of concurrent communicating proceses, which may grow and shrink and move about". This fluidity takes the pi-Calculus to a level not reached by CCS, CSP or classical automata. Broadly, pi is an extension to CCS that allows the very channels used for inter-process communication to be passed as communication elements. In communicating a channel, the effect is a dynamic re-mapping of the architecture. </nowiki>

<nowiki>Mobility in the pi-calculus [</nowiki>12<nowiki>] can be used to express parallel algorithms, and Occam 2.1 [</nowiki>5<nowiki>] has been extended with elements of mobility in Occam-pi [</nowiki>9<nowiki>], so these ideas might be usefully added to XC [</nowiki>2<nowiki>]. PiXC makes programming with the Pi-calculus accessible and familiar, by modestly extending the XC [</nowiki>2] programming language. These extensions allow mobile processes and channels to be declared and have a language semantics.

=== Where we were ===
<nowiki>From Barron's concept for the transputer [</nowiki>6<nowiki>] that "a calculus is likely to take the form of a program language, which has primitive operations enabling communication between parallel processes", the relationship between Occam and CSP was exploited heavily by INMOS. From its beginning [</nowiki>3<nowiki>] Hoare's CSP postulated "...that input and output are basic primitives of programming and that parallel composition of communicating sequential processes is a fundamental program structuring method." Over time CSP evolved into a model for concurrency [</nowiki>4] which tests processes against logical specifications (e.g. failures and trace semantics), when Occam took-up the software baton.

<nowiki>Independently of and at about the same time as CSP emerged, and in response to a critique of von-Neumann automata, CCS [</nowiki>11<nowiki>] surfaced with the assertion that "communication and concurrency are complementary notions" CCS theories of observational equivalence test process automata against each other at their communication ports. This provides a complementary viewpoint to testing logical specifications and properties, and is a good fit with Barron's ideas of a component [</nowiki>6] "The transputer focuses interest on the transfer of information across a boundary, rather than on the processing of information within that boundary."

=== Where we are ===
<nowiki>Aside from influential ideas, several of which have re-emerged in different forms, Occam has brought about neither significant developments in Operating System Architecture nor a compelling reason for industry to make the costly transition to parallel programming en masse. However, the ideas continue to evolve and nowadays the Occam mantel lies with KroC [</nowiki>8<nowiki>] and Occam-pi [</nowiki>9].

<nowiki>While the XMOS architecture makes it practical to use software to perform many functions that are traditionally implemented in hardware, transition to the new technology could be made more widespread through a general purpose programming language that can express mobile algorithms, i.e. ones in which the data flow and control flow change dynamically in response to system input. And it is with the pi-calculus [</nowiki>12] successor to CCS, where processes can migrate and channels themselves can be passed between processes, that a significant theoretical breakthrough has been made, so that instead of a static architecture we have a dynamic model.

=== Where we want to be ===
The aim is to bring the new hardware and theoretical advances to bear on a mobile programming language, to ease the transition for designers and industry more widely into parallel system design and process-oriented software development, using XMOS processors.

Aside from an entry in [http://en.wikipedia.org/wiki/XCore_XS1-L1 Wikipedia]<nowiki>, "[XMOS] Threads can also use Channels to communicate and synchronise allowing a CSP style of programming", there is scant detail relating to the formal CSP-basis of XC/XS-1. Whether one will emerge likely depends on any academic gain in "translating" to XC from Occam. And, like the theoretical foundation for Occam-pi [</nowiki>9<nowiki>] has evolved (by blending elements of the CSP, pi-Calculus and Petri-net models [</nowiki>10]), we can adapt a model best-suited for expressing mobile algorithms in the pi-calculus to XC.

==== Fluid architecture ====
<nowiki>Pi is well-suited for modelling internets [</nowiki>12]; consider an internet (TCP/IP) server that accepts socket connection requests at a well-known address, and spawns a child process to serve each new connection concurrently. Pi is also well-suited for general purpose programming and expressing algorithms; t<nowiki>he dynamic communication of mobile channels and mobile processes through channels enables the function and data control flow to evolve in response to run-time events [</nowiki>10].

= Constructs =
Existing operational constructs in XC/XS-1 required to implement mobility are first identified, then new syntactic constructs for XC are proposed based upon Pi-calculus semantics.

== Operational constructs ==
PiXC requires operational constructs in the XS-1 in order to migrate runnable processes and to allocate dynamic channel endpoints.

=== Runnable processes ===
The XS-1 instruction set provides for runnable processes through thread allocation and freeing, which is commonly accessed using the XC PAR construct. This operates quite distinctly from a ''fork'' in UNIX, and requires code for the process entry point to be statically linked. A process is run when code and data pointers are loaded into a set of registers, which are presented to the XS-1 scheduler. And a process terminates on return (or join), when its register set is freed.

=== Dynamic channels ===
Dynamic channels are those channel endpoint resources which are allocated to a process, and eventually freed, for which XS-1 instructions and registers are provided.

== New constructs ==
New syntactic constructs are needed to program mobility in PiXC.

=== Mobile processes ===
Mobile processes are those which migrate, to run at different locations at different times. To be mobile, rather than just invoked in the accepted way, a process has to preserve some state and provide various function entry points, which suggests a mobile context operating entirely within the process. And to be safe, a process has to be sent through a channel to a new location.

==== Applications ====
Consider a dynamic master-slave scenario, where the master measures runtime performance for some application (we don't say how this measurement works) and decides to run a mobile slave process to take some of the workload on a new processor.

Consider a dynamic device driver, where a runtime event is input and a mobile driver process is run to service it.

==== Declarations ====
A mobile process is a function declared with the ''mobile'' qualifier. This provides a guide to the compiler in scoping both a ''mobile'' code segment and process member variables.

mobile void p0( chanend out, chanend in ) // p0 is a qualified function
{
}

In general the ''mobile'' qualifier has no effect on the function body operational semantics, or on any nested function calls; however, there are certain restrictions on code and data scope which follow.

A mobile process cannot be invoked like a normal function.

int f( chanend top0, chanend fromp0 )
{
p0( fromp0, top0 ); // compiler error, cannot invoke mobile process
}

Rather, before a mobile process is run, it first has to be received along a channel by a running process context (see 2.2.1.5 ), following which a new thread (runnable process) is scheduled.

==== Mobile context ====
Mobile context refers to the scope of static variables and functions accessed by a mobile process. The compilation must arrange storage for a mobile process to enable its member functions and data to reside in different XS-1 core memories at different times.

===== Member variables =====
Process member variables maintain state across migrations. In particular they support mobile processes being communicated along channels, to resume at a new future location and context.

There are no new syntactic qualifiers for mobile process member variables. The static keyword serves in the usual way, so that member variables are taken to lie within ''mobile'' process scope.

mobile void p1( chanend out, chanend in )
{
mobile static int i = 0; // i is a static int in mobile scope
mobile static timer t; // t is a static timer in mobile scope
}

The ''mobile'' qualifier on static variables would not be written by programmers; it shows how the compiler needs to allocate storage for member variables, as if it had been written. The compiler may rename the member variables to qualify the mobile context: p1::i, p1::t, p1::in and p1::out, which is not exposed as syntax the programmer would write.

===== Non-member variables =====
Variables nested within a mobile process without the static qualifier are just taken as temporary automatic (stack) variables.

===== Member functions =====
Process member functions are those referenced within a ''mobile'' process scope. In particular they support mobile processes being communicated along channels, to run at a new future location.

There are no new syntactic qualifiers for mobile process member functions. The static keyword serves to declare member functions in a new way (for XC) within ''mobile'' process scope.

mobile void p2( chanend out, chanend in )
{
mobile static int f( ); // f is a static function in mobile scope
}

The ''mobile'' qualifier on static function declarations would not be written by programmers; it shows how the compilation needs to allocate a code segment for member functions, as if it had been written. The compiler may rename member functions to qualify the mobile context: p2::f.

Member functions themselves are written as static functions at file level, with no further qualifiers.

mobile static int f( void )
{
}

The ''mobile'' qualifier would not be written by programmers; rather the compiler always assumes it is inherited if and only if a static function is referenced by a mobile process.

===== Nested member variables =====
Follows as 2.2.1.3.1 <nowiki>; a </nowiki>''mobile'' qualifier on static variables would not be written by programmers but is assumed by the compiler when a nested function inherits the ''mobile'' qualifier.

===== Nested member functions =====
Follows as 2.2.1.3.3 <nowiki>; a </nowiki>''mobile'' qualifier on static functions would not be written by programmers; but the referenced function should be declared within mobile process scope. The source code:

mobile void p3( chanend out, chanend in ) // p3 is a mobile process
{
int i; // i is an automatic (stack) int
static int f( ); // f is a static function in process scope
static int g( ); // g is a static function in process scope
i = f( ); // i holds the result of f of g
}
static int f( void )
{
return( g( )); // result is value of f of g
}
static int g( void )
{
return( 0 ); // result is value of g
}

===== Non-member functions =====
There is no such thing as a non-member function. A non-static function cannot be called within ''mobile'' process scope, and results in a compilation error.

mobile void p4( chanend out, chanend in )
{
int f( ); // compiler error, function needs static in mobile context
g( ); // compiler warning, function g not declared in mobile context
}

The reason for this threefold: to allow the compiler to treat file-scope and process-scope in similar yet distinct ways; to avoid the compiler having to search through other compiled units to locate required code; and to prevent the need for multiple (and hence incoherent) copies of data. For the latter, consider if a function, ''g'', is both called by a mobile process and also called elsewhere by a plain function, then it would be necessary to store two copies of ''g'' member variables, as the copy for the mobile process may be communicated into a remote core memory.

Note the caveat that library functions cannot be called within mobile process scope (unless the whole mobile process and its members are compiled into the same library unit).

===== Initial binding =====
Unless otherwise received, mobile processes are initially bound (as if they had been received) by passing mobile processes as parameters to process threads. Here ''myThread'' is a function that is run as a process (from a ''par'' statement).

void myThread( mobile p1 )
{
}

The compiler will check each mobile process is given at most one initial binding. If no initial binding is provided for a mobile process, the program may deadlock as no running thread would ever receive or be able to send the mobile; the compiler could issue a warning in this case. (This is made more clear in the case studies in section 5.1.2 .)

==== Sending ====
A mobile process is declared precisely to enable its communication along a channel, for execution by a receiving process context as a new thread.

The top-level mobile process is sent as a unit. Here, ''q0'' is a function running in the source process context, where it is assumed ''p1'' is currently bound.

void q0( chanend c )
{
<nowiki>c <: p1;</nowiki> // p1 is sent along channel c; its state ceases to exist in
// the context of q0 process, and its thread is terminated
}

There is no new syntax, and the existing communication output primitive serves. When a mobile process is sent, a destructor may be called and its state goes out of context in ''q0''.

At runtime the compiler will cause the (fully qualified) member variables to be sent as a single packet or structure (or Occam 2.1 style protocol, see 2.2.3 ) to the receiving process.

At buildtime, where it is communicated, the linker will link the object code for a mobile process with each processor's executable unit (so the code itself is not sent at runtime), and allocate space to receive the mobile process member variables.

==== Receiving ====
Until a mobile process is received (into a destination process context) no valid state exists for it. A mobile process is received by a destination process along a channel; the top-level unit as a whole is received. Here, ''q1'' is a function running in the receiving destination process context.

void q1( chanend c )
{
chan i, o;
c :> p1( o, i ); // p1 is received along channel c;
// its state exists in the context of q1 process,
// bound to the local chanends,
// and p1 runs concurrently as a new thread
}

There is no new syntax, and the existing communication input primitive serves. Once a mobile process is received, a constructor may be called and its state comes into context; this includes binding its input and output chanends to local channels.

Rather than a free variable name, the input parameter is the bound mobile process name; this defines the data structure received, being the process member variables.

The ''p1'' state remains valid for the duration of the receiving process context, after which a mobile process destructor may be called, which includes un-binding the local chanends. If ''p1'' should persist beyond the lifetime of the destination process context, it should be communicated to another process before this destination process terminates.

=== Mobile channels ===
Mobile channels are those which migrate, to bind with different endpoints at different times.

To be mobile, rather than just used in the accepted way, a channel has first to be emptied before migrating. And to be safe, a channel has to be sent from a source process through a channel, possibly itself, to a destination process. Once sent, the source process can no longer access the migrated channel; and the destination process can only access the migrated channel once received.

==== Applications ====
Consider a dynamic master-slave example, where the master measures runtime performance for some algorithm (we don't say how this measurement works) and decides to send a channel (endpoint) to a slave process on some other processor for it to take some of the workload.

Consider a dynamic device driver, where a runtime event is input and a channel (endpoint) is sent to a driver process for it to service the event.

==== Declarations ====
New syntax declares mobile channels and mobile chanends.

===== channel =====
A mobile channel is a channel declared with the ''mobile'' qualifier. This provides a guide to the compiler for allocating and binding channel endpoints.

chan mobile c; // c is a qualified channel

A mobile channel can be used at global level by a sequential process, or, unlike a conventional channel, passed as an argument to multiple processes in a ''PAR'' statement. This allows the compiler to know which contexts the channel may bind in.

chan mobile data;
par
{
procA( data );
procB( data );
procC( data );
}

In general the mobile qualifier has no effect on a channel semantics as a point-to-point pipe; rather it extends endpoints with variable-like semantics, allowing them to be dynamically (re-)bound.

===== chanend =====
Mobile endpoints are bound in two cases: when a mobile channel is input by a destination process; or when a processes fixes it, by omitting the ''mobile'' qualifier from its definition.

Channel endpoints are passed into functions as parameters. The ''mobile'' qualifier is used when declaring a mobile channel endpoint in a function scope.

void x0( chanend mobile c ) // c is not bound on entry to x0
{ // (it may have been bound by the caller)
}

==== Mobile context ====
The ''mobile'' qualifier is used by the compiler to allocate storage space for channel endpoints, but not to bind them. The compiler may rename mobile channels to qualify the mobile context: x0::c.

===== constructor =====
The compiler may call channel (endpoint) constructor functions in two different cases: on entry to a function if the channel is fixed, and if ''c'' is input communicated.

void x1( chanend c ) // c is bound (fixed) on entry to x1
{
}

Without a ''mobile'' qualifier, x1::c is fixed (bound), even if the endpoint passed in is qualified.

===== Initial binding =====
Unless otherwise fixed, unbound chanend points are initially bound (as if they had been received) by further qualifying the function definition of a mobile channel with ''mobile:b''.

void x2( chanend mobile:b c ) // c is initially bound on entry to x2
{ // (but otherwise behaves as a mobile)
}

Each channel has exactly two endpoints that can be fixed or initially bound. The compiler will check that the allowed endpoints are initially bound or fixed.

===== destructor =====
The compiler may call channel (endpoint) destructor functions in two different cases: on exit from a function, where the channel endpoint may no longer be bound (once it passes out of scope); and if ''c'' is output communicated, where the channel is always unbound.

==== Sending ====
Mobile channels may be sent from a source process to a destination, communicated along a channel, to re-bind with the destination process.

void x3( chanend d, chanend mobile c )
{
<nowiki>d <: c;</nowiki> // mobile channel endpoint c is sent along channel d,
// its destructor unbinds c from the process context of x3
}

There is no new syntax, and the existing communication output primitive serves. Once a channel is sent, an (endpoint) destructor may be called and the channel is unbound.

===== Sending itself =====
A mobile channel may be sent from one process to another along itself, to bind at a new endpoint.

void x4( chanend mobile c )
{
<nowiki>c <: c;</nowiki> // mobile channel endpoint c is sent along channel c,
// its destructor unbinds c from the process context of x4
}

There is no new syntax, and the existing communication output primitive serves. The compiler will cause the channel endpoint to be sent. Once a channel is sent, an (endpoint) destructor may be called and the channel is unbound.

Sending a channel along itself is useful if you consider a master-slave process relationship, in which the master sends a channel to a slave process for servicing and when that slave is done it returns the channel (see 3.2.2 ).

==== Receiving ====
Mobile channels may be received by a destination process from a source, communicated along channels, to bind at a new endpoint.

void y0( chanend d, chanend mobile e ) // e is not bound on entry to y0
{
d :> e; // mobile channel endpoint e is received along channel d,
// when its constructor is called and e is bound
}

There is no new syntax, and the existing communication input primitive serves. The chanend ''e'' is within scope from the local function declaration, ''y0'', but unbound. The chanend ''e'' will be able to receive valid input only after it is itself received in a channel communication. On receipt, an (endpoint) constructor may be called and the channel ''e'' is bound; after which ''e'' is able to receive valid input.

===== Receiving itself =====
Any mobile channel (endpoint) can input to itself. The new input value overwrites the former value with immediate effect.

void y1( chanend d, chanend mobile e ) // e is not bound on entry to y1
{
d :> e; // mobile channel endpoint e is received on d and bound
e :> e; // mobile channel endpoint e is received on e and re-bound
d :> d; // compiler error, received channel is not mobile (or fixed)
}

This allows the compiler to treat channel scope in a consistent way, in an extended variable-like semantics.

=== Protocols ===
As mobile processes and mobile channels are developed and re-used, maintaining correct data exchange between processes can become a source of errors. A ''protocol''<nowiki> can be used to specify the data structure that is communicated over a channel. This can be used with both mobile and plain (non-mobile) channels to enable compiler checking for data exchange. The idea is based on the protocol found in Occam 2.1 [</nowiki>5], or perhaps more like Pascal records.

==== Channel context ====
A protocol can be used in the context of a channel and chanends.

===== Channel protocol =====
A channel is qualified with a protocol by specifying a data structure. This provides a guide to the compiler for binding channel endpoints.

chan c0:int; // c0 is a channel qualified with a simple protocol

A mobile channel can be similarly qualified with a protocol.

chan mobile c1:int; // c1 is a mobile channel qualified with a protocol

The protocol data structure is a container, which is a sequence of data types. A simple protocol contains a single (scalar) data type, such as c0 and c1 above. A complex protocol contains more than one data type in a sequence.

chan c2:int:char; // c2 is a channel which communicates a complex protocol

While the definition of a protocol shares similarities with a structure (or class), its elements are not named and cannot be communicated independently of each other.

===== Chanend protocol =====
A channel endpoint (mobile or otherwise) can be bound with a protocol.

void x0( chanend c:int ) // c is bound on entry to x0 by a protocol
{
}

The compiler shall perform static checks on the protocol data type consistency of a channel declaration, its binding to chanends, and its use within process and function scope.

==== Protocol types ====
A protocol is a type of sequence, named using the ''protocol'' keyword.

protocol p0 // p0 is a named protocol
{
int:char; // p0 is a sequence of int then char
}

Once a named protocol type is defined, it can be used to qualify a channel or a chanend.

chan c3:p0; // c3 uses a complex protocol of type p0

===== Protocol case =====
A protocol can be constructed by embedding cases to form a named case protocol.

protocol p1 // p1 is a named case protocol
{
case int:char; // p1 is a sequence of either int then char,
case int:int; // or int then int;
case void; // or default cases
}

The void case supports default processing when no receiving pattern match is wanted; it cannot be sent.

===== Protocol array types =====
One or more variables of the same type may be combined to form an array.

protocol p2
{
<nowiki>case unsigned char[10];</nowiki> // p2 is a sequence of 10 unsigned chars,
<nowiki>case int:char[2];</nowiki> // or an int then 2 chars

}

===== Ambiguity =====
The compiler may raise a warning or an error if a protocol definition is potentially ambiguous.

protocol p3
{
case int:char;
case int; // compiler warning, potential protocol ambiguity

}

Static ambiguity occurs when more than one receive case cannot be uniquely decided. A protocol is unambiguous when outputting on a channel bound to a protocol.

==== Sending ====
Data is sent along channels bound to a protocol using the usual mechanism, with a small extension for sending sequences. The compiler will check the data type sequence used occurs in the channel protocol definition.

void x5( chanend mobile c:p3 )
{
int v;
char w;
<nowiki>c <: v,w;</nowiki> // v,w is a sequence of int:char, a case in protocol p3
<nowiki>c <: w;</nowiki> // compiler error, no such case in protocol
}

==== Receiving ====
Data is received along channels bound to a protocol using the channel input mechanism of XC. The compiler will check all possible protocol cases are provided for. For an unnamed protocol a select statement is not required; where one is required for a named case protocol.

void y2( chanend d:p2 )
{
int v;
<nowiki>unsigned char w[10];</nowiki>
select
{
case d :> w; <nowiki>// w matches unsigned char[10] found in p3</nowiki>
case d :> v:w; <nowiki>// v:w matches with the sequence int:char[2] in p3</nowiki>
}
}

<nowiki>In the second case for function y2, type int:char[2] is found in p3 and this is allowed because v:w of type int:char[10] can contain the received data correctly. If the compiler enforces strict type checking then v:w would not match int:char[2], in both array dimension and unsigned-ness. </nowiki>

===== Ambiguous receive =====
void y3( chanend mobile e:p3 )
{
int v;
char w;
select
{
case e :> v,w; // v,w is a sequence of int:char found in p3
case e :> v; // int is found in p3, but possibly
} // compiler error, select statement with ambiguous protocol
}

In the case of y3, the compiler cannot determine if more data is expected after the leading int and therefore cannot distinguish the case.

===== Default receive =====
When a case protocol is defined with a void case, a receiving function can provide a default case for un-matched entries. This allows functions to match a subset of the protocol cases, and discard all others.

void y4( chanend mobile e:p1 )
{
int v;
char w;
select
{
case e :> v,w; // v and w contain input values
case void
{
// handle all other input cases (no values known)
}
}
}

Without a default case, the compiler would generate an error for un-handled protocol cases in y4.

If within a source file the scope of a protocol is fully contained and any particular case is never sent, then an omitted receive case can be cast away silently or just issued with a warning. This is allowed because the suspect case will never be communicated.

= Design patterns =
Several design patterns can illustrate how to use mobile processes and channels. These also provide a further insight into the extended PiXC syntax and its meaning.

== Mobile processes ==
Mobile processes allow services to migrate, such that the program control flow is changed. But for such powerful concepts, they are actually fairly simple building blocks. A crucial concept of processes is statefulness, so that even after migrating (from one hardware processor to another) they can resume where they left off.

=== State machine pattern ===
The state machine pattern is used to enable a mobile process to resume execution after migrating. There are no special constructs required for a state machine; rather, a design pattern using a static variable with process-qualified scope serves.

mobile void p0( chanend out, chanend in )
{
static int p0_state = 0;
switch( p0_state )
{
case 0 :
{
}
break;
...
default :
{
}
}
}

=== Roaming pattern ===
In the roaming pattern, mobile processes migrate between contexts as a function of their data- or event-driven processing. Here, ''roam0'' is a function in some process context.

void roam0( chanend c, chanend i, chanend o )
{
int t = 1; // initially assume task 1
c :> p1( o, i ); // wait to receive mobile process p1
for( ; t > 0; )
{
// calculate next task, t, on p1 state
switch( t )
{
case 1:
{
// perform task t1, interacting with p1
}
break;
...
default :
{
// not a task for roam0 in this context
<nowiki>c <: p1( o, i );</nowiki> // migrate mobile process p1
t = 0; // exit loop
}
}
}
}

== Mobile channels ==
Mobile channels allow data to be shared by processes such that the program data flow follows data event processing. Sharing data allows processes to be small and purposeful, handing over channels (and the data that passes through them) to other processes in turn. This is a powerful concept, in which data flows over a network of inter-connected processes, and yet mobile channels are fairly simple building blocks.

=== Master-Slave pattern ===
In the case of a master-slave process arrangement, each master-slave share a ''control'' channel over which will be communicated a ''data'' channel. A seperate source process outputting on the ''data'' channel does not (need to) know which slave it is connected with. This pattern seperates control flow on fixed channels from the data flow over mobile channels. Note master initially binds mobile channel data, before it is able to send it; the compiler checks each chanend is fixed or initially bound once.

chan controlA, controlB;
chan mobile data;

par
{
source( data );
master( controlA, controlB, data );
slaveA( controlA, data );
slaveB( controlB, data );
}

void master( chanend A, chanend B, chanend mobile:b D )
{
<nowiki>A <: D;</nowiki> // give data channel D endpoint to slaveA
A :> D; // take data channel D endpoint from slaveA
<nowiki>B <: D;</nowiki> // give data channel D endpoint to slaveB
B :> D; // take data channel D endpoint from slaveB
}

void slaveA( chanend ctrl, chanend mobile data )
{
ctrl :> data; // wait for a worker channel from master
// process i/o on data
<nowiki>ctrl <: data;</nowiki> // return data to master
}

void slaveB( chanend ctrl, chanend mobile data )
{
ctrl :> data; // wait for a worker channel from master
// process i/o on data
<nowiki>ctrl <: data;</nowiki> // return data to master
}

void source( chanend out ) // out is fixed
{
// perform i/o on out
}

Processes ''master'', ''slaveA'', ''slaveB'' and ''source'' may reside on different processor cores and memories.

=== Self-Send pattern ===
A channel can be received, and when done with, sent along itself to the peer process. This pattern mixes both control flow and data flow on mobile channels. (However, it doesn't do away with the need for a control channel to send the initial mobile endpoint.)

chan controlA, controlB;
chan mobile dandc;

par
{
selfsend( controlA, controlB, dandc, dandc );
slaveA( controlA, dandc );
slaveB( controlB, dandc );
}

void selfsend(
chanend A,
chanend B,
chanend dac0, /* fix endpoint0 of dandc */
chanend mobile:1b dac1 /* specify which endpoint, and initial bind */
)
{
<nowiki>A <: dac1;</nowiki> <nowiki>// give mobile channel dandc[1] to slaveA</nowiki>
<nowiki>// process i/o on dandc[0] with slaveA</nowiki>
dac0 :> dac1; <nowiki>// receive mobile channel into dandc[1]</nowiki>
<nowiki>B <: dac1;</nowiki> <nowiki>// give mobile channel dandc[1] to slaveB</nowiki>
<nowiki>// process i/o on dandc[0] with slaveB</nowiki>
dac0 :> dac1; <nowiki>// receive mobile channel into dandc[1]</nowiki>
}

void slaveA( chanend ctrl, chanend mobile dac )
{
ctrl :> dac; // wait for a mobile channel from master
// process i/o on dac
<nowiki>dac <: dac;</nowiki> // return dac
}

void slaveB( chanend mlink, chanend mobile c )
{
ctrl :> dac; // wait for a mobile channel from master
// process i/o on dac
<nowiki>dac <: dac;</nowiki> // return dac
}

<nowiki>The two endpoints dandc[0] and dandc[1] are identified, in this case by explicitly binding dac1 to </nowiki>chanend mobile:1<nowiki> so that defacto the compiler will bind the remaining endpoint dandc[0] to dac0 which also happens to be fixed. The endpoint dac1 is also initially bound to </nowiki>''selfsend''. The processes ''master'', ''slaveA'' and ''slaveB'' may reside on different processors.

=== Pipeline pattern ===
The pipeline pattern is analogous to data passing through a processor pipeline. In this pattern for mobile channels, data passes through a set of processes by communicating a mobile channel between them. When it holds the mobile channel each process performs some function(s) on the data input from it, before deciding which process is next to receive the mobile channel. Unlike a static arrangement, the sequence of processes does not have to be pre-determined.

A variation on the master-slave pattern, prior to returning the mobile channel, each slave first sends a value along it to identify which slave process should be the next receiver.

chan controlA, controlB;
chan mobile data;

par
{
pipeline( controlA, controlB, data, data );
slaveA( controlA, data );
slaveB( controlB, data );
}

void pipeline( chanend A, chanend B, chanend D0, chanend mobile:b1 D1 )
{
int v = 0; <nowiki>// initially send server channel D[1] to slaveA</nowiki>
for( ;; )
{
switch( v )
{
case 0:
{
<nowiki>A <: D1;</nowiki> <nowiki>// give server channel D[1] to slaveA</nowiki>
}
break;
case 1:
{
<nowiki>B <: D1;</nowiki> <nowiki>// give server channel D[1] to slaveB</nowiki>
}
break;
}

<nowiki>// process i/o on D[0] with slave</nowiki>

D0 :> v; // identity of next slave to receive mobile channel
D0 :> D1; <nowiki>// receive mobile channel into D[1]</nowiki>
}
}

void slaveA( chanend ctrl, chanend mobile d )
{
int v = 1; // default next process identity
for( ;; )
{
ctrl :> d; // wait for a worker channel from master

// process i/o on d

// calculate v, identity of next receiving process
<nowiki>d <: v;</nowiki> // send identity of next process in pipeline
<nowiki>d <: d;</nowiki> // return d
}
}

void slaveB( chanend ctrl, chanend mobile d )
{
int v = 0; // default next process identity
for( ;; )
{
ctrl :> d; // wait for a worker channel from master

// process i/o on d

// calculate v, identity of next receiving process
<nowiki>d <: v;</nowiki> // send identity of next process in pipeline
<nowiki>d <: d;</nowiki> // return d
}
}

= Semantics =
== Informal meaning ==
The semantics of PiXC can be informally presented, to better understand certain implementation issues.

=== Mobile context ===
The x::y mobile context for member variables and functions serves as a convenience to denote compiler semantics for mobile processes. It is not parsed as input syntax, and the programmer would not write it. The mobile context for processes does not extend beyond data and function encapsulation, constructors and destructors.

==== Minimal impact ====
<nowiki>Section A.3 of Programming XC [</nowiki>2], names and storage, helps to estimate the likely cost of extensions. PiXC should impose the minimal set of changes on XC, that do what is needed.

==== Non-explicit ====
It is not necessary to introduce (C++-style) classes or namespaces or to explicate a mobile context, and would increase what the XC compiler would have to do anew. Namespaces provide a context for symbols, and group related functions and data spread over several source files or libraries.

==== Issues ====
A mobile context is needed for the XC compiler to allocate storage space for mobile processes, which are long-lived and can migrate. A mobile context solves several implementation issues, including memory map, liveness, coherency and scalability, amongst others.

===== Memory Maps =====
The PiXC compiler should generate mobile process object code exactly once. During compilation global variables (or memory allocated to hold them) are fixed offset from dp (register 13). If a mobile context for member variables were omitted, then either:

* the memory maps of different processors would have to be made the same, in order for the common mobile process object code to access member variables,which is wasteful, or
* the object code would need to be compiled seperately for each processor, in order to access member variables in the different memory maps, which is also wasteful.

By using a mobile context, the compiler can offset member variables with respect to another register, say r11, per thread; or the compiler could treat member variables like far pointers, and go through a jump table; or another method could be used.

===== Liveness =====
A mobile process is constructed when it is received by a process. Similarly it is destructed when it is sent by a process. If a mobile context for member variables were omitted, each variable would need a 'lifetime' guard, which would need testing, on each and every access by a non-mobile process.

===== Coherency =====
When a process migrates from a source to a destination processor, its destination data members need to store the values already calculated in the source processor. If a mobile context for member variables were omitted, overwriting them when a mobile is received at the destination processor would appear as a corruption to other processes running on the destination processor.

And running on the new destination processor, changes written by the mobile process to global data would not be visible to other processes running on the original source processor.

The Hoare/Dijkstra multiple-update solution requires a guard on sharedglobal data; accessing a global from parallel processes is guarded in XC at compile time, so only one thread is permitted to write to a global. A mobile context gives a dynamic alternative to this solution.

===== Scalability =====
PiXC should provide for the future when mobility is extended to heterogenous networks, to avoid the need to change or break existing programs or language features. Using a mobile context solves mobility problems generally, which should scale up to heterogenous processor networks.

= Case Studies =
Case studies provide more in-depth examples of mobile processes and channels.

== Ethernet ==
<nowiki>The Ethernet case study extends the example in chapter 6.5 of XMOS Programming XC [</nowiki>2]. Changes to the extended source code are deliberately kept as few as possible, for ease of drawing a direct comparison.

<nowiki>This case study shows how 2 mobile process transmit clients can share the single ethernet driver without conflict, that mobile processes can act like a semaphore over multiple processors, and member variable state is maintained over mobility. First the text book [</nowiki>2] code is given (with corrections, and including a dummy program) and second extended versions are given; one with mobile processes and the other using mobile channels.

=== Basic program ===
/*
<nowiki>* Programming XC chapter 6.5</nowiki>
<nowiki>* </nowiki>
<nowiki>* A single thread on an XS1 device can be used to implement a full duplex </nowiki>
<nowiki>* </nowiki> <nowiki>100Mbps Ethernet Media Independent Interface (MII) protocol [2]. This </nowiki>
<nowiki>* </nowiki> protocol implements the data transfer signals between the link layer and
<nowiki>* </nowiki> physical device (PHY).
<nowiki>* </nowiki>
<nowiki>* The signals are as follows:</nowiki>
<nowiki>* </nowiki> TXCLK is a free running 25MHz clock generated by the PHY.
<nowiki>* </nowiki> TXEN is a data valid signal driven high by the transmitter during frame
<nowiki>* </nowiki> transmission.
<nowiki>* </nowiki> TXD carries a nibble of data per clock period from the transmitter to
<nowiki>* </nowiki> the PHY.
<nowiki>* </nowiki> RXCLK is a free running clock generated by the PHY.
<nowiki>* </nowiki> RXDV is a data valid signal driven high by the PHY during frame
<nowiki>* </nowiki> transmission.
<nowiki>* </nowiki> RXD carries a nibble of data per clock period from the PHY to the
<nowiki>* </nowiki> receiver.
<nowiki>* </nowiki>
<nowiki>* The transmitter starts by sending a preamble of nibbles of value 0x5,</nowiki>
<nowiki>* </nowiki> followed by two nibbles of values 0x5 and 0xD. The data, which must be in
<nowiki>* </nowiki> the range of 64 to 1500 bytes, is then transmitted, least significant bit
<nowiki>* </nowiki> first, followed by four bytes containing a CRC.
<nowiki>*/</nowiki>

'''<nowiki>#include</nowiki>'''<nowiki> <xs1.h></nowiki>

'''<nowiki>#define</nowiki>''' MORE 0
'''<nowiki>#define</nowiki>''' DONE 1

/* The port TXD performs a 32-to-4 bit serialisation of data onto its pins.
<nowiki>* </nowiki> It is synchronised to the 1-bit port TXCLK and uses the 1-bit port TXEN
<nowiki>* </nowiki> as a ready-out strobe signal that is driven high whenever data is
<nowiki>* </nowiki> driven. <nowiki>*/</nowiki>
'''static''' '''port''':32 '''out''' '''buffered''' TXD = XS1_PORT_4B;
'''static''' '''port''' '''out''' TXEN = XS1_PORT_1K;
'''static''' '''port''' '''in''' TXCLK = XS1_PORT_1J;
'''static''' '''port''' '''in''' TXER = XS1_PORT_1L;

/* The port RXD performs a 4-to-32-bit deserialisation of data from its
<nowiki>* </nowiki> pins.
<nowiki>* </nowiki> It is synchronised to the 1-bit port RXCLK and uses the 1-bit port RXDV
<nowiki>* </nowiki> as a ready-in strobe signal that causes data to be sampled only when
<nowiki>* </nowiki> the strobe is high.
<nowiki>*/</nowiki>
'''static''' '''port''':32 '''in''' '''buffered''' RXD = XS1_PORT_4A ;
'''static''' '''port''' '''in''' RXDV = XS1_PORT_1I ;
'''static''' '''port''' '''in''' RXCLK = XS1_PORT_1H ;
'''static''' '''port''' '''out''' RXER = XS1_PORT_1G;

'''static''' '''clock''' clktx = XS1_CLKBLK_1;
'''static''' '''clock''' clkrx = XS1_CLKBLK_2;

'''static''' '''int''' txerr = 0;
'''static''' '''int''' rxerr = 0;

/* In this configuration, the processor has only to output data once every
<nowiki>* </nowiki> eight clock periods and does not need to explicitly output the data valid
<nowiki>* </nowiki> signal.
<nowiki>* </nowiki> miiConfigTransmit defines and configures the ports in this way.
<nowiki>*/</nowiki>
'''static''' '''void''' '''miiConfigTransmit'''(
'''clock''' clk,
'''in''' '''port''' TXCLK,
'''buffered''' '''out''' '''port''':32 TXD,
'''out''' '''port''' TXEN,
'''in''' '''port''' TXER
)
{
'''configure_clock_src'''( clk, TXCLK ); /* TXCLK provides edges for clk */
'''configure_out_port'''( TXD, clk, 0 ); /* TXD clocked by clk, initially 0 */
'''configure_out_port'''( TXEN, clk, 0 ); /* TXEN clocked by clk, initially 0 */

/* TXD to drive TXEN high whenever data is output; initial output 0;
<nowiki>* the strobe remains 1 for sizeof( TXD ) clocks */</nowiki>
'''configure_out_port_strobed_master'''( TXD, TXEN, clk, 0 );

TXER :> txerr; /* initial state of TXER */

start_clock( clk );
}

/* In this configuration, the port can sample eight values before the data
<nowiki>* </nowiki> must be input by the processor, and the processor does not need to
<nowiki>* </nowiki> explicitly wait for the data valid signal.
<nowiki>* miiConfigReceive defines and configures the ports in this way.</nowiki>
<nowiki>*/</nowiki>
'''static''' '''void''' '''miiConfigReceive'''(
'''clock''' clk,
'''in''' '''port''' RXCLK,
'''buffered''' '''in''' '''port''':32 RXD,
'''in''' '''port''' RXDV,
'''out''' '''port''' RXER
)
{
'''configure_clock_src'''( clk, RXCLK ); /* RXCLK provides edges for clk */
'''configure_in_port'''( RXD, clk ); /* RXD clocked by clk */
'''configure_in_port'''( RXDV, clk ); /* RXDV clocked by clk */

/* RXD to drive RXDV high whenever data is output;
<nowiki>* the strobe remains 1 for sizeof( TXD ) clocks */</nowiki>
'''configure_in_port_strobed_slave'''( RXD, RXDV, clk );

rxerr = 0;
<nowiki>RXER <: rxerr; </nowiki> /* clear RXER */

start_clock( clk );
}

/* Configure the receive and transmit ports to the PHY device
<nowiki>*/</nowiki>
'''void''' '''miiConfigRxTx'''( '''void''' )
{
miiConfigReceive( clkrx, RXCLK, RXD, RXDV, RXER );
miiConfigTransmit( clktx, TXCLK, TXD, TXEN, TXER );
}

/* miiTransmitFrame takes frame data from another thread and outputs it to
<nowiki>* </nowiki> the MII ports. For simplicity, the error signals and CRC are ignored.
<nowiki>* </nowiki>
<nowiki>* It first inputs from the channel c the size of the frame in bytes. It then</nowiki>
<nowiki>* </nowiki> outputs a 32-bit preamble to TXD, which is driven on the pins as nibbles
<nowiki>* </nowiki> over eight clock periods. On each iteration of the for loop, the next 32
<nowiki>* </nowiki> bits of data are then output to TXD for serialising onto the pins. This
<nowiki>* </nowiki> gives the processor enough time to get around the loop before the next
<nowiki>* </nowiki> block of data must be driven.
<nowiki>*/</nowiki>
'''void''' '''miiTransmitFrame'''(
'''out''' '''buffered''' '''port''':32 TXD,
'''streaming''' '''chanend''' c
)
{
'''int''' numBytes;
'''int''' tailBytes;
'''int''' tailBits;
'''int''' data;

/* Input size of next packet */
c :> numBytes;
tailBytes =( numBytes / 4 );
tailBits =( tailBytes * 8 );

/* Output row of 0x5s followed by 0xD (little endian) */
<nowiki>TXD <: 0xD5555555;</nowiki>

/* Output complete 32-bit words for serialisation */
'''for'''( '''int'''<nowiki> i=0; i <( numBytes - tailBytes ); i+=4 )</nowiki>
{
c :> data; /* input data from client thread */
<nowiki>TXD <: data;</nowiki>
}

/* Output partial 32-bits of data for serialisation */
'''if'''( 0 != tailBits )
{
c :> data; /* input data from client thread */

/* Output the remaining bits of data that represent valid frame data */
partout( TXD, tailBits, data ); /* __builtin partout( ) */
}
}

/* miiReceiveFrame receives a single error-free frame and outputs it to
<nowiki>* </nowiki> another thread. For simplicity, the error signal and CRC are ignored.
<nowiki>* </nowiki>
<nowiki>* The processor waits for the last nibble of the preamble (0xD) to be </nowiki>
<nowiki>* </nowiki> sampled by the port RXD. The actual data is then received, which is in
<nowiki>* </nowiki> the range of 64 to 1500 bytes, least significant nibble first, followed
<nowiki>* </nowiki> by four bytes containing a CRC. On each iteration of the loop, it waits
<nowiki>* </nowiki> for either next eight nibbles of data to be sampled for input by RXD or
<nowiki>* </nowiki> for the data valid signal RXDV to go low.
<nowiki>* </nowiki>
<nowiki>* XS1 devices provide a single-entry buffer up to 32-bits wide and a 32-bit </nowiki>
<nowiki>* </nowiki> shift register, requiring up to 64 bits of data being input over two
<nowiki>* </nowiki> input statements once the data valid signal goes low.
<nowiki>*/</nowiki>
'''void''' '''miiReceiveFrame'''(
'''in''' '''buffered''' '''port''':32 RXD,
'''in''' '''port''' RXDV,
'''streaming''' '''chanend''' c
)
{
'''int''' dataValid;
'''int''' data;
'''int''' tail; /* stores bit-count in last received part-word */

/* Wait for start of frame */
RXD '''when''' pinseq( 0xD ):> '''void'''<nowiki>;</nowiki>
RXDV :> dataValid;

/* Receive frame data /crc */
'''do'''
{
'''select'''
{
'''case''' RXD :> data :
{
/* Input next 32 bits of data */
<nowiki>c <: MORE; </nowiki> /* indicate to receiving thread, more data follows */
<nowiki>c <: data; </nowiki> /* send next data word to receiving thread */
}
'''break'''<nowiki>;</nowiki>

'''case''' RXDV '''when''' pinseq( 0 ):> dataValid :
{
/* An effect of using a port’s serialisation and strobing
<nowiki>* </nowiki> capabilities together is that the ready-in signal may go low
<nowiki>* </nowiki> before a full transfer width’s worth of data is received.
<nowiki>* Input any bits remaining in port. </nowiki>
<nowiki>*/</nowiki>
tail = endin( RXD ); /* __builtin endin( ) */

/* send remaining data words to receiving thread */
'''for'''( '''int''' byte =( tail >> 3 ); byte > 0; byte -= '''sizeof'''( '''int''' ))
{
RXD :> data;
<nowiki>c <: MORE;</nowiki>
<nowiki>c <: data;</nowiki>
}

/* indicate to receiving thread, end of data and how many bits are
<nowiki>* </nowiki> valid in the last word */
<nowiki>c <: DONE ;</nowiki>
<nowiki>c <: tail >> 3;</nowiki>
}
'''break''' ;
}
}
'''while'''( 0 != dataValid );
}

/* Dummy program follows *************************************
<nowiki>*/</nowiki>

/* txClient dummy
<nowiki>*/</nowiki>
'''void''' '''txClient'''( '''chanend''' '''streaming''' c )
{
'''static''' '''const''' '''int'''<nowiki> dataOut[ ]={ 'H', 'e', 'l', 'l', 'o' };</nowiki>
'''static''' '''int''' runCount = 0;

{
<nowiki>c <:( </nowiki>'''sizeof'''( dataOut )/ '''sizeof'''<nowiki>( dataOut[ 0 ]));</nowiki>
'''for'''( '''int'''<nowiki> i=0; i < </nowiki>'''sizeof'''( dataOut ); i++ )
{
<nowiki>c <: dataOut[ i ];</nowiki>
}

runCount++;
}
}

/* rxClient dummy
<nowiki>*/</nowiki>
'''void''' '''rxClient'''( '''chanend''' '''streaming''' c )
{
'''static''' '''int'''<nowiki> buf[ 1500 ];</nowiki>
'''int''' todo;
'''int''' validBits;

'''for'''( '''int'''<nowiki> i=0; i < </nowiki>'''sizeof'''( buf ); i++ )
{
c :> todo;
'''switch'''( todo )
{
'''case''' MORE :
{
<nowiki>c :> buf[ i ];</nowiki>
}
'''break'''<nowiki>;</nowiki>

'''case''' DONE :
{
c :> validBits;
i = '''sizeof'''( buf ); /* exit loop */
}
'''break'''<nowiki>;</nowiki>

'''default''' :
{
/* protocol breakdown */
i = '''sizeof'''( buf ); /* exit loop */
}
'''break'''<nowiki>;</nowiki>
}
}

'''if'''( DONE != todo )
{
/* protocol failure, or ran out of buffer space */
}
}

/* Run the drivers and dummy client threads in parallel
<nowiki>*/</nowiki>
'''int''' '''main'''( '''void''' )
{
'''chan''' '''streaming''' txc;
'''chan''' '''streaming''' rxc;

miiConfigRxTx( );

'''par'''
{
'''while'''( ! txerr )
{
'''par'''
{
miiTransmitFrame( TXD, txc );
txClient( txc );
}
}
'''while'''( ! rxerr )
{
'''par'''
{
miiReceiveFrame( RXD, RXDV, rxc );
rxClient( rxc );
}
}
}

'''return'''( txerr + rxerr );
}

=== Mobile processes ===
/*
<nowiki>* PiXC version of Programming XC chapter 6.5 using mobile processes</nowiki>
<nowiki>* </nowiki>
<nowiki>* ... rest of header as </nowiki>''' 5.1.1 '''
<nowiki>*/</nowiki>

'''<nowiki>#include</nowiki>'''<nowiki> <xs1.h></nowiki>

'''<nowiki>#define</nowiki>''' MORE 0
'''<nowiki>#define</nowiki>''' DONE 1

/* Because mobile processes names are bound on receiving, we use a simple
<nowiki>* </nowiki> protocol enum to allow a random selection for receipt.
<nowiki>*/</nowiki>
'''typedef''' '''enum'''
{
''CLIENTA'' = 0,
''CLIENTB'' = 1
} CLIENT_ID;

... port definitions as ''' 5.1.1 '''
'''... clock definitions as 5.1.1 '''

'''static''' '''int''' txerr = 0;
'''static''' '''int''' rxerr = 0;

... '''miiConfigTransmit as 5.1.1 '''
... '''miiConfigReceive as 5.1.1 '''
'''... miiConfigRxTx as 5.1.1 '''
... '''miiTransmitFrame as 5.1.1 '''
... '''miiReceiveFrame as 5.1.1 '''

/* Dummy program follows *************************************
<nowiki>*/</nowiki>

/* txClient dummy
<nowiki>* </nowiki>
<nowiki>* Chanends txaIn and txaOut are fixed (or bound)</nowiki>
<nowiki>*/</nowiki>
mobile '''void''' '''txClientA'''( '''chanend''' txaOut, '''chanend''' txaIn )
{
'''static''' '''const''' '''int'''<nowiki> dataOut[ ]={ 'H', 'e', 'l', 'l', 'o', ' ', 'A' };</nowiki>
'''static''' '''int''' runCount = 0; /* mobile process member variable */

{
<nowiki>txaOut <: </nowiki>'''sizeof'''( dataOut );
'''for'''( '''int'''<nowiki> i=0; i < </nowiki>'''sizeof'''( dataOut ); i++ )
{
<nowiki>txaOut <: dataOut[ i ];</nowiki>
}

runCount++; /* member variable maintained over mobility */
}
}

/* txClient dummy
<nowiki>* </nowiki>
<nowiki>* Chanends txbIn and txbOut are fixed (or bound)</nowiki>
<nowiki>*/</nowiki>
mobile '''void''' '''txClientB'''( '''chanend''' txbOut, '''chanend''' txbIn )
{
'''static''' '''const''' '''int'''<nowiki> dataOut[ ]={ 'H', 'e', 'l', 'l', 'o', ' ', 'B' };</nowiki>
'''static''' '''int''' runCount = 0; /* mobile process member variable */

{
<nowiki>txbOut <: </nowiki>'''sizeof'''( dataOut );
'''for'''( '''int'''<nowiki> i=0; i < </nowiki>'''sizeof'''( dataOut ); i++ )
{
<nowiki>txbOut <: dataOut[ i ];</nowiki>
}

runCount++; /* member variable maintained over mobility */
}
}

/* txClient scheduler.
<nowiki>* </nowiki>
<nowiki>* </nowiki> Randomly selects which transmit client is given access to the ethernet
<nowiki>* </nowiki> driver.
<nowiki>* </nowiki> Send the chosen mobile process (context) to main thread.
<nowiki>* </nowiki> Wait for its return.
<nowiki>*/</nowiki>
'''void''' '''txSched'''( chanend ch, mobile txClientA, mobile txClientB )
{
'''timer''' t0; /* timer, used as a random choice */
'''int''' t;

'''for'''( ;; )
{
t0 :> t;
'''if'''( 0x1 & t )
{
<nowiki>ch <: CLIENTA;</nowiki>
<nowiki>ch <: txClientA; </nowiki> /* send mobile process (and lose its context) */
ch :> txClientA; /* receive mobile process bound name (and context) */
}
'''else'''
{
<nowiki>ch <: CLIENTB;</nowiki>
<nowiki>ch <: txClientB; </nowiki> /* send mobile process (and lose its context) */
ch :> txClientB; /* receive mobile process bound name (and context) */
}
}
}

/* rxClient dummy
<nowiki>*/</nowiki>
'''void''' '''rxClient'''( '''chanend''' '''streaming''' c )
{
'''static''' '''int'''<nowiki> buf[ 1500 ];</nowiki>
'''int''' todo;
'''int''' validBits;

'''for'''( '''int'''<nowiki> i=0; i < </nowiki>'''sizeof'''( buf ); i++ )
{
c :> todo;
'''switch'''( todo )
{
'''case''' MORE :
{
<nowiki>c :> buf[ i ];</nowiki>
}
'''break'''<nowiki>;</nowiki>

'''case''' DONE :
{
c :> validBits;
i = '''sizeof'''( buf ); /* exit loop */
}
'''break'''<nowiki>;</nowiki>

'''default''' :
{
/* protocol breakdown */
i = '''sizeof'''( buf ); /* exit loop */
}
'''break'''<nowiki>;</nowiki>
}
}

'''if'''( DONE != todo )
{
/* protocol failure, or ran out of buffer space */
}
}

/* Run the drivers and dummy client threads in parallel
<nowiki>*/</nowiki>
'''int''' '''main'''( '''void''' )
{
'''chan''' '''streaming''' rxc;
'''chan''' sc;
'''chan''' txaIn;
'''chan''' txaOut;
'''chan''' txbIn;
'''chan''' txbOut;
CLIENT_ID id;

miiConfigRxTx( );

'''par'''
{
txSched( sc, txclientA, txClientB ); /* initially bind txclientA, txclientB */

'''while'''( ! txerr )
{
/* Receiving a mobile process (over a channel) is done into a bound
<nowiki>* </nowiki> name and not a free name. Therefore, we first receive and switch
<nowiki>* </nowiki> on a client_id.
<nowiki>*/ </nowiki>
sc :> id;
'''switch'''( id )
{
'''case''' CLIENTA :
{
/* receive mobile process bound name (and its context),
<nowiki>* bind its input and output channel-endpoints to a local </nowiki>
<nowiki>* channel, and it is run as a parallel thread </nowiki>
<nowiki>*/</nowiki>
sc :> txClientA( txaOut, txaIn );
miiTransmitFrame( TXD, txaOut );
/* send mobile process bound name (and lose its context),
<nowiki>* unbind its input and output channel-endpoints from local </nowiki>
<nowiki>* channels, and terminate its thread </nowiki>
<nowiki>*/</nowiki>
<nowiki>sc <: txClientA( txaOut, txaIn );</nowiki>
}
'''break'''<nowiki>;</nowiki>

'''case''' CLIENTB :
{
/* receive mobile process bound name (and its context),
<nowiki>* bind its input and output channel-endpoints to a local </nowiki>
<nowiki>* channel, and it is run as a parallel thread </nowiki>
<nowiki>*/</nowiki>
sc :> txClientB( txbOut, txbIn );
miiTransmitFrame( TXD, txbOut );
/* send mobile process bound name (and lose its context),
<nowiki>* unbind its input and output channel-endpoints from local </nowiki>
<nowiki>* channels, and terminate its thread </nowiki>
<nowiki>*/</nowiki>
<nowiki>sc <: txClientB( txbOut, txbIn );</nowiki>
}
'''break'''<nowiki>;</nowiki>
}
}

'''while'''( ! rxerr )
{
'''par'''
{
miiReceiveFrame( RXD, RXDV, rxc );
rxClient( rxc );
}
}
}

'''return'''( txerr + rxerr );
}

=== Mobile channels ===
/*
<nowiki>* PiXC version of Programming XC chapter 6.5 with mobile channels</nowiki>
<nowiki>* </nowiki>
<nowiki>* ... rest of header as </nowiki>''' 5.1.1 '''
<nowiki>*/</nowiki>

'''<nowiki>#include</nowiki>'''<nowiki> <xs1.h></nowiki>

'''<nowiki>#define</nowiki>''' MORE 0
'''<nowiki>#define</nowiki>''' DONE 1

'''<nowiki>#define</nowiki>''' mobile /* _ONLY_ to produce more insightful PiXC compilation reports <nowiki>*/</nowiki>

/* Because mobile processes names are bound on receiving, we use a simple
<nowiki>* </nowiki> protocol enum to allow a random selection for receipt.
<nowiki>*/</nowiki>
'''typedef''' '''enum'''
{
''CLIENTA'' = 0,
''CLIENTB'' = 1
} CLIENT_ID;

... port definitions as ''' 5.1.1 '''
'''... clock definitions as 5.1.1 '''

'''static''' '''int''' txerr = 0;
'''static''' '''int''' rxerr = 0;

... '''miiConfigTransmit as 5.1.1 '''
... '''miiConfigReceive as 5.1.1 '''
'''... miiConfigRxTx as 5.1.1 '''
... '''miiTransmitFrame as 5.1.1 '''
... '''miiReceiveFrame as 5.1.1 '''

/* Dummy program follows *************************************
<nowiki>*/</nowiki>

/* txClient dummy with fixed channels
<nowiki>*/</nowiki>
'''void''' '''txClientA'''( '''chanend''' txaOut, '''chanend''' txaIn )
{
'''static''' '''const''' '''int'''<nowiki> dataOut[ ]={ 'H', 'e', 'l', 'l', 'o', ' ', 'A' };</nowiki>
'''static''' '''int''' runCount = 0; /* mobile process member variable */

{
<nowiki>txaOut <: </nowiki>'''sizeof'''( dataOut );
'''for'''( '''int'''<nowiki> i=0; i < </nowiki>'''sizeof'''( dataOut ); i++ )
{
<nowiki>txaOut <: dataOut[ i ];</nowiki>
}

runCount++;
}
}

/* txClient dummy with fixed channels
<nowiki>*/</nowiki>
'''void''' '''txClientB'''( '''chanend''' txbOut, '''chanend''' txbIn )
{
'''static''' '''const''' '''int'''<nowiki> dataOut[ ]={ 'H', 'e', 'l', 'l', 'o', ' ', 'B' };</nowiki>
'''static''' '''int''' runCount = 0; /* mobile process member variable */

{
<nowiki>txbOut <: </nowiki>'''sizeof'''( dataOut );
'''for'''( '''int'''<nowiki> i=0; i < </nowiki>'''sizeof'''( dataOut ); i++ )
{
<nowiki>txbOut <: dataOut[ i ];</nowiki>
}

runCount++;
}
}

/* txClient scheduler.
<nowiki>* </nowiki>
<nowiki>* </nowiki> Randomly selects which transmit client is given access to the ethernet
<nowiki>* </nowiki> driver .
<nowiki>* </nowiki> Initially bound to txaIn, txaOut, txbIn, txbOut.
<nowiki>* </nowiki> Send the chosen mobile process (context) to main thread.
<nowiki>* </nowiki> Wait for its return.
<nowiki>*/</nowiki>
'''void''' txSched(
'''chanend''' ch,
'''chanend''' mobile:b txaIn, /* initially bind txaIn endpoint */
'''chanend''' mobile:b txaOut, /* initially bind txaOut endpoint */
'''chanend''' mobile:b txbIn, /* initially bind txbIn endpoint */
'''chanend''' mobile:b txbOut /* initially bind txbOut endpoint */
)
{
'''timer''' t0; /* timer, used as a random choice */
'''int''' t;

'''for'''( ;; )
{
t0 :> t;
'''if'''( 0x1 & t )
{
<nowiki>ch <: CLIENTA;</nowiki>
<nowiki>ch <: txaIn; </nowiki> /* send mobile channel (and lose chanend) */
<nowiki>ch <: txaOut; </nowiki> /* send mobile channel (and lose chanend) */
ch :> txaIn; /* receive mobile channel (and collect chanend) */
ch :> txaOut; /* receive mobile channel (and collect chanend) */
}
'''else'''
{
<nowiki>ch <: CLIENTB;</nowiki>
<nowiki>ch <: txbIn; </nowiki> /* send mobile channel (and lose chanend) */
<nowiki>ch <: txbOut; </nowiki> /* send mobile channel (and lose chanend) */
ch :> txbIn; /* receive mobile channel (and collect chanend) */
ch :> txbOut; /* receive mobile channel (and collect chanend) */
}
}
}

/* rxClient dummy
<nowiki>*/</nowiki>
'''void''' '''rxClient'''( '''chanend''' '''streaming''' c )
{
'''static''' '''int'''<nowiki> buf[ 1500 ];</nowiki>
'''int''' todo;
'''int''' validBits;

'''for'''( '''int'''<nowiki> i=0; i < </nowiki>'''sizeof'''( buf ); i++ )
{
c :> todo;
'''switch'''( todo )
{
'''case''' MORE :
{
<nowiki>c :> buf[ i ];</nowiki>
}
'''break'''<nowiki>;</nowiki>

'''case''' DONE :
{
c :> validBits;
i = '''sizeof'''( buf ); /* exit loop */
}
'''break'''<nowiki>;</nowiki>

'''default''' :
{
/* protocol breakdown */
i = '''sizeof'''( buf ); /* exit loop */
}
'''break'''<nowiki>;</nowiki>
}
}

'''if'''( DONE != todo )
{
/* protocol failure, or ran out of buffer space */
}
}

/* Run the drivers and dummy mobile process client threads in parallel
<nowiki>*/</nowiki>
'''int''' '''main'''( '''void''' )
{
'''chan''' sc;
'''chan''' '''streaming''' rxc;
CLIENT_ID id;
'''chan''' mobile txaIn; /* mobile chanend un-bound */
'''chan''' mobile txaOut; /* mobile chanend un-bound */
'''chan''' mobile txbIn; /* mobile chanend un-bound */
'''chan''' mobile txbOut; /* mobile chanend un-bound */

miiConfigRxTx( );

'''par'''
{
txClientA( txaOut, txaIn ); /* mobile chanend fixed in definition */

txClientB( txbOut, txbIn ); /* mobile chanend fixed in definition */

/* mobile chanends initially bound in definition of txSched */
txSched( sc, txaIn, txaOut, txbIn, txbOut );

'''while'''( ! txerr )
{
/* Receiving a mobile process (over a channel) is done into a bound
<nowiki>* </nowiki> name and not a free name. Therefore, we first receive and switch
<nowiki>* </nowiki> on a client_id.
<nowiki>*/ </nowiki>
sc :> id;
'''switch'''( id )
{
'''case''' CLIENTA :
{
sc :> txaIn; /* receive mobile chanend (and bind context) */
sc :> txaOut; /* receive mobile chanend (and bind context) */

miiTransmitFrame( TXD, txaOut );

<nowiki>sc <: txaIn; </nowiki> /* send mobile chanend (and unbind context) */
<nowiki>sc <: txaOut; </nowiki> /* send mobile chanend (and unbind context) */
}
'''break'''<nowiki>;</nowiki>

'''case''' CLIENTB :
{
sc :> txbIn; /* receive mobile chanend (and bind context) */
sc :> txbOut; /* receive mobile chanend (and bind context) */

miiTransmitFrame( TXD, txbOut );

<nowiki>sc <: txbIn; </nowiki> /* send mobile chanend (and unbind context) */
<nowiki>sc <: txbOut; </nowiki> /* send mobile chanend (and unbind context) */
}
'''break'''<nowiki>;</nowiki>
}
}

'''while'''( ! rxerr )
{
'''par'''
{
miiReceiveFrame( RXD, RXDV, rxc );
rxClient( rxc );
}
}
}

'''return'''( txerr + rxerr );
}

= Extensions =
The mobile process extensions could be further extended in several ways.

== Mobile context ==
<nowiki>The file-scope static declaration which serves as the mobile context for process member variables and process member functions could be relaxed if the compiler/linker will search through a collection of source files and check for reference calls [hard]. </nowiki>

Or mobile contexts could be incorporated with namespaces. Alternatively and perhaps less pleasingly (as the base language is XC and not XC++), programmers could write fully qualified names for process member variables and functions, along the lines outlined in the previous sections: p0::x<nowiki> [easier]. </nowiki>

== Assignment ==
Mobile channel endpoints are declared in the definition of a containing function; this is for consistency with XC. They extend endpoints with a variable-like semantics. And values are assigned (to a mobile endpoint) as the variable component of a channel input expression.

If chanend was made a proper data type, an equivalent variable-like semantics for mobile chanend binding could be provided through assignment.

void swapchan( chanend control, chanend mobile d1, chanend mobile d2 )
{
chanend mobile c; // a local variable of type chanend, unbound
control :> d1; // bind d1 endpoint by input (constructor)
control :> d2; // bind d2 endpoint by input (constructor)
c = d2; // temporary, bind c by assignment
d2 = d1; // re-bind d2 by assignment
d1 = c; // re-bind d1 by assignment
}

This is safe provided all channel bindings were input to the function through a communication expression.

== Process arrays ==
If the mobile process defines a proper data type then arrays of processes could be declared, sharing a single definition. For example,

mobile<nowiki> void p[8]( chanend out, chanend in );</nowiki>

This provides an array of alike mobile processes, each with independent (member variables) state including local bindable channels, able to roam the processor network looking for work assignment.

== Channel arrays ==
With the introduction of protocols, channel arrays become meaningful. It is not yet clear exactly how they may prove useful, however.

== Heterogenous networks ==
By sending process member variables only, and not code, the mobile model extends to heterogenous processor networks (in which a distinct compiled unit exists for each processor type, e.g. XS-1, ARM7). The requirement for operating in heterogenous processor networks is to transmit the data in a uniform layout, for which XML could be used.

== Mobile algorithms ==
As a general purpose programming language, PiXC can be used to express mobile algorithms; the design patterns given are such an example. The dynamic communication of mobile channels and mobile processes through channels enables the function and data control flow to evolve in response to run-time events. This opens up a sub-branch of computer science research.

= Conclusions =
PiXC is a proposal to extend XC with mobility and to formalise (extensions to) a compiler for PiXC that targets XMOS processors. Syntax and a meaning for mobile processes and mobile channels is given. Certain syntax and semantics are omitted (and others are probably waiting discovery), and those given could yet change in future drafts.

= References =
<nowiki>[</nowiki>1] [http://www.xmos.com/published/xs1_en XMOS XS1 Architecture], May D., 2008

<nowiki>[</nowiki>2] [http://www.xmos.com/published/xc_en Programming XC on XMOS devices], Watt D., 2009

<nowiki>[</nowiki>3] [http://portal.acm.org/citation.cfm?id=359576.359585#abstract Communicating Sequential Processes], Hoare C.A.R., C.ACM 21(8) pp:666-677, 1978.

<nowiki>[</nowiki>4] [http://en.wikipedia.org/wiki/Communicating_sequential_processes Communicating Sequential Processes], Hoare C.A.R., Prentice Hall, 1985.

<nowiki>[</nowiki>5] [http://en.wikipedia.org/wiki/Occam_(programming_language) Occam Programming Manual]<nowiki>, INMOS Limited, Prentice Hall, 1984. [See also </nowiki>[http://wotug.org/occam/ Occam2], 1988]

<nowiki>[</nowiki>6] [http://books.google.co.uk/books?id=rT05AAAAIAAJ&pg=PA343&lpg=PA343&dq=transputer+transistor+computer&source=bl&ots=7T5oM1avV9&sig=Od6ckIjVgQBH8T2OaBvvA2ihNlY&hl=en&ei=caIRSq2CNJnNjAe31dnkCA&sa=X&oi=book_result&ct=result&resnum=7#v=onepage&q=transputer%20transistor%20computer&f=false The Transputer], Barron I., 1978.

<nowiki>[</nowiki>7] [http://en.wikipedia.org/wiki/Transputer Transputer Reference Manual], INMOS Limited, Prentice Hall, 1988.

<nowiki>[</nowiki>8] [http://www.cs.kent.ac.uk/projects/ofa/kroc/ Kent Relocatable Occam Compiler], [http://www.cs.kent.ac.uk/research/groups/sys/kroc.html University of Kent]

<nowiki>[</nowiki>9] [https://www.cs.kent.ac.uk/research/groups/plas/wiki/OccamPiReference/ Occam-pi], [http://www.cs.kent.ac.uk/pubs/2003/1721/content.ps RmoX], [http://frmb.org/pubs/qm-occampi-rmox.pdf Occam-pi and RMoX], [http://www.cs.kent.ac.uk/research/groups/sys/kroc.html University of Kent]

<nowiki>[</nowiki>10] [http://www.cs.kent.ac.uk/pubs/2004/1969/content.pdf Communicating Mobile Processes], [http://www.cs.kent.ac.uk/projects/ofa/kroc/csp-model-cpa2008.pdf Communicating Mobile Channels], [http://www.cs.kent.ac.uk/research/groups/sys/kroc.html University of Kent]

<nowiki>[</nowiki>11] [http://en.wikipedia.org/wiki/Calculus_of_communicating_systems Communication and Concurrency], Milner R., [http://www.pearsoned.co.uk/Student/detail.asp?item=100000000010554 Prentice Hall]<nowiki>, 1989. [see also Calculus of Communicating Systems, Milner A.J.R., Springer Verlag LNCS 92, 1980.] </nowiki>

<nowiki>[</nowiki>12] [http://en.wikipedia.org/wiki/Pi_calculus pi-Calculus], Milner R., [http://www.cambridge.org/uk/catalogue/catalogue.asp?isbn=9780521658690 Cambridge], 1999.

XOSIG IoI

Jhrose — Sat, 26 Jun 2010 14:30:02 GMT

Jhrose: XOSIG Index Of Ideas

= XOSIG Index of Ideas =
Copyright © XMOSlinkers jhrose, 2009-2010. Version 0.3.1. These notes are distributed with the [http://www.gnu.org/copyleft/fdl.html FSF Free Documentation License version 1.3] as a community work.

= Introduction =
XOSIG provides a forum covering all theoretical and practical aspects of operating systems relating to XMOS technology.

== Aims ==
These notes aim to outline substantive ideas within XOSIG, providing a first port-of-call to locate projects and those involved with them. Each may be expanded upon in related projects and their references.

== Summary ==
<nowiki>XMOS processors such as the XS-1 core [</nowiki>4.1<nowiki>] equip system designers with process-oriented hardware and software building blocks, not unlike the INMOS Transputer cores which predated them. An XMOS XS-1 is a multi-core processor, each core with its own memory and i/o links [</nowiki>4.1<nowiki>]. The cores embed support for a number of services commonly provided by an operating system on general purpose processors, including multi-threading, communication, general purpose i/o, and timers. And like INMOS with Occam, XMOS provide a parallel programming language in XC [</nowiki>4.2] which can be considered the Operating System Language of XS-1 processors.

Using XC, an operating system is not a necessity in an system of homogenous XS-1 processors. However, there are a number of Operating System technologies that could be applied to extend the services provided by XS-1 and XC, and those that could be applied to network with heterogenous systems.

== Table of Content ==
Each idea is listed in the table below and linked to a later section of these notes.

{| class="prettytable"
| Project
| Summary
| Status

|-
| 2 XOSS
| XS-1 Operating System Services to extend services provided by XS-1 and XC and to network with heterogenous systems.
| Just an idea

|-
| 3 HyperviXor
| XS-1 as a Hypervisor servicing a number of Concurrent Operating Systems.
| Abandoned

|-
| 4 PiXC
| To use the pi-calculus as a model to extend XC with mobile processes and mobile channels.
| Just an idea

|-
| 5 PiXOS
| To use the pi-calculus as a model and PiXC to implement a Dynamic Operating System for XMOS processors.
| Just an idea

|-
| 6 FreeRTOS
| A port of FreeRTOS to the XS-1.
| Project

|-
| 7 Next idea...
| Next idea...
| ...

|}
= XOSS =
Proposal for XS-1 Operating System Services to extend those services provided by XS-1 and XC, and in particular a form of paged memory management. To provide hardware that enables networking with mainstream host processors running Operating Systems like VxWorks or Linux.

== Aims ==
The aim of XOSS is twofold:

* to expand the operating system services provided by XS-1 cores and the XC language,
* to integrate with multi-processor Operating Systems and extend application parallelism.

== Contacts ==

{| class="prettytable"
! Identity
! Contact

|-
| jhrose
| Via XMOS Exchange

|}
== Summary ==
The XS-1 processor does not provide an External Memory Interface (EMIF), which could introduce non-determinism between threads. And we are taught to program for limited xcore memory using data shared through channels, rather than writing large monolithic algorithms. Still, there are occasions when access to secondary memory would prove beneficial.

There are common operating system services which the XS-1 core does not embed, such as memory caching which would allow use of both a secondary cache and an external main memory, and services which XC does not support, such as a service registry which would allow a set of distributed services to be run across heterogenous processor networks. And the scope for parallel applications can be extended to run not just on multi-cores but also over multi-processors.

== Project ==
<nowiki>To provide hardware for secondary memory, to extend PAR in XC to mark caching points, and to provide methods for communication with a host processor including virtual channels. The project is more fully described in [</nowiki>2.3].

=== Secondary memory ===
The XS-1 provides no memory objects beneath the L1 Cache, and the processor has no ability to address external memory. To provide the next level multi-cycle Level-2 Cache and lowest Main Memory necessitates both a system design and either toolchain support for XC.

=== Hardware ===
A proposed Level-2 Cache and Main Memory system design is proposed, using an FPGA to provide a cache and to interface an external 400MHz DDR SDRAM. And with some development the same hardware is proposed as an interface to a Host Processor Node, through Dual-Port Memory and an Xlink connection. Caching requires an extension to XC (or a custom library), and has a real-time performance overhead.

=== Extended PAR ===
Cache-misses would stall the processor for a large number of cycles, so facilitating them at known scheduling points is desirable. The XC programming language includes just such a known scheduling point in the PAR statement, where the programmer spawns threads. Consider the following proposed extended PAR, in which the set of threads is named and declared with proposed new keywords:

PAR set_of_abc IS PAGED
{
a( );
b( );
c( );
}

in which ''set_of_abc'' is a name like a variable name, and ''IS PAGED'' is an attribute. This works similarly for replicated PAR, for example:

PAR<nowiki>( int i=0; i<4; i++ ) array</nowiki>_of_a IS PAGED
{
<nowiki>a[ i ]( );</nowiki>
}

=== Virtual Channels ===
As each XS-1 core has a finite set of channel resources, XOSS could provide a library of Virtual Channels (VCH). A large number of VCHs could be multiplexed over a few physical channels. And exposing XOSS VCHs over the Host Processor Node Xlink interface as a Linux device would allow a direct exchange of data between XOSS/XS-1 and Linux threads.

== References ==
<nowiki>[</nowiki>2.1] [http://www.xmos.com/published/xs1_en XMOS XS1 Architecture], May D., 2008

<nowiki>[</nowiki>2.2] [http://www.xmos.com/published/xc_en Programming XC on XMOS devices], Watt D., 2009

<nowiki>[</nowiki>2.3] [http://www.xcore.com/forum/download/file.php?id=16 XOSS Proposal], jhrose, 2009.

= HyperviXor =
XS-1 hardware as a Hypervisor servicing a number of Concurrent Operating Systems.

== Aims ==
* To use XS-1 threads and resources to virtualise Concurrently running Operating Systems

== Contacts ==

{| class="prettytable"
! Identity
! Contact

|-
| jhrose
| Via XMOS Exchange

|}
== Summary ==
A Hypervisor provides a low-level service to Operating Systems, much as operating systems themselves virtualise resources to software applications. In systems with multiply different real-time and concurrent requirements, benefit can be had in dividing the application among different Operating Systems with differing characteristics and services.

== Project ==
Abandoned because it will be cheaper just to use another processor for each sub-system OS.

== References ==
= PiXC =
To use the pi-calculus as a model to extend the XC programming language with mobile processes and mobile channels.

== Aims ==
The aims of PiXC are:

* <nowiki>To use the pi-calculus [</nowiki>4.5<nowiki>] as a model to extend XC [</nowiki>4.2] with mobility
* <nowiki>To formalise (extensions to) a compiler for PiXC that targets XMOS processors [</nowiki>4.1]

== Contacts ==

{| class="prettytable"
! Identity
! Contact

|-
| jhrose
| Via XMOS Exchange

|}
== Summary ==
<nowiki>As Milner begins the introduction [</nowiki>4.5<nowiki>], "[pi is]...a calculus for analysing properties of concurrent communicating proceses, which may grow and shrink and move about". This fluidity takes the pi-Calculus to a level not reached by CCS, CSP or classical automata. In the broadest nutshell, pi is an extension to CCS that allows the very channels used for inter-process communication to be passed as communication elements. </nowiki>

PiXC makes programming with the Pi-calculus accessible and familiar, by modestly extending the XC programming language. These extensions allow mobile processes and channels to be declared and have a language semantics. Extensions to input and output statements allow mobile processes to be communicated along channels, so the mobile context leaves the sender process and arrives at the receiving process where it runs in parallel. The sender and receiver process can reside on different processors. The state (or context) of a mobile process is preserved over its migration, so that its lifetime persists for the duration of the whole program.

== Project ==
<nowiki>To extend XC with mobile processes and mobile channels. The project is more fully described in [</nowiki>4.6].

=== Fluid architecture ===
<nowiki>In addition to modelling internets [</nowiki>4.5], we assert Pi is also well-suited for general purpose programming and expressing algorithms. <nowiki>The dynamic communication of mobile channels and mobile processes through channels enables the function and data control flow to evolve in response to run-time events [</nowiki>4.4].

=== Mobile Processes ===
Mobile processes are those which migrate, to run at different locations at different times. To be mobile, rather than just invoked in the accepted way, a process has to preserve some state and provide various function entry points, which suggests a ''mobile-context'' structure operating entirely within the process. And to be safe, a process has to be sent through a channel to a new location.

=== Mobile Channels ===
Mobile channels are those which migrate, to bind with different endpoints at different times. To be mobile, rather than just used in the accepted way, a channel has first to be emptied so that it is state-less before migrating. And to be safe, a channel has to be sent from a source process through a channel, possibly itself, to a destination process. Once sent, the source process can no longer access the migrated channel; and counterwise the destination process can only access the migrated channel once received.

== References ==
<nowiki>[</nowiki>4.1] [http://www.xmos.com/published/xs1_en XMOS XS1 Architecture], May D., 2008

<nowiki>[</nowiki>4.2] [http://www.xmos.com/published/xc_en Programming XC on XMOS devices], Watt D., 2009

<nowiki>[</nowiki>4.3] [https://www.cs.kent.ac.uk/research/groups/plas/wiki/OccamPiReference/ Occam-pi], [http://www.cs.kent.ac.uk/pubs/2003/1721/content.ps RmoX], [http://frmb.org/pubs/qm-occampi-rmox.pdf Occam-pi and RMoX], [http://www.cs.kent.ac.uk/research/groups/sys/kroc.html University of Kent]

<nowiki>[</nowiki>4.4] [http://www.cs.kent.ac.uk/pubs/2004/1969/content.pdf Communicating Mobile Processes], [http://www.cs.kent.ac.uk/projects/ofa/kroc/csp-model-cpa2008.pdf Communicating Mobile Channels], [http://www.cs.kent.ac.uk/research/groups/sys/kroc.html University of Kent]

<nowiki>[</nowiki>4.5] [http://en.wikipedia.org/wiki/Pi_calculus pi-Calculus], Milner R., [http://www.cambridge.org/uk/catalogue/catalogue.asp?isbn=9780521658690 Cambridge], 1999.

<nowiki>[</nowiki>4.6] PiXC proposal, jhrose, 2009-10.

= PiXOS =
To use the Pi-calculus to model and PiXC to develop a Dynamic Operating System for XMOS processors.

== Aims ==
The aims of PiXOS are:

* <nowiki>To use the pi-calculus [</nowiki>4.5] as a paradigm for a Dynamic Operating System
* <nowiki>To use PiXC [</nowiki>4.6<nowiki>] to develop an Operating System for XMOS processors [</nowiki>4.1]

== Contacts ==

{| class="prettytable"
! Identity
! Contact

|-
| jhrose
| Via XMOS Exchange

|}
== Summary ==
In traditional operating systems, especially those targetting embedded systems, the executable unit is commonly statically linked so that the set of possible services is fixed during compilation, and resources like memory and CPU are shared among processes through virtualisation. In systems with an interface, libraries may be dynamically link-loaded at runtime to extend the set of kernel modules or device drivers. However, the concept of operation, the way people view and program for operating systems, largely remains fixed on a rigid architecture which is not at all fluid.

<nowiki>As Milner begins the introduction [</nowiki>4.5<nowiki>], "[pi is]...a calculus for analysing properties of concurrent communicating proceses, which may grow and shrink and move about". In the broadest nutshell, pi is an extension to CCS that allows the very channels used for inter-process communication to be passed as communication elements. In communicating a channel, the effect is a dynamic re-mapping of the architecture. </nowiki>

== Project ==
<nowiki>To develop PiXC-language libraries that implement a Dynamic Operating System Architecture. The project is more fully described in [</nowiki>5.3].

=== Fluid architecture ===
<nowiki>In addition to modelling internets [</nowiki>4.5], we assert Pi is also well-suited for modelling a dynamic operating system, whose very architecture changes dynamically to fulfil the state transitions of its processes. <nowiki>The communication of mobile channels and mobile processes through channels enables network topology to evolve in response to run-time events [</nowiki>4.4].

=== Mobile Services ===
A dynamic operating system can publicise a set of mobile processes, which migrate to run at different locations at different times. Each mobile process can implement an Operating System Service (including Interrupt Service Routines). When not in use a Mobile Service (MS) resides dormant in a registry; and when needed an MS is claimed by a process, to which it migrates and runs in parallel.

=== Device Drivers ===
A dynamic operating system can publicise a set of static device drivers through mobile channels, whose endpoints migrate to bind with different processes at different times. A static driver controls a fixed-location hardware capability, such as an i/o port. When not in use a Mobile Endpoint (ME) resides dormant in a registry; and when needed an ME is claimed by a process, to which it migrates.

== References ==
<nowiki>[5</nowiki>.1] [http://www.xmos.com/published/xs1_en XMOS XS1 Architecture], May D., 2008

<nowiki>[5</nowiki>.2] [http://en.wikipedia.org/wiki/Pi_calculus pi-Calculus], Milner R., [http://www.cambridge.org/uk/catalogue/catalogue.asp?isbn=9780521658690 Cambridge], 1999.

<nowiki>[</nowiki>5.3] PiXOS proposal, jhrose, 2010.

= FreeRTOS =
A port of FreeRTOS to the XS-1.

== Aims ==
FreeRTOS aims to provide:

* a portable, Open Source, royalty free, mini Real Time Kernel
* tasks, co-routines, and inter-task communication

== Contacts ==

{| class="prettytable"
! Identity
! Contact

|-
| bianco
| Via XMOS Exchange

|}
== Summary ==
* preemptive, cooperative and hybrid scheduling

* support for over 23 distinct architectures

* designed to be small; typically a kernel binary image will be in the region of 4K to 9K bytes

* portable code structure predominantly written in C

* supports both [http://www.freertos.org/taskandcr.html tasks and co-routines]

* [http://www.freertos.org/Stacks-and-stack-overflow-checking.html stack overflow detection] options

* no software restriction on the number of tasks that can be created

* no software restriction on the number of priorities that can be used

* no restrictions imposed on priority assignment - more than one task can be assigned the same priority

* [http://www.freertos.org/Inter-Task-Communication.html queues, binary semaphores, counting semaphores, recursive semaphores and mutexes] for communication and synchronisation between tasks, or between tasks and interrupts

* [http://www.freertos.org/Inter-Task-Communication.html#Mutexes mutexes] with priority inheritance

* Free embedded software source code

* royalty free

== Project ==
To port FreeRTOS to the XS-1 architecture.

=== Source ===
The FreeRTOS kernel source is spread over 4 source files and 10 header files written in standard C, which are compiled using the XCC toolchain. Then there is a portable subdirectory, within which architecture-specific source files in C and assembler reside. A new portable sub-directory for XCC is created, and a target sub-directory for XMOS_XS1 containing C and XC source files.

=== XS-1 port ===
The port_xc.c source declares a timer resource, used to provide the FreeRTOS kernel timer. The kernel is run each time the timer expires, to perform a context switch. The portmacro.h file defines basic types, constants and macros, including atomic functions to enable and disable interrupts. A macro is provided to make a kernel call entry point, though the only kernel function implemented so far is a context switch. The port.c file supports scheduler functions. The port_asm.S file implements task context save and restore functions, the tick ISR, and functions to initialise each task stack and the kernel on startup. Memory allocation is provided using the XCC built-in heap library.

== References ==
<nowiki>[6</nowiki>.1] [http://www.freertos.org/ http://www.freertos.org/]

<nowiki>[6.2] </nowiki>[http://www.xcore.com/projects/freertos-port http://www.xcore.com/projects/freertos-port]

= Next idea... =
== Aims ==
== Contacts ==

{| class="prettytable"
! Identity
! Contact

|-
|
|

|}
== Summary ==
== Project ==
== References ==

XMOS Operating System Interest Group (XOSIG)

Jhrose — Sat, 26 Jun 2010 13:56:01 GMT

Jhrose: /* PiXC */

XOSIG provides a forum covering all theoretical and practical aspects of operating systems relating to XMOS technology.
We have our group at [http://www.xcore.com/groups/xmos-operating-system-interest-group-xosig] where members are encouraged to propose ideas. Or group members are active within xcore and make various contributions to the forum, for example [http://www.xcore.com/forum/viewtopic.php?f=17&t=83].

== Index Of Ideas ==
An XOSIG Index Of Ideas is maintained. Its aim is to outline substantive ideas within XOSIG, providing a first port-of-call to locate projects and those involved with them. The current source can be found at [[XOSIG IoI]], and a PDF of version 0.3.1 can be found at [http://www.xcore.com/forum/download/file.php?id=118]. Other ideas have been proposed in group postings.

== FreeRTOS ==
XOSIG group member Bianco has provided a port of FreeRTOS for the XS-1 processor. This is a traditional virtualising kernel that runs multiple tasks on a single XS-1 core thread. The project is maintained at [http://www.xcore.com/projects/freertos-port].

== PiXC ==
PiXC is a proposal to extend the XC programming language with mobile processes and mobile channels, loosely based on ideas from the Pi-calculus. One of its aims is to break away from the traditional "virtualisation" mechanism to create a new "processisation" paradigm for Operating Systems. The current specification can be found at [[PiXC]] and a PDF of version 0.3 is at [http://www.xcore.com/forum/download/file.php?id=118]. There has been recent discussion on version 0.3 protocol component at [http://www.xcore.com/forum/viewtopic.php?f=17&t=83&start=30].

SPI spec files for use with xflash and flashlib

Jason — Fri, 25 Jun 2010 13:15:26 GMT

Larry:

On this page you can find the SPI specification files which provide the parameters needed to use XFlash and FlashLib.

'''Current files for download:'''

* [http://xcore.com/wiki/index.php/File:A25L40PT.txt Atmel A25L40PT]
* [http://xcore.com/wiki/index.php/File:EON_EN25F20.txt EON EN25F20]

Innovation and entrepreneurship

Jonathan — Thu, 24 Jun 2010 22:52:36 GMT

Jason: /* Innovation and Entrepreneurship */

XMOS technology contains all the key ingredients of a great technology platform to start companies - a general technology with many applications, a receptive and in some cases rather desperate market and a helpful community for support.

As with anything, there are hurdles that need to be overcome.

This guide is intended as a guide for engineers with an interest in entrepreneurship - to try to explain how to overcome some of the basic hurdles and answer some common questions when you start up.

It goes without saying on a Wiki that you take the advice at your own risk and potential peril. Those writing it have only your best interests at heart.

== I have an idea. Now what? ==

Right. Well the first thing is to have a good think about it from a number of basic angles. Here are the questions that are easiest to throw at it to see if it can meet some basic acid tests:

* How long will it take to build this? How many people need to be involved? What skills do you need? Do you need extra technology, licenses or hardware?
* How well do you know your market? Do you know any direct customers?
* Is this an idea that relies on secrecy in one form or another (patents, etc)? If so, would you consider your idea worthy of a patent?
* What happens if someone copies you?
* Do you love your idea?

The reason for the first question is obvious. If you can't answer these, you need to go and do some work - these are the basics.

The second question is so you can go and talk to people. If you don't know anyone who wants to buy your stuff, why not? Go find them. You have no idea if you have anything useful until you have talked to potential customers. Find someone who wants to buy it...!

The third question is getting a bit more subtle. Ideas that are based mostly on patents - and protection of some form - are often quite vulnerable, because patents are expensive and can rarely be used by a startup against anyone other than another startup. This is generic advice - your startup is a stronger proposition if it doesn't really need patents to protect itself - and instead uses its ability to get there first and keep innovating and building expertise. This ties into a point I want to make later.

What happens if someone copies you? Well - you have to know the answer. Back to basics. What can you do? If the answer is "sue them", give up now. Look for pricing solutions, look for product superiority. Market advantage. Etc. Work out what the barriers are to entry are, whether they make sense, how you can respond to new entrants.

Finally, if you don't love your idea it really isn't worth it. You have to. You're going to have people far less intelligent than you telling you it's crap for a long time. Get used to it.

So here's the final point. Ideas are not startups. Startups are not ideas. Gone are the days when one moment of ingenuity was enough to start a successful company. Ideas, models, products are too easy to copy. Streams of ideas, streams of innovation, streams of creativity are not. Try to find yourself a niche in which you can be the best in the world at something. And then keep innovating to make sure you never lose that position.

== More Coming Soon ==

XMP-64 Group

Jamie — Wed, 16 Jun 2010 14:36:22 GMT

Jamie: added some example code

Welcome to the XMP-64 group page. The aim is to gather or link to any useful related information here such as example code, guides or general tips.

== What is the XMP-64? ==

The XMP-64 is an experimental 64-core device. It features 16 XS1-G4 chips connected together in a hypercube topology. For more information check the offical XMOS [https://www.xmos.com/products/development-kits/xmp-64 page].

== Performance experiments ==

Available through the XMOS website is a '[http://www.xmos.com/published/xmp64measurements performance measurements]' document. This gives details of a number of experiments performed with the device to gain some insight into some of its characteristics, such as the time taken to deliver messages in a congested network.

The [http://www.xcore.com/projects/xmp-64-performance-experiments source code] of the experiments is available, and is a good place to start if writing XMP-64 software for the first time.

== Example program ==

Here is a complete example XC program which runs one process on each of the 64 cores, 16 of which switch on an led attached to the core.

<pre>
#include <platform.h>
#include <xs1.h>

#define NUM_CORES 64
#define STEP 4

out port leds[] = {
on stdcore[0] : XS1_PORT_1E,
on stdcore[4] : XS1_PORT_1E,
on stdcore[8] : XS1_PORT_1E,
on stdcore[12]: XS1_PORT_1E,
on stdcore[16]: XS1_PORT_1E,
on stdcore[20]: XS1_PORT_1E,
on stdcore[24]: XS1_PORT_1E,
on stdcore[28]: XS1_PORT_1E,
on stdcore[32]: XS1_PORT_1E,
on stdcore[36]: XS1_PORT_1E,
on stdcore[40]: XS1_PORT_1E,
on stdcore[44]: XS1_PORT_1E,
on stdcore[48]: XS1_PORT_1E,
on stdcore[52]: XS1_PORT_1E,
on stdcore[56]: XS1_PORT_1E,
on stdcore[60]: XS1_PORT_1E
};

void foo(int number, out port led) {
led <: 1;
while(1) {}
}

void bar(int number) {
while(1) {}
}

int main(char args[]) {
chan c[NUM_CORES];
par {
par (int i=0; i<NUM_CORES; i+=STEP) {
on stdcore[i] : foo(i, leds[i/STEP]);
par (int j=1; j<STEP; j++)
on stdcore[i+j] : bar(i+j);
}
}
return 0;
}
</pre>

XMOS Cookbook by russf, Berni

Russf — Wed, 09 Jun 2010 23:21:30 GMT

Russf: XMOS Cookbook overview

This is the general wiki page for XMOS Cookbook. A place to gather general information on how to get started, and how to organize modules.

The first bundle of XMOS Cookbook code is a [http://github.com/XMOSCookbook/xmos_network_modules repackaging of XMOS's tcp/ip stack, version 1v3]. By removing version suffixes in the module names, the rebundling makes it easier to integrate those modules into other code, and then update the modules to newer versions with minimal code changes.

It should be possible to create new GIT superprojects that compose these and other modules, to create new projects.

Fixes to Common Deprecation Warnings

Russf — Wed, 09 Jun 2010 02:06:16 GMT

Russf:

== Release 10.04 ==

=== Language token '''clock''' deprecated ===

==== Example warning: ====

smi.h:60:15: warning: language type `clock' is deprecated
smi.h:60:15: warning: clock type is now defined in xs1.h

This occurs when clock is found, but xs1.h has not been included.

#include "xs1.h"

above the first occurrence of '''clock''' in a file, to prevent this warning.

=== Use of stdcore array without -target option deprecated ===

==== Example warning: ====

.././../module_ethernet/src/server/getmac.xc:52:1: warning: stdcore array used with no -target option specified.

Suggestion

Suggestion here

=== Report switch changes - '''--show-report''' deprecated ===

xcc: warning: --show-report is deprecated, use -report instead

Edit your Makefile(s) by replacing '''--show-report''' with '''-report'''

XC-1

Andy — Thu, 03 Jun 2010 20:10:26 GMT

Andy:

The XC-1 Development Kit was the first low-cost prototyping board from XMOS, based on the four-core XS1-G4 chip. It has been replaced by the XC-1A and is no longer sold.

== Specification ==

* XS1-G4 four-core 400MHz device: 1600 MIPS, 256KB RAM, 32KB OTP
* USB power and host debugger connection
* Four pushbutton and LED pairs
* 12 bi-colour LEDs
* Integrated speaker
* 60 pins user I/O expansion from two cores
* 0.1” pitch through-hole prototyping area
* Credit card sized (85 x 54 mm)

== User Programming and Demo Mode ==

When you first connect the XC-1 to the USB port on your computer, it boots from internal OTP and runs the demonstration code. To use the XC-1 in programming mode disconnect the card from the USB cable and reconnect it while holding down Button A.

The LEDs around the buttons flash three times to indicate that the card is in
programming mode. The card stays in program mode until you disconnect it from the USB cable, when the XC-1 is automatically reset to its default demo state.

Using Channels in XC

Folknology — Thu, 03 Jun 2010 15:10:44 GMT

Folknology: /* Channels Enable Modularisation */

== Overview of channels ==

Today we are going to learn the basics about channels in the XC programming language.

When dealing with concurrency common problems arrive with sharing data, how does one guarantee that two concurrent processes don't try to make changes to the same data at the same time. Thus if this kind of data sharing can be bypassed one of the major pitfalls of concurrent programming can be avoided. Channels represent a way for different concurrent processes to send messages to each other on a controlled fashion. Because messages are passed by value the data sharing problem does not exist. We know by simply using channels we are communicating data safely between processes.

== Background ==

The method of passing messages by channels in XC is based on the formal language [http://en.wikipedia.org/wiki/Communicating_sequential_processes Communicating Sequential Processes (CSP)]. CSP was highly influential in the design of the [http://en.wikipedia.org/wiki/Occam_(programming_language) occam programming language], which was the programming language for the INMOS [http://en.wikipedia.org/wiki/Transputer Transputer].

== Basic Channel Usage ==

Processes in XC running on Xmos are represented by threads either on the same core or on different cores, they are a universal mechanism to safely exchange data between threads. What is more the XC language has event based language constructs to enable efficient use of channels within program flow. Just like XS1 cores allow program flow based on input pin states and events, XC also enables you to alter the flow of your program based on arrival of messages or data over channels. If this were not so each thread would have to block its flow permanently until channel messages arrived. The key to the is feature of XC is the select construct when combined with an infinite loop such as While(1):

<pre>
while(1){
select
{
case wait for x to happen:
process(x);
break;
case wait for y to happen :
process(y);
break;
default :
if neither X or Y happened do this by default
do_default();
break;
}
}
</pre>

When this select runs, 3 things can happen :
<ol>
<li>X happens and process(x) is called</li>
<li>Y happens and process(y) is called</li>
<li>Neither X or Y happens and thus do_default() is called</li>
</ol>

So select means select the program flow from these possible cases depending on external events, select waits concurrently (because of the controlling while loop) for one of them to happen on a first come first served basis. Such events may be results of timers reaching values, port inputs or even channel inputs and these can be combined to create the event flow required for your solution.

But there are some basic rules channels, ports and timers may only appear in any one case, if your case depends on the state of input from a channel, timer or port and has multiple possibilities or states, these have to be catered for in the flow of that case. This can often be achieved by adding a switch statement or if/else conditions in the flow for example here is the select statement married with a switch in order to create a light switch controller:

<pre>
#include <platform.h>
#include <stdio.h>
#define DELAY 1000000000
#define ON 1
#define OFF 0

port lamp = XS1_PORT_1K;

void lamp_control_mod(chanend c, port lamp){
unsigned int time = 0;
timer t;
while(1){
select
{
case c :> msg :
switch (msg)
{
case ON:
lamp <: 1;
t :> time ;
time += DELAY;
break;
case OFF :
lamp <: 0;
break;
}
case when timeafter(time) : // lets save energy, someone left the light on
lamp <: 0;
break;
}
}

main(void){
chan c;
par {
test_lc_mod(c);
lamp_control_mod(c,lamp);
}
}
</pre>

The control of the lamp's state is initially determined by messages send over channel c from a remote concurrent processes (thread) which could be on the same core or another core. The function listens to that channel for its instructions and activates or deactivates the lamp accordingly. In addition because we are environmentally friendly bunch at XCore we decided to add this neat energy saving light timer to switch the lamp off after a predetermined delay. If the light control had other responsibilities to tend to when light switching or energy saving was being actioned, we could add a default section to do such housekeeping. here an exercise to explore selects further :

1) Our lamp controller moonlights as a an energy meter, as do all of our appliance controllers, thus when it is not busy doing its job it estimates power used. In this case the lamp is a small low powered 10 Watt LED type. add the code required so that when the controller is queried over channel c about its energy used since it started it prints out the accumulated value using a printf() statement.

== Channels Enable Modularisation ==

We are assuming the test_lc_mod(c) understands the operation of lamp_control_mod and sends the relevant ON's and OFF's. By this we are asserting a contract between the 2 modules test_lc_mod and lamp_control_mod. This is an important feature of contract programming (or contracting to an interface or documented command set). It may see trivial to design a lamp controller in this way but it actually has advantages. lets replace test_lc_mod with toggle_mod and close the channel loop:

<pre>
void toggle_switch_mod(chanend c,port button){
int state = OFF;
while(1){
select
{
case button :> void :
state = !state;
c <: state;
break;
}
}
}

main(void){
chan c;
par {
toggle_switch__mod(c,button);
lamp_control_mod(c,lamp);
}
}
</pre>

An because we are programming by contract and using channels the toggle switch could be on any core or thread. What's more we can interchange other standard switch modules that speak "lamp_control", perhaps we want a factory like control switch with an on and off button, well that's simple and we don't have to touch our lamp_controller_mod:

<pre>
void factory_switch_mod(chanend c,port onButton, port offButton){
while(1){
select
{
case onButton :> void :
c <: ON;
break;
case offButton :> void :
c <: OFF;
break;
}
}
}

main(void){
chan c;
par {
factory_switch__mod(c,onButton,offButton);
lamp_control(c,lamp);
}
}
</pre>

Thus we can separate concerns of our design in a modular fashion not just to distribute work across teams but also to allow reuse of modules. The channels enable these modules to operate not only on different threads but also different cores or even chips connected via Xmos Links thus.

<pre>
main(void){
chan c;
par {
on stdcore[0] : factory_switch__mod(c,onButton,offButton);
on stdcore[1] : lamp_control(c,lamp);
}
}
</pre>

2) We have been asked to create a new kind of automated switch module, that uses a buffered active low phototransistor and emitter pair to detect a beam of light across the doorway so that the lamp can be turned on automatically when someone walks into the room. Develop a module that speaks "lamp" to the following prototype:

<pre>
auto_switch_mod(chanend c, port phtoDetector, port photoEmitter){..}
</pre>

3) After adding the automated light switch we have been asked to improve our lamp controller by adding some intelligence to further save energy, in testing we found the lamp being switched on even in clear daylight, which of course wastes energy. Adapt the lamp controller to receive a second port in its prototype to include the output of a buffered photo transistor. When the photo transistor detects light its output is taken low, when no light is detected it is taken high. remember that the photo transistor is sensitive enough to detect the light from the lamp.

== Dynamic Channel Usage ==

Ok if you have got this far and completed the exercises you will have a good understanding of channel basics well done, you are now ready to get some more value from these essential features of XC. So having worked so hard to get here I think you have earned enough brownie points to play a game. But as usual we are going to play a game with channels thrown in for good measure, so lets play table tennis.

<pre>
#include <platform.h>
#include <stdio.h>
#define END -1
#define PING 0
#define PONG 1
#define PINGS 5

void ping(chanend c){
int reply;
c <: PING;
for(int i = 0; i < PINGS; i++){
select
{
case c :> reply :
switch(reply)
{
case PONG :
printf("Ping received Pong\n");
c <: PING;
break;
default :
printf("Ping received unknown reply\n");
break;
}
break;
}
}
c :> reply;
printf("Goodbye cruel Pong\n");
c <: END;
}

void pong(chanend c){
int msg;
while(1){
select
{
case c :> msg :
switch(msg)
{
case PING :
printf("Pong received Ping\n");
c <: PONG;
break;
case END :
return;
default :
printf("Pong received unknown message\n");
break;
}
break;
}
}
}

main(void){
chan c;
par {
pong(c);
ping(c);
}
printf("End of all Pings\n");

return 0;
}
</pre>

In this game of table tennis we have two players Ping and Pong, Ping starts by pinging Pong and Pong responds by ponging Ping is that clear ;-)

Both ping and pong use printc() to acknowledge that they have received ball (in the form of a message) from the other player. When you run this you should get the following:

<pre>
Pong received Ping
Ping received Pong
Pong received Ping
Ping received Pong
Pong received Ping
Ping received Pong
Pong received Ping
Ping received Pong
Pong received Ping
Ping received Pong
Pong received Ping
Goodbye cruel Pong
End of all Pings
</pre>

What this shows is the use of channels in a dynamic fashion. In our previous example channels were used in the same direction; the switch always sent over the channel, the lamp always received over the channel. Well it doesn't have to work in this manner channels can be used bi-directionally, but we must take care about using them in both directions, we must keep track of which thread is sending and which thread is receiving, otherwise things go very wrong! Channels require symmetric input and output, that is for every input there must be an input, if this isn't observed it will crash the program. You can see the effects by removing the "c :> reply;" line recompiling and re-running, notice the resource errors you get when trying to run the program with this channel fault. There are a number of other more subtle gotchas that can happen with this dynamic channel usage try moving the first "c <PING" to after the for statement and see what happens. See if you can guess what is going on here.

4) Because our xmos chip will be used in a very battery powered situation, power consumption is paramount and other devices may have a greater priority for power than lighting. We have therefore been instructed that the switches must be power conscious and may be allocated quotas, if those quotas are reached the lamp switching should be disabled until the system is restarted to allow power to be routed to more critical devices. Thus Armed with our new dynamic channel techniques rewrite the lamp_control_module to return the power usage (over the same channel) after receiving a channel message READ (an integer value different from ON or OFF say 3). When the lamp_control module receives this it should respond to the switch_mod with the reading of power consumptionsince last READ query, rather than using printf(). Also modify the switch modules to disable the lamp usage when the consumption reaches a passed in quota. The READ requested should be generated by a timer running in the switch modules and should be polled at least once every second. Once quota is met and lamp disabled the switch module needs to printf() its status and then complete its thread along with the lamp control thread. Remember in this case the switch is in charge, it is the supervisor so things must be orchestrated with that in mind.

XMOS devices

Otitov — Tue, 01 Jun 2010 15:43:39 GMT

Russf: /* G series */

XMOS devices

== L series ==
* XS1-L1 - Low power 1 core processor
** [http://www.xmos.com/products/xs1-l-family/l1lq64 64LQFP]
** [http://www.xmos.com/products/xs1-l-family/l1lq128 128TQFP]
* XS1-L2 - Low power 2 core processor
** [http://www.xmos.com/products/xs1-l-family/l2qn124 124QFN]

== G series ==
* XS1-G4 - 4 core processor
** [http://www.xmos.com/products/xs1-g-family/xs1-g4-144bga-package 144BGA]
** [http://www.xmos.com/products/xs1-g-family/xs1-g4-512bga-package 512BGA]
* XS1-G2 - 2 core processor
** [http://www.xmos.com/products/xs1-g-family/xs1-g2-144bga-package 144BGA]

Xtag Xtag2 and kits on Ubuntu

Folknology — Thu, 20 May 2010 16:27:41 GMT

XMatt: /* USB Support on other Linux distributions */

= Ubuntu USB Support =

This page assumes you have installed the latest version of the XMOS Development Tools (https://www.xmos.com/technology/design-tools) version 10.4 or greater.

In order to use an XMOS development kit, XTAG or XTAG-2 based product on Ubuntu you may have to go through additional USB configuration steps in order to connect to the boards.

Open a terminal, change directory to your tools path and run the following:
source SetEnv
This configures your environment for the XMOS tools.
To detect the boards run:
xrun -l
this will list boards recognised by the XMOS tools (10.4) connected to the USB bus.

If you cannot see your board listed (no devices) you may need the additional steps below.

== USB Native Driver Support ==

USB driver support is provided natively on Linux. The method required to enable the driver, however, depends on the distribution you are using and the kernel version.

Get your kernel versions by running:
uname -r
You will need this information to see what kernel support for USB you have.

=== With USBFS Support ===

If your distribution provides usbfs support (e.g. pre kernel 2.6.31-20), follow these steps:

1. Edit the fstab file to add usb mounting details
sudo nano /etc/fstab

Add the following lines to the end of the file:

none /proc/bus/usb usbfs defaults,devmode=0666 0 0
none /dev/bus/usb usbfs defaults,devmode=0666 0 0

2. Press CTRL+O to write the changes, then CTRL+X to exit

3. Unmount the USB file systems with the following commands:

sudo umount /proc/bus/usb
sudo umount /dev/bus/usb

4. Remount the USB file systems with the following commands:

sudo mount /proc/bus/usb
sudo mount /dev/bus/usb

You should be ready to go. Use xrun as above to find your devices. If you still do not see your devices, disconnect and reconnect your devices. If you get complaints about usbfs being unsupported, or no /proc/bus/usb whilst completing the above commands you may need further steps - see the next section.

A useful command for linux usb detective work (not XMOS-specific) is issuing the following:
sudo lsusb
This will list all of the USB devices Linux knows are connected. By issuing this command when the device is plugged in and then repeating when it is unplugged you can see if the device is picked up or not by detecting the differences in its results.

=== Without USBFS Support ===

If your distribution does not support usbfs (for example Ubuntu 9.10 kernel 2.6.31-20), you need to set permissions using a udev rule. The procedure depends on the type of debug adapter you are using.

==== External Debug Adapter (XTAG-2) ====

Example kits are XK1, SparkFun XMOS development board and NetStamp.

If your development board uses an external XTAG-2 debug adapter, create a file "/etc/udev/rules.d/99-xmos.rules" using your favourite editor.

sudo nano /etc/udev/rules.d/99-xmos.rules

Add these lines to it:

SUBSYSTEM!="usb|usb_device", GOTO="xmos_rules_end"
ACTION!="add", GOTO="xmos_rules_end"

# 20b1:f7d1 for xmos xtag2
ATTRS{idVendor}=="20b1", ATTRS{idProduct}=="f7d1", MODE="0666",
SYMLINK+="xtag2-%n"

LABEL="xmos_rules_end"

Use CTRL+O to write changes and CTRL+X to quit.

To get the device to recognise the new rule, restart the udev service. This varies by distribution but for Ubuntu, you can restart udev by running:

sudo restart udev

When you have restarted the udev service, disconnect and reconnect your debug adapter/board, or alternatively reboot your system. In the latter case the device will automatically pick up the revised udev rule so you do not need to unplug your device. You should now be able to see your XTAG-2 device listed by using xrun.

==== Integrated Debug Adapter (FTDI/XTAG) ====

Example kits include XC-2, XC-3, XC1/1A, XC5.

If your development board uses an integrated debug adapter or an XTAG(-1), you may be able to enable the driver by adding the following to "/etc/udev/rules.d/98-xmos.rules"

SUBSYSTEM!="usb|usb_device", GOTO="xmos_rules_end"
ACTION!="add", GOTO="xmos_rules_end"

# 20b1:f7d1 for xmos xtag2
ATTRS{idVendor}=="20b1", ATTRS{idProduct}=="f7d1", MODE="0666",
SYMLINK+="xtag2-%n"

# 0403:6010 for XC-1 with FTDI dual-uart chip
ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", MODE="0666",
SYMLINK+="xc1-%n"

LABEL="xmos_rules_end"

Providing the distribution includes the /proc/bus/usb directory, you can then bind the /dev/bus/usb directory onto /proc/bus/usb:

mount --bind /dev/bus/usb /proc/bus/usb

''NOTE this step may not work, particularly if you do not have /proc/bus/usb. in which case you will also likely need the FTDI patch for the tools see below.''

Then restart the udev service or reboot your system - see External Debug Adapter section above.

''NOTE: The FTDI/XTAG issue (see Integrated Debug Adapater section) has been reported to FTDI Support by XMOS and we are waiting for an official release that resolves the problem, this will be included in a later tools release. In the meantime XMOS has an unofficial patched version of the device library that works on Ubuntu 9.10 kernel 2.6.31-20. If you would like a copy of the library please send a support ticket via the official XMOS support site https://www.xmos.com/support/contact that includes "Linux FTDI Library Request" in the Subject field.''

= USB Support on other Linux distributions =

Please visit the official XMOS knowledge base for information on development kits for Linux distributions other than Ubuntu.

http://www.xmos.com/kbase/index.php?View=entry&EntryID=27

Development Tools Setup Tips

Paul — Sun, 16 May 2010 00:05:05 GMT

Paul: Created page with '== XCC Fails on Ubuntu x64? == On clean ubuntu x64_64 installs you may encounter an error similar to the following: <pre> $ xcc bash: xcc: command not found </pre> This is due t…'

== XCC Fails on Ubuntu x64? ==
On clean ubuntu x64_64 installs you may encounter an error similar to the following:
<pre>
$ xcc
bash: xcc: command not found
</pre>

This is due to certain 32bit libraries that are required by the XMOS tools not being installed. To fix this run:
<pre>
$ sudo apt-get install ia32-libs
</pre>

Inline Assembly

Paul — Sun, 16 May 2010 00:00:58 GMT

Paul: Created page with '== Example of Streaming Channel Inline Assembly functions == This is an example of a header (.h) file that allows interaction with streaming channels. '''NOTE:''' The reason it …'

== Example of Streaming Channel Inline Assembly functions ==
This is an example of a header (.h) file that allows interaction with streaming channels.

'''NOTE:''' The reason it is in a header file is that the compiler will not inline the function if it is used across modules. Putting it in a .h file gives the compiler every chance inline it!

<pre>
#ifndef STREAMING_CHANS_H_
#define STREAMING_CHANS_H_

#include <xs1.h>
#include <xccompat.h>

#ifdef __XC__
inline static unsigned streaming_chan_inuint(streaming chanend c)
#else
inline static unsigned streaming_chan_inuint(chanend c)
#endif
{
unsigned value;
__asm__ __volatile__ (
"in %0, res[%1]" :
"=r"(value) :
"r"(c)
);
return value;
}

#ifdef __XC__
inline static void streaming_chan_outuint(streaming chanend c, unsigned value)
#else
inline static void streaming_chan_outuint(chanend c, unsigned value)
#endif
{
__asm__ __volatile__ (
"out res[%0], %1" :
/* no outputs */ :
"r"(c), "r"(value)
);
}

#ifdef __XC__
inline static unsigned char streaming_chan_inuchar(streaming chanend c)
#else
inline static unsigned char streaming_chan_inuchar(chanend c)
#endif
{
unsigned value;
__asm__ __volatile__ (
"int %0, res[%1]" :
"=r"(value) :
"r"(c)
);
return value;
}

#ifdef __XC__
inline static void streaming_chan_outuchar(streaming chanend c, unsigned char value)
#else
inline static void streaming_chan_outuchar(chanend c, unsigned char value)
#endif
{
__asm__ __volatile__ (
"outt res[%0], %1" :
/* no outputs */ :
"r"(c), "r"(value)
);
}

#endif /*STREAMING_CHANS_H_*/
</pre>

XCore Soft Reset

Paul — Sat, 15 May 2010 23:54:26 GMT

Andy:

This page describes how to reset an XCore chip utilising software.

Any writes to the PLL Control Register (register 6 on the L and G series) cause the chip to reset and reboot, even if the value is unchanged. Access functions are provided in the xs1.h header file. For example:

<pre>
#include <xs1.h>

void chipReset(void)
{
unsigned x;

read_sswitch_reg(get_core_id(), 6, x);
write_sswitch_reg(get_core_id(), 6, x);
}
</pre>

Note: This method will not cause the [[XC-1]] Development Kit to fully reset. The program must still be reset from the XDE.

Programming Ports in XC

Paul — Sat, 15 May 2010 23:35:25 GMT

Paul: Created page with 'This page describes how to utilise ports and their features in XC along with simple worked examples. == Basic Port Use == == Configuring Clocked Ports == == Configuring Ports …'

This page describes how to utilise ports and their features in XC along with simple worked examples.

== Basic Port Use ==

== Configuring Clocked Ports ==

== Configuring Ports with Handshaking ==

== Unorthodox port usage ==
This section handles things that are possible with ports that might be considered 'unorthodox'.

=== Outputting the inverted output of another 1 bit port ===
By utilising a clock block a developer is able to output the inverse of a 1 bit port on another 1 bit port without needing to write to the port (NOTE: this only works with 1 bit ports and will use 1 clock block).

This can be configured using the following code block:

<pre>
void setup_inverted_port( out port p, out port p_inv, clock c )
{
// set port p as the source for clock block c
set_clock_src (c, p);

// set port p_inv to be attached to the clock block c
set_port_clock (p_inv, c);

// set port p_inv to output the clock block c
set_port_mode_clock (p_inv);

// start the clock block and therefore the inverted output
start_clock( c );
}
</pre>

Programming in XC

Paul — Sat, 15 May 2010 23:23:38 GMT

Paul:

XC is a C like language developed by XMOS that has a feature set to allow easy access to many of the XMOS architecture's novel aspects.

As part of this feature set XC has syntax for the direct use of channels, ports, timers without the need for calling complex (and ugly!) API functions.

XC is designed to be a 'safe' language to help the developer avoid many of the potential pitfalls associated with more 'less safe' languages such as C. Some of the safeguards include automatic array bounds checking and not allowing the use of pointers or shared memory within XC.

For a user's first interaction with XC XMOS recommends the tutorials that are part of the XMOS development environment (XDE) and for a more comprehensive look at the XC language XMOS have published ''Programming XC on XMOS Devices'' which is available for free download [http://www.xmos.com/system/files/xcuser_en.pdf] or for purchase as a printed book [http://www.xmos.com/products/documentation/programming-xc-xmos-devices].

* [[Programming Ports in XC]]
* [[Using Channels in XC]]

Calling functions that have pointer arguments

Paul — Sat, 15 May 2010 23:11:05 GMT

Paul: Created page with 'If you have a C function that requires a pointer (such as one that access an array) you may want to call it from XC. As XC does not support pointers, some minor modifications wil…'

If you have a C function that requires a pointer (such as one that access an array) you may want to call it from XC. As XC does not support pointers, some minor modifications will be needed for your header files.

An example function such as the one below needs to be called from XC:

<pre>
void foo( char *bar, unsigned *n )
{
/*... access array */
}
</pre>

The following declaration should be made in the appropriate header file:

<pre>
#ifdef __XC__
void foo( char bar[], unsigned &n );
#else
void foo( char *bar, unsigned *n );
#endif
</pre>

This will then allow you to pass a char array and integer by reference.

Programming in C

Paul — Sat, 15 May 2010 23:02:09 GMT

Paul:

Programming in C for an XMOS device is very much like programming for any other platform. The main difference is that access to ports, channels and such like is not via the memory map. Accessing these resources requires calling custom XC functions or implementing custom inline assembly.

C/C++ and XC can be mixed. This can be useful when porting existing code or when you want to utilise pointers or such like.

For more information see:

[[Using channels and ports in C/C++]]

[[Calling functions that have pointer arguments]]

Development Tools

Paul — Sat, 15 May 2010 23:01:51 GMT

Kris:

This page is the main portal for information about the XMOS development tools and their use.

The current XMOS development tools can be downloaded here [https://www.xmos.com/technology/design-tools]

The main XMOS documents covering use of the tools can be found here [http://www.xmos.com/support/documentation]

The source for open parts of the XMOS tool chain is available from [https://www.xmos.com/technology/design-tools-source]

* [[Programming in XC]]
** [[Programming Ports in XC]]
** [[Using Channels in XC]]
** [[Fixes to Common Deprecation Warnings]]

* [[Programming in C]]
** [[C Compiler]]
** [[Using channels and ports in C/C++]]
** [[Calling functions that have pointer arguments]]
* [[Programming in Assembly]]
** [[Inline Assembly]]
* [[Development Tools Setup Tips]]
** [[Xtag Xtag2 and kits on Ubuntu]]
* Useful Techniques and Examples
** [[Active Energy Conservation (AEC)]]
** [[XCore Soft Reset]]

Using channels and ports in C/C++

Paul — Sat, 15 May 2010 22:56:58 GMT

Jamie: Added name mangling section

Currently ports and channel interaction in C or C++ has to be achieved by the user writing their own XC functions that can handle the various operations they require. These XC functions can then be called from C or C++ when needed.

== Channel and Port Types in C/C++ ==

You can have a channel as an argument to a C function by using the 'xccompat.h' include. For example:

<pre>
#include <xccompat.h>
#include "channel_funcs.h"

void c_func( chanend c )
{
unsigned v;
while (1)
{
xc_channel_out(c, v);
v = xc_channel_in( c );
}
}
</pre>

Where the channel interaction functions would be defined in 'channel_funcs.xc' such as:

<pre>
void xc_channel_out(chanend c, unsigned v)
{
c <: v;
}
</pre>

===Name mangling===

To avoid name mangling with C++, you need to give the C++ functions called from XC, C linkage. For example, the header 'channel_funcs.h', for the C++ file channel_funcs.ccp would be:
<pre>
#ifdef __cplusplus
extern "C" {
#endif

void cpp_func(chanend c);

#ifdef __cplusplus
}
#endif
</pre>
For more information on mixing C and C++ see [http://www.parashift.com/c++-faq-lite/mixing-c-and-cpp.html].

C Compiler

Paul — Sat, 15 May 2010 22:49:42 GMT

Paul:

We have a C/C++ compiler based on LLVM, [http://llvm.org], [http://en.wikipedia.org/wiki/Llvm]

The C compiler comes as part of the XMOS tool chain and the source for LLVM based tool set is available from XMOS [https://www.xmos.com/technology/design-tools-source].

The C compiler has available to it the standard C libaries such as stdlib, stdio etc.

AEC

Paul — Sat, 15 May 2010 22:45:19 GMT

Paul:

When all of the active threads on an XCore are paused your XCore is idle. Active Energy Conservation (AEC) reduces the clock rate when this occurs and can save 80% of the dynamic power when enabled. AEC is simple to enable during an application's initialization routine and is completely automatic once enabled.

Read the AEC app note for more details [http://www.xmos.com/system/files/xs1lengconserve.pdf]