CS/COE 535M

Acceleration of Algorithms in Reconfigurable Hardware

Lockwood, Fall 2001

Machine Problem 3

Software Data Processing in Reprogrammable Hardware

Assigned	Monday, October 8, 2001
Due Date	Friday, October 19, 2001, 4pm
Purpose:	Introduction of the FPX KCPSM Module
Points	50

Introduction

The FPX provides simple and fast mechanisms to process cells or packets directly in hardware. By performing all computations in FPGA hardware, cells and packets can be processing at the full line speed of the card [currently 2.4 Gbits/sec].

Although hardware modules are well suited for processing data with high throughput, software modules are well suited for implementing some complex control functions. For this reason, the FPX KCPSM Module has been implemented for the FPX that executes software on a softcore processor embedded in reprogrammable hardware. By including this design, it is possible to implement active networking functions on the FPX using both hardware and software. The KCPSM, a 8-bit microcontroller from Xilinx Corp. has been embedded into the FPX KCPSM Module. The module includes circuits that allow the program memory of the KCPSM to be dynamically reprogrammed over the network through the use of UDP datagrams. Therefore, the function of the processing module can be changed dynamically, on a packet by packet basis. Currently, up to four packets with a maximum length of 256 bytes can be stored in the module for processing and up to two programs with a maximum length of 256 instructions can be stored in the module for execution.

Background: The FPX KCPSM Module

The FPX KCPSM Module is a small, active, and reconfigurable processing module for the FPX using the Layered Protocol Wrappers and the KCPSM. The Protocol Wrappers process the incoming ATM cells and provide the module with valid UDP packets. The module then loads the contents of the packets into the program or data memory of the processor according to the first word of the payload. If the module takes in a program packet, the KCPSM will reset and run the new program after it has finished processing the current packet. If the module takes in a data packet, the KCPSM will process the new packet after it has finished processing all of the previous packets. When the module is not accepting any incoming packets, it will send the completed program and data packets back to the Layered Protocol Wrappers. The Layered Protocol Wrappers pack the completed packets into valid ATM cells. The block diagram of the FPX KCPSM Module is shown in Figure 1.

Figure 1: Block Diagram of the FPX KCPSM Module

Background: The KCPSM

The KCPSM (Constant (K) Coded Programmable State Machine) is a 8-bit microcontroller and takes only 35 CLBs in a FPGA. It provides 49 different instructions, 16 registers, 256 directly and indirectly addressable ports, and a maskable interrupt at 35 millions instructions per second (MIPS). It can be used in conjunction with an UART to process serial input and output. Its functions and performance are adequate to process packets and control network traffic. The KCPSM was developed by Ken Chapman of Xilinx Corp. and is designed for use with its Virtex and Spartan-II devices. It is provided in the form of an EDIF macro and can be embedded into any FPGA design. It also includes an assembler and debugger for writing and testing programs for the KCPSM. Two modules of dual-port memory are required in order to use the KCPSM. One dual-port memory acts as the program memory while the other acts as the data memory. Both are generated using the COREGEN program provided from Xilinx Corp. The block diagram of the KCPSM is shown in Figure 2.

Figure 2: Block Diagram of the KCPSM

Description of the Assignment

The purpose of the first part of this assignment is to write an assembly program that encrypts / decrypts the string stored in the UDP Payload using the ROT13 algorithm. The purose of the second part of this assignment is to write an assembly program that compresses / decompresses the string stored in the UDP Payload using the RLE algorithm. The purpose of the third part of this assignment is to run both of the assembly programs in simulation using Modelsim.

The tar files for this package can be downloaded here. It consists of six folders, coregen, package, sim, syn, vhdl and wrappers. The coregen folder includes all the files generated from COREGEN. The package folder includes all the files from the KCPSM package from Xilinx Corp. The sim folder includes all the simulation files for use with Modelsim, and the setup is exactly the same as MP1. The syn folder includes the project files for use with Synplicity Pro. The wrappers folder includes all the files from the Layered Protocol Wrappers package. The vhdl folder includes the vhdl files of the FPX_KCPSM module. The contents of the tar file is listed below:

KCPSM/coregen/ COREGEN Folder

kcpsm_sim.vhd The vhdl file for simulating the KCPSM. It is not synthesizable.
program_sim.vhd The vhdl file for simulating the dual-port program memory. It is not synthesizable.
dataram_sim.vhd The vhdl file for simulating the dual-port data memory. It is not synthesizable.
fifo_63x36_sim.vhd The vhdl file for simulating the FIFO used by the FPX KCPSM Module. It is not synthesizable.
*.edn The EDIF Macro files for synthesis with the Xilinx backend tools.

