BYU Configurable Computing Home || Internal Lab Pages

Brigham Young University Configurable Computing Lab

New Lab Member Orientation

Updated: June 12, 2002

Table of Contents
Administrivia JHDL Managing the JHDL Code Jikes JNI Apache ANT QuickStart: Putting It All Together XMAC Javadoc Jab & Tbone CLI: Command Line Interpreter, navigating in JAB Netlisting & EDIF Files Appendix A: JHDL Tree Structure

Administrivia

Welcome to the largest, and by many's estimate, the most prestigious laboratory in the department. You'll find intriguing research and rub shoulders with the brightest students at the University.

Weekly lab meetings

The date and time changes semesterly.
The meetings generally last under an hour.

Door code

The code changes semesterly.

Linux Cluster Machines

You'll need an account on the Linux (pronounced "LYNN-ucks" NOT "LINE-ucks") cluster machines, rumored to be housed in the basement of the Clyde. Find the acting lab manager/sysop and bother them about this. You will also need to be added to the fpga group. This currently must be done twice, once for the linux machines, and again for the HP boxes. For the linux machines, be aware that the /tmp directories are purged weekly of old files.

There are currently 15 Linux Cluster machines, a higher number in the hostname means more RAM, but they are also more heavily used. ccl1.ee.byu.edu --> ccl15.ee.byu.edu

HP Workstations

Any lab member can use the six open HP workstations at the front of the lab. Your FPGA Linux username and login should work on those machines. The HP machines have Internet Explorer installed, type

iexplorer

for a browser that doesn't uglify your pages like Netscape.

SSH: Secure Shell

So, the HP Workstations are not very fast, at least not when compared to the Linux cluster boxes. Consequently, you'll find it beneficial to remotely login to those linux machines.

Lab Web Page password

Our lab maintains an "internal" web page for use only by members of the lab. There's a link to it from splish.ee.byu.edu, which is linked from www.ee.byu.edu. Login with:

username: jhdl
password: rocks

Bugzilla

http://bugs.jdhl.org/

We use Bugzilla to track bugs in JHDL. If you find a legitimate bug or have an idea for an enhancement, just submit it! You will need to create an account with Bugzilla.

Printing

The HP workstations are not setup to print on the FPGA Lab printer. Instead, SSH to a Linux lab machine, (like "bang",) and type:

lpr filename

To print two pages per sheet, try :

mpage -2 filename |lpr

Home Directories

CAEDM, the engineering consortium, imposes limits on your account data storage. Because of that, you'll quickly find a need to copy your files to your unlimited quota account on /ka1/users/your_username (It is possible that your drive space might be on /fpga1 /fpga2 /fpga or /cad instead of /ka1)

Those familiar with UNIX will know the command to do this copying: after having logged in to your FPGA account, enter:

