SpiNNaker message proxying support code. The protocol uses binary message
frames within a websocket. That websocket will have been opened within an
HTTPS-encrypted session where the session's user was authorised to access the
particular job that is the context for the websocket. Messages sent via the
protocol can only ever access boards allocated to the job.
The protocol has five messages that clients can send, three of which have
replies and one of which can also be sent from the server/proxy to the
client. All messages consist of a sequence of little-endian words, possibly
followed by some payload data (of length limited by the maximum size of a
SpiNNaker SDP or SpiNNaker boot message; the framing does not itself impose a
maximum message length):
Protocol inside web socket
| Name |
Request Layout (words) |
Response Layout (words) |
| Open
Connected Channel |
Request
0
| Correlation ID
| Chip X
| Chip Y
| UDP Port on Chip
|
|
Response
0
| Correlation ID
| Channel ID
|
|
| Establish a UDP socket that will talk to the given Ethernet
chip within the allocation. Returns an ID that can be used to refer to that
channel. Note that opening a socket declares that you are prepared to receive
messages from SpiNNaker on it, but does not mean that SpiNNaker will send any
messages that way. The correlation ID is caller-nominated, and just passed
back uninterpreted in the response message. |
| Close
Channel |
Request
1
| Correlation ID
| Channel ID
|
|
Response
1
| Correlation ID
| Channel ID (if closed) or 0 (not closed)
|
|
| Close an established UDP socket, given its ID. Returns the ID
on success, and zero on failure (e.g., because the socket is already closed).
The correlation ID is caller-nominated, and just passed back uninterpreted in
the response message. The channel may have been opened with either Open
Connected Channel or Open Unconnected Channel. |
| Send
Message |
Request
2
| Channel ID
| Raw message bytes...
|
|
N/A |
| Send a message to SpiNNaker on a particular established UDP
configuration. This is technically one-way, but messages come back in the
same format (i.e., a 4 byte prefix to say that it is a message, and another 4
bytes to say what socket this is talking about). The raw message bytes
(including the half-word of ethernet frame padding) follow the
header. Messages sent on connections opened with Open Unconnected
Channel will be ignored. |
| Open
Unconnected Channel |
|
Response
3
| Correlation ID
| Channel ID
| IP Address
| UDP Port on Server
|
|
| Establish a UDP socket that will receive from the allocation.
Returns an ID that can be used to refer to that channel. Note that opening a
socket declares that you are prepared to receive messages from SpiNNaker on
it, but does not mean that SpiNNaker will send any messages that way. The
correlation ID is caller-nominated, and just passed back uninterpreted in the
response message. Also included in the response message is the IPv4 address
(big-endian binary encoding; one word) and server UDP port for the
connection, allowing the client to instruct SpiNNaker to send messages to the
socket on the server side of the channel (which is not necessarily accessible
from anything other than SpiNNaker). No guarantee is made about whether any
message from anything other than a board in the job will be passed on.
Sending on the channel will only be possible with the Send Message
To operation. |
| Send Message
To |
Request
4
| Channel ID
| Chip X
| Chip Y
| UDP Port on Chip
| Raw message bytes...
|
|
N/A |
| Send a message to a SpiNNaker board (identified by coordinates
of its ethernet chip) to a given UDP port. This is one-way. The raw message
bytes (including the half-word of ethernet frame padding) follow the
header. The channel must have been opened with Open Unconnected
Channel. Any responses come back as standard messages; if doing calls
with this, it is advised to only have one in flight at a time. |
| Error |
N/A |
Response
5
| Correlation ID
| UTF-8 error message bytes...
|
|
| A response that may be given to Open Connected
Channel, Close Channel, or Open Unconnected Channel.
This indicates that a failure to perform an operation occurred. The
correlation ID is whatever ID was provided in the request message that this
is a response to. The remainder of the message is UTF-8 text that provides
some human-readable description of what the problem was, if the server
chooses to provide one.
Note that the server is never required to send this message; it may summarily
close the websocket instead. |