Contents | Prev | Next
J2ME CDC 1.0
Porting Guide

Starting CVM

Contents

Invoking CVM
Time/Date Operations
Runtime Options

Invoking CVM

The method of starting CVM depends on the target platform environment which it is run on. The following are examples which outline several commonly used methods of starting CVM on the various target platforms. The examples demonstrate the execution of a HelloWorld Java class located in the testclasses.zip which is built in the CVM/CDC build process.

The examples assumes that you have already built the CVM executable. If not, see Building CVM and CDC/Foundation for details on building the CVM executable.

  1. Invoking CVM on Linux from a shell command line
  2. For Linux, CVM is an executable located in the build/linux/bin relative to the top directory where you unzipped the CDC distribution. To start CVM, type in the following at the command prompt:
    > cd topdir/build/linux/bin
    > cvm -Djava.class.path=../testclasses HelloWorld
    

  3. Invoking CVM on VxWorks from C code
  4. For VxWorks, the entry point to CVM is either the runJava function or the runJavaArgs function. The runJava function takes a single string as an argument as follows:
    int runJava(const char *options);
    
    options is a string which consist of CVM runtime options delimited by blank spaces followed by the name of the main Java class to be executed. For example,
    void yourFunction(void) {
        extern int runJava(const char *options);
        runJava("-Djava.class.path=../testclasses HelloWorld");
    }
    

    The runJavaArgs function takes up to ten individual string arguments as follows:

    int runJavaArgs(const char *a0, const char *a1, const char *a2, const char *a3,
                    const char *a4, const char *a5, const char *a6, const char *a7,
                    const char *a8, const char *a9);
    
    Each of the string is to hold a single CVM runtime option and one main Java class to be executed. Unused arguments can be passed NULL strings. For example,
    #undef NULL
    #define NULL ((void *)0)
    void yourFunction(void) {
        extern int runJavaArgs(const char *a0, const char *a1,
                    const char *a2, const char *a3, const char *a4, const char *a5,
                    const char *a6, const char *a7, const char *a8, const char *a9);
    
        runJavaArgs("-Djava.class.path=../testclasses", "HelloWorld",
                    NULL, NULL, NULL,
                    NULL, NULL, NULL, NULL, NULL);
    }
    

    Note: The two functions behave identically, with the following exception: the string arguments of the runJavaArgs function can contain blank spaces which are not construed as delimiters between CVM runtime options, but all blank spaces in the string argument of the runJava function will be construed as delimiters between CVM runtime options. Hence, when starting CVM using the runJavaArgs function, a CVM runtime option may contain blank spaces. This is not true for the runJava function.

    Note: On VxWorks, starting a second virtual machine instance while another is already running is not currently supported. Instead, to run multiple Java applications on the same VM instance, use a wrapper main Java program to invoke each of the Java applications.

  5. Invoking CVM on VxWorks from a shell command line
  6. From a VxWorks shell command prompt, CVM can be started using the runJava function as follows:
    -> runJava "-Djava.class.path=../testclasses HelloWorld"
    
    From a VxWorks shell command prompt, CVM can also be started using the runJavaArgs function with up to ten individual string arguments as follows:
    -> runJava "-Djava.class.path=../testclasses","HelloWorld"
    
    See notes above on the difference between runJava and runJavaArgs and the limitation on the number of CVM instances running on VxWorks at the same time.

Time/Date Operations

For the CVM to perform time/date oriented operations on VxWorks, the internal time-of-day clock of VxWorks must be set to the correct time in GMT. The CVM can then be told which time zone it is operating in via the user.timezone property. Refer to the target's Board Support Package documentation and the timeLib module of VxWorks for ways to set the OS time-of-day clock.

Runtime Options

The following are CVM runtime options that can be specified at the point where CVM is started:
-Dproperty=value
Set a system property value.

-fullversion
Display build version information, then exit.

-showversion
Display product version information and continue.

-version
Display product version information, then exit.

-Xbootclasspath=bootclasspath
Specify a colon-separated (Linux) or semicolon-separated (VxWorks) list of directories, JAR archives, and ZIP archives to search for boot class files. These are used in place of the boot class files included in the CDC. If CVM is started from the bin directory that contains the CVM executable, the default bootclasspath is the ../lib directory.

-Xbootclasspath/a=path
Specify a colon-separated (Linux) or semicolon-separated (VxWorks) path of directories, JAR archives, and ZIP archives to append to the default boot class path.

-Xbootclasspath/p=path
Specify a colon-separated (Linux) or semicolon-separated (VxWorks) path of directories, JAR archives, and ZIP archives to prepend in front of the default boot class path.

-Xdebug
Enables debugging support in the VM. Refer to jdb description for more details and an example.
Note: This runtime option is only supported if CVM was built with the CVM_JVMDI=true option.

-Xgc:gc_specific_options
Specifies garbage collector (GC) specific options. For the default generational garbage collector that is bundled with CVM, the GC specific option is youngGen=nnn to specify the size of the young object generation, in bytes. Append the letter k or K to indicate kilobytes, or m or M to indicate megabytes. The default value is 1M.
Note: If a licensee implements a custom garbage collector, the accepted GC specific options will depend on that custom implementation.

-Xmssize
Specify the size, in bytes, of the memory allocation pool. (This value may be rounded up by the GC implementation). Append the letter k or K to indicate kilobytes, or m or M to indicate megabytes. The default value is 4M. Examples:
-Xms6291456
-Xms6144k
-Xms6m

-Xrunlib
Load a dynamic library.

-XsafeExit
Make sure all resources are freed and the VM destroyed upon exit. This is the default for non-process-model operating systems, such as VxWorks, but is not usually done for process-model operating systems, such as Linux.

-Xsssize
Set thread stack size in bytes. As for the -Xms option, the value can use the letters k, K, m, or M to indicate kilobytes or megabytes.

-Xtrace:value
Turn on trace flags. The following list shows the hexadecimal values to turn on each trace flag. To turn on multiple flags, bitwise-OR the values of all the flags you wish to turn on, and provide that result as the -Xtrace value.
Note: This runtime option is only supported if CVM was built with the CVM_DEBUG=true option.

Value What Is Traced
0x00000001 Opcode execution
0x00000002 Method execution
0x00000004 Internal state of the interpreter loop on method calls and returns
0x00000008 Fast common-case path of Java synchronization
0x00000010 Slow rare-case path of Java synchronization
0x00000020 Mutex locking and unlocking operations
0x00000040 Consistent state transitions. Garbage Collection (GC)-safety state only.
0x00000080 GC start and stop notifications
0x00000100 GC root scans
0x00000200 GC heap object scans
0x00000400 GC object allocation
0x00000800 GC algorithm internals
0x00001000 Transitions between GC-safe and GC-unsafe states
0x00002000 Class static initializers
0x00004000 Java exception handling
0x00008000 Heap initialization and destruction, global state initialization, and the safe exit feature
0x00010000 Read and write barriers for GC
0x00020000 Generation of GC maps for Java stacks
0x00040000 Class loading
0x00080000 Class lookup in VM-internal tables
0x00100000 Type system operations
0x00200000 Java code verifier operations
0x00400000 Weak reference handling
0x00800000 Class unloading
0x01000000 Class linking

-Xverify:[all | remote | none]
Verify classes according to the suboption. -Xverify:all verifies all classes. -Xverify:remote verifies remote classes only. -Xverify:none turns off class verification.

Contents | Prev | Next
Copyright © 2000 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: jcp-cdc-comments@eng.sun.com
Sun