cp -r /ee/your_user_login_name/* .

Note that by copying your files to the FPGA account they change groups. Don't worry, you can always use chgrp to change it back to "ee" if needed.

Note: sometimes your account on a computer is called your "drive space."

Running programs

(sorry is this is elementary, we just want to have an even playing field)

To get to a command prompt you click on the computer icon on the bottom of your screen (assuming you've logged into an HP workstation.) A shell (command interpreter) window pops up. Often the default is the csh shell which is not very friendly (feature packed). Type

tcsh

to get a much better shell which allows a command history (by pressing up and down) and other convenient features. If you write shell scripts, consider using the sh shell for portability. Use CDE Dterm for colors and proper key mapping. Perhaps you'll find a different shell you prefer, if that is the case, you'll find useful the man pages on chsh, which changes the default shell. Type

man chsh

Obviously, you'd prefer the display to be shown on your computer and not the remote one. Normally ssh does this by default, particularly if it is invoked with the -X command-line option. ... but maybe not. Want find out? Type

echo $DISPLAY

If the result is the name of your computer then it should work as desired. If not, enter the following, (replacing zap with your computer name):

setenv DISPLAY zap.ee.byu.edu:0.0

Text Editors

It is claimed that EMACS/XEMACS is the lab preference for text editing. Some use lyx (a LaTek GUI), particularly for writing papers. A select minority hold to VI/VIM. The author uses nedit, for syntax highlighting, and pico for generally editing, . Use gv to read .ps files and acroread to display .pdf files. gimp is used for graphic editing.

Scripting Languages

PERL, a scripting language, is used for a couple of tasks. Search Google for a quick tutorial and get up to speed on it. It is very useful and very used. Incidentally, PHP is MUCH easier to use. It is available on the ee machines, as is Python. Strangely, there are some die-hard ruby fans in the lab.

Untar a Unix / Linux file

With files that have the .tgz, tar.gz, or tar.z extension use this command:

tar -zxvf [filename with all extensions]

JHDL

JHDL (Just-Another Hardware Description Language), though many call it Java Hardware Description Language, which seems to fit the acrostic better. (Though there could be some licensing issues with SUN over the use of the name.)

Overview

JHDL was created in 1998 at BYU by EE faculty member Dr. Hutchings and Peter Bellows (the erstwhile student). It is an innovative approach to HDLs (Hardware Description Languages) in that it attacks the circuit design problem from the point of view of logic elements (gates, flip-flops, wires, etc.) rather than obscure behavioral descriptions as would be found in some other HDLs (reference VHDL, Forge, and others). Simply put, JHDL is a structually based HDL.

JHDL also has the advantage of being based on an already existing syntax and development platform (Java). This makes it easy to use and learn, and ensures it's platform-independence. JHDL is used in this lab to interface with FPGA devices, though it can be used in conjunction with other CCMs (configurable computing machines.) The FPGA Publications page contains the original Hutchings/Bellows JHDL paper, among others.

A primary use of JHDL is as a tool-suite/design-environment for describing configurable computing applications which merges the circuit description and the control program into a single, integrated piece of software.

Benefits and Progress of JHDL

JHDL requires only the standard Java Virtual Machine (JVM.) For more information on the JHDL tools go to the JHDL home page at JHDL homepage

JHDL Competition

HandleC
VHDL
Forge
Verilog

Quick JHDL Introduction

Converting a digital design into a format suitable for the FPGA involves a number of important steps. These steps are called the "Design Flow". The steps used in our design flow are shown in the figure below:

Each of these steps is described below:

Design Entry: In this step, we create (or "enter") our design. We will create our designs by writing Java class files using the JHDL design libraries. JHDL provides a number of design aids to help us with this process (schematic viewer, hierarchy browser).
Simulation: Once we have created your design, it is necessary to verify that our design operates correctly. We can use the JHDL simulator to test our design and verify that it operates as specified. JHDL provides a number of simulation aides to assist us: the waveform viewer and the test bench capability.
Netlisting: After we have simulated our design and corrected any design errors, we are ready to convert our JHDL design into a industrial standard netlist format named EDIF (Electronic Design Interchange Format). JHDL includes an EDIF netlister that we will use to convert our design into the appropriate EDIF format.
Technology Mapping: One of the most important steps in this design process is to convert your design into a physical representation suitable for the technology of interest. For example, if we were targeting Xilinx Spartan FPGAs, we would need to convert our EDIF netlist to a design "bitstream" suitable for that part. This technology mapping process involves the execution of several tools provided by Xilinx. These tools perform the following functions: mapping (map the Xilinx primitives to logic resources on the FPGA), placement (place the logic cells in physical locations on the FPGA), routing (route the signals between the logic cells) and bitstream generation. It is possible that our design will have problems during this technology mapping step: we may use too many resources or an illegal combination of resources. If we experience problems at this point, we might need to modify our design and start over.

Note: Another meaning of the term "Technology Mapping" is used to refer to mapping from generic JHDL "Logic" methods to a technology specific JHDL library of cells. Cells from that library are what are used to create a specific circuit descriptions in the EDIF file. This Logic-->Technology-Specific Library "Technology Mapping" occurs between steps [Design Entry] and [Simulation.]
Design Download: Once we have completed the technology mapping step and have created a valid FPGA design, we are ready to download our bitstream to our board and test our design.

It should be mentioned that while this "Quick JHDL Introduction" describes the normal design flow, another very interesting capability of JHDL tools is to perform hardware execution and verification from the very same environment used for circuit simulation. This capability is usually dependent on given "readback" features of FPGA chips, which allow the host computer to get a snapshot of the state of the FPGA. The readback image is then correlated with the original JHDL design to be used to update the values in circuit visualization tools used during hardware execution. We commonly refer to this as hardware mode execution of the design.

Managing the JHDL Code

Overview

FYI, CVS, a TLA(three letter acronym), stands for Concurrent Versions Systems.

CVS is a "Source Control" or "Revision Control" tool designed to keep track of source changes made by groups of developers working on the same files, allowing them to stay in sync with each other as each individual chooses.

Bugs can creep in when software is modified, and may not be detected until a long time after the modification is made. With CVS, it is possible to retrieve old versions to find which change caused the bug.

CVS can also help when a project is being worked on by multiple people, where overwriting each others' changes is easy to do. CVS solves this problem by having each developer work in their own directory and then instructing CVS to merge the work when each programmer is done.

CVS deserves some study. Get started reading at:

Or you can read the summary that follows:

Theory of Operation

adapted from links above

CVS solves the problem of one programmer locking other out with its unreserved check-out model: Checking out a file doesn't give a developer exclusive rights to that file. Other developers can also check it out, make their own modifications, and check it back in.

"Wait!" you're probably saying. "But don't later checkins overwrite earlier ones?" The quick answer is "no." A longer answer is that CVS detects when multiple developers make changes to the same file and automatically merges those changes.

"Whoa!" Automatically? Don't worry -- CVS is cautious and will merge automatically only as long as the changes aren't made to the same lines of code. If CVS can't safely resolve the changes, the developer will have to merge them manually.

Note: some people call the CVS directory the "Code Repository."

CVS saves its version-control information in Revision Control System (RCS) files stored in a directory hierarchy, called the Repository, which is separate from the user's working directory.

Files in the Repository are stored in a format dictated by the RCS commands CVS uses to do much of its real work. RCS files are standard byte-stream files with an internal format described by keywords stored in the files themselves.

To begin work, you execute a checkout command, handing it a module name or directory path (relative to the $CVSROOT variable) you want to work on. CVS copies the latest revision of each file in the specified module or directory out of the Repository and into a directory tree created in your current directory. You may specify a particular branch to work on by symbolic name if you don't want to work on the default (main or trunk) branch.

You may then modify files in the new directory tree, build them into output files and test the results. When you want to make your changes available to other developers, you commit them back into the Repository.

Other developers can check out the same files at the same time. To merge the committed work of others into your working files you use the update command. When your merged files build and test correctly, you may commit the merged result. This method is referred to as copy-modify-merge, which does not require locks on the source files.

At any time, usually at some milestone, you can tag the committed files, producing a symbolic name that can be handed to a future checkout command. A special form of tag produces a branch in development, as usually happens at release time.

When you no longer plan to modify or refer to your local copy of the files, they can be removed.

Before you can use CVS, you need to set the CVSROOT environment variable to the repository's path. Whoever is in charge of your project's configuration management will know what this is; perhaps they've made a global definition for CVSROOT somewhere.

Note: If CVSROOT is not set, it will complain like this:


cvs checkout: No CVSROOT specified!  Please use the `-d' option 

cvs [checkout aborted]: or set the CVSROOT environment variable

A Simple CVS Example

CVS doesn't work on ordinary directory trees; you need to work within a directory that CVS creates for you

Suppose you are working on a project named httpc, You checkout the code like this:

cvs checkout httpc


cvs checkout: Updating httpc 

U httpc/.cvsignore 

U httpc/Makefile 

U httpc/httpc.c 

U httpc/poll-server

The command cvs checkout httpc means, "Check out the source tree called httpc from the repository specified by the CVSROOT environment variable." CVS puts the tree in a subdirectory named `httpc':

cd httpc

 $ ls -l


 total 8 

 drwxr-xr-x  2 jimb          512 Oct 31 11:04 CVS 

 -rw-r--r--  1 jimb           89 Oct 31 10:42 Makefile 

 -rw-r--r--  1 jimb         4432 Oct 31 10:45 httpc.c 

 -rwxr-xr-x  1 jimb          460 Oct 30 10:21 poll-server

Most of these files are your working copies of the httpc sources. However, the subdirectory called `CVS' (at the top) is different. CVS uses it to record extra information about each of the files in that directory, to help it determine what changes you've made since you checked it out.

Making Changes:

Once CVS has created a working directory tree, you can edit, compile and test the files it contains in the usual way -- they're just files.

gcc -g -Wall httpc.c -o httpc

Merging your changes:

Since each developer uses their own working directory, the changes you make to your working directory aren't automatically visible to the other developers on your team. CVS doesn't publish your changes until you're ready. When you're done testing your changes, you must commit them to the repository to make them available to the rest of the group. We'll describe the cvs commit command below.

However, what if another developer has changed the same files you have, or the same lines? Whose changes should prevail? It's generally impossible to answer this question automatically; CVS certainly isn't competent to make that judgment.

Thus, before you can commit your changes, CVS requires your sources to be in sync with any changes committed by the other team members. The cvs update command takes care of this:

cvs update


  cvs update: Updating . 

  U Makefile 

  RCS file: /u/src/master/httpc/httpc.c,v 

  retrieving revision 1.6 

  retrieving revision 1.7 

  Merging differences between 1.6 and 1.7 into httpc.c 

  M httpc.c

Note: With the cvs update command, CVS merges changes into your working copy only; the repository and the other developers' working directories are left undisturbed. It is up to you to test the merged text, and make sure it's valid.

A line of the form `M file' like (M httpc.c) means that file has been Modified by you, and contains changes that are not yet visible to the other developers. These are changes you need to commit. In this case, `httpc.c' now contains both your modifications and those of the other user.

Since CVS has merged someone else's changes into your source, it's best to make sure things still work.

Committing your changes

Now that you have brought your sources up to date with the rest of the group and tested them, you are ready to commit your changes to the repository and make them visible to the rest of the group. The only file you've modified is `httpc.c', but it's always safe to run cvs update to get a list of the modified files from CVS:

cvs update


  cvs update: Updating . 

  M httpc.c


  As expected, the only file CVS mentions is `httpc.c'; it says it
  contains changes which you have not yet committed. You can commit
  them like so:




cvs commit httpc.c

  At this point, CVS will start up your favorite editor and prompt you for a
  log message describing the change. When you exit the editor, CVS will
  commit your change:




  Now that you have committed your changes, they are visible to the rest
  of the group. When another developer runs cvs update, CVS will
  merge your changes to `httpc.c' into their working directory.




  It's important to understand what CVS does and doesn't consider a
  conflict. CVS does not understand the semantics of your program; it
  simply treats its source code as a tree of text files. If one developer adds a
  new argument to a function and fixes its callers, while another developer
  simultaneously adds a new call to that function, and does not pass the
  new argument, that is certainly a conflict -- the two changes are
  incompatible -- but CVS will not report it. CVS's understanding of
  conflicts is strictly textual.




  In practice, fortunately, conflicts are rare. Usually, they seem to result
  from two developers attempting to address the same problem, a lack of
  communication between developers, or disagreement about the design of
  the program. Allocating tasks to developers in a reasonable way reduces
  the likelihood of conflicts.

CVS: A Bulletted Summary 


Each developer uses cvs checkout to create her own copy of
  the source tree from the CVS repository. The command can
  operate on a directory tree, a single file or a module; a module
  groups several files or directories into one entity which can be
  operated on as a unit. One defines modules by editing the
  `modules' file.

The developer modifies, compiles and tests the code in her copy of
  the source tree (called a working directory) with whatever editors
  and tools she chooses -- Emacs, make, etags, etc. She uses cvs
  add and cvs remove to add and remove files.

When the changes are complete, the developer uses cvs commit
  to merge her changes back into the repository. This makes her
  changes available to other developers.

At any point, the developer may use cvs update to merge
  changes committed by others into her working directory. If there
  are uncommitted changes to files in her working directory, CVS
  prints a message and attempts to merge the changes from the
  repository with her changes in the working directory. If the merge
  fails, CVS indicates a conflict which she resolves manually with a
  text editor.

The developer can show the differences between two revisions with
  cvs diff; show the log of changes to a particular file with cvs
  log; show the history of each line of a file with cvs annotate;
  and show who has used cvs checkout, cvs tag, and several
  other CVS commands, using cvs history.

CVS supports watches, allowing developers to request notification
  when someone begins editing a file or obtain a list of developers
  currently working on a file.

The user can record the state of the repository at a particular point
  with the cvs tag command and use that tag as an argument to
  most CVS commands, for example to retrieve the files as of the
  tagged point.

The developer can create a new development branch with cvs
  tag -b, and manipulate branches with cvs update -r and
  cvs checkout -r. Subsequent operations in that working
  directory apply to that branch. To return to the main branch, the
  developer can use cvs update -A. The cvs update -j
  command merges changes made on another branch into the
  working directory.

The existence or nonexistence of a file is itself version controlled so
  that files can exist on some but not all branches and users can
  reproduce the state of the files at any given point in time.
  The developer can mark a file as binary, which prohibits merging
  and line terminator conversions, using cvs admin.




CVS Usage in Our Lab: Checking Out JHDL
You can check out a copy of the JHDL tree from the CVS repository to poke through it to learn about the organization of JHDL. Packages of interest are
byucc.jhdl.base, byucc.jhdl.Logic, , byucc.jhdl.apps, etc. Also, take a look at the API documentation generated by javadoc.



Here's  how to check out JHDL:



First, SSH to a cluster machine, say ccl7
ssh ccl7

Then change to the temp drive, make a cvs directory, mycvs, and enter
that directory
cd /tmp
mkdir mycvs
cd mycvs

Set the CVSROOT environment variable, and run the cvs checkout command
setenv CVSROOT /fpga3/cvsroot/
cvs co byucc/jhdl

A couple minutes later

.

.

.

U byucc/jhdl/util/xmac/WireMethodsParser.java

U byucc/jhdl/util/xmac/WireParser.java

U byucc/jhdl/util/xmac/XMAC.java

U byucc/jhdl/util/xmac/XMACParser.java

U byucc/jhdl/util/xmac/config.xml

U byucc/jhdl/util/xmac/xmac

U byucc/jhdl/util/xmac/xmac.xsd

cvs checkout: Updating byucc/jhdl/util/xmac/config

$


Hurrah, We've checked out the latest JHDL source. 
CVS Errors
If you weren't added to the fpga group you'll probably get the
following message:



cvs checkout: Updating byucc/jhdl 

cvs checkout: failed to create lock directory in repository `/fpga3/cvsroot//fpga/byucc/jhdl': Permission denied 

cvs checkout: failed to obtain dir lock in repository `/fpga3/cvsroot//fpga/byucc/jhdl'

cvs [checkout aborted]: read lock failed - giving up





Talk to the EE sysops to have this corrected.


Jikes

Jikes is a compiler that translates Java source files as defined in The Java
 Language Specification into the bytecoded instruction set and binary format
 defined in The Java Virtual Machine Specification. Features include:

strict adherence to the language specification,
extremely fast compile speed,
built-in dependence analysis, allowing incremental compilation and
automatic makefile generation.



Jikes is a Java compiler from IBM that works pretty much like javac, but
much, much faster. You probably already have it in your path, because it's
in /usr/bin. The only other setup you need is to tell it where your Java
runtime jarfile is: It's called rt.jar, and it's in jre/lib in the directory
where Java is, which is probably /usr/local/java/jre/lib. You shoulde set the 
JIKESPATH like this:
setenv JIKESPATH /usr/local/java/jre/lib/rt.jar:$CLASSPATH


JNI - Java Native Interface
    The JNI allows Java code that runs within a Java Virtual Machine (VM) to operate with applications and libraries written in other
    languages, such as C, C++, and assembly. In addition, the Invocation API allows you to embed the Java Virtual Machine into your
    native applications.




    Programmers use the JNI to write native methods to handle those situations when an application cannot be written entirely in the
    Java programming language. For example, you may need to use native methods and the JNI in the following situations:


	The standard Java class library may not support the platform-dependent features needed by your application.
	You may already have a library or application written in another programming language and you wish to make it accessible to Java applications.
	 You may want to implement a small portion of time-critical code in a lower-level programming language, such as assembly, and then have your Java application call these functions.


    Programming through the JNI framework lets you use native methods to do many operations. Native methods may represent legacy
    applications or they may be written explicitly to solve a problem that is best handled outside of the Java programming environment.


Apache Ant (Another Neat Tool)

ANT is like "make", that is, it is a program for simplifying and organizing the
building (compilation) of large programming projects.  ANT was designed
specifically for JAVA programs.  Info on ANT can be found at the Ant Homepage

Theory of Operation

ANT needs an input file to tell it what to do.  This file is called, by default,
build.xml. Here is a recent BYU FGPA Lab build.xml file.




XML, by the way, is another TLA standing for "eXtensible Markup Language."  Both
XML and HTML are extended from SGML, the Standard Generalized Markup Language, so they
are similar. With markup languages expect to find nested structures of elements defined by angle bracket
tags.  Within those tags you'll get meta-properties and between those tags
you'll find the data.  Common elements in ANT include <project> <target> and
<property>




When Ant is run, it first parses the buildfile, then it goes to the default
target tag (or the target specified by the user) and begins executing the
commands specified by nested tags within that target.  All of the commands
themselves are represented by XML tags.  Targets can also indicate that they
depend on other targets (with a depends attribute).  Ant ensures that all of the
targets listed in the depends attribute are executed before the current target
is run.


Details
In this lab, Ant is located in /opt. Our version uses another parser called
Xerces rather than the default one.

Building the Checked Out JHDL
Let's check out the latest JHDL and build it:



We want the fastest lab machine: rhynn. So first we SSH there:
> ssh rhynn
byrdmr@rhynn's password: 
Last login: Mon Jan 14 16:44:16 2002 from zap.ee.byu.edu

Then, We change to the /dev/shm drive (a RAM disk) and create a check out directory which we
will name mycvs. Next, we check out a tagged version of the source and docs
[byrdmr@rhynn ~]$ cd /dev/shm
[byrdmr@rhynn shm]$ cd mycvs/
[byrdmr@rhynn mycvs]$ cvs co -r JHDL_RELEASE_0_3_15 byucc/jhdl docs/jhdl

Now we set a few environment variables
[byrdmr@rhynn mycvs]$ setenv JAVA_HOME /usr/local/java
[byrdmr@rhynn mycvs]$ setenv ANT_OPTS "-Xms32M -Xmx128M"
[byrdmr@rhynn mycvs]$ setenv PATH /usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin:/opt/ant/bin
[byrdmr@rhynn mycvs]$ setenv CLASSPATH .:/usr/local/java/jre/lib/rt.jar 

We set the classpath to force the use of jikes, a better compiler than javac.


Now we cd into the directory with our build.xml file:
cd byucc/jhdl

Now we run ANT:
[byrdmr@rhynn jhdl]$ ant -Dcvs.docs.src=docs/ -Dbuild.dir="JHDL-0.3.15" -Dversion=0.3.15 -Dfiltering=on release-all 

This is what ANT returns:

Buildfile: build.xml 



init:

     [echo] >>> JHDL 0.3.11-development [2002]

     [echo] >>> run the [usage] target to list available targets



prepare-directories:

.

.

.



BUILD SUCCESSFUL



Total time: 16 minutes 6 seconds





If the build was successful, ANT copies lots of files to a build directory and compiles the tree
into a subdirectory called "classes." At this point, JHDL is checked out and
built, and we are almost ready to start compiling JHDL programs. First, recall
that we will use Jikes to compile our .java files and Sun's JVM
(java) to execute them.



Be sure to delete the mycvs directory in /dev/shm after you have copied 
the files out of
the build directory!

A Longer ANT Description:

The default target for the build of JHDL is the compile target.  The compile
target depends on several other targets which build a special build directory
structure, copy only the desired source files, and prepares other files, such as
XMAC-generated code and resource files.  After those other targets complete
their tasks, the compile target will compile the desired Java source code to the
build/classes directory.




To see a list of the major targets that you can run, execute the command

ant usage


To see a more comprehensive list of the targets that you can run, execute the
command
ant -projecthelp


You may also set properties in a build.properties file.  This file may contain
the name/value pairs for all of the properties which you would like to have set
every time you run Ant to build JHDL.  Put your build.properties file in the
base directory.




The standard JHDL build includes a wide range of tools that no one project
probably uses.  To streamline the build, Use custom includes and excludes, to
suit your specific needs.

Directory Naming Conventions Used in ANT

The "test," "docs," and "old" directories are treated in special ways by Ant, as
directed by the buildfile.  The test directories are not compiled by default.
The docs directories are not copied over to build/src (so they could contain
.java files if necessary); instead they are copied to the same directory in
which javadoc-generated HTML documentation is made.  The old directories are
simply ignored by Ant altogether.




Put all test files and examples that demonstrate correct functionality in a
subdirectory called "test".  For more information about writing and executing
tests, see How To Test JHDL




If you have resources that compliment your javadoc comments, put them in a
subdirectory called "docs".  This is a good place for .gif files, additional
.html files, and other resources to include with the javadoc information




If a file is not needed anymore, run cvs remove on it.  If the file is of
historical interest, or can otherwise be useful as reference, move it to a
subdirectory called "old".




Most of the time you will not need to worry about modifying the build.xml file
in byucc/jhdl.  However, if your changes to JHDL require special treatment for
the build, be sure to update the build.xml file.

Speeding up ANT

Ant builds can be very I/O-bound, especially if performed on an NFS (Network
File System) drive.  The JHDL build currently involves 2000-3000 files.  For
normal builds, the copy and compilation dependencies are verified for each of
these files.  If the file queries are done over your network connection, as with
NFS, the process of merely checking timestamps on files quickly adds up to be a
very big job.




To avoid this problem, you should consider performing your Ant builds on the
local drive of the computer you are using.  All of the Linux and HP-UX machines
have a /tmp drive available for such purposes.  Many Windows machines may have a
C:\temp\ directory.  Also, some of the Linux machines in the lab may have a
/home drive available.  You can copy your CVS-checked-out files to one of these
drives (or just perform the CVS chekout directly on the drive).  With the file
I/O no longer using the network, you will find your Ant builds going much
faster, as well as your overall system performance improving.  (The network can
be a real bottleneck.)




WARNING:  The /tmp drives on Linux and HP-UX machines (as well as other variants
of Unix) are often cleaned out by a process running in the background.  That
process looks for files that are older than some relative date and deletes them.
If you choose to work on a /tmp drive and you care about the work you have done
there, you must remember to copy your directory back to a network drive when you
are done.  Alternatively, you could use a program or script that recursively
updates the timestamps of all of your files to trick the /tmp scrubber.  Also,
beware that the /tmp and /home drives are not backed up by the lab or the Spice
sysops.  (Only the network drives are backed up.)

Subdirectories

By default, the Ant build of JHDL will check the dependencies of every file to
compile in the whole JHDL tree.  With approximately 3000 files, this can take a
long time (especially over NFS).  However, most of the time, you may only care
about compiling some subdirectory of the JHDL tree, depending on where you are
developing and working.  You can use the start.path property to tell Ant to
focus on just that subdirectory and the child directories in it.  For example,
to compile just the byucc/jhdl/Logic/Modules directory, you could run the
following:
ant -Dstart.path=byucc/jhdl/Logic/Modules


A handy tool for doing this from any directory is a script that Aaron Stewart
wrote.  This script, called build (or whatever you rename it, if you choose),
allows you to go to any part of the JHDL tree in which you may be working, edit
some files, then just run the build script from that same directory.  The script
automatically determines where you are in the byucc/jhdl directory hierarchy and
runs Ant with the start.path property set to that value.




To use this script, do the following:


Download the script into a location in your command path.  (For example, if
  ~yourUserName/bin is in your command path, you could put it there.)  You may
  have to run the rehash command from the command line to refresh your
  terminal's path setting or modify the initialization file (e.g.  .cshrc) which
  sets your path if you are adding a new directory to your path.  
Go into your   local copy of the JHDL tree and into a subdirectory where you are
working.
Run build.





QuickStart: Putting It All Together

Java Version
To discover which version of Java you hava installed, type:
java -version

On CCL7, it returns:



java version "1.3.1_02"

Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1_02-b02)

Java HotSpot(TM) Client VM (build 1.3.1_02-b02, mixed mode)


To run JHDL, you need a Java 1.3.0 or better. The beta version 
1.4.0 is ok. Either SUN or IBM's JDK's work nicely. 

Setting Up JHDL Paths

To use the latest JHDL we checked out and built in this tutorial example, we type:
setenv CLASSPATH .:/tmp/mycvs/build/classes

Or, to use the latest "stable" lab release, type:
setenv CLASSPATH .:/fpga3/jhdl/release/latest/JHDL.jar:/fpga3/jhdl/release/swing/swing.jar

Next, we need to setup Jikes' JIKESPATH
setenv JIKESPATH /usr/local/java/jre/lib/rt.jar:$CLASSPATH

Finally, to use java we need to put it into the PATH. Since we are
ssh'd into a linux machine, we enter: 

setenv PATH /usr/local/java/bin:$PATH

We can now enter jikes and java and see the default output. If
no errors appear, we are ready to code! Be sure to add your working
directory to the CLASSPATH or Java will complain like this:

error Exception in thread "main" Java.lang.NoClassDefFoundError

For my working directory I entered the following:
setenv CLASSPATH .:$CLASSPATH
 
If you've SSH'd into a machine, you'll need to export the display to get swing windows to appear:
setenv DISPLAY zap:0

To make sure your Java is working, try compiling and executing the following
file: helloworld.java
class helloworld
{
        public static void main(String args[])
        {
                System.out.println("Hello World");
        }
}

Then type 
java jab
You might get:




Problem with constructor javax.swing.plaf.FontUIResource and args {Dialog,0,12} :  and types {class

java.lang.String,int,int} : java.lang.reflect.InvocationTargetException

java.lang.Exception: Stack trace

        at java.lang.Thread.dumpStack(Thread.java:997)

        at javax.swing.UIDefaults$ProxyLazyValue.createValue(UIDefaults.java:663)

        at javax.swing.UIDefaults.get(UIDefaults.java:145)

        at javax.swing.MultiUIDefaults.get(MultiUIDefaults.java:46)

        at javax.swing.UIDefaults.getFont(UIDefaults.java:223)

        at javax.swing.UIManager.getFont(UIManager.java:456)

        at javax.swing.LookAndFeel.installColorsAndFont(LookAndFeel.java:90)

        at javax.swing.plaf.basic.BasicPanelUI.installDefaults(BasicPanelUI.java:51)

        at javax.swing.plaf.basic.BasicPanelUI.installUI(BasicPanelUI.java:42)

        at javax.swing.JComponent.setUI(JComponent.java:322)

        at javax.swing.JPanel.updateUI(JPanel.java:107)

        at javax.swing.JPanel.(JPanel.java:67)

        at javax.swing.JPanel.(JPanel.java:97)

        at byucc.jhdl.apps.Viewers.BrowserMainFrame.BrowserMainFrame.(BrowserMainFrame.java:72)

        at byucc.jhdl.apps.Jab.BrowserCore.(BrowserCore.java:100)

        at byucc.jhdl.apps.Jab.BrowserCore.main(BrowserCore.java:1229)

Exception in thread "main" java.lang.NoClassDefFoundError

        at java.lang.Class.forName0(Native Method)

        at java.lang.Class.forName(Class.java:120)

        at java.awt.GraphicsEnvironment.getLocalGraphicsEnvironment(GraphicsEnvironment.java:58)

        at java.awt.Font.initializeFont(Font.java:264)

        at java.awt.Font.(Font.java:298)

        at byucc.jhdl.apps.Viewers.BrowserMainFrame.BrowserTree.(BrowserTree.java:22)

        at byucc.jhdl.apps.Viewers.BrowserMainFrame.BrowserMainFrame.(BrowserMainFrame.java:77)

        at byucc.jhdl.apps.Jab.BrowserCore.(BrowserCore.java:100)

        at byucc.jhdl.apps.Jab.BrowserCore.main(BrowserCore.java:1229)





Which simply means that because we've SSH'd into a machine and intend to run an xwindows application (via swing), we
forgot to export the display to our machine we're typing at. In my case, I'm logged into ZAP, so I type:
setenv DISPLAY zap:0

Now we're again free to enter
java jab

Jab will spawn two new windows. A JAB Console and a Circuit Browser.



In the SSH window you might see, right before the two new windows are launched:




Font specified in font.properties not found [--symbol-medium-r-normal--*-%d-*-*-p-*-adobe-fontspecific]

.

.

.


This is not a problem and is being worked on.



In the JAB console, you might see:



Unable to open file: /ka1/users/byrdmr/.jabrc
Again, this is not a problem. The .jabrc ("JAB-are-see") file, unneeded, is used for storing frequently used aliases.
To get rid of this message, type touch ~/.jabrc


XMAC
Basic JHDL components are available in a number of sizes. For example, AND gates range from 2 to 8 inputs wide. To accomplish this, the standard AND gate class contains
many overloaded constructors for the different numbers of inputs. A script
file, written in XML, automates this task, and is called XMAC. 



Javadoc

Javadoc is a tool that parses the declarations and documentation comments in a set of source files and produces a set of HTML pages
    describing the classes, inner classes, interfaces, constructors, methods, and fields.


Jab & Tbone

Definitions:

JAB (Just-Another Browser), is not deprecated in favor of JB, Jab Lite
	JAb is a graphical circuit browser. The tools
	byucc.jhdl.apps.Viewers.cvt.tool as well as
	byucc.jhdl.apps.StimulatorStimulator and
	byucc.jhdl.apps.dtb.DynamicTestBench are the preferred tools for circuit
	simulation and execution.
Test Bench
	A program that will automatically run your circuit through some test vectors.
Tbone
	A test bench program that lets you do things that you would otherwise only be
    able to do by writing a test bench.
CLI
	A command line interpreter system used in Jab and Tbone to parse and execute user commands.



CLI: Command Line Interpreter, navigating in JAB
CLI is the command interpreter which allows you to interface with JAB. 
The CLI commands are listed in the User's Manual.


Netlisting & EDIF files

Once a JHDL design (or a design from any other HDL) is finished,
it is output into in a format that can be interpreted by the tools
that will convert it into something that can be used to configure an FPGA.
This is what netlisting is all about.




Electronic Design Interchange Format (EDIF) files



Appendix A: JHDL Tree Structure:

Here's a snapshot of the JHDL directories taken June 3, '02


    
      
	BYU Configurable Computing Home
      
      ||
      
	Internal Lab Pages