Home -> Board Server    

  On this page:  
  VL2 documentation:  
This page describes the custom software for the board server, which is a program named "embedded". One board server is attached to each FPGA board, and provides access to one or more FPGAs on that board. The board server is hosted by an FX12 FPGA (about the hardware) which runs PPC Linux (about the software).

This component of the virtual lab is considered to be confidential, so it is not available for download. However, the documentation is still published for completeness. In the source code repository, the board server can be found in "nonfree/software/".

Compiling the board server software

You must build the GNU toolchains (see here) before you can compile the board server software. Run the "build-software" script in "nonfree". The compiled binaries are placed in the "bin/" directory:

The modules of the board server are as follows: The board server uses two libraries in addition to the standard libc. These are zlib, the compression library used in gzip, and the Xilinx XSVF player distributed with Xilinx Application note XAPP058. The licences on all of these libraries allow them to be linked with proprietary software. The source code for zlib is found in "free/buildroot/build_powerpc/zlib-1.2.3/" after build-buildroot completes. The source code for XSVF is found in "nonfree/software/xsvf/": this has been modified slightly for the board server environment.

Message Handling

vlab protocol message handling system is an unusual feature of the board server software. Commands, messages and error codes are defined in two text files: The message.py compiler uses the definitions in these files to generate the following components: The reason for this design is to avoid specifying anything about a message in more than one place. Generally, it is bad practice to put constant values in code when those constants are used in several locations. Message codes, error codes and commands are constants, so there should be exactly one source definition.

Board Configuration and the Data Directory

The "data/" directory in the embedded.tgz file contains one subdirectory for each supported FPGA board. (Note that an FPGA board is distinct from an actual FPGA. A board might contain several FPGAs, and it might also include other hardware that is not used by VL2.) The subdirectory tells the board server everything it needs to know about each board.

The simplest FPGA board is probably the BurchEd Spartan-2E board, given the name burched here. In order to tell the board server to use this board, you would specify the following section in the econfig configuration file:

    driver = xsvf
    board_dir = data/burched
Because a board subdirectory might support more than one programming method, you have to specify the driver to be used. In this case, it is "xsvf", i.e. the code in "drvxsvf.c" should be used for JTAG programming. The presence of the "xsvf.cfg" file in the board subdirectory is the clue that "xsvf" is supported. You must also specify a path to the board subdirectory ("board_dir"): this can be absolute or relative to the directory that you run "embedded" from. Relative paths are probably easiest, since this makes it easy to use the same configuration files on a workstation and on the FX12.

Unless you want to add support for new types of FPGA board, this is all you will ever need to do: pick the right driver, and give the right "board_dir". Adding support for new types of board is a topic in itself, and there is a different method for each driver.

The embedded.tgz File

The embedded.tgz file contains the board server software, the "data" directory, and sample configuration files. Typically, this would be installed on each FX12 system. This could be done by placing its contents in "free/local/", so it would be included in the root filesystem.

However, because VL2 is useless without a network connection, you might also want each FX12 board to download "embedded.tgz" on bootup. This is useful because it allows software updates to be applied to any number of VL2 systems without needing to update the Flash memory in each one.

This networked update is done by the "free/local/etc/init.d/S60embedded" script, which is executed as Linux boots. It obtains a HTTP URL from the "/jffs2/update" file and downloads update.sh to /tmp/ from that location. update.sh is then executed as a program. The sample update.sh file in bin/ will download embedded.tgz by HTTP, then unpack it. Finally, S60embedded executes "embedded" to start the board server.

FX12 Board Configuration

When an FX12 board has been correctly initialised, the /jffs2/ directory on the FX12 board contains a persistent filesystem implemented by Flash memory. This is used to store system-specific configuration files. There are currently three of these: Sample versions of all of these files can be found in the setup/ directory of embedded.tgz. You should copy the samples to /jffs2/, then edit them to match your requirements. You can use the vi editor. If you don't like vi, you can also create the files using cat, e.g.:
        # cat <<EOF >econfig
        bitfile_megabytes = 4
        info_text = virtual lab 2 board!

        driver = xsvf
        board_dir = data/fx12

  Copyright (C) Jack Whitham 1997-2011