JOP - Java Optimized Processor

Home
Documentation
Performance
Download
Applications
Getting Started
Simulation
Links

Cyclone Board
LEON/Nios
Acex Board

LEGO MindStorms
Java TCP/IP

Teaching Material

Contact

Wiki

Getting Started

This document is also available as PDF: An Introduction to the Design Flow for JOP

This document describes the design flow for JOP - how to build the Java processor and a Java application from scratch (the VHDL and Java sources) and download the processor to an FPGA and the Java application to the processor.

1 Introduction

JOP [2], the Java optimized processor, is an open-source development available for different targets (Altera and Xilinx FPGAs and various types of FPGA boards). To support several targets the design-flow gets a little bit complicated. There is a Makefile available and when everything is set up correct a simple

    make

should build everything from the sources and download a Hello World example. However, to costumize the Makefile for a different target it is necessary to understand the complete design flow.

1.1 Tools

All needed tools are freely available.

Java 2 Platform 1.4, Standard Edition Java compiler and runtime
Cygwin GNU tools for Windows. Packages cvs, gcc and make are needed
Quarts II Web Edition VHDL synthesis, place and route for Altera FPGAs
Jam STAPL Byte-Code Player FPGA configuration in batch mode (jbi32.exe)

The PATH variable should contain entries to the executables of all packages (java and javac, Cygwin bin, Quartus executables and jbi32). Check the PATH at the command prompt with:

    javac
    gcc
    make
    cvs
    quartus_map
    jbi32

All the executables should be found and usually report their usage.

1.2 Getting Started

This sections shows a quick step-by-step build of JOP for the Cyclone target in the minimal configuration. All directory paths are given relative to the JOP root directory jop. The build process is explained in more detail in one of the following sections.

1.2.1 Download the Source

Create a working directory and download JOP from the www.opencores.org CVS server:

 cvs -d :pserver:anonymous@cvs.opencores.org:/cvsroot/anonymous -z9 co -P jop

All sources are downloaded to a directory jop. For the following command change to this directory. Create the needed directories with:

    make directories

1.2.2 Tools

The tools are built with following make command:

    make tools

1.2.3 Assemble the Microcode JVM, Compile the Processor

The JVM configured to download the Java application from the serial interface is built with:

    make jopser

This command also invokes Quartus to build the processer. If you want to build it within Quartus follow the following instructions:

Start Quartus II and open the project jop.qpf from directory quartus/cycmin in Quartus with File - Open Project.... Start the compiler and fitter with Processing - Start Compilation. After successful compilation the FPGA is configured with Tools - Programmer and Start.

1.2.4 Compiling and Downloading the Java Application

A simple Hello World application is the default application in the Makefile. It is built and downloaded to JOP with:

    make japp

The "Hello World" message should be printed in the command window and the LED on the board should blink.

For a different application change the Makefile targets or override the make variables at the command line. Following example builds and runs some benchmarks on JOP:

    make japp -e P1=bench P2=jbe P3=DoAll

1.3 Xilinx Spartan-3 Starter Kit

For the Xilinx starter kit the design flow is very similar:

Compile the ISE project under xilinx/s3sk
Download JOP to the FPGA
Connect a serial cable from the board to your PC
Open a command prompt in java/target
Change the COM-port in doit.bat and disable the line with jbi32.exe
type: doit test test Hello

Now your first Java program runs on JOP/Spartan-3!

2 Booting JOP - How Your Application Starts

Basically this is a two step process: a.) configure the FPGA and b.) load the Java application. There are different ways to perform these steps.

2.1 FPGA Configuration

FPGAs are usually SRAM based and lose their configuration after power down. Therefore the configuration has to be loaded on power up. For development the FPGA can be configured via a download cable (with JTAG commands). This can be done within the IDEs from Altera and Xilinx or with command line tools such as quartus_pgm or jbi32.

When the device shall boot automatically the configuration has to be stored in non volatile memory such as Flash. Serial Flash is directly supported by an FPGA to boot on power up. Another method is to use a standard parallel Flash to store the configuration and additional data (e.g. the Java application). A small PLD reads the configuration data from the Flash and shifts it into the FPGA. This method is used on the Cyclone and ACEX boards.

2.2 Java Download

When the FPGA is configured the Java application has to be downloaded into the main memory. This download is performed in microcode as part of the JVM startup sequence. The application is a .jop file generated by JOPizer. At the moment there are three options:

