Jack Whitham - Virtual Lab

		JACK WHITHAM

		Home -> vlab Protocol


	On this page: vlab Protocol Interaction example Commands Reference Message Reference Errors Reference


	VL2 documentation: Introduction Administrating VL2 Authorisation File Board Server Board Server Hardware Debug Device Design Goals Downloads EMS Client Extending VL2 Mutual Exclusion Daemon PPC Linux for FX12 FPGAs Relay Shell Using VL2 vlab Module vlab Protocol vlabif Module vlabif Protocol vlabifhw

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:

Using the vlab module or some other API. In this mode, a library interacts with VL2 on your behalf, translating method calls to vlab protocol commands and translating status and error messages to return values and exceptions. If you only do this, you do not need to know about the vlab protocol.
Using any SSH client, e.g. OpenSSH. In this mode, you manually authenticate then interact with VL2 in a "command line" environment. You type vlab protocol commands; VL2 responds with status and error messages according to the vlab protocol. This method is useful in at least two situations:
- Using the serial connection to an FPGA. Every VL2 FPGA has a serial connection to the board server and this is directly accessible by SSH. You can use this mode to interact with programs running on your FPGA. For example, if your FPGA contains a Microblaze processor running uClinux, the serial connection might be used as the system console.
- Debugging VL2 applications. In the command line mode, it is easy to request the status of the board server and inspect the bit files that are loaded. This is useful for checking that your programs have done the right thing.

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.

Command	Accepted by...				Documentation
Command	client	relay	embe dded	mutex daemon	Documentation
`boardassign`	n	y	n	n	Format: boardassign <network_name> <port> Grant access to a board.
`boardrequest`	n	n	n	y	Format: boardrequest <board_name> Request access (and mutual exclusion lock) for board_name.
`check`	n	n	y	n	Format: check Requests information about this board server: its configuration and status.
`connect`	n	y	n	n	Format: 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.
`endlist`	y	y	n	y	Format: endlist Terminates a list.
`error`	y	y	n	y	Format: error <error_code> The general error message; this message is produced by most commands that could not be completed normally.
`exit`	n	y	y	y	Format: exit Disconnect.
`help`	n	y	y	n	Format: help Print a reminder of the available commands.
`instanceoffline`	n	n	n	y	Format: 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.
`jdw`	n	n	y	n	Format: 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.
`loadbits`	n	n	y	n	Format: 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.
`loadready`	y	y	n	n	Format: 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.
`mversion`	y	y	n	n	Format: mversion <version_code> Reports the mutex daemon version.
`ok`	y	n	n	y	Format: ok The general acknowledgement message.
`program`	n	n	y	n	Format: 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.
`reloadmutex`	n	n	n	y	Format: reloadmutex Cause the mutex daemon to reload its configuration file, bringing in new board information without kicking users offline.
`rem`	y	y	y	y	Format: 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.
`setrelay`	n	n	y	n	Format: 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.
`setuart`	n	n	y	n	Format: 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.
`setuid`	n	n	n	y	Format: setuid <uid> Register user id (uid) with mutual exclusion daemon.
`showbits`	n	n	y	n	Format: 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.
`userinfo`	y	y	n	y	Format: 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.
`userrequest`	n	y	n	y	Format: userrequest <board_name> Request the status of each instance of a specific board.
`useuart`	n	n	y	n	Format: 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.
`useuartprogram`	n	n	y	n	Format: 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.
`usinguart`	y	y	n	n	Format: usinguart This message acknowledges a useuart or useuartprogram command.
`wall`	y	n	y	n	Format: 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 Code	Documentation
Message Code	Documentation
`activityinfo`	Format: 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.
`bitinfo`	Format: 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.
`boardinfo`	Format: boardinfo Reports the board server's info_text string. Generated in response to the check command.
`endlist`	Format: endlist Terminates a list.
`error`	Format: error <error_code> The general error message; this message is produced by most commands that could not be completed normally.
`eversion`	Format: eversion <version_code> Reports the board server version.
`fpgainfo`	Format: fpgainfo Reports information about the FPGAs connected to this board server: the number of FPGAs, the driver name, and the Xilinx part name.
`jdwdata`	Format: jdwdata <hexdata> Base-16 encoded data produced as a result of a JDW_SHIFT_RW command.
`jdwfail`	Format: jdwfail <errorstring> Special error type generated when a "JTAG Direct Write" command failed, to distinguish such errors from protocol errors.
`loaded`	Format: 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).
`loadready`	Format: 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.
`mversion`	Format: mversion <version_code> Reports the mutex daemon version.
`ok`	Format: ok The general acknowledgement message.
`programfailed`	Format: programfailed <bid> <error_code> FPGA programming failed.
`programok`	Format: programok <bid> Bit file is now programmed on the FPGA.
`rem`	Format: 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.
`rversion`	Format: rversion <version_code> Reports the relay shell version.
`userinfo`	Format: 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.
`usinguart`	Format: usinguart This message acknowledges a useuart or useuartprogram command.
`wall`	Format: wall <text_message> "Write all": a message from another user of the board server.

Errors Reference

Error Code	Documentation
Error Code	Documentation
`alloc`	Format: error alloc ... Unable to allocate a buffer for this bitfile.
`alreadylocked`	Format: error alreadylocked ... You already hold a lock.
`badbaud`	Format: error badbaud ... Requested baud rate is not supported by the hardware.
`badsize`	Format: error badsize ... Number of bytes is not valid for this FPGA.
`busy`	Format: error busy ... Requested FPGA board is busy.
`cantlockjtag`	Format: error cantlockjtag ... JTAG Direct Write access is locked by something else.
`command`	Format: error command ... Unsupported command.
`config`	Format: error config ... Server configuration error.
`denied`	Format: error denied ... Bitfile id (BID) is not valid: programming is denied.
`disconnect`	Format: error disconnect ... Disconnected.
`donenothigh`	Format: error donenothigh ... DONE pin did not go high.
`idfailed`	Format: error idfailed ... Reading IDCODE from FPGA failed.
`jdwfail`	Format: error jdwfail ... Failure in JTAG Direct Write.
`nojtag`	Format: error nojtag ... No JTAG support on this board.
`nomutexdaemon`	Format: error nomutexdaemon ... The mutual exclusion daemon is not running.
`none`	Format: error none ... No error.
`noresp`	Format: error noresp ... No response.
`nosetuid`	Format: error nosetuid ... Use the setuid command first.
`nospace`	Format: error nospace ... There is no space for new bitfiles.
`nosuchfpga`	Format: error nosuchfpga ... The FPGA number is invalid.
`nosuchrelay`	Format: error nosuchrelay ... The relay number is invalid.
`notjdw`	Format: error notjdw ... Not a valid JTAG Direct Write command.
`notlocked`	Format: error notlocked ... JTAG Direct Write not locked.
`nouart`	Format: error nouart ... Requested UART does not exist.
`parsebits`	Format: error parsebits ... Unable to parse bit file header.
`permission`	Format: error permission ... Board access denied.
`pqfull`	Format: error pqfull ... Programming queue is full.
`tdomismatch`	Format: error tdomismatch ... TDO readback mismatch during XSVF playback: FPGA disconnected?
`timeout`	Format: error timeout ... Connection timed out due to inactivity.
`unavailable`	Format: error unavailable ... Requested FPGA board is not online.
`unknown`	Format: error unknown ... Unknown error.
`unknownboard`	Format: error unknownboard ... Unknown FPGA board requested.
`wrongdriver`	Format: error wrongdriver ... IDCODE not recognised by the driver: FPGA not supported.
`xsvferror`	Format: error xsvferror ... Error in XSVF file.


		Copyright (C) Jack Whitham 1997-2011