JamaicaVM 3.4 — User Documentation

The Virtual Machine for Realtime and Embedded Systems

aicas GmbH

Table of Contents
Why Read This Book?
This Book's Audience
Getting This Book
Getting JamaicaVM
Release Notes — JamaicaVM 3.4
Request for Comments
Notations and Conventions
1. Introduction
Hard Realtime Execution Guarantees
Real-Time Specification for Java support
Minimal footprint
ROMable code
Native code support
Dynamic Linking
Fast Execution
Tools for Realtime and Embedded System Development
2. Installation
On Linux Systems
Installation with root privileges
Installation for a single user without root privileges
Specifying the Location of the Toolchains
On Sun/Solaris Systems
On Windows
Jamaica Directory structure
3. Jamaica Tool Chain Overview
Creating class files out of Java source files using jamaicac
Using the jamaicavm command
Building an application using the Jamaica Builder
4. Jamaicac - Java Bytecode Compiler
Jamaicac Usage
Classpath options:
Compliance options:
Warning options:
Debug options:
Ignored options
5. Jamaicavm Commands
JamaicaVM Options
JamaicaVM Extended Options
Environment variables used by JamaicaVM
Additional extended options of jamaicavmp
Additional options of jamaicavmdi
6. Jamaica Builder
How the Builder tool works
Builder Usage
General Options
Classes, files and paths
Smart linking
Memory and threads
GC configuration
RTSJ settings
Native code
Builder Extended Usage
General Options
Classes, files and paths
Native code
Cross Compiling Environments
Optimized for Embedded Systems
7. Memory Management Configuration
Configuration for soft-realtime applications
Initial heap size
Maximum heap size
Finalizer thread priority
Reserved memory
Using a GC thread
Stop-the-world Garbage Collection
Configuration for hard-realtime applications
Usage of the Memory Analyzer tool
Building using the Memory Analyzer
Measuring an application's memory requirements
Fine tuning the final executable application
Constant Garbage Collection Work
Comparing dynamic mode and constant GC work mode
Determination of the worst case execution time of an allocation
Numblocks usage
8. Profiling using the Builder
Creating a profile
Creating a profiling application
Using the profiling VM
Dumping a profile via network
Creating a micro profile
Using a profile with the Builder
Building with a profile
Building with multiple profiles
Interpreting the profiling output
Format of the profile file
9. Jamaica and the Java Native Interface (JNI)
Using JNI
Jamaicah usage
Classes, files, and paths
10. Performance Optimizations
Code Size vs. Runtime Performance
Using Smart Linking
Using Compilation
Optimizing RAM Memory Demand
Measuring RAM requirements
Memory for an Application's Data Structures
Memory for API libraries
Memory Required for Threads
Memory Required for Line Numbers
11. The Real-Time Specification for Java
Realtime programming with the RTSJ
Realtime Garbage Collection
Relaxations in JamaicaVM
Use of Memory Areas
Thread priorities
Runtime checks for NoHeapRealtimeThread
Static Initializers
Class PhysicalMemoryManager
Strict RTSJ Semantics
Use of Memory Areas
Thread priorities
Runtime checks for NoHeapRealtimeThread
Static Initializers
Class PhysicalMemoryManager
Limitations of RTSJ implementation
12. Guidelines for Realtime Programming in Java
Computational Transparency
Efficient Java Statements
Non-Obvious Slightly Inefficient Constructs
Statements Causing Implicit Memory Allocation
Operations Causing Class Initialization
Operations Causing Class Loading
Supported Standards
Real-Time Specification for Java
Java Native Interface
Java 2 Micro Edition
Memory Management
Memory Management of RTSJ
Configuring a Realtime Garbage Collector
Programming with the RTSJ and Realtime Garbage Collection
Memory Management Guidelines
Scheduling and Synchronization
Schedulable Entities
Programming Guideline Summary
Memory Allocation
13. JamaicaVM plug-in for Eclipse
Eclipse integration
Virtual machines and class library
Jamaica Builder and Ant support
Getting Eclipse and the JamaicaVM plug-in
Installing Eclipse
Installing the JamaicaVM plug-in
Additional resources
14. Debugging with Eclipse
Enabling the Debugger Agent
Using the Debugger
Setting Breakpoints
Inspecting Variables
Remote debugging
Limitations of the Debugging Interface
15. ThreadMonitor
Run-time system configuration
ThreadMonitor Tool
16. FAQ - Frequently Asked Questions
A. Targets
SUN Solaris
Loading an application
Starting an application
Linking the application to the VxWorks kernel image
Special notes
RTEMS Configuration
Running an application
Linker Directives File
Additional Target configuration
Windows CE
RedHawk Linux
Running an application
B. Exit codes
Jamaica VM
Jamaica Builder, jamaicah, numblocks
C. Properties
Properties Set by the User
Predefined properties
D. Class Libraries
JamaicaVM Class Libraries
E. Datatypes
JamaicaVM Datatype Sizes
F. Limitations
JamaicaVM Limitations
JamaicaVM Builder Limitations
G. Default Values
JamaicaVM default values
Builder default values
H. Environment variables
JamaicaVM environment variables
JamaicaVM Builder environment variables
Jamaicac environment variables
Jamaicah environment variables
Numblocks environment variables
Debugging environment variables
I. Third Party Licenses
GNU Classpath License
Eclipse Public License (EPL)
Index of Options
List of Tables
4-1. Warnings created by jamaicac
5-1. Environment variables used by JamaicaVM
7-1. Typical number of blocks for objects
14-1. Arguments for built in agent via option agentlib
14-2. Jamaica Debugging Interface Limitations
15-1. Controls
B-1. Standard exit codes
B-2. Exit codes of errors
B-3. Exit codes of internal errors
B-4. Other exit codes
B-5. Standard exit codes
B-6. Exit codes of errors
B-7. Exit codes of internal errors
C-1. Properties set by the user
C-2. Predefined properties
D-1. Libraries that can be specified via -setLibaries
E-1. JamaicaVM datatype sizes
F-1. JamaicaVM limitations
F-2. Static Compiler Limitations
G-1. JamaicaVM default values
G-2. Jamaica Builder default values
H-1. Environment variables used by JamaicaVM
H-2. JamaicaVM Builder environment variables
H-3. Jamaicac Builder environment variables
H-4. Jamaicah environment variables
H-5. Numblocks environment variables
H-6. Debugging environment variables
List of Figures
1-1. The Jamaica Toolset
3-1. The Jamaica Toolchain
6-1. The Builder tool
6-2. A simple Java program
9-1. An example class for JNI.
9-2. The C header files for JNI methods are generated by jamaicah
9-3. The C implementation of the native function JNITest.write_HW_Register
12-1. Use of final local variable
12-2. Java Threads in a classic JVM are interrupted by the garbage collector thread
12-3. RealtimeThreads can interrupt garbage collector activity
12-4. JamaicaVM provides realtime behavior for all threads.
12-5. Priority Inversion
12-6. Priority Inheritance
12-7. Priority Ceiling Emulation Protocol
12-8. Deadlocks are possible with Priority Inheritance
13-1. A project with JamaicaVM as "Project JRE"
13-2. Jamaica Ant Editor editing an Ant script
14-1. General view of the Eclipse Debug View user interface
14-2. Setting the project's main Java class in the debug configuration
14-3. Breakpoint markers visible in the left margin of the editor
14-4. Viewing variables in the Display window
14-5. Debugger commands in the Run... menu
14-6. Setting connection properties for a remote debugging session
15-1. Control view of the ThreadMonitor