Getting started
From JopWiki
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.
Contents |
[edit] Introduction
JOP,<ref>Martin Schoeberl. JOP: A Java Optimized Processor for Embedded Real-Time Systems. PhD thesis, Vienna University of Technology, 2005.</ref> 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.
[edit] 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.
[edit] Getting Started
This section 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.
[edit] Download the Source
Create a working directory and download JOP from the OpenCores 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
[edit] Tools
The tools are built with following make command:
make tools
[edit] 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 processor. 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.
[edit] Speed Configuration (optional)
By default, this builds the 80 Mhz configuration. To build the 100 MHz configuration, edit quartus/cycmin/jop.qsf and change jop_config_80 to jop_config_100, then redo the steps above.
[edit] Method Cache Configuration (optional)
The default configuration (for the Altera Cyclone) is a 4 KB method cache configured with 16 blocks (i.e., a variable block cache). For the Xilinx targets, the cache size is 2KB because Xilinx does not (or did not) support easily configurable block RAMs.
To change from a variable block cache to a dual-block cache, you will need to edit the top-level VHDL. Here is an example from vhdl/top/jopcyc.vhd:
entity jop is generic ( ram_cnt : integer := 2; -- clock cycles for external ram -- rom_cnt : integer := 3; -- clock cycles for external rom OK for 20 MHz rom_cnt : integer := 15; -- clock cycles for external rom for 100 MHz jpc_width : integer := 12; -- address bits of java bytecode pc = cache size block_bits : integer := 4 -- 2*block_bits is number of cache blocks );
Here, the square of jpc_width is the cache size, and the square of block_bits is the number of blocks. If you want to simulate a dual block cache, then set block_bits to 1. (If you want to use a single block cache, you have to modify cache.vhd to force a miss at the cache lookup.)
[edit] 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
[edit] 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!
[edit] 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.
[edit] 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.
[edit] 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<ref>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.</ref>) 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.
[edit] 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.
[edit] The Design Flow
This section describes the design flow to build JOP in greater detail.
[edit] 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<ref>The Java JDK still comes without the javax.comm package and getting this optional package correct installed is not that easy - Blame Sun.</ref>.
[edit] 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).
[edit] 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).
[edit] 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).
[edit] 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.
[edit] 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 the ACEX 1K50 project page. 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.
[edit] 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.
The following table 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 |
[edit] 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.
[edit] Eclipse
In folder eclipse there are several Eclipse projects that you can import into your Eclipse workspace. All projects use the Eclipse path variable<ref>Eclipse (path) variables are workspace specific.</ref> 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. The following table 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 |
Add the libraries from .../jop/java/lib (as external archives) to the build path of the project joptools<ref>Eclipse can't use path variables for external .jar files - annoying</ref>. 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.
[edit] 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.
[edit] 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.
The following table 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 | - | - |
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.
[edit] 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.
[edit] Porting JOP
Add a description about the files (memory).
[edit] 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.
[edit] 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 [#subsubsec:quartus 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.
[edit] 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 [#subsubsec:quartus 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.
[edit] Extending JOP
JOP is a soft-core processor and customizing it for an application is an interesting opportunity.
[edit] Native Methods
The native language of JOP is microcode. A native method is implemented in JOP microcode. The interface to this native method is through a special bytecode. The mapping between native methods and the special bytecode is performed by JOPizer.
When adding a new (special) bytecode to JOP following files have to be changed:
- jvm.asm implementation
- Native.java method signature
- JopInstr.java mapping of the signature to the name
- JopSim.java simulation of the bytecode
- JVM.java (just rename the method name)
- Startup.java only when needed in a class initializer
- WCETInstruction.java timing information
First implement the native code in JopSim.java for easy debugging. The real microcode is added in jvm.asm with a label for the special byctecode. The naming convention is jopsys_name. In Native.java provide a method signature for the native method and enter the mapping between this signature and the name in jvm.asm in JopInstr.java. Provide the execution time in WCETInstruction.java for the WCET analysis.
The native method is accessed by the method provided in Native.java. There is no calling overhead involved in the mechanism.
[edit] A new Peripheral Device
Creation of a new peripheral devices involves some VHDL coding. However, there are several examples in jop/vhdl/scio available.
All peripheral components in JOP are connected with the SimpCon<ref>Martin Schoeberl. SimpCon - a simple SoC interconnect, draft. December 2005.</ref> interface. For a device that implements the Wishbone<ref>Wade D. Peterson. WISHBONE system-on-chip (SoC) interconnection architecture for portable IP cores, revision: B.3. www.opencores.org, September 2002.</ref> bus, a SimpCon-Wishbone bridge (sc2wb.vhd) is available (e.g. it is used to connect the AC97 interface in the dspio project).
A simple start is 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<ref>These are not real functions and are substituted by special bytecodes on application building with JOPizer.</ref> 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);
Best practise is to create a new IO configuration scio_xxx.vhdl and a new Quartus project for this configuration. So the changes are not mixed up with a new version of JOP. For the new Quartus project only the three files jop.cdf, jop.qpf, and jop.qsf have to be copied in a new directory under quartus. This new directory is the project name that has to be set in the Makefile:
QPROJ=yourproject
The new VHDL module and the scio_xxx.vhdl are added in jop.qsf. This file is a plain ASCII file and can be edit with a standard editor or within Quartus.
[edit] 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.
[edit] Notes
TODO:
- pcsim
- JopSim
[edit] A Customized Instruction
Add a description how to implement a customized microcode instruction with hardware support on JOP.
[edit] Footnotes
<references/>
