----- The TYA 1.6 README written by Albrecht Kleine -----

0. CONTENTS
===========

 1. WHAT IS TYA?
 2. WHAT DO YOU NEED?
 3. SOME RELEASE NOTES
 4. COMPILATION
 5. INSTALLATION
 6. USAGE
 7. A FIRST TRY
 8. IF ANYTHING FAILS
 9. EXAMPLES
10. HOW DOES IT WORK?
11. MORE ABOUT JIT-COMPILER
12. PROBLEMS AND BUGS
13. FILES
14. 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 the final in a row of about 20 releases
 
* This release adds a more compatible class access mechanism
  on JDK1.1, so demo/test/InitTest.java is passed for the first
  time. At beginning this looks unimportant, but it is essential
  enough! There is software out there which will run the first
  time together with TYA. For JDK 1.2 this was already done
  in TYA 1.5.
* Also there are some basic roots for later (?) developements
  like using a 2nd compiler pass etc.


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:
 1. configuration using ./configure,
 2. compilation using make, 
 3. 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
 1. specifying it explicitly
        ./configure --libdir=/usr/mydir/lib
 2. 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.
    *************************************************************
	
 3. 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 no 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.


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

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

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

----
* 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.)