The FPX Wrapper Library

Introduction

The Wrapper Library is a collection of VHDL components to handle higher level protocols directly in hardware. It is primarily designed for the Field-programmable Port Extender (FPX), but could be used in any hardware design. So far, wrappers have been developed for ATM cells, AAL5 frames, IP and UDP.

Documentation

Summary Paper: Layered Protocol Wrappers for Internet Packet Processing in Reconfigurable Hardware, by Florian Braun, John Lockwood, and Marcel Waldvogel, Proceedings of Hot Interconnects 9 (HotI-9) Stanford, CA, Aug 22-24, 2001, pp. 93-98.
Detailed Tech Report: Layered Protocol Wrappers for Internet Packet Processing in Reconfigurable Hardware, by Florian Braun, John W. Lockwood, and Marcel Waldvogel, Washington University, Department of Computer Science, Technical Report WUCS-01-10, July, 2001.

Download and Installation

There are two ways to get hand on the wrapper library. You can either download a distribution file, or you can checkout the VHDL sources via CVS.

Wrapper Distribution File (last updated: October 13, 2003)

You can download the package wrappers.zip. The package contains structural VHDL files to simulate the wrappers with your design and EDIF files to synthesize your design for use in hardware. To simulate your design with the wrappers use the VHDL files in the distribution. To synthesize your design copy the EDN files to the target directory. The Xilinx tools will then include the components. The following files are included in the package:

Cell Processor
cellproc_sim.vhdl	VHDL file to simulate cell processor. This file is not synthesizable.
cellproc.edn	synthesized cell processor
fifo_127x32.edn	coregen components
Frame Processor
frameproc_sim.vhdl	VHDL file to simulate frame processor. This file is not synthesizable.
framewrapper.vhdl	frame wrapper combines cell and frame processor
frameproc.edn	synthesized frame processor
fifo_127x32.edn, fifo_15x7.edn	coregen components
IP Processor
ipproc_sim.vhdl	VHDL file to simulate IP processor. This file is not synthesizable.
ipwrapper.vhdl	IP wrapper combines frame wrapper and IP processor
ipproc.edn	synthesized IP processor
fifo32x36.edn, ram512x16.edn, fifo_512x34.edn	coregen components
UDP Processor
udpproc_sim.vhdl	VHDL file to simulate UDP processor. This file is not synthesizable.
udpwrapper.vhdl	UDP wrapper combines IP wrapper and UDP processor
udpproc.edn	synthesized UDP processor
fifo16x36.edn	coregen component

Wrapper Sources from CVS

The FPX VHDL sources are stored in a CVS repository. If you're local to the ARL network or have an account here, you can checkout the sources in the following ways:

the complete source tree directly via
cvs -d /project/arl/fpx/cvsroot co FPX_ROOT
only the ProtocolWrappers sub-module:
cvs -d /project/arl/fpx/cvsroot co FPX_ROOT/RAD/MODULES/LIB/ProtocolWrappers
if you cannot mount the /project drive (e.g. on univac or external machine), you can use ssh to access CVS:
bash: export CVS_RSH=ssh
csh: setenv CVS_RSH ssh
both: cvs -d <yourname>@chewbacca:/project/arl/fpx/cvsroot co FPX_ROOT/RAD/MODULES/LIB/ProtocolWrappers

To compile the library for simulation type make sim_files in the directory FPX_ROOT/RAD/MODULES/LIB/ProtocolWrappers. Both synplify_pro and the Xilinx tools need to be in your path in order to compile the wrappers. This will create both the EDIF (.edn) files as well as the _sim files need for simulation. The resulting files will be in the edn_files and the sim_files directories.

Examples

If you're using the Layered Protocol Wrappers for the first time, you probably want to take a look at the following examples to see how to use it. There are also two tutorials written in Microsoft PowerPoint slides: the Layered Protocol Wrappers and the Layered Protocol Wrappers Exercise. Be sure to check out the important updates below before using the protocol wrappers.

Wrapper Examples is a framework that can be used to instantiate the Layered Protocol Wrappers. It contains a development directory for each application layer.

Changelog

It is a bit late to start a changelog now that the wrappers are in a fairly stable state, but better late than never!

December 15, 2004 - Fixed a bug which caused incorrect IP checksums to be calculated. Previously, the header checksum calculation didn't check the data enable signal and assumed that the IP header would always come into the circuit as a single chunk. This is not always the case, especially when IP options are included. The outbound processor now checks for data enable signal at each clock cycle during the checksum calculation. Also, the size of some buffers in the outbound IP Processor was increased from 4 deep to 32 deep. This additional buffer depth will help prevent any possible buffer overflow issues.
Affected files: IPwrapper/vhdl/outbound.vhd
June 30, 2004 - Fixed a deficiency in the outbound side of the IP wrapper when packets contain IP options. Previously, the outbound side of the IP wrapper did not include options headers in its checksum calculation. Because of this, any packet that included IP options would have an invalid checksum and would get dropped by the receiver. The inbound side IP wrapper is unchanged as it already processed options correctly.
Affected files: IPwrapper/vhdl/outbound.vhd
March 15, 2004 - Fixed flow control issues in IPProcessor.outbound. An error in the flow control logic may have caused the wrapper code to lock up when exposed to heavy traffic loads.
Affected files: IPwrapper/vhdl/outbound.vhd
October 13, 2003 - Fixed bug in inbound side of the IPProcessor which caused the Non-IPv4-packet data path to lock up after an indeterminate amount of time. Symptoms of this bug included DHCP and ARP packets getting dropped after circuit had been running for a short while.

Important Updates

This section details changes that have been made to the protocol wrappers since the original document was written in 2001. It is extremely important to follow these changes, as without them the wrappers WILL NOT work properly.

A new control signal was added to the IP and UDP Wrapper interfaces. The original IP and UDP wrappers used SOF, SOP, EOF, and DATAEN signals. The newest version of the wrappers introduces another control signal named SOIP. The SOIP signal is asserted high for one clock cycle on the first word of the IP header in both the IP and UDP wrappers. This is helpful because some networks may use frame headers such as LLC/SNAP encapsulation or MAC frames.
If your network does not use any frame headers, then you can just use the distribution as is. However, if your network does use from headers, then you will need to checkout the wrapper distrobution from CVS and modify the FPX_ROOT/RAD/MODULES/LIB/ProtocolWrappers/IPProcessor/vhdl/ipproc.vhd file. The constant at the beginning of the file, num_pre_hdr_wrds, indicates the number of frame headers that you expect to see in your packets. Following this, you must re-synthesize the IP wrapper. Refer to the README file in the wrapper distrobution for details on how to do this.
Another important change to the IP and UDP wrappers has to do with the protocol for sending updates to the outbound side of the IP wrapper. The original wrappers used the data words following the EOF signal to pass updates to the IP wrapper. To do this, bit 15 of these data words was set to 0 when updating and 1 when all updates were complete (see page 12 of Layered Protocol Wrappers for Internet Packet Processing in Reconfigurable Hardware for more details). The newest version of the protocol wrappers makes this a little more intuitive by reversing this protocol. Now, bit 15 of the data words must be set to 1 when sending updates to the IP wrapper, and 0 when no updates are necessary. This change makes it easier for users to generate their own packets since they no longer need to know about setting bit 15 unless they want to send updates.

last updated: $Date: October 13, 2003 15:35:36 $ by jmm5@arl.wustl.edu