Control Tokens Help

[monk_is_batman]

I'm trying to get going with control tokens using outct/inct/testct but am having some trouble. I understand there are 12, two of them are mentioned in the XS1 Architecture Manual, END and PAUSE, but I couldn't find specifically which two they were, e.g. 0 and 1. Do any of the others have names or they completely general purpose? Is there some other documentation with some more details on how control tokens work?

If anyone has used these before and has some example code that would be very useful to me if it is available. Thanks.

[tyler]

Did you look in the XS1-G System Spec file?
http://www.xmos.com/system/files/xsystem.pdf Section 3.5.1

[monk_is_batman]

So There are more than 12, but 12 are defined with specific uses? Does that mean if I want to use control tokens for specific other functions I should use the other 53 reserved values?

Still wondering if anyone has done this before and has examples.

[tyler]

I agree, this document is a bit confusing here. It defines the four important control tokens:

Four Application Control Tokens have been predefined, and these shall not be used
for any other purpose:
Name Value Description
END 0x01 End - free up interconnect and tell target.
PAUSE 0x02 Pause - free up interconnect but don’t tell target.
ACK 0x03 Acknowledge operation completed successfully.
NACK 0x04 Acknowledge that there was an error.
Note that these are the token values seen by the application software. When
transmitted over a 5-wire link the END and PAUSE tokens are represented by
special token values.

Then explains that all others can be used however you want:

All other token values can be used by the application
software in any way that it sees fit.

And then the next sentence defines more tokens that should be used, and goes on to list these 11 more and how the 53 next bytes are reserved:

In addition to the application tokens, there is a block of tokens that are reserved
for specific operations. These tokens have predefined meanings, and any implementation
should use those meanings. Below 11 of those tokens are defined, all other 53 token values between 0x8b and 0xc0 are reserved for future use.

So -- which ones should be used/redefined, and which ones are reserved?

[Jamie]

The immediate versions of outct and chkct allow the encoding of 12 unique values, 4 of which are reserved leaving you with 8 to define however. It's better to use pairs of the immediate versions as you save on loading a value. With the register versions of the control token instructions you could use any of the possible 256 values (as control tokens are 8 bit). And although the reserved tokens (0x8b to 0xc0) have meanings, it seems like using them for another purpose won't make any difference, but the xsystem manual isn't too clear about this.

[monk_is_batman]

@Jamie - Thanks for the response that does clear things up for me. Is there any other advantage to using the immediate versions? I think these may not work in my application as I had planned on reading in a control token and performing a switch on it. However if the immediate versions are better I could always follow it with a byte of data specifying the command being sent - but this removes any gain of not needing to load the value.

@tyler - I'm having those problems a lot the further I go into the documentation. I have been reading about the PAUSE token and been getting incomplete/confusing descriptions. I found the following in the XS1 Architecture pdf.

Another control token is PAUSE. Like END, this causes the route through the interconnect
to be disconnected. However the PAUSE token is not delivered to the receiving thread.
It is used by the outputting thread to break up long messages or streams, allowing the
interconnect to be shared efficiently.

The I was reading the XS1-G System spec linked above and it said:

If a thread wants to temporarily suspend a stream it may issue a PAUSE token at any time,
which will free up the circuit and return the communication wires to a low power state.

The second quote doesn't sound like this allows sharing and sounds like it is designed for power saving, but I suppose the PAUSE token could do both, would be helpful if that was explicitly stated in both documents. Also neither of these seem to mention how to get out of this state. Is it automatically resumed when data is sent? If so why is it not automatically paused when data is not being constantly sent?

[Jamie]

Is there any other advantage to using the immediate versions? I think these may not work in my application as I had planned on reading in a control token and performing a switch on it. However if the immediate versions are better I could always follow it with a byte of data specifying the command being sent - but this removes any gain of not needing to load the value.

If you're reading it in to perform a switch then you would want to use inct anyway. An extra instruction or two won't make too bigger difference on infrequent communications but for instance in XC, every communication is preceeded by a two-way exchange of control tokens to establish the connection and followed by this again to close it:

Code: Select all

outct res[r0], 0x0
chkct res[r0], 0x0
out res[r0], r11
outct res[r0], 0x1
chkct res[r0], 0x1

The second quote doesn't sound like this allows sharing and sounds like it is designed for power saving, but I suppose the PAUSE token could do both, would be helpful if that was explicitly stated in both documents. Also neither of these seem to mention how to get out of this state. Is it automatically resumed when data is sent? If so why is it not automatically paused when data is not being constantly sent?

Yes both are effects of PAUSE, and you're right neither mention how to unpause a connection, I would assume it would become unpaused when the pausing party next sends a message.