Serial line: JOP listens to the serial line and the data is written into the main memory. A simple echo protocol performs the flow control. The baud rate is usually 115kBaud.
USB: Similar to the serial line version, JOP listens to the parallel interface of the FTDI FT2232 USB chip. The FT2232 performs the flow control on the USB level and the echo protocol is omitted.
Flash: For stand alone applications the Java program is copied from the Flash (relative Flash address 0, mapped Flash address is 0x80000¹) to the main memory (usually a 32-bit SRAM).

To select on method for downloading a customized version of the JVM is generated and the complete processor has to be built. The generation is performed by the C preprocessor (gcc) on jvm.asm. The serial version is generated by default, the USB or Flash version are generated by defining the preprocessor variables USB or FLASH. To speed up simulation in ModelSim there is a forth method where the Java application is loaded by the test bench instead of JOP. This version is generated by defining SIMULATION. There are four small batch-files in directory asm that perform the JVM generation: jopser, jopusb, jopflash, and jopsim.

2.3 Combinations

Theoretically all ways to configure the FPGA can be combined with all ways to download the Java application. However, only two combinations are useful:

For VHDL or Java development configure the FPGA via the download cable and download the Java application via the serial line or USB.
For a stand-alone application load the configuration and the Java program from the Flash.

3 The Design Flow

This section describes the design flow to build JOP in greater detail.

3.1 Tools

There are a few tools necessary to build and download JOP to the FPGA boards. Most of them are written in Java. Only the tools that access the serial line are written in C².

3.1.1 Downloading

These little programs are already compiled and the binaries are checked in in the CVS. The sources can be found in directory c_src.

down.exe: The workhorse to download Java programs. The mandatory argument is the COM-port. Optional switch -e keeps the program running after the download and echoes the characters from the serial line (System.out in JOP) to stdout. Switch -usb disables the echo protocol to speed up the download over USB.
e.exe: Echo the characters from the serial line to stdout. Parameter is the COM-port.
amd.exe: An utility to send data over the serial line to program the on-board Flash. The complementary Java program util.Amd must be running on JOP.
USBRunner.exe: Download the FPGA configuration via USB with the FTDI2232C chip (dpsio board).

3.1.2 Generation of Files

These tools are written in Java and are delivered in source form. The source can be found under java/tools/src and the class files are in jop-tools.jar in directory java/tools/dist/lib.

Jopa: The JOP assembler. Assembles the microcoded JVM and produces on-chip memory initialization files and VHDL files.
BlockGen: converts Alter memory initialization files to VHDL files for a Xilinx FPGA.
JOPizer: links a Java application and converts the class information to the format that JOP expects (a .jop file). JOPizer uses the bytecode engineering library (BCEL).

3.1.3 Simulation

JopSim: reads a .jop file and executes it in a debug JVM written in Java. Command line option -Dlog="true" prints a log entry for each executed JVM bytecode.
pcsim: simulates the BaseIO expansion board for Java debugging on a PC (using the JVM on the PC).

3.2 Targets

JOP has been successfully ported to several different FPGAs and boards. The main distribution contains the ports for the FPGAs:

Altera Acex 1K30 or 1K50
Altera Cyclone EP1C6 or EP1C12
Xilinx Spartan-3

Besides the ports to different FPGAs there are ports to different boards.

3.2.1 ACEX EP1K50C144 Jopcore

This board was one of the first targets (besides the KFL project) for JOP and the design files of the board are now available as open-source from http://www.opencores.org/projects.cgi/web/acxbrd/overview. As the FPGA is a little bit dated the latest features of JOP (e.g. the enhancements in the method cache) are not available in the Acex port. Use jop_20040913_v37_web.zip from the archive section. Two Quartus projects for this board are available: acxmin, a minimum configuration containing only a serial interface, and acxtal, a configuration for the baseio extension board. The ACEX specific files are jopacx.vhd and mem.vhd.

3.2.2 Cyclone EP1C6/12

This board is pin-compatible to the ACEX board and comes in two versions: with an Cyclone EP1C6 or EP1C12. The board contains:

Altera Cyclone EP1C6Q240 or EP1C12Q240 FPGA (see data sheet)
1MB fast SRAM
512KB Flash (for FPGA configuration and program code)
32MB NAND Flash
ByteBlasterMV port
Watchdog with LED
EPM7064 PLD to configure the FPGA from the Flash (on watchdog reset)
Voltage regulator (1V5)
Crystal clock (20 MHz) at the PLL input (up to 640 MHz internal)
Serial interface (MAX3232)
56 general purpose IO pins