KCPSM/package/ KCPSM Package Folder

kcpsmble.exe The KCPSM assembler.
psmdebug.exe The KCPSM debugger.
convert.exe The KCPSM converter.
chkhello/ and chksum/ and test/ The folder that includes example KCPSM programs.

KCPSM/sim/ Simulation Folder

testbench.vhd The testbench for this FPX module. It is not synthesizable.
clock.vhd The clock for this FPX module. It is not synthesizable.
fake_NID_in.vhd and fake_NID_out.vhd The fake input / output from the NID. It is not synthesizable.
INPUT_CELLS.DAT The input files read by the testbench. Modify this file so that the desired data input is being injected into the RAD.
SW_CELLSOUT.DAT The output files from the egress. Because the loopback_module is instantiated at the egress, the output data is the same as the input data from the NID.
LC_CELLSOUT.DAT The output files from the ingress. Because the ROT13_module is instantiated at the ingress, the output data is modified by the ROT13_module. Look at this file to check if the ROT13_module is actually encrypting or decrypting the data.
testbench.do The Modelsim macro files.
modelsim.ini The Modelsim configuration files. It includes the path to the Xilinx libraries.

KCPSM/syn/ Synthesis Folder

proj.prj and proj.prd The project files for Synplicity Pro. It tells Synplicity Pro which vhdl files should be included for synthesis.
rad-xcve1000/ All the synthesis output files should be stored in this folder.
rad-xcve1000/build The backend script for executing the Xilinx backend tools.
rad-xcve1000/rad_loopback.ucf The FPGA chip pin constraints file.
rad-xcve1000/bitgen.ut The BITGEN option file.

KCPSM/vhdl/ VHDL Source Folder

blink.vhd The vhdl file for the blink component. It controls the blinking of the LED on the FPX board. There is no need to modify this file.
loopback_module.vhd The vhdl file for the loopback_module that is going to be instantiated by the rad_loopback_core. There is no need to modify this file.
rad_loopback_core.vhd The vhdl file for the rad_loopback_core component. It instantiates the interface_module at the ingress and the loopback_module at the egress. There is no need to modify this file.
rad_loopback.vhd The vhdl file for the top-level design of the rad_loopback. There is no need to modify this file.
module.vhd The vhdl file for the interface_module. There is no need to modify this file.
udpecho.vhd The vhdl file for the UDPEcho. There is no need to modify this file.
interface.vhd The vhdl file for the interface. There is no need to modify this file.

KCPSM/wrappers/ The Layered Protocol Wrappers Package Folder

cellproc_sim.vhd The vhdl file for simulating the Cell Processor. It is not synthesizable.
frameproc_sim.vhd The vhdl file for simulating the Frame Processor. It is not synthesizable.
ipproc_sim.vhd The vhdl file for simulating the IP Processor. It is not synthesizable.
udpproc_sim.vhd The vhdl file for simulating the UDP Processor. It is not synthesizable.
framewrapper.vhdl The vhdl file for the Frame Wrapper. It instantiates the Cell Processor and the Frame Processor and connects them together.
ipwrapper.vhdl The vhdl file for the IP Wrapper. It instantiates the Frame Wrapper and the IP Processor and connects them together.
udpwrapper.vhdl The vhdl file for the UDP Wrapper. It instantiates the IP Wrapper and the UDP Processor and connects them together.
*.edn The EDIF Macro files for synthesis with the Xilinx backend tools.

iptestbench/ The IPTESTBENCH Package Folder
udptestbench/ The UDPTESTBENCH Package Folder

Part 1: A ROT13 KCPSM Program

In this part of the assignment, write a KCPSM program that encrypts / decrypts the string stored in the UDP Payload using the ROT13 algorithm. Follow the steps below in order to generate a ".TBP" file from the ROT13 KCPSM program that can be used for simulation in ModelSim. Refer to Figure 3 to understand the format of a UDP Datagram. The FPX data bus is 32-bit, but the KCPSM data bus is only 8-bit, so the lowest 8-bit (7 downto 0) of the FPX data bus corresponds to byte 0, 4, 8 etc. of the KCPSM Data memory and the highest 8-bit (31 downto 24) of the FPX data bus corresponds to byte 3, 7, 11 etc. of the KCPSM Data memory.

Figure 3: Format of a UDP Datagram

KCPSM Registers, Constants and Special Instructions

