Jack Whitham - Virtual Lab

		JACK WHITHAM PhD MEng Professional Activities - Publications - Software - Articles

		Home -> Software -> Virtual Lab -> Board Server


	On this page: Board Server Compiling the board server software Message Handling Board Configuration and the Data Directory The embedded.tgz File FX12 Board Configuration


	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

Board Server

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:

boarddaemon - board server for a Linux workstation. This version uses the user-mode parallel port drivers ("modprobe parport") as a JTAG interface, and a standard serial port for communication. If these are not available, then JTAG debugging data is written to /tmp.
relay - relay shell for a Linux server or workstation (see here).
embedded.tgz - package for the FX12 system. This contains the following files and directories:
- embedded - board server compiled for FX12, i.e. PowerPC Linux.
- data/ - configuration files for each supported FPGA board. These tell the board server how to program the FPGA (see below).
- setup/ - contains three system-specific configuration files (see configuration).
The purpose of embedded.tgz is described below.
Two other programs: mutexdaemon and setupuser.

The modules of the board server are as follows:

embedded.c - main function, initialisation code and server logic. This file contains implementations of each of the commands in the form of C functions. It also implements the select server engine; the select system call is used to listen on a number of file descriptors including TCP/IP connections and UARTs.
bitfilebuf.c - bit file buffers provide temporary storage for FPGA bit files. Any attempt to load a new bit file causes an allocation request to be sent to this module. The least recently used buffer that is not locked is chosen. If the request cannot be satisfied (e.g. if all buffers are locked) then an error message is sent to the user. Buffers are locked in two situations: (1) loading is still in progress, and (2) the bit file in the buffer has been scheduled for programming. In the first situation, the lock expires as soon as loading completes or when the user disconnects.
bitparse.c - the bit file parser obtains the header fields from each bit file (giving the name of the NCD file, target FPGA part name and synthesis date) and is used as part of the validation process for a bit file.
cfgread.c - generic configuration file parser.
common.c - common function library, containing mostly string manipulation functions.
drvxsvf.c - FPGA programming driver that uses the JTAG bus and the Xilinx XSVF player. All FPGA programming drivers in the board server have a standardised interface defined in drv.h: this allows new types of FPGA driver to be added freely. This FPGA driver is not FPGA-specific; it is set up for a particular FPGA using board configuration files.
jtag.c - JTAG driver that acts as an interface to the GPIO driver in the kernel. This supports both low-level JTAG commands (e.g. set TCK = 0) and high-level JTAG commands (e.g. move to SHIFT DR state).
modeljtag.c - A software model of a JTAG controller, intended for testing and debugging purposes. JTAG activity is captured by this model when it is enabled, and written to "/tmp/jtag-debug". Large data transfers (e.g. bit file downloads) are represented by CRC-32 checksums in the debugging file.
pqueue.c - Implements the programming queue: the list of bit files waiting to be loaded onto an FPGA. Bit files in the queue are locked until programming completes. A single bit file can be present in the queue more than once.
sigcatcher.c - Catches POSIX signals that might otherwise cause undesired behaviour, particularly SIGPIPE and SIGHUP.
testmode.c - Implements the "test mode" of the board server. In test mode, the board server can act as a standalone XSVF player. This is useful for testing an XSVF file.
uartbuf.c - Each UART has associated input and output buffers, since writes to a Linux UART device are not buffered in the kernel, and consequently a write operation is not guaranteed to succeed if the UART FIFO is full. This module implements those buffers.
user.c - Implements communication with a user: sending and receiving vlab protocol messages.

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

The 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:

messagecodes (also contains commands)
errorcodes

The message.py compiler uses the definitions in these files to generate the following components:

message.h - macro definitions of the message codes, e.g. MSG_BITINFO. These are used throughout the source code to avoid specifying messages as strings.
message_embedded.c, message_relay.c - command dispatchers for the board server and relay shell. When a command is received, the decoders in these modules determine which C function will handle it, then obtain the parameters.
HTML files - part of this documentation.
vlabmsg.py - part of the vlab module.

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:

    [fpga]
    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. XSVF instructions are available.

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:

econfig - board server configuration file. This specifies (at least) the FPGA board driver to be used. It might also specify other settings for the board server. The default startup scripts copy it to /tmp before running the board server. Here is a sample:
```
        [server]
        bitfile_megabytes = 4
        info_text = virtual lab 2 board!

        [fpga]
        driver = xsvf
        board_dir = data/fx12
```
network - network configuration file. This specifies the MAC address and the IP address for the FX12, in the following format:
```
        export MAC=00:56:4c:41:42:34
        export IP=192.168.124.52
```
There is currently no way to specify a gateway or use DHCP. (DHCP is not very useful since the MAC address would still need to be specified; MAC addresses are not built into Ethernet chipsets, they are obtained from EEPROMs and user software.) Obviously, it is important to ensure that there are no MAC or IP address conflicts on your network.
update - update configuration file. This specifies the source URL for the update.sh script (executed at bootup). Here is an example:
```
        export UPDATE=http://192.168.124.2/VL2/update.sh
```

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
        [server]
        bitfile_megabytes = 4
        info_text = virtual lab 2 board!

        [fpga]
        driver = xsvf
        board_dir = data/fx12
        EOF
        #


		Copyright (C) Jack Whitham 1997-2011