JACK WHITHAM    
       
    Home -> vlab Protocol    

   
 
  On this page:  
 
   
 
  VL2 documentation:  
 
All communication between a VL2 client (e.g. the vlab module) and a relay shell takes place via the SSH protocol. Within the SSH connection, the vlab protocol is used.

You can control VL2 in two equivalent ways:

Interaction example

When you are connected to the relay shell, you use the "connect" command to make a connection to a specific board. For example, to connect to board "s3esk", you enter:

    connect s3esk
Once connected, you can issue any of the commands listed in the
reference below. The "help" command gives a useful reminder of the commands available. As an example of another useful command, in order to set the baud rate of UART 0 to 115200 baud, you would send:
    setuart 0 115200
Most commands return a message beginning with either "ok" or "error", but other messages can be generated (see reference). Messages consist of a message code followed by additional information: if an error has occurred, this will usually explain why. For example, trying to set a UART to the unsupported baud rate of 555 baud produces the following message:
    setuart 0 555
    error badbaud Requested baud rate is not supported.
The second word on the "error" line is the "short error code". It tells the client software about the error message. Of course, the client library could raise an exception with the descriptive text ("Requested baud rate is not supported."), but this would be unhelpful since the actual error condition could only be identified by parsing the text, which might change in future versions. Therefore, a version-independent short error code is used instead.

The set of available commands changes depending on whether you are connected to the relay server or board server.

Commands Reference

Commands are accepted by the relay shell and board server. They are also sent between the relay shell and the mutual exclusion daemon.
CommandAccepted by...Documentation
clientrelayembe ddedmutex daemon
boardassignnynnFormat:
boardassign <network_name> <port>
Grant access to a board.
boardrequestnnnyFormat:
boardrequest <board_name>
Request access (and mutual exclusion lock) for board_name.
checknnynFormat:
check 
Requests information about this board server: its configuration and status.
connectnynnFormat:
connect <board_server_name>
Connect to the specified board server. The board server is identified by an English name, which must be in the configuration file for the relay server. The relay server configuration file gives the network address of the board server. There is (intentionally) no way to connect to an arbitrary network address or port number. This command is only supported on the relay server.
endlistyynyFormat:
endlist 
Terminates a list.
erroryynyFormat:
error <error_code>
The general error message; this message is produced by most commands that could not be completed normally.
exitnyyyFormat:
exit 
Disconnect.
helpnyynFormat:
help 
Print a reminder of the available commands.
instanceofflinennnyFormat:
instanceoffline 
Notify the mutex daemon that the assigned instance is offline (this always follows a boardrequest and boardassign). The board will be removed from circulation for a short period of time.
jdwnnynFormat:
jdw <parameters...>
"JTAG Direct Write". The parameter(s) are interpreted by the JTAG Direct Write module according to its own protocol which is not documented here.
loadbitsnnynFormat:
loadbits <number_of_bits>
Tell the board server that the user wishes to upload a bit file. The bit file must be compressed with zlib after being generated in .bit format by the Xilinx bitgen tool. Headerless bit files are not allowed; neither are uncompressed bit files. The parameter is the size of the bit file, in bits, after compression. The board server configuration specifies a maximum size for the compressed data. After this command is acknowledged by a loadready message, the user must send the compressed bit file data. The bit file data may be recorded by the relay server.
loadreadyyynnFormat:
loadready <bid> <number_of_bits>
The board server is ready to receive a compressed bit file. The parameters of this message specify the bit file id (bid) and the number of bits that are expected. Once this message is received, transfer of the compressed bit file should begin.
mversionyynnFormat:
mversion <version_code>
Reports the mutex daemon version.
okynnyFormat:
ok 
The general acknowledgement message.
programnnynFormat:
program <fpga_number> <bid>
A job is scheduled for the FPGA programmer, requesting that the bit file with the given bid be programmed onto the specified FPGA. This command will fail if a valid bit file with the given bid is not present in the bit file buffers: the buffers operate on a least recently used basis, so old bit files can be removed by new ones, although bit files in the programming queue are never removed. Note:
  • This command returns immediately with an acknowledgement message; the actual programming process will take place at some point in the future.
  • Use the check command to examine the status of the programming queue.
  • Users can issue further commands after program.
  • Disconnecting does not remove items from the programming queue.
  • A second acknowledgement message is sent if the user is still connected when programming completes.
