Skip Headers
Oracle® Java Micro Edition Embedded Client Architecture Guide
Release 1.1
E23813-01
  Go To Table Of Contents
Contents

Previous
Previous
 
Next
Next
 

A cvm Reference

This appendix describes the cvm command in detail.

This appendix includes these topics:

Synopsis

cvm [-options] class [options ...]
cvm [-options] -jar jarfile [options ...]

Description

cvm launches a Java application. It does this by starting a Java virtual machine, loading its system classes, loading a specified application class, and then invoking that class's main method, which must have the following signature:

public static void main(String args[])

The first non-option argument to cvm is the name of the top-level application class with a fully qualified class name that contains the main method. The Java virtual machine searches for the main application class, and other classes used, in three locations: the system class path, the extension class path and the user class path. See the Oracle Java Micro Edition Embedded Client Customization Guide for more information about Java class paths. Non-option arguments after the main application class name are passed to the main method.

If the -jar jarfile command-line option is used, cvm launches the application in the jar file. The manifest of the jar file must contain a line of the form MainClass:package.classname. The classname string identifies the class having the main method which serves as the application's starting point.

The Oracle Java Micro Edition Embedded Client Developer's Guide has more information about launching Java applications with cvm.

Options

cvm borrows some of its command-line options from java, the Java SE application launcher. Other options are unique to cvm and may require certain build options to enable the necessary run-time features. For command-line options that take a size parameter, the default units for size are bytes. Append the letter k or K to indicate kilobytes, or m or M to indicate megabytes.

Table A-1 describes the command-line options that are shared with the Java SE application launcher.

Table A-1 Java SE Command-Line Options

Option Description
-help

Display usage information and exit.

-showversion

Display product version information and continue.

-version

Display product version information and exit.

-fullversion

Display build version information and exit.

-Dproperty=value

Set a system property value. See Appendix B for a description of security properties for Oracle Java Micro Edition Embedded Client.

-classpath classpath
-cp classpath

Specify an alternate user class path. The default user class path is the current directory. See Class Search Path Basics for more information on classpaths.

-Xbootclasspath[/a | /p]:classpath

Specify the extension class path. /a appends classpath list to the default path. /p prepends classpath list to the default path. See Class Search Path Basics for more information on classpaths.

-Xmssize

Set the start size of the memory allocation pool (heap). This value must be greater than 1000 bytes.

The default value is 2M.

-Xmxsize

Set the maximum heap size.

The default value is 7M.

-Xmnsize

Set the minimum heap size.

The default value is 1M.

-Xsssize

Each Java thread has two stacks: one for Java code and one for native code. The maximum native stack size of the main thread is determined by the native application launcher (for example, shell or operating system.). For subsequent threads, the maximum native stack size is set by the -Xss option, although this can be ignored by the underlying operating system. See Table A-4 for a description of the command-line options for controlling the size of the Java stack.

The default value is 0 which indicates that the value is actually set by the native environment.

-enableassertions [:<package>… | :<class> ]
-ea [:<package>... | :<class>]

Enable Java assertions. These are disabled by default. With no arguments, this switch enables assertions for all user classes. With one argument ending in , the switch enables assertions in the specified package and any subpackages. If the argument is simply , the switch enables assertions in the unnamed package in the current working directory. With one argument not ending in , the switch enables assertions in the specified class.

If a single command line contains multiple instances of these switches, they are processed in order before loading any classes. So, for example, to run a program with assertions enabled only in the package com.wombat.fruitbat (and any subpackages), the following command could be used:

% cvm -ea:com.wombat.fruitbat … <MainClass>

The -enableassertions and -ea switches apply to all class loaders and to system classes (which do not have a class loader). There is one exception to this rule: in their no-argument form, the switches do not apply to system. This makes it easy to turn on assertions in all classes except for system classes. The -enablesystemassertions option enables asserts in all system classes (that is, it sets the default assertion status for system classes to true). To run a program with assertions enabled in the package com.wombat.fruitbat but disabled in class com.wombat.fruitbat.Brickbat, the following command could be used:

% cvm -ea:com.wombat.fruitbat… \

-da:com.wombat.fruitbat.Brickbat <MainClass>

-disableassertions [:<package>… | :<class> ]
-da [:<package>... | :<class> ]

Disable Java assertions. This is the default behavior.

With no arguments, -disableassertions or -da disables assertions. With one argument ending in , the option disables assertions in the specified package and any subpackages. If the argument is simply , the switch disables assertions in the unnamed package in the current working directory. With one argument not ending in , the switch disables assertions in the specified class.

The -disableassertions and -da switches apply to all class loaders and to system classes that do not have a class loader. There is one exception to this rule: in their no-argument form, the switches do not apply to system. This makes it easy to turn on assertions in all classes except for system classes. A separate switch is provided to enable assertions in all system classes. See the description of the -disablesystemassertions option.

