NOTES: Patching J2ME for RTEMS
==============================


This file contains information about the port of the J2ME,
Sun's Java virtual machine KVM for RTEMS.


Steps:

1. Get J2ME from Sun's web site:

    http://java.sun.com/products/j2me     /* The API and VM specs */
    http://java.sun.com/products/cldc     /* KVM - what we are working on */
    http://java.sun.com/products/midp     /* The Mobile Information Device Profile */
    http://java.sun.com/features/2000/09/lgtelecom.html     /* From the Press */

NOTE: This requires registration.

File: j2me_cldc-1_0-src-winsol.zip  ( 4.8M ).



2. unzip archive on some working directory.

  cd j2me_cldc
  patch -p1 <j2me_cldc-rtems-20001021.patch


CygWin 1.1.x:

 NOTE: the patch.exe utility does not handle CR/LF conversion
       correctly, and sometimes these corrections are required.

 tr -d '\r' <j2me_cldc-rtems.patch | patch -p1
 dos2unix build/rtems/config.rtems
 find -name Makefile -exec dos2unix {} \;
 find -name "*.h" -exec dos2unix {} \;

3. Locate the rtems configuration to match you RTEMS tree,
and the options that you need to use....


  cd build/rtems
  edit config.rtems

Options to Edit:

  a) RTEMS options: 

    RTEMS_BSP=pc486   ( put your BSP here )

    RTEMS_MAKEFILE_PATH=/opt/rtems/$(RTEMS_BSP)  ( install point for RTEMS )

    HOST_PLATFORM= { win32 | solaris }  - more hosts will be supported later.
I have done all my tests under CygWin 1.1.2. No Linux host is available
at the moment. It should be very similar to Solaris.


    RTEMS_NETWORK_SUPPORT=     { true | false }
    This option enable the network facilities of RTEMS.

    INCLUDE_ASYNC_SUPPORT=     { true | false }
    This option provide the "async" native capability of the KVM.
    See KVM documentation for details. On RTEMS this is implemented
    using POSIX threads. This must be true if network or io
    functionality is turned on.

    INCLUDE_RTEMS_IO_SUPPORT=  { true | false }
    Provided extensions to serial port, syslog and other services.



  b) J2ME options: ( see j2me docs for this )

    ROMIZING= { true | false }  -- this option must be true( currently ).

    INCLUDE_ALL_CLASSES= { false | true }  -- this option when set to
false, turn the KVM to have a minimal foot print. It'll disable network
support, all native async stuff, and IO support. Also, the KVM executes
much more faster because it does not need to grab mutexes, etc.


    USE_JAM= { true | false }  -- turning this option ON, requires to 
have NETWORK support under RTEMS.


4. Build

   Requirements: A java Run-time ( JDK 1.x )  -- java.exe and javac.exe
   Windows Host: VC++ 6.0 compiler

NOTE: Java virtual machine ( java ) as well as a java compiler( java )
      must be available on the path in order to build. The same
      for a "C" compiler. For Windows, VC++ 6.0 is fine. GCC under CygWin
      might be fine, but has not been tested.


   RTEMS Requirements:
      + Working network  -- if USE_JAM is turned on.
      + Posix API        

See Native asynchronous support below for details.


NOTE: I have tested this under CygWin 1.1.2

   make



6. Endianess ( Little & Big )


 j2me_cldc\kvm\VmRtems\h\machine_md.h

FIXME: This still not totally fixed. The peoblem is that
indirectly the file machine/endian.h gets included and
it defines both LITTLE_ENDIAN and BIG_ENDIAN. The 
solution for the time being was to undef both symbols
at the end of "global.h" and re-define them, based on the
CPU endianess in rtems/score/cpu.h.
A better solution needs to be found.


7. Native Asynchronous support

Native asynchronous support requires some POSIX resources,
See file: kvm/VmRtems/src/runtime2_md.c for details.
It requires a pool of threads, one mutex and one semaphore.

 Posix Thread       = 5
 Posix Mutex        = 1
 Posix Semaphore    = 1

This feature allows native code to block while waiting on
some IO, semahore, etc. See KVM documentation about Async
calls.


8. Rtems IO support

A few native classes have been added to the system.
The services provided by them:

   + Serial port access
   + Syslog facility from java
   + Standard input access ( InputStream ) linked to
     RTEMS console ( kbd ).

The services provided, allows java programs to have network
support, socket, datagram, http. Also, serial communication and
logging. These service will cover the majority of applications
that potentially can be written in java under RTEMS.


9. Rtems Examples

Under kvm/VmRtems/build/samples/src there are a few example
programs that are loaded by default to the system. They show
how to use some important service provided from java.

   + serial communication
SerialConnectionExample.java -- an application that receives a
byte on the serial port and display it on RTEMS' console. Bytes
read from the RTEMS console are sent over the serial link.


   + syslog logging
SyslogExample.java  -- application that logs a few messages
to a syslog daemon ( network configuration ).

   + tcp/ip access ( get www.yahoo.com page )
ConnectExample.java  -- this program opens the www.yahoo.com
page, and reads it.

   + hello world ( default )
HelloWorld.java -- well, this is the most *useful* program ever.

   + Dummy performance test
DummyPerfTest.java --- a very silly program that concatenate
10000 bytes to a string, and measuere the time spent to do that.

   + thread example
ThreadExample.java -- a simple program that create a few threads.


*** IMPORTANT:  ****
To change the java application that RTEMS will run at startup, 
you must edit the arguments passed to the KVM. 
This is done editing the file
Under kvm/VmRtems/src/rtems_init.c, line 235 ( or somewhere around it ).



10. TODO:

  a) Add graphics support ( microwindows )


  b) Linux  Host



7. Credits

Please forgive me, if I missed you here....

    + Efren Serra           <efren.serra@eng.sun.com>
    + Joel Sherrill         <joel.sherrill@OARcorp.com>
    + Rosimildo da Silva.   <rdasilva@connecttel.com>



Oct 22, 2000.
Rosimildo da Silva.  rdasilva@connecttel.com
Have fun.

