----- The TYA 1.7v2 README written by Albrecht Kleine -----

0. CONTENTS

WHAT IS TYA?
WHAT DO YOU NEED?
SOME RELEASE NOTES
COMPILATION
INSTALLATION
USAGE
A FIRST TRY
IF ANYTHING FAILS
EXAMPLES
HOW DOES IT WORK?
MORE ABOUT JIT-COMPILER
PROBLEMS AND BUGS
FILES
THANKS

1. WHAT IS TYA?

TYA is a JIT-compiler designed as an add-on to the Blackdown and BSD ports of JDK 1.1 and JDK 1.2 for x86-Linux and -FreeBSD. TYA is ``100% unofficial'', in no way related to Sun.

Some users mailed success stories using TYA with different JDK1.1 ports, for example ports by S.Nikitin and The Open Group.

I've written TYA:

without knowledge of Sun(tm)'s JDK source code! (*.c code etc. - except some shipped include/*.h files),
in my spare time,
using only public information sources, including
- Frank Yellin's JIT interface documentation concerning the java.lang.Compiler class under the headline ``The Java Native Code API'',(archived on javasoft site),
- some of Sun(tm)'s well known JDK-include/*.h files for native code interfacing
- and two books dealing with the JVM by F.Yellin and M.K.Dalheimer.

Note: Yes, it is possible now to get Sun's JDK source code now,

      but their license is incompatible to GPL so I won't sign,
      hence not use their source code.

2. WHAT DO YOU NEED?

Important: -You need a newer running port of the JDK 1.1.x or 1.2 on a Linux or FreeBSD platform Please note that Chapman's port of JDK 1.0.2 is no longer supported. -You have to read and understand the file COPYRIGHT for legal stuff. -Read this file carefully.

3. SOME RELEASE NOTES

This release is a bugfix release for 1.8 "final".

4. COMPILATION

The original TYA distribution does not contain a precompiled form of TYA. If you want to use this software, you have to compile it first. If you compile the source code (or if you use precompiled code from somewhere else) YOU AGREE with the contents of file COPYRIGHT (...else delete the complete TYA from your computer). The result of the compilation process is one file: a shared library file called libtya.so. Read the following chapters for details on how to product and install the library.

5. INSTALLATION

A clear advantage of TYA is: There is no problem in giving TYA a try!

The configuration and installation has 3 steps:

configuration using ./configure,
compilation using make,
installation. You can simply copy the libtya.so file to the location where the JVM can find it (/usr/lib or /usr/local/lib, depending you your configuration). If you provide the library location to ./configure, then make install will do this.

So, for simple cases, there should be no need to modify Makefile at all. But if you need to change the location of the library, configure allows you to override the installation directory, by either

specifying it explicitly
./configure --libdir=/usr/mydir/lib
using jdk lib dir (placing TYA among other lib*.so files from the jdk port)
./configure --libdir=java
- THIS is the way I prefer, because it's easy to switch to a
- different JDK by editing a symlink to one current JDK.
New in TYA 1.0 is the option --with-jdk: here you would specify
where main Java directory lies. This is intended for those who have multiple Java environments installed; you can specify which one you want to use for TYA.

Some notes:
* For FreeBSD: Maybe you have to create your own special Makefile. Unfortunately I can't tell much about FreeBSD, but previous release was confirmed by mail to run together with both ELF and A.OUT systems. (I am not a FreeBSD expert, but anyway it was no problem to compile and run TYA on a 3.1 ELF system using gcc 2.7.2.1 plus jdk-1.1.8)

The egcs compiler throws some warnings you can simply ignore, gcc does not. For example ``unknown_control_flow'' is one of them.
If you own newer x86 CPU it's a good idea to replace gcc's standard option -m486 by -mpentiumpro or similar appropriate to your CPU by editing Makefile.
TYA should run on any CPU >= 386 but thas was never tested for 386. The machine code TYA generates itself is optimized for running on plain 586.
If you install libtya.so among the other java libs, it is default located in a dir called ``green_threads''. May be you should symlink libtya.so into native_threads or care by other ways (LD_LIBRARY_PATH) that java can pick up the library.

