JamaicaVM 3.4 — User Documentation

The Virtual Machine for Realtime and Embedded Systems

aicas GmbH


Table of Contents
Preface
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
Portability
Fast Execution
Tools for Realtime and Embedded System Development
Contact
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
JamaicaVM Options
JamaicaVM Extended Options
Environment variables used by JamaicaVM
jamaicavm_slim
jamaicavmp
Additional extended options of jamaicavmp
jamaicavmdi
Additional options of jamaicavmdi
6. Jamaica Builder
How the Builder tool works
Builder Usage
General Options
Classes, files and paths
Smart linking
Compilation
Memory and threads
GC configuration
RTSJ settings
Profiling
Native code
Builder Extended Usage
General Options
Classes, files and paths
Compilation
Profiling
Native code
Miscellaneous
Example
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
Recommendations
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
Examples
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
Example
9. Jamaica and the Java Native Interface (JNI)
Using JNI
Jamaicah usage
General
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
General
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
Finalizers
Configuring a Realtime Garbage Collector
Programming with the RTSJ and Realtime Garbage Collection
Memory Management Guidelines
Scheduling and Synchronization
Schedulable Entities
Synchronization
Libraries
Programming Guideline Summary
Efficiency
Memory Allocation
EventHandlers
Monitors
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
Requirements
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
Limitations
VxWorks
Installation
Loading an application
Starting an application
Linking the application to the VxWorks kernel image
Limitations
Special notes
RTEMS
Installation
RTEMS Configuration
Running an application
INTEGRITY
Installation
Linker Directives File
Additional Target configuration
Windows
Limitations
Windows CE
Limitations
OS-9
Limitations
QNX
Installation
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)
Bibliography
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