JACK WHITHAM    
       
    Home -> vlab Module    

   
 
  On this page:  
 
   
 
  VL2 documentation:  
 
The VL2 client library is implemented in Python as a module named "vlab". You can import "vlab" into your own program by (1) getting the vlab module zip archive from the download page, (2) extracting the archive in your working directory to create a "vlab" subdirectory, then (3) importing "vlab" as follows:
    import vlab
Having done this, you have access to a complete API for controlling FPGAs connected to VL2. You can write programs such as the examples on the user guide page, and you will never need to use the vlab protocol directly.

A typical usage of the module begins as follows:

 1  import vlab
 2  from twisted.internet import reactor
 3
 4  def gotChannel(vl):
 5      pass
 6
 7  auth = vlab.loadAuthorisation("vluser.key")
 8  vlf = vlab.VlabClientFactory(auth)
 9  vlf.getChannel().callback(gotChannel)
10  reactor.connectTCP(auth.relay_server_name, 22, vlf)
where:


Module Documentation

 
 
vlab.vlab
index
vlab.py

# Virtual Lab
# $Id: vlab.py,v 1.17 2009/01/09 23:59:58 jack Exp $
#
# Copyright (C) 2008-2009, Jack Whitham

# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.

# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.

# You should have received a copy of the GNU General Public License along
# with this program; if not, write to the Free Software Foundation, Inc.,
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
#

 
Classes
       
exceptions.Exception
VlabBitfileException
VlabException
ConnectException
VlabErrorException
processor.Twisted
VlabChannel
VlabClientFactory
VlabClientSSHConnection
VlabClientTransport
VlabClientUserAuth
VlabUARTProtocol
VlabAuthorisation
VlabBitInfo
VlabUserInfo
VlabVersion

 
class ConnectException(VlabException)
    
Method resolution order:
ConnectException
VlabException
exceptions.Exception

Methods inherited from exceptions.Exception:
__getitem__(...)
__init__(...)
__str__(...)

 
class VlabAuthorisation
    Holds authorisation data for a virtual lab user.
 
  Methods defined here:
__init__(self)

 
class VlabBitInfo
    Holds information about a bit file, returned by the
getBitInfo method.
 
  Methods defined here:
__init__(self)
__str__(self)

 
class VlabBitfileException(exceptions.Exception)
    An exception that is raised if an invalid bit file is
supplied to the sendBitfile method. 
 
In this case, "invalid" means that the bit file did not
pass validation on the board server, e.g. it was made for the
wrong FPGA type, or it was truncated, or it didn't have a valid
header.
 
  Methods inherited from exceptions.Exception:
__getitem__(...)
__init__(...)
__str__(...)

 
class VlabChannel(processor.Twisted)
    A Protocol for interacting with virtual lab services.
 
Instances of this class are created by VlabClientSSHConnection objects.
 
  Methods defined here:
__init__(self, register_fn=None, debug=False, fail_fn=None, **args2)
Create a new VlabChannel with the specified register_fn.
 
This __init__ method is normally called from the SSHConnection
serviceStarted method.
awaitEndMessage(self)
Creates a Deferred that will be called when an "end" message
is received. 
 
"end" messages indicate that a command has been processed by the
server. The "end" messages are: ok, endlist, usinguart, error.
connect(self, board_name)
Connect to a board. This is only possible
when you have a connection to a relay shell.
 
Returns a Deferred. The callback will be called when the
connection is made; its parameter will be True.
disconnect(self)
Disconnect from a board or relay server.
This method doesn't return anything.
getBitInfo(self)
Request a list of bit file buffers on the board server.
 
Returns a Deferred. The callback will be called with a list
of VlabBitInfo objects, one for each bit file buffer.
getBoardUserInfo(self, board_name)
Request a list of users of the specified board_name.
 
Returns a Deferred. The callback will be called with a list
of VlabUserInfo objects, one for each instance of board_name.
jtagDirectCommand(self, jdw_cmd, *params)
Use the JTAG Direct Write module to execute a JTAG commmand.
 
Returns a Deferred. The callback will be called with a Boolean
that is True if the command was successful, False otherwise.
jtagDirectShift(self, readback, last, data, num_bits)
Shift data using the JTAG Direct Write module.
 
Returns a Deferred. If readback=True, then the callback
will be called with the received data. If not, then the callback
will be called with True.
openUART(self, uart_num, protocol)
Connect the specified Protocol object to UART uart_num.
 
Returns a Deferred. The callback will be called with parameter
True once the action has completed.
openUART is only possible when the channel is connected to a
board server. It can only be done once. Once it is done,
other commands are no longer possible. This means you will
normally need a control connection (for commands) and a
data connection (for UART data).
programFPGA(self, fpga_num, bid)
Schedule programming the specified bit file (bid) onto FPGA fpga_num.
 
Returns a Deferred. The callback will be called with True
as its parameter on success. The errback is called on failure.
programFPGAopenUART(self, fpga_num, bid, uart_num, protocol)
Schedule programming a bit file and open a UART.
 
This method combines the functionality of programFPGA and
openUART. The UART is opened during FPGA programming, so that
(1) no data is captured from the previous configuration, and
(2) no data is lost due to a gap between configuration completion
and a call to openUART. Like openUART, this method returns
a Deferred that is called with parameter True once the action
is completed.  The method can only be called 
when the channel is connected to a
board server, and it can only be called once. Once it is called,
other commands are no longer possible. This means you will
normally need a control connection (for commands) and a
data connection (for UART data).
sendBitfile(self, bits, compress_level=9)
Send a bit file to the board server.
 
Returns a Deferred. The callback will be called with the bid 
(bit file id), which is an integer. To load the bit file onto an
FPGA, you must call programFPGA with the bid.
setRelay(self, relay_number, state)
Set the state of the specified relay.
 
