----- The TYA 1.1v3 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 ``100% unofficial'' JIT-compiler original designed as 
an add-on to Randy Chapman's port of JDK 1.0.2 for Linux (x86).
I have added some changes in TYA code for working together 
with the newer 1.1.x ports by Steve Byrne and Sergey Nikitin.

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,
 - from the beginning for running together with AWT-package graphics,
 - using only public information sources delivered by
   * 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.

Since TYA 0.4 I have received more cool contributions
from other people, so now it's a team effort.

BUT DO NOT FORGET: USE  tya  AT YOUR OWN RISK!


2. WHAT DO YOU NEED?
====================

Important:
 -You need a 586-pc running Linux port of the JDK 1.1.6.
 -You have to read and understand file COPYRIGHT for legal stuff.
 -Read this file carefully.


3. SOME RELEASE NOTES
=====================

Current TYA releases should run most applets and programs 
out there including swing, beans, browsers, servers etc.

For details (WHAT's NEW) look into Changelog file. 



4. COMPILATION
==============

The original TYA distribution doesn't contain TYA in a binary form.
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) YOU AGREE with the contents of file COPYRIGHT (...else 
delete the complete TYA from your computer).


BTW: Never do exchange versions compiled for a special JDK
with different versions, this won't work (except 1.1.5 
and 1.1.6 sbb releases).



5. INSTALLATION
===============

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

Please note, the configuration process has changed completely (since 
TYA 0.6). Many thanks to Artur!
After configuration ./configure , compilation ("make") simply copy the 
libtya.so file to the location where the JVM can find it ("make install")

So, for simple cases, there should be no need to modify Makefile at all.
But if you are interested to change the handling of the libdir,
configure allows to override install dir, by either
1) specifying it explicite
./configure --libdir=/usr/mydir/lib
2) using jdk lib dir (TYA among other lib*.so files from the jdk port)
./configure --libdir=java

3) New in TYA 1.0 is the option --with-jdk: here you would specify
where main java directory lies.



6. USAGE
========

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 envionment via  

      export JAVA_COMPILER=tya

This way you don't have to change any scripts.
BTW: if you want to remove TYA from your system, delete the sources, the 
libfile, etc., and do not use the "-Djava.compiler=tya" property.



Because some users complained about debug messages, here is a note
about TYA debug message device [new in TYA 1.0]:

If you do not like to see any messages by TYA on stderr device please 
set the TYA_LOGFILE environment via

      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. [tnx to Eric]

(BTW: the messages about exceptions caught by TYA are quite harmless.)
      



7. A FIRST TRY
==============

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

	TYA 0.4 (for J1.0.2) loaded. Copyright (c) 1997,98 Albrecht Kleine
	This should be a (c) line ^^^   (else TYA is not loaded.)
	tya
	Linux
	
If there is an error that JVM cannot find the TYA shared lib,  at least
the JVM-1.0.2 would NOT give any error hint !!!  So the copyright 
message is an important indicator for proper loading the TYA lib. 
Never remove this line.
Line 3 shows us the property is set right.
Line 4 detects the right OS ;-)



8. IF ANYTHING FAILS
=====================


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

If anything other 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.

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 disabeling and recompiling 
in an order as follows:

// #define FAST_NATIVE102STYLE	        (at first)
// #define EXCEPTIONS_BY_SIGNALS
// #define USEASM
// #define TRY_FAST_INVOKE
// #define USE_REG_OPT
// #define INLINING			(at 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 unknown for me. 

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



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            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

(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


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 the also the jdk (1.1.1 up to 1.1.6),
Linux-kernel and libc.
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 in four parts:

- at first we _translate_ 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 are calling
  the methods, handling exceptions to the caller level and preparing
  the interface to the GC.

- last but not least we are hooking 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.)


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()
-  there could be some BIG security holes
-  too high recursion level could cause 
   stack overflow errors [unlike pure JVM]
-  the JNI is not complete checked

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 TYA making better and bugfree.
We will log your patches etc. in file CHANGELOG. Thank you.


13. FILES
=========

Never mix this files together with other projects.

D O C U M E N T A T I O N
-------------------------
COPYING.GPL			<- license
COPYRIGHT			<- important copyright info
README       			<- you read
FAQ				<- new in 1.0

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 new configuration tool files

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

tyaasm.S			<- asm stuff

tya.h				<- source, include file
tyaconfig.h			<- source, include file for cfg.



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''

Test*				<- both...
javacspeed			<- ... for internal tests



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>
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>
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>
Artur Skawina <skawina@usa.net>
.......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 and all Java-based names are registered trademarks of Sun Microsystems, Inc.

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

*** =David Engberg's excellent guavac compiler (v1.0 and earlier)