source: trunk/doc/README.OS2@ 230

OpenJDK 6 Alpha for OS/2 and eCS

Version 1.6.0 Build 19 Beta (2010-12-30)

This is a beta build intended for testing purposes.



INTRODUCTION

This document contains a brief information on the OS/2 version of the
OpenJDK 6 product. Please read it carefully before starting your work.
You may also visit the project page at

  http://svn.netlabs.org/java/wiki

to get more information and the latest news and also to report bugs.

To get a brief list of OS/2-specific changes from release to release
please see the CHANGES.OS2 file included in this distribution.



REQUIREMENTS

In order to use this version of OpenJDK, you will need the following:

  - A OS/2 Warp 4 Fixpack 16+, OS/2 Warp 4.5 or eComStation operating system.

  - Odin32 library version 0.6.21541 (2010-12-30) or above:

    ftp://ftp.netlabs.org/pub/odin/odin32bin-20101230-release.wpi



INSTALLATION

  The OpenJDK product is distributed in two packages: the JRE and the SDK
  (which includes a copy of JRE). Simply take a necessary package and unzip it
  to a directory of your choice. You will need to add the \bin subdirectory
  inside this directory to PATH and BEGINLIBPATH to allow for starting Java
  executables from an arbitrary location:

    set PATH=<directory>\bin;%PATH%
    set BEGINLIBPATH=<directory>\bin;%BEGINLIBPATH%

  Also make sure there are no traces of other Java installations in the
  environment because this is known to make problems (this in particular means
  that the CLASSPATH environment variable should not be set).

  Alternatively, you may add this subdirectory to PATH and LIBPATH statements
  of your CONFIG.SYS (and reboot) to make the given Java installation the
  default one.



MEMORY REQUIREMENTS

  Sometimes you may find out that starting a Java application fails with the
  following error message:

     Error occured during initialization of VM
     Could not reserve enough space for object heap
     Could not create the Java virtual machine.

  This means that the amount of memory Java wants to reserve for its heap is
  bigger than the maximum free block of memory available to the Java process.
  Note that the size of this free block does not directly depend on the amount
  of physical RAM installed in your computer (because the physical RAM may be
  extended using the swap file, for instance). It rather depends on the virtual
  address limit set by OS/2 for the process. In older OS/2 versions that don't
  support high memory (e.g. the ones based on pre-WSeB kernels) this limit
  is known to be 512M. In later versions it is controlled by the
  VIRTUALADDRESSLIMIT parameter in CONFIG.SYS (which is specified in megabytes
  and defaults to 1024M).

  Furthermore, not all memory within the virtual address limit is available to
  the process. Some small fraction of it is used by the kernel and the rest is
  divided in two more or less equal parts: the private arena and the shared
  arena. As said, the size of these arenas does not depend on the amount of
  physical RAM and can be approximated using the following table. Note that the
  values in the table are not the initial arena sizes but rather the sizes of
  the maximum free block of memory available in the corresponding arena to a
  dummy process that does nothing but queries these system values (all numbers
  are in MB, the first column is for systems with no high memory support):

  VIRTUALADDRESSLIMIT                *512 | 1024 | 1536 | 2048 | 3072
  -------------------------------------------------------------------
  Max free block in private arena     267 |  432 |  880 | 1328 | 2224
  Max free block in shared arena      228 |  404 |  852 | 1230 | 2196

  Note that these values are gathered on a default eCS 2.0 GA system and may
  vary depending on what system DLLs get loaded into each process; they are
  given only as an example. You may get the real values on your system with
  a variety of tools gathering system information, such as THESEUS.

  On the other hand, when calculating the default amount of memory to reserve
  for the heap (which is called the maximum heap size in the documentation),
  Java uses the physical RAM size as a base, not the the size of the free block
  in the private arena (where Java actually allocates the heap). Below is a
  simplified version of the algorithm for these calculations:

  1. Use MIN (MaxRAM, <physical_RAM>) as the base RAM value. MaxRAM is a Java
     constant that defaults to 1G for the client (default) Java virtual machine
     and to 4G for the server JVM.

  2. Divide this base RAM value by MaxRAMFraction (4 by default) and assign the
     result as the default value for the maximum heap size (MaxHeapSize).

  3. Use the MaxHeapSize value increased by 20-30% (for the needs other than the
     Java heap) as the size of the memory block to allocate in the private
     arena.

  So, if your machine has, say, 2G of RAM and you attempt to start it in server
  mode (using the -server command line option), Java will want 512M (2G/4) plus
  additional 20-30%. This would obviously not fit into 432M of free private
  memory available for the process when VIRTUALADDRESSLIMIT is set to 1024 and
  it was the case with earlier releases of OpenJDK 6 for OS/2 as well as with
  the releases of InnoTek Java 1.4.x for OS/2.

  Starting with version 6 Beta 2, OpenJDK for OS/2 solves this problem by
  limiting the amount of memory Java wants for the heap to the actual size of
  the available memory block in the private arena. So, in the above case Java
  would actually get about 310M in server mode (instead of performing a failed
  attempt to allocate 512M). You may change this limit by changing the
  VIRTUALADDRESSLIMIT value in CONFIG.SYS (according to the table above), but
  please note that values higher than 1024 may cause problems with some drivers
  (for example, it is known that JFS and HPFS386 drivers cannot allocate a disk
  cache of the big size if the VIRTUALADDRESSLIMIT value is too high).

  In either case, the above describes how Java calculates the defaulut maximum
  heap size. You may always override this default using the -Xmx<size> Java
  command line option if you are not satisfied with the default value for some
  reason or if your applcation gives you the "Could not reserve enough space for
  object heap" message at startup. However, keep in mind that if you specify a
  -Xmx value which is, increased by 20-30% as described in step 3 above, bigger
  than the maximum free block in the private arena, you will get the same memory
  allocation error which indicates that you should use a smaller value.



CURRENT LIMITATIONS

  1. OpenJDK will not work correctly under the OS/2 SMP kernel (Java process
     hangs are very likely). This is a known problem of Odin32 which will be
     addressed in further releases. The workaround is to use the OS/2 UNI or
     Warp4 kernel instead.

  2. The separate JRE package of OpenJDK is not currently available. You may
     still extract JRE from the SDK package (it is located in the \jre
     subdirectory of the SDK distribution archive).

  3. AWT and Swing always use font anti-aliasing for all standard components.
     If you want to disable anti-aliasing, you may use the following Java
     command line argument:

       -Dawt.useSystemAAFontSettings=off

     However, this is not recommended since Java uses standard OS/2 Type1
     fonts by default which look really ugly with anti-aliasing turned off.

  3. Some rarely used Java system classes may be still missing in this release.

  See the project roadmap for more information on the current progress and
  future plans:

    http://svn.netlabs.org/java/roadmap

  Feel free to request new features and report bugs using the project bug
  tracker abaialble at:

    http://svn.netlabs.org/java/report



CREDITS

Dmitry A. Kuminov (development)
Silvan Scherrer (management)

netlabs.org (hosting & support)

Oracle Corporation (original OpenJDK product)

We also want to THANK all individuals and organizations who made the donations
to this project and helped to make it happen.


Oracle and Java are registered trademarks of Oracle and/or its affiliates.
OS/2 and OS/2 Warp are trademarks of the IBM Corporation and/or its subsidiary(-ies).
eComStation is a trademark of Serenity Systems International and/or its subsidiary(-ies).
Other names may be trademarks of their respective owners.