The KCPSM has 16 8-bit registers and can be used in the program using the "sX" format, where "X" is one of the following: 0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F. Constants can also be used in the program and is specified in the form of a two-digit hexadecimal value ranging from 0x00 to 0xFF.

The KCPSM provides several instructions used to handle Interrupt and I/O operations:

ENABLE INTERRUPT This instruction enables future interrupt requests. If the program wants to support interrupt requests, this instruction should be the first instruction of the program because the KCPSM does not enable interrupt request by default.
DISABLE INTERRUPT This instruction disables future interrupt requests.
RETURNI ENABLE This instruction is a special variation of the RETURN instruction. It concludes an interrupt service routine and specifies that future interrupt requests are enabled.
RETURNI DISABLE This instruction is the same as the RETURNI ENABLE instruction except it specifies that future interrupt requests are disabled.
INPUT This instruction enables 8-bit data values external to the KCPSM to be transferred to any one of the internal registers. The port address can be specified directly as a constant value or indirectly as the contents of any other registers.
OUTPUT This instruction enables 8-bit data values in any one of the internal registers to be transferred to logic external to the KCPSM. The port address can be specified directly as a constant value or indirectly as the contents of any other registers.

For detailed explanation of every instruction available to the KCPSM, refer to the KCPSM Application Notes.

KCPSM Program Template

All KCPSM programs should follow a template in order for them to work with the Interface module. A program should first enables the interrupt of the KCPSM so that the Interface unit is able to reset the KCPSM. Next, it should check if a data packet is stored in the memory. If there is no data packet stored in the memory, it should signal to the Interface that it has done processing and there is no write by writing 0x00 to address 0xFF. If there is a data packet stored in the memory, it can start processing. After the processing is done, it should signals to the Interface that it has done processing by writing 0xFF to address 0xFF. Finally, it should suspends the KCPSM. A KCPSM program template can be downloaded here.

Assembling a KCPSM Program

An assembler called KCPSMBLE is included in the KCPSM package from Xilinx Corp and needs to be executed in a PC platform. KCPSM programs are best written using plain text editors such as Notepad. The program file needs to be saved in a 8.3 file format with a .PSM extension.

The command line used to assemble a KCPSM program is: kcpsmble prog_name.psm.

After KCPSMBLE finishes assembling the program, several files are generated:

Direct EDIF netlist (.edn). It is a "black box" for a single-port block RAM, and its content has been initialized to the machine code of the program starting at address 0x00. This file can be used for synthesis immediately if the KCPSM is connected to the Program Memory using a single-port block RAM in a ROM configuration.
Coefficient File (.coe). It is a coefficient file used by COREGEN. This file can be modified so that the KCPSM can connect to the Program Memory using any blok RAM configuration. For this project, the coefficient file generated by KCPSMBLE has been modified so that COREGEN can generate a dual-port block RAM module with its content being initialized to the machine code of the program.
FORMAT.PSM File. It is the orginal file reformatted.
Log File (.log). It shows the assembly process in details.
Xilinx Foundation Simulation File (.hex). It is used to initialize the contents of the block RAM in simulation.

Debugging a KCPSM Program

A simple debugger called PSMDEBUG is included in the KCPSM package from Xilinx Corp and needs to be executed in a PC platform. It allows the user to test the operation of the program and provides internal program details such as program flow, I/O operations, and values of internal registers and flags. Notice that the ".coe" file used must be the one generated by KCPSMBLE and be unmodified.

The command line used to debug a KCPSM program is: psmdebug prog_name.coe.

Detail instructions on how to debug the program will appear on the screen after PSMDEBUG is executed.

Converting a KCPSM Program

Because the ".coe" file generated by KCPSMBLE is targeted to use with Single-Port block RAMs generated by COREGEN, some modifications to that file must be made before it can be used with the Dual-Port block RAMS. Also, the raw content of the KCPSM program stored in the ".coe" file must be converted before it can be used for simulation or laboratory testing. A C program called CONVERT is written to accomplish these tasks.

The command line used is: convert prog_name.coe.

Two files are generated after the CONVERT program is executed:

program.coe. It is a coefficient file used by COREGEN to generate a dual-port block RAM. The content of the generated dual-port block RAM will be preloaded with the KCPSM program.
INST.TBP. It is a file used by the IP2FAKE and UDPTEST programs. IP2FAKE takes in the INST.TBP file to produced a fake ATM cell for simulation, and UDPTEST takes in the INST.TBP to send a UDP datagram over the network.

Part 2: A RLE KCPSM Program

In this part of the assignment, write a KCPSM program that compresses and another KCPSM program that decompresses the string stored in the UDP Payload using the RLE algorithm. Follow the above steps in order to generate a ".TBP" file from the RLE Encode KCPSM program and another ".TBP" file from the RLE decode KCPSM program that can be used for simulation in ModelSim.

A RLE Encode KCPSM Program

The RLE Encode KCPSM Program compresses the string by replacing the repeating characters by a "count". In order to simplify the problem, the valid input characters are between 'A' to 'Z' and 'a' to 'z', and the maximum repetition is limited to 9. Take a look at the following examples to understand the specifications of the RLE Encode KCPSM Program.

"AAAABBBCCD" is encoded to "A4B3C2D".
"AAAAAAAAAAAAABBBBBBBCCDD" is encoded to "A9A4B7C2D2".
"AAAA444EEF" is not a valid input. Numbers are not allowed in the input string.

Notice that the count is represented as an ASCII number character, not a decimal number, in the encoded string. It is done this way to allow easy testing and verification.

A RLE Decode KCPSM Program

The RLE Decode KCPSM Program decompresses the string by replacing the count with the repeating characters as specified by the value of the count. The valid input of the RLE Decode program includes all the valid output of the RLE Encode program. Take a look at the following examples to understand the specifications of the RLE Decode KCPSM Program.

"A4B3C2D" is decoded to "AAAABBBCCD".
"A9A4B7C2D2" is decoded to "AAAAAAAAAAAAABBBBBBBCCDD".
"A8B1C0DEF" is not a valid input. It does not make sense to make "B" repeat 1 time or "C" repeat 0 time.
"A8B7C34DF" is not a valid input. It does not need to support repetitions that are more than 9 times.

Part 3: Simulation of the ROT13 and RLE Programs

In this part of the assignment, simulate the ROT13 and RLE KCPSM program in Modelsim.

Using the IPTestbench to Generate Fake ATM Cells for Simulation

A simulation simulation testbench has been setup to test the functionality of this module, which is the same setup as the previous machine problems. In order to generate a fake program packets/cells for simulation, use the ".TBP" file generated by the CONVERT program as the input to the IP2FAKE program. In order to generate a fake data packets/cells for simulation, use a plain text editor to modify the following sample ".TBP" file, and use it as the input to the IP2FAKE program. Please note that the first word of the payload must be 0x00000001 to indicate that it is a data packet/cell. The sample "HELLO.TBP" program can be download here.

The command line option to build the IPTestbench package is: make.

Copy the "INST.TBP" and "HELLO.TBP" file into the iptestbench folder.
The command line option to use the ip2fake program is: ip2fake FILENAME.TBP FILENAME.DAT.

Copy the "INST.DAT" and "HELLO.DAT" into the sim folder. Create a new input file to the testbench by using the "cat" command.
The command line option to use the cat program is: cat WAIT.DAT INST.DAT WAIT.DAT HELLO.DAT > INPUT_CELLS.DAT.

Implementation Hints for the ROT13 and RLE KCPSM Programs

There are some suggestions to approach this assignment:

Read the FPX KCPSM Module Technical Report. It provides detailed information on the FPX KCPSM Module.
Read the KCPSM Application Notes. It provides detailed information on the KCPSM.
Read the IPTestbench Webpage. It provides detailed information on how to build and use the IPTestbench Package.
Read the UDPTestbench Webpage. It provides detailed information on how to build and use the UDPTestbench Package.
There is no multiplication / division / modulo instruction in the KCPSM instruction set. Try to avoid using them.
There is no comparison instruction in the KCPSM instruction set. Try to use the substract instruction in conjunction with the conditional jump instruction instead.
There is no stack or internal memory in the KCPSM. The 16 registers are all the temporary storage, so use them effectively.
The UDP Length field is at byte 0x1C and 0x1D. Try to verify this using Figure 3.
The first word of the UDP Payload is at byte 0x20. Try to verfiy this using Figure 3.

Things to Turn In

Here is a check list of the things you need to turn in:

The Software Data Processing in Reprogrammable Hardware
- ROT13 KCPSM Program code that assembles and works.
- Timing diagram(s) (from Modelsim) clearly showing that the ROT13 KCPSM program is working correctly.
- RLE Encode and Decode KCPSM Program codes that assemble and work.
- Timing diagram(s) (from Modelsim) clearly showing that the RLE Encode and Decode KCPSM programs are working correctly.

Please print the grade sheet and staple it on top of your machine problem.