-enablesystemassertions
-esa

Enable assertions in all system classes (sets the default assertion status for system classes to true).

-disablesystemassertions
-dsa

Disable assertions in all system classes.


Table A-2 describes the Oracle Java Micro Edition Embedded Client-specific command-line options.

Table A-2 CDC-Specific Command-Line Options

Option Description

-XbuildOptions

Display build options and exit.

-XshowBuildOptions

Display build options and continue.

-XappName=value

Specify the application name for QPE. This is used to identify the cvm process for native application management and control.

-Xverify:[all | remote | none]

Perform class verification.

  • all verify all classes.

  • remote verify all but preloaded and system classes.

  • none do not perform class verification.

The default value is remote. If -Xverify is used without any arguments, the value is all.

-XfullShutdown

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

-Xgc:suboption

Specify GC-specific options. The default GC is the generational garbage collector described in the Oracle Java Micro Edition Embedded Client Customization Guide. See Table A-3 for a description of the suboptions.

Other garbage collectors are unsupported.

-Xopt:suboption

Control the Java stack. See Table A-4 for a description of the suboptions. The different suboptions can be appended into a single argument with name/value pair separated by commas.

-XtimeStamping

Enable timestamping.

-Xtrace:flags

Turn on trace flags. Table A-5 shows the hexadecimal values to turn on each trace flag. To turn on multiple flags, bitwise-OR the values of all the flags you want to turn on, and use that result as the -Xtrace value. Requires the CVM_TRACE=true build option. (Not enabled in binary edition.)

-Xjnicheck

-Xjnicheck performs additional checks for Java Native Interface (JNI) functions. Specifically, the virtual machine validates the parameters passed to the JNI function as well as the runtime environment data before processing the JNI request. Any invalid data encountered indicates a problem in the native code, and the Java Virtual Machine will terminate with a fatal error in such cases.

This feature is useful when many new native entry points have been added. It can help avoid crashes from mismatched parameters to native routines.

Expect a performance degradation when this option is used.


Table A-3 describes the suboptions for the -Xgc command-line option.

Table A-3 -Xgc: Suboptions

Option Description

maxStackMapsMemorySize=size

Set the size of the stack map cache. The default value is 0xFFFFFFFF.

stat

Collect and display garbage collection statistics.

youngGen=size

Set the size of the young object generation.

NOTE: this option is specific to the default generational collector.

The default value is 1M.


Table A-4 describes the suboptions for the -Xopt command-line option.

Table A-4 -Xopt: Suboptions

Suboption Description

stackMinSize=size

Set the initial size of the Java stack, from <32…65536>.The default for JIT-based systems is 3K and the default for non-JIT based systems is 1K.

stackMaxSize=size

Set the maximum size of the Java stack, from <1024…1048576>. The default is 128K.

stackChunkSize=size

Set the amount the Java stack grows when it must expand <32…65536>. The default for JIT-based systems is 2K and the default for non-JIT based systems is 1K.

forceDoubleRounding

Applicable only to x86 platforms. If true (the default) double-precision floating point results are rounded.

useStrictFP

Applicable only to x86 platforms. Enable or disable Java SE strictfp semantics, which improves portability of applications that use floating point, possibly reducing precision on some platforms. The default is true.

useSSE

Applicable only to x86 platforms. Enable Streaming SIMD Extensions, which improves the speed of floating point add, sub, mul, div and a few other operations. The default is '2' which means SSE extension version 2. The value '0' disables the extensions. All other values map to '2'.


Table A-5 describes the flags used by the -Xtrace command-line option. This option is useful for run-time development purposes only and is not enabled in the binary edition.

Table A-5 -Xtrace: Flags (Not Enabled in Binary Edition)

Value Description

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.


Table A-6 describes the command-line options available with the CVM_JVMTI build option. See the Oracle Java Micro Edition Embedded Client Developer's Guide for an example of how to use these command-line options.

Table A-6 JVMTI Options

Option Description

-Xdebug

Enable VM-level debugging support.

-Xrunlib:[help]|[option=value, ]

Enable feature in shared library. For example, hprof profiling support.


Table A-7 describes the command-line options available with the CVM_JIT=true build option. The Oracle Java Micro Edition Embedded Client Customization Guide describes these options and the concepts behind them.

Table A-7 -Xjit: Options

Option Default Description

bcost=cost

4

Cost of a backward branch, between <0...32767>.

climit=cost

20000

The popularity threshold for a given method, between <0...65535>. The VM compares a per-method count based on bcost, icost and mcost against this threshold to determine when to compile a given method.

codeCacheSize=value

512k

Size of code cache where compiled methods are stored, between <0...32M>.

compile=suboption

policy

When to compile methods. See Table A-9 for descriptions of the suboptions for compile. The default policy is based on the suboption defaults listed in this table.

icost=cost

20

Cost of an interpreted-to-interpreted method call, between <0...32767>.

inline=suboption

all

Perform method inlining when compiling. See Table A-8 for descriptions of the suboptions for inline.

lowerCodeCacheThreshold=percentage

90%

Lower code cache threshold, between <0%..100%>. The dynamic compiler decompiles methods until the code cache reaches this threshold.

maxCompiledMethodSize=value

65535

Maximum size of a compiled method, between <0...64K>.

maxInliningCodeLength=value

68

Maximum size of an inlined method, between <0...1000>. This value is used as a threshold that proportionally decreases with the depth of inlining. Therefore, shorter methods are inlined at deeper depths. In addition, if the inlined method is less than value/2, the dynamic compiler allows unquickened opcodes in the inlined method.

maxInliningDepth=value

12

Maximum inlining depth of inlined methods/frames, between <0...1000>.

maxWorkingMemorySize=value

512k

Maximum working memory size for the dynamic compiler, between <0...64M>.

mcost=cost

50

Cost for transitioning between a compiled method and an interpreted method, and vice versa. Between <0..32767>.

minInliningCodeLength=value

16

The floor value for maxInliningCodeLength when its size is proportionally decreased at greater inlining depths.

policyTriggeredDecompilations=boolean

true

Policy triggered decompilations. If false, then never decompiles a method to make room for more compilations. Methods remain compiled until the class is unloaded, even if the code cache is full.

trace=suboption


Set dynamic compiler trace options. See Table A-10.

upperCodeCacheThreshold=percentage

95

Upper code cache threshold, between <0%...100%>. The dynamic compiler starts decompiling methods during a GC when the code cache passes this threshold unless policyTriggeredDecompilations=false.

XregisterPhis=boolean

true

Unsupported.

XcompilingCausesClassLoading=boolean

false

Unsupported.

Xpmi=boolean

true

Unsupported.

XregisterLocals=boolean

true

Unsupported.

aot=boolean

true

Enable/disable AOTC.

aotFile=file


AOTC file path.

recompileAOT=boolean

false

Recompile AOTC code when this option is set to true. The existing AOTC code is replaced when this option is used.

aotCodeCacheSize=size

672K

Size for the code cache used for AOTC.

aotMethodList=file


File containing a list of methods to be compiled and saved for AOTC.


Table A-8 describes the command-line options for selecting when to inline methods.

Table A-8 -Xjit:inline= Suboptions

Suboption Description

all

Enable all the options listed below to perform inlining whenever possible. The default.

none

Do not perform inlining.

virtual

Perform inlining on virtual methods.

nonvirtual

Perform inlining on nonvirtual methods.

vhints

Virtual hints. Use hints gathered while interpreting a method to choose a target method to get inlined when an invokevirtual opcode is compiled.

ihints

Interface hints. Use hints gathered while interpreting a method to choose a target method for inlining when an invokeinterface opcode is compiled.

Xvsync

Inline virtual synchronized methods. Off by default. Unsupported.

Xnvsync

Inline non-virtual synchronized methods. Off by default. Unsupported.

Xdopriv

Inline privileged methods specified by java.security.AccessController.doPrivileged(). On by default. Unsupported.


Table A-9 describes the top-level command-line options that control dynamic compiler policies.

Table A-9 -Xjit:compile= Suboptions

Suboption Description

policy

Compile according to existing compilation policy parameters such as icost and climit. The default.

all

Compile all methods aggressively. Note: this hurts performance and should be used only for testing the dynamic compiler.

none

Do not compile any methods.


Table A-10 describes the command-line options for controlling dynamic compiler tracing. These options require a build with CVM_TRACE_JIT=true. These options are experimental and unsupported.

Table A-10 -Xjit:trace= Options

Suboption Description

bctoir

Print information regarding the conversion of Java bytecodes to the JIT internal representation (IR), including a complete dump of all IR nodes.

codegen

Print the generated code in a format similar to the assembler language of the target processor. If the build option CVM_JIT_DEBUG=true, then this also prints the JavaCodeSelect rule used to generate the code interspersed with the generated code.

inlining

Print method inlining information during the bytecode to IR pass, such as which methods were inlined and which ones were not.

iropt

Print information about optimizations done in the bytecode to IR pass.

osr

Print a message when compilation of a method is triggered by on stack replacement (OSR).

stats

Print statistics gathered during compilation.

status

Print a line of status each time a method is compiled. The output includes the name of the method and whether it was compiled successfully.