6. USAGE

You may either specify the compiler to the JVM on the command line, or you may set an environment variable that will let the JVM find the compiler.

For the command line option, run Java using option "-Djava.compiler=", like this example:

java    -Djava.compiler=tya       Iview          Valetta.jpg
#         ^ set property ^        ^your pgm      ^ pgm's options

But a better and easier way is setting the JAVA_COMPILER environment variable, as in

export JAVA_COMPILER=tya

This way you don't have to change any scripts.

To remove TYA from your system, delete the sources, the libfile, etc., and do not use the "-Djava.compiler=tya" property.

TYA sends a certain amount of debug text to stderr. You may redirect it, or you may control its destination with an environment variable, as in

export TYA_LOGFILE=tya_logfile_what_ever

With some exceptions TYA should be quiet unless you compile TYA with enabled settings DEBUG or one of the VERBOSE modes.

(For example: sometimes I am using "export TYA_LOGFILE=/dev/tty12" and switch to screen #12 using alt-F12 for looking to TYA's messages.)

Please note, the messages about exceptions caught by TYA and about extended code space etc. are quite harmless.

7. A FIRST TRY

Execute ``Sy'', the output should look similar to the following:

TYA 1.1v4 (for J117) loaded. Copyright (c) 1997,98 The TYA Team Contact The TYA Team via Albrecht Kleine <kleine@ak.sax.de> tya
Linux

The copyright message tells you that TYA is correctly loaded. Line 3 shows us the property is set right. Line 4 detects the right OS ;-)

New in TYA 1.2 is a test for catching interrupts by TYA: go into the demo directory and execute the CatchEx script. The Java program should tell you about caught interrupts twice. If this program crashes, you have a problem. But I will explain how to solve this at the end of next chapter.

8. IF ANYTHING FAILS

If you have trouble using the automatic configuration, you should take a look into config.h and Makefile. Look for proper setting of the state of Jxxx flags.

If anything else goes wrong, check Makefile, config.h and tyaconfig.h for proper settings. There are some #defines in the source code file tyaconfig.h:

#define VERBOSE
-enable for some time & size informations, but won't help in case of core dumps
#define VERBOSE_ASM86
-some information about produced assembler code #define DEBUG
-lots of information about invocation etc. #define GATHERSTATS
-compare notes in Changelog file

The predefined settings are designed for speed, not for maximized crash security. So if you have trouble, disable all experimental stuff in tyaconfig.h, and TYA should run, but perhaps slow. Go into a cycle of commenting out features and recompiling in an order as follows:

// #define EXCEPTIONS_BY_SIGNALS (see note below) // #define USE_REG_OPT
// #define USEASM
// #define TRY_FAST_INVOKE
// #define INLINING (disable this last)

Each time you disable a #define the TYA will run slower, but you have more chances to get TYA running in an JDK port that is unknown to me.

If you want to maintain code for different data structure I recommend switching off #define USEASM.

BTW: the shipped CatchEx example is good to check a problem with EXCEPTIONS_BY_SIGNALS.
For the compilation for JDK1.2 it is disabled by default: it's to bad documented at all, but why not play with...?

9. EXAMPLES

The shipped Sieve benchmark on my computer (P200/32M/Linux 2.0.x):

JVM 1.0.2 19
JVM 1.0.2 +TYA 0.1 126
JVM 1.0.2 +TYA 0.2 153
JVM 1.0.2 +TYA 0.3 222
JVM 1.0.2 +TYA 0.3 229

JVM 1.1.1 (sbb)      77
JVM 1.1.5 (sbb)      80
JVM 1.1.5 (sn)       17

JVM 1.1.1 +TYA 0.2 150
JVM 1.1.3 +TYA 0.3 215
JVM 1.1.3 +TYA 0.4 220
JVM 1.1.5 +TYA 0.5 245
JVM 1.1.5 +TYA 0.6 249
JVM 1.1.6 +TYA 1.1 259
JVM 1.1.7 +TYA 1.2 261
JVM 1.1.7 +TYA 1.3 269
JVM 1.1.7 +TYA 1.4 300
JVM 1.1.7 +TYA 1.6 334