The Cyclone specific files are jopcyc.vhd or jopcyc12 and mem32.vhd. This FPGA board is designed as a module to be integrated with an application specific IO-board. There exist following IO-boards:

simpexp: A simple bread board with a voltage regulator and a SUBD connector for the serial line
baseio: A board with Ethernet connection and EMC protected digital IO and analog input
bg263: Interface to a GPS receiver, a GPRS modem, keyboard and a display for a railway application
lego: Interface to the sensors and motors of the LEGO Mindstorms. This board is a substitute for the LEGO RCX.
dspio: Developed at the University of Technology Vienna, Austria for digital signal processing related work. All design files for this board are open-source.

Table 1 lists the related VHDL files and Quartus project directories for each IO board.

IO board	Quartus	IO top level
simpexp	`cycmin`	`scio_min.vhd`
baseio	`cycbaseio`	`scio_baseio.vhd`
bg263	`cybg`	`scio_bg.vhd`
lego	`cyclego`	`scio_lego.vhd`
dspio	`dspio`	`scio_dspio.vhd`

Table 1: Quartus project directories and VHDL files for the different IO boards

3.2.3 Xilinx Spartan-3

The Spartan-3 specific files are jop_xs3.vhd and mem_xs3.vhd for the Xilinx Spartan-3 Starter Kit and jop_trenz.vhd and mem_trenz.vhd for the Trenz Retrocomputing board.

4 Eclipse

In folder eclipse there are several Eclipse projects that you can import into your Eclipse workspace. All projects use the Eclipse path variable³ JOP_HOME that has to point to the root directory of the JOP sources. Under Window - Preferences... select General - Workspace - Linked Resources and create the path variable JOP_HOME with New....

Import the projects with File - Import.. and Existing Projects into Workspace. Select as root directory .../jop/eclipse, select the projects you want to import and press Finish. Table 2 shows all available projects.

Project	Content
`jop`	The target sources
`joptools`	Tools such as `Jopa`, `JopSim`, and `JOPizer`
`pc`	Some PC utilities (e.g. Flash programming via UDP/IP)
`pcsim`	Simulation of the basio hardware on the PC

Table 2: Eclipse projects

Add the libraries from .../jop/java/lib (as external archives) to the build path of the project joptools⁴. If you prefer your workspace to be out of the JOP directory tree just copy the content of .../jop/eclipse to your Eclipse workspace and import the projects from there.

5 Simulation

This section contains the information you need to get a simulation of JOP running. There are two ways to simulate JOP:

High-level JVM simulation with JopSim
VHDL simulation (e.g. with ModelSim)

This section is about running a VHDL simulation with ModelSim. All simulation files are vendor independent and should run on any versions of ModelSim or a different VHDL simulator. You can simulate JOP even with the free ModelSim XE II Starter Xilinx version.

5.1 Background Information

To simulate JOP, or any other processor design, in a vendor neutral way models of the internal memories (block RAM) and the external main memory are necessary. Beside this, only a simple clock driver is necessary. To speed-up the simulation a little bit a simulation of the uart output, which is used for System.out.print(), is also part of the package.

Table 3 lists the simulation files for JOP and which program generates the initialization data. The non-generated VHDL files can be found in directory vhdl/simulation.

VHDL file	Function	Initilization file	Generator
`sim_jop_types_100.vhd`	JOP constant definitions	-	-
`sim_rom.vhd`	JVM microcode ROM	`mem_rom.dat`	`Jopa`
`sim_ram.vhd`	Stack RAM	`mem_ram.dat`	`Jopa`
`sim_jbc.vhd`	Bytecode memory (cache)	-	-
`sim_memory.vhd`	Main memory (Java application)	`mem_main.dat`	`jop2dat`
`sim_pll.vhd`	A dummy entity for the PLL	-	-
`sim_uart.vhd`	Print characters to stdio	-	-

Table 3: Simulation specific VHDL files

The needed VHDL files and the compile order can be found in sim.bat under modelsim.

The actual version of JOP contains all necessary files to run a simulation with ModelSim (or is there another VHDL simulator available?). In directory vhdl/simulation you will find:

A test bench: tb_jop.vhd with a serial receiver to print out the messages from JOP during the simulation
Simulation versions of all memory components (vendor neutral)
Simulation of the main memory

Jopa generates various mem_xxx.dat files that are read by the simulation. The JVM that is generated with jopsim.bat assumes the Java application preloaded in the main memory. jop2dat generates a memory initialization file from the Java application file (package_App.jop) that is read by the simulation of the main memory (sim_memory.vhd).

In directory modelsim you will find a small batch file (sim.bat) that compiles JOP and the test bench in the correct order and starts ModelSim.

The whole simulation process (including generation of the correct microcode) is started with:

    make sim

After a few seconds you should see the startup message from JOP printed in ModelSims command window.

6 Files Types You Might Encounter

As there are various tools involved in the complete build, you will find files with various extensions. The following list explains the file types you might encounter when changing and building JOP.

The list is far from being complete - it's just a start. The following files are the source files:

.vhd: VHDL files describe the hardware part and are compiled with either Quartus or Xilinx ISE. Simulation in ModelSim is also based on VHDL files.
.v: Verilog HDL. Another hardware description language. Used more in the US.
.java: Java - the language that runs native on JOP.
.c: There are still some tools written in C.
.asm: JOP microcode. The JVM is written in this stack oriented assembler. Files are assembled with Jopa. The result are VHDL files, .mif files, and .dat files for ModelSim.
.bat: Usage of these DOS batch files still prohibit running the JOP build under Unix. However, these files get less used as the Makefile progresses.
.xml: Project files for Ant. Not used anymore - they are out dated.

Quartus II and Xilinx ISE need configuration files that describe your project. All files are usually ASCII text files.

.qpf: Quartus II Project File. Contains almost no information.
.qsf: Quartus II Settings File defines the project. VHDL files that make up your project are listed. Constraints such as pin assignments and timing constraints set here.
.cdf: Chain Description File. This file stores device name, device order, and programming file name information for the programmer.
.tcl: Tool Command Language. Can be used in Quartus to automate parts of the design flow (e.g. pin assignment).
.npl: Xilinx ISE project. VHDL files that make up your project are listed. The actual version of Xilinx ISE converts this project file to a new format that is not in ASCII anymore. Very annoying.
.ucf: Xilinx Foundation User Constraint File. Constraints such as pin assignments and timing constraints set here.

javac and jar produce following file types from the Java sources:

.class: A class file contains the bytecodes, a symbol table and other ancillary information and is executed by the JVM.
.jar: The Java Archive file format enables you to bundle multiple files into a single archive file. Typically a .jar file will contain the class files and auxiliary resources. A .jar file is essentially a zip file that contains an optional META-INF directory.

The following files are generated by the various tools from the source files:

.jop: The file makes up the linked Java application that runns on JOP. It is generated by JOPizer and can be either downloaded (serial line or USB) or stored in the Flash (or used by the simulation with JopSim or ModelSim)
.mif: Memory Initialization File. Describe the initial content of on-chip block memories for Altera devices.
.dat: memory initialization files for the simulation with ModelSim.
.sof: SRAM Output File. Configuration for Altera devices. Used by the Quartus programmer or by quartus_pgm. Can be converted to various (or too many) different format. Some are listed below.
.pof: Programmer Object File. Configuration for Altera devices. Used for the Flash loader PLDs.
.jbc: JamTM STAPL Byte Code 2.0. Configuration for Altera devices. Input file for jbi32.
.ttf: Tabular Text File. Configuration for Altera devices. Used by flash programming utilities (amd and udp.Flash to store the FPGA configuration in the boards Flash.
.rbf: Raw Binary File. Configuration for Altera devices. Used by the USB download utility (USBRunner) to configure the dspio board via the USB connection.
.bit: Bitstream File. Configuration for Xilinx devices.

7 Porting JOP

Add a description about the files (memory).

7.1 Test Utilities

To verify that the port of JOP is successful there are some small test programs in asm/src. To run the JVM on JOP the microcode jvm.asm is assembled and will be stored in an on-chip ROM. The Java application will than be loaded by the first microcode instructions in jvm.asm into an external memory. However, to verify that JOP and the serial line are working correct it is possible to run small test programs directly in microcode.

One test program (blink.asm) does not need the main memory and is a first test step before testing the possible changed memory interface. testmon.asm can be used to debug the main memory interface. Both test programs can be built with the make targets jop_blinktest and jop_testmon.

7.1.1 Blinking LED and UART output

In directory asm the blink test program is built with:

    build blink

Compile and download the FPGA configuration as described in Section 1.2.3. After download the watchdog LED should blink and the FPGA will print out 0 and 1 on the serial line. Use a terminal program or the utility e.exe to check the output from the serial line.

7.1.2 Test Monitor

In directory asm the test monitor is built with:

    build testmon

Start a terminal program (e.g. HyperTerm) to communicate with the monitor program. Compile and download the FPGA configuration as described in Section 1.2.3.

After download the program prints the content of the memory at address 0. The program understands following commands:

A single CR reads the memory at the current addres and prints out the address and memory content
addr=val; writes val into the memory location at address addr

One tip: Take care that your terminal program does not send a LF after the CR.

8 Acknowledgments

Ed Anuff wrote testmon.asm to perform a memory interface test and BlockGen.java to convert Altera .mif files to Xilinx memory blocks. BlockGen.java was the key tool to port JOP to Xilinx FPGAs in general and the Spartan-3 more specific. Flavius Gruian wrote JOPizer to generate the .jop file from the application classes. JOPizer is based on the open source BCEL and a substitute to Sun's proprietary JavaCodeCompact.

9 Notes

pcsim
JopSim

When adding a new (special) bytecode to JOP following files have to be changed:

JopInstr.java
jvm.asm
JopSim.java
JVM.java (just rename the method name)
Startup.java when needed in class initializer

9.1 A Customized Instruction

Add a description how to implement a customized or native instruction with hardware support on JOP.

9.2 A new Peripheral Device

Creation of a new peripheral devices involves some VHDL coding. However, there are several examples jop/vhdl/scio.

All peripheral components in JOP are connected with the SimpCon [3] interface. If you want to use a device that implements the Wishbone [1] bus, a SimpCon-Wishbone bridge is available (e.g. it is used to connect the AC97 interface in the dspio project).

I would suggest to start by using an example and change it to your needs. Take a look into sc_test_slave.vhd. All peripheral components (SimpCon slaves) are connected in one module usually named scio_xxx.vhd. Browse the examples and copy one that best fits your needs. In this module the address of your peripheral device is defined (e.g. 0x10 for the primary UART). This IO address is mapped to a negative memory address for JOP. That means 0xffffff80 is added to the address.

By convention this address mapping is defined in com.jopdesign.sys.Const. Here is the UART example:

    // use neagitve base address for fast constant load
    // with bipush
    public static final int IO_BASE = 0xffffff80;
    ...
    public static final int IO_STATUS = IO_BASE+0x10;
    public static final int IO_UART = IO_BASE+0x10+1;

The IO devices are accessed from Java by native⁵ functions: com.jopdesign.sys.Native.rd() and wr(). Again an example with the UART:

    // busy wait on free tx buffer
    // no wait on an open serial line, just wait
    // on the baud rate
    while ((Native.rd(Const.IO_STATUS)&1)==0) {
        ;
    }
    Native.wr(c, Const.IO_UART);

I would suggest that you create your own scio_xxx.vhdl and your own Quartus project for your configuration. So you're not mixing your changes up when you download a new version of JOP. For your new Quartus project you only have to copy the three files jop.cdf, jop.qpf, and jop.qsf in a new directory under quartus. This new directory is the project name you have to set in the Makefile: QPROJ=yourproject

You new VHDL module and the scio_xxx.vhdl are added in jop.qsf. This file is a plain ASCII file and you can edit it with your editor or with Quartus if you like.

References

[1]: Wade D. Peterson. WISHBONE system-on-chip (SoC) interconnection architecture for portable IP cores, revision: B.3. www.opencores.org, September 2002.
[2]: Martin Schoeberl. JOP: A Java Optimized Processor for Embedded Real-Time Systems. PhD thesis, Vienna University of Technology, 2005.
[3]: Martin Schoeberl. SimpCon - a simple SoC interconnect, draft. Available at: http://www.opencores.org/projects.cgi/web/simpcon/, December 2005.

Footnotes:

¹All addresses in JOP are counted in 32-bit quantities. However, the Flash is connected only to the lower 8 bits of the data bus. Therefore a store of one word in the main memory needs four loads from the Flash.

²The Java JDK still comes without the javax.comm package and getting this optional package correct installed is not that easy - Blame Sun.

³Eclipse (path) variables are workspace specific.

⁴Eclipse can't use path variables for external .jar files - annoying

⁵These are not real functions and are substituted by special bytecodes on application building with JOPiter.