Returns a Deferred. The callback will be called with the OK
message unless the specified relay does not exist.
setUART(self, uart_number, baud)
Set the baud rate for the specified UART.
 
Returns a Deferred. The callback will be called with the OK
message. The baud rate can be any of the standard RS232 baud rates,
e.g. 9600, 38400, 115200.

Data and other attributes defined here:
name = 'session'

 
class VlabClientFactory(processor.Twisted)
    Create new virtual lab clients.
 
The purpose of this class is to connect to a virtual lab
service (a relay shell, to be exact) and then provide access
to the VlabChannel object that has been created during the
connection. The VlabChannel object is used to interact with
the relay shell and board server.
 
A typical usage of VlabClientFactory is as follows:
>>> factory = VlabClientFactory(VlabAuthorisation())
>>> factory.getChannel().addCallback(GotChannel).addErrback(Fail)
>>> reactor.connectTCP('foobar.cs.york.ac.uk', 22, factory)
In this example, your method GotChannel will be called when the
channel is available. The errback function Fail is called if there
is a connection error.
 
An alternative usage allows connections via SOCKS.
>>> factory = vlab.VlabClientFactory(auth_data=VlabAuthorisation(),
        socks_connect_address='foobar.cs.york.ac.uk',
        socks_connect_port=22)
>>> factory.getChannel().addCallback(GotChannel).addErrback(Fail)
>>> reactor.connectTCP('socksserver.example.com', 1080, factory)
In this example, the connection is made via the SOCKS service
at socksserver.example.com.
 
  Methods defined here:
__init__(self, auth_data, socks_connect_address=None, socks_connect_port=None, debug=False)
abort(self)
Abort all scheduled connection attempts.
getChannel(self)
Get the VlabChannel object representing the connection.
 
Returns a Deferred. The callback will be called with the VlabChannel
object.

 
class VlabClientSSHConnection(processor.Twisted)
    SSHConnection for virtual lab services.
 
Instances of this class are created by VlabClientTransport objects.
 
  Methods defined here:
__init__(self, register_fn, fail_fn, debug, *args1, **args2)

 
class VlabClientTransport(processor.Twisted)
    Client transport for virtual lab services.
 
Instances of this class are created by VlabClientFactory objects.
 
  Methods defined here:
__init__(self, register_fn, fail_fn, auth_data, debug, socks_connect_address, socks_connect_port)

 
class VlabClientUserAuth(processor.Twisted)
    Authentication for virtual lab services.
 
Instances of this class are created by VlabClientTransport objects.
 
  Methods defined here:
__init__(self, auth_data, *args1, **args2)

 
class VlabErrorException(VlabException)
    An exception that occurred on the board or relay shell.
 
The exception has been reported over the SSH connection using 
an error message. The VlabErrorException object has an
errorcode attribute that is one of the codes listed in
this module, e.g. ERR_UNAVAIALBLE. It also has an English
description of the error which is printed if the exception is
not caught.
 
 
Method resolution order:
VlabErrorException
VlabException
exceptions.Exception

Methods defined here:
__init__(self, errorcode, reason)

Methods inherited from exceptions.Exception:
__getitem__(...)
__str__(...)

 
class VlabException(exceptions.Exception)
    All virtual lab exceptions inherit this.
 
  Methods inherited from exceptions.Exception:
__getitem__(...)
__init__(...)
__str__(...)

 
class VlabUARTProtocol(processor.Twisted)
    A Protocol for communication with a virtual lab UART.
 
The typical usage for this class is, given a VlabClientFactory vlf:
>>> vl = yield vlf.getChannel()
>>> yield vl.connect("boardname")
>>> uart = VlabUARTProtocol()
>>> yield vl.openUART(0, uart)
 
The protocol automatically buffers incoming data, so you can
wait for data using:
>>> data = yield vlabuart.read(10)
Outgoing data is not buffered. You can send data using:
>>> vlabuart.write(data)
 
Any type of Protocol can be connected to a UART using openUART.
You may also be interested in vlab.terminal.DumbTerminal, which
opens an interactive session, and in the vlabif module, which
implements a higher-level communications protocol for debugging.
 
  Methods defined here:
__init__(self)
consume(self)
Send received data to consumers, if possible.
dataReceived(self, data)
This method is called by the transport when data is
received.
discard(self)
Discards incoming data buffer contents.
flush(self)
Ignored: exists for compatibility.
makeConnection(self, transport)
This method is called automatically when a connection
is made.
read(self, request_nbytes)
Read a number of bytes from the virtual lab UART.
 
Returns a Deferred. The callback will be called with a
string containing the specified number of bytes,
once they are received.
write(self, data)
Write data to the virtual lab UART.

 
class VlabUserInfo
    Holds information about a virtual lab user, returned by the
getBoardUserInfo method.
 
  Methods defined here:
__init__(self)
__str__(self)

 
class VlabVersion
    Holds information about the software versions of various parts
of the virtual lab. Available as the "version" field of VlabChannel.
 
  Methods defined here:
__init__(self)
__str__(self)
lowest(self)
Returns the lowest software version currently in use
within the virtual lab.

 
Functions
       
loadAuthorisation(fname)
Load a VlabAuthorisation object from disk. The object
is typically passed to VlabClientFactory.
processUserInfo(userinfo_table, index, valid, user_name, lock_count)
saveAuthorisation(auth, fname)
Save a VlabAuthorisation object to a disk file, for
distribution to a virtual lab user.
vlabProcessMessage(handler_class, message_table, message_buffer, new_data, debug)
Internal function; process a message that has been received.



       
  Copyright (C) Jack Whitham 1997-2011