(kaffe 0.83 218)

The second project is a more practical one: it is an example from image processing using AWT (but not running using kaffe**)

The color separation of the jpeg-image from Valetta into red/green/blue layers takes:

-circa 4700 milliseconds for JVM 1.0.2

-circa 2400 milliseconds for JVM 1.0.2 together with TYA 0.1, -circa 1600 milliseconds for JVM 1.0.2 together with TYA 0.2, -circa 1100 milliseconds for JVM 1.1.x together with TYA 0.3, -circa 950 milliseconds for JVM 1.1.x together with TYA 0.4, -circa 880 milliseconds for JVM 1.1.x together with TYA 0.5, -circa 800 milliseconds for JVM 1.1.x together with TYA 0.7, -circa 770 milliseconds for JVM 1.1.x together with TYA 1.1, -circa 750 milliseconds for JVM 1.1.x together with TYA 1.2 -circa 600 milliseconds for JVM 1.1.7 together with TYA 1.4

The Valetta snapshot has circa 150000 pixels, so there are 750000 method invocations to do!

Please consider: this milliseconds are not really comparable, because I've changed also the jdk (1.1.1 up to 1.1.7), Linux-kernel and libc, window manager and color depth. Also some jdk needs different memory, so sometimes I've added switches like ``-ms2M'' to avoid gc.

10. HOW DOES IT WORK?

My JIT consists of four parts:

The first part is a translator to convert the Java byte code into x86-code, always a complete method at once. For this purpose I've written a set of producers of preassembled machine code blocks (one for each opcode), using a big outer switch glued together during JIT-compilation.
The second part is the interface to the JVM: here we decide if a method get this translation or not. (BTW, nearly all methods can be translated except native methods - and this is how it will handle the graphics-peers: these are compiled native methods, we won't hook their invokers.) You see: this JIT is NOT intended to run without the JVM.
The third part is the method invocation process: we call the methods, handle exceptions to the caller level and prepare the interface to the GC.
Last but not least we hook into JVM's hooks: this is the way to add the TYA JIT compiler into the virtual machine.
Another one, which can be unused, is a bytecode pre-processing to do some optimizations. It detects basic blocks, and check for constant propagation and dead code elimination. This part can be disabled by checking the C-pre-processor variable USE_BYTECODE_OPTIMIZATION in the file tyaconfig.h

11. MORE ABOUT JIT-COMPILER

The most important source of information is Frank Yellin's ``JAVA native code API'' documentation concerning the java.lang.Compiler class.

^^^^^^^^^^^^^
(Look for file jit_interface.html, somewhere archived on javasoft site.)
Unfortunately this stuff now is completely outdated, but should help to get a feeling what's going on.

12. PROBLEMS and BUGS

If you want to help developing TYA, grep for some FIXMEs.

Problems are:
- there are error situations handled by TYA via

termination by calling abort()
- no support for JVM-profiling or -debugging interfaces - some quick_opcodes are NOT yet implemented, but

it seems they are not used.

Remember: use this software AT YOUR OWN RISK.

Please do NOT send useless bug reports like this to me: ! Full thread dump:
! "Finalizer thread" (TID:0x404c23b0, sys_thread_t:0x412cbf2c) prio=1 ! "Async Garbage Collector" (TID:0x404c2368, sys_thread_t:0x412a9f2c) prio=1 ! "Idle thread" (TID:0x404c2320, sys_thread_t:0x41287f2c) prio=0 ! "clock handler" (TID:0x404c21f8, sys_thread_t:0x41265f2c) prio=11 ! "main" (TID:0x404c20a0, sys_thread_t:0x817bd00) prio=5 current thread ! n1.main(Compiled Code)
! Monitor Cache Dump:
! Registered Monitor Dump:

!    Finalize me queue lock:     unowned
!    Thread queue lock:     unowned
!............etc........................

In most cases they are pretty useless for me. But in some situations mailing of a SMALL Java file together with a description could help.

You are invited to help make TYA better and bugfree. We will log your patches etc. in file CHANGELOG. Thank you.

13. FILES

D O C U M E N T A T I O N

COPYING.GPL                     <- license
COPYRIGHT                       <- important copyright info
README                          <- you read
FAQ                             <- more doc

S O U R C E C O D E

ChangeLog <- release & contributions history

Makefile.in
acconfig.h
config.h.in
configure
configure.in <- the configuration tool files

tya.c
tyaruntime.c
tyaexc.c
tyautil.c
tyarechelp.c
tyarecode.c <- the C source files tyaoptimize.c

tya.S
tyaasm_freeBSD.S

tyaasm.S                        <- asm stuff 
                                   (``FreeBSD'' here means ``a.out-systems'')

tya.h                           <- source, include file

tyaconfig.h                     <- source, main include file for configuration

T E S T I N G S T U F F (in demo directory)

Makefile <- for rebuilding

Sy                              <- example 1 (to verify the compiler-property)
SystemProperties.class          <- bytecode
SystemProperties.java           <- source code

Sieve                           <- example 2    the prime sieve
Sieve.class                        (one of kaffe's benchmarks)
Sieve.java                      <- source code

Iview                           <- example 3
Iview.java                      <- source
Iview.class                     <- bytecode
IviewCanvas.class               <- bytecode
IviewColorFilter.class          <- bytecode
Valetta.jpg                     <- ``The Maltese balconies''

CatchEx                         <- example 4
ExceptionsTest.java             <- source
ExceptionsTest.class            <- bytecode

ArithOpt                        <- example 5 : a pure arithmetic calculation
ArithOpt.class          <- bytecode
ArithOpt.java           <- source

Test*                           <- both...
javacspeed                      <- ... for internal tests (jdk1.1 only)
JNI/*                           <- for JNI interface testing
test/*                          <- by Artur (detects resolving mode)

14. THANKS

I want to say THANK YOU
for promotion / testing / bug reports / hints / contribution / grammar_help to:

Marcel Ammerlaan <marcel@ch.twi.tudelft.nl> Artur Biesiadowski <abies@pg.gda.pl>
Steven Bird-Downum <bird@runner.utsa.edu> Joe Carter <joseph.carter@man.brite.co.uk> John Collins <jcollins@cs.umn.edu>
Jon Cox <jcox@experiments.com>
Patrick D'Cruze <pdcruze@fusion.iinet.net.au> Olaf Flebbe <O.Flebbe@science-computing.de> Didier Gautheron <dgautheron@magic.fr>
Jason Gilbert <jason@scott.net>
David Lucas <ddlucas@lse.com>
Louis-David Mitterrand <mito@aparima.com> Wolfgang Muees <wolfgang@wmsickte.escape.de> Eugen N.Vasilchenko <eugen@inter-soft.com.ru> phillips <phillips@online-computers.dyn.ml.org> Georg Prossinagg <Georg.Prossinagg@humanomed.co.at> Neal Sanche <neal@nsdev.org>
Matthias Sattler <m_sattle@informatik.uni-kl.de> Rene Schmit <rene@bss.lu>
Ean Schuessler <ean@novare.net>
Kazuyuki Shudo <shudoh@muraoka.info.waseda.ac.jp> Artur Skawina <skawina@usa.net>
Suresh Srinivas <ssuresh@cthulhu.engr.sgi.com>

.......and all others......

More special thanks for writing Java demo programs that revealed special TYA bugs you will find mentioned in ChangeLog file.

That's all folks.
Bye,
Albrecht
mailto:kleine@ak.sax.de

The algorithm for optimizing the byte code has been developped by Gab', mailto:gabriel.heitzler@prism.uvsq.fr

* Java, Sun and all Java-based names are registered trademarks of Sun Microsystems, Inc.

** =Tim Wilkinson's kaffe version 0.83 . (Didn't try later versions.)