reloadmutexnnnyFormat:
reloadmutex 
Cause the mutex daemon to reload its configuration file, bringing in new board information without kicking users offline.
remyyyyFormat:
rem 
This message should always be ignored by software. It exists for the benefit of users that have connected directly to lab services using SSH.
setrelaynnynFormat:
setrelay <relay_number> <state>
Sets the state of a relay, if relays are present on the board. The state may be 1 (on) or 0 (off). Currently, relays are only supported on the FX12 platform, which has two relays numbered 1 and 2.
setuartnnynFormat:
setuart <uart_number> <baud_rate>
The baud rate of the specified UART is set. Not all baud rates are supported, but all of the most common RS232 rates are available. The UART is identified by a number from 0 to 3. For some FPGA boards, only UART 0 is connected to FPGA hardware. The change in baud rate takes place as soon as the current contents of the outgoing buffer have been sent. The UART always operates with 8 bits, no parity, and one stop bit.
setuidnnnyFormat:
setuid <uid>
Register user id (uid) with mutual exclusion daemon.
showbitsnnynFormat:
showbits 
List the bit files already loaded on the board server. Bit files are stored in bit file buffers when they have been loaded. This command will generate a number of bitinfo messages, one for each bit file buffer.
userinfoyynyFormat:
userinfo <index> <valid> <user_name> <lock_count>
Reports the status of an instance of a specific board. This shows who is currently using that board.
userrequestnynyFormat:
userrequest <board_name>
Request the status of each instance of a specific board.
useuartnnynFormat:
useuart <uart_number>
Connect to the specified UART. After this command is acknowledged by an ok message, any data that is sent will be relayed to the UART. Any data received by the UART is sent across the network. The connection is 8 bit clean, i.e. all bytes are relayed verbatim. There is no way to exit from this command apart from disconnecting. If this command is used on a UART that another user is currently using, then the older user is disconnected and their connection is replaced with the new one. The UART always operates with 8 bits, no parity, and one stop bit.
useuartprogramnnynFormat:
useuartprogram <fpga_number> <uart_number> <bid>
Two actions are taken. Firstly, programming is scheduled for a specified FPGA as for the program command. Then, during programming, the action for a useuart command is executed. In this way, UART output can be captured from the very beginning of FPGA operation without capturing output from the previous FPGA configuration. Two acknowledgement messages are generated: ok (immediately) and usinguart during programming.
usinguartyynnFormat:
usinguart 
This message acknowledges a useuart or useuartprogram command.
wallynynFormat:
wall <text_message>
"Write all": send a text message to all other users of the board server. The message is not 8 bit clean (all characters must be printable according to the C function isprint) and the length is also limited.

Message Reference

Messages are sent to the user by the relay shell or board server. They are also sent between the relay shell and the mutual exclusion daemon.
Message CodeDocumentation
activityinfoFormat:
activityinfo <num_queue_items> <percent_done>
Reports the status of the programming queue. The number of items in the queue is given along with the percentage of the current item that has been sent.
bitinfoFormat:
bitinfo <index> <bid> <number_of_bits> <design_name> <part_name> <syn_date> <syn_time>
Reports the status of a bit file buffer. When a bit file is correctly loaded, number_of_bits will be greater than zero. If an error occurred, or if the load is not complete, the status will be reported in the design_name field.
boardinfoFormat:
boardinfo 
Reports the board server's info_text string. Generated in response to the check command.
endlistFormat:
endlist 
Terminates a list.
errorFormat:
error <error_code>
The general error message; this message is produced by most commands that could not be completed normally.
eversionFormat:
eversion <version_code>
Reports the board server version.
fpgainfoFormat:
fpgainfo 
Reports information about the FPGAs connected to this board server: the number of FPGAs, the driver name, and the Xilinx part name.
jdwdataFormat:
jdwdata <hexdata>
Base-16 encoded data produced as a result of a JDW_SHIFT_RW command.
jdwfailFormat:
jdwfail <errorstring>
Special error type generated when a "JTAG Direct Write" command failed, to distinguish such errors from protocol errors.
loadedFormat:
loaded <bid> <is_valid>
Bit file loading is complete. If is_valid is non-zero, then the bit file decompressed correctly and passed the validation checks (which examine the bit file header).
loadreadyFormat:
loadready <bid> <number_of_bits>
The board server is ready to receive a compressed bit file. The parameters of this message specify the bit file id (bid) and the number of bits that are expected. Once this message is received, transfer of the compressed bit file should begin.
mversionFormat:
mversion <version_code>
Reports the mutex daemon version.
okFormat:
ok 
The general acknowledgement message.
programfailedFormat:
programfailed <bid> <error_code>
FPGA programming failed.
programokFormat:
programok <bid>
Bit file is now programmed on the FPGA.
remFormat:
rem 
This message should always be ignored by software. It exists for the benefit of users that have connected directly to lab services using SSH.
rversionFormat:
rversion <version_code>
Reports the relay shell version.
userinfoFormat:
userinfo <index> <valid> <user_name> <lock_count>
Reports the status of an instance of a specific board. This shows who is currently using that board.
usinguartFormat:
usinguart 
This message acknowledges a useuart or useuartprogram command.
wallFormat:
wall <text_message>
"Write all": a message from another user of the board server.

Errors Reference

Error CodeDocumentation
allocFormat:
error alloc ...
Unable to allocate a buffer for this bitfile.
alreadylockedFormat:
error alreadylocked ...
You already hold a lock.
badbaudFormat:
error badbaud ...
Requested baud rate is not supported by the hardware.
badsizeFormat:
error badsize ...
Number of bytes is not valid for this FPGA.
busyFormat:
error busy ...
Requested FPGA board is busy.
cantlockjtagFormat:
error cantlockjtag ...
JTAG Direct Write access is locked by something else.
commandFormat:
error command ...
Unsupported command.
configFormat:
error config ...
Server configuration error.
deniedFormat:
error denied ...
Bitfile id (BID) is not valid: programming is denied.
disconnectFormat:
error disconnect ...
Disconnected.
donenothighFormat:
error donenothigh ...
DONE pin did not go high.
idfailedFormat:
error idfailed ...
Reading IDCODE from FPGA failed.
jdwfailFormat:
error jdwfail ...
Failure in JTAG Direct Write.
nojtagFormat:
error nojtag ...
No JTAG support on this board.
nomutexdaemonFormat:
error nomutexdaemon ...
The mutual exclusion daemon is not running.
noneFormat:
error none ...
No error.
norespFormat:
error noresp ...
No response.
nosetuidFormat:
error nosetuid ...
Use the setuid command first.
nospaceFormat:
error nospace ...
There is no space for new bitfiles.
nosuchfpgaFormat:
error nosuchfpga ...
The FPGA number is invalid.
nosuchrelayFormat:
error nosuchrelay ...
The relay number is invalid.
notjdwFormat:
error notjdw ...
Not a valid JTAG Direct Write command.
notlockedFormat:
error notlocked ...
JTAG Direct Write not locked.
nouartFormat:
error nouart ...
Requested UART does not exist.
parsebitsFormat:
error parsebits ...
Unable to parse bit file header.
permissionFormat:
error permission ...
Board access denied.
pqfullFormat:
error pqfull ...
Programming queue is full.
tdomismatchFormat:
error tdomismatch ...
TDO readback mismatch during XSVF playback: FPGA disconnected?
timeoutFormat:
error timeout ...
Connection timed out due to inactivity.
unavailableFormat:
error unavailable ...
Requested FPGA board is not online.
unknownFormat:
error unknown ...
Unknown error.
unknownboardFormat:
error unknownboard ...
Unknown FPGA board requested.
wrongdriverFormat:
error wrongdriver ...
IDCODE not recognised by the driver: FPGA not supported.
xsvferrorFormat:
error xsvferror ...
Error in XSVF file.



       
  Copyright (C) Jack Whitham 1997-2011