ChorusOS 4.0.1 PowerPC 60x/750 Target Family Guide

ChorusOS 4.0.1 for PowerPC 60x/750 Additional Man Pages

The following man pages are not available for on-line use using the man command. They will be integrated with the package of man pages in a later major release of the product.

section 1CC: Host and Target Utilities

java(1CC)
startjvm(1CC)

section 2K: Kernel System Calls

monitor(2K), monitorInit(2K), monitorGet(2K), monitorNotify(2K), monitorNotifyAll(2K), monitorRel(2K), monitorWait(2K)

section 5FEA: ChorusOS Features and APIs

JVM(5FEA)
MONITOR(5FEA)

java(1CC)

NAME

java- Java interpreter

SYNOPSIS

rsh target arun $JVM_ROOT/bin/java

-quit

-rehash

ENVAR

VALUE

-viewclasses

-viewthreads

classname

args

FEATURES

JVM

DESCRIPTION

java is a target utility.

The java command executes Java bytecodes created by the Java compiler, javac, on the host system.

The classname argument is the name of the class to be executed and must be fully qualified by including the package in the name, for example:

example% rsh target arun JVM_ROOT/bin/java java.lang.String

Note that any arguments that appear after classname on the command line are passed to the main() method of the class.

The bytecodes for the class are put in a file called classname.class by compiling the corresponding source file with javac. All Java bytecode files end with the filename extension .class, which the compiler automatically adds when the class is compiled. The classname argument must contain a main() method defined as follows:

class Aclass {
     public static void main(String argv[]){
     . . .
     }
}

The java command returns control to the command interpreter as soon as it has succeeded in loading the class. It then executes the main() method and exits unless main() creates one or more threads. In this case, java does not exit until the last thread exits. Note that exiting a class never causes the Java Virtual Machine to exit in the context of ChorusOS.

When defining classes, specify their locations using the APP_CLASSPATH environment variable, which consists of a colon-separated list of directories that specifies the path.

OPTIONS

The following options are supported:

-quit

Kill all running Java threads and terminate the jvmd actor.

-rehash

Reload environment variables.

If the environment variables to reload are provided as a set of whitespace-separated variable-value argument pairs to the -rehash option, the Java Virtual Machine will reload only those environment variables that are specified. Otherwise the -rehash option forces the Java Virtual Machine to reload all relevant environment variables. (See ENVIRONMENT VARIABLES.)

-viewclasses

List all Java currently loaded classes in the jvmd actor.

-viewthreads

List all Java threads currently running in the jvmd actor.

ENVIRONMENT VARIABLES

The following environment variables are supported:

JVM_ROOT

Base directory where the Java Virtual Machine is installed.

Default value: /opt/jvm (as seen from the target system).

JVM_CLASSPATH

Search path for non-verified bootstrap classes and resources.

Default value: ${JVM_ROOT}/classes.

JVM_LIBPATH

Search path for bootstrap native libraries.

Default value: ${JVM_ROOT}/lib.

JVM_DEBUG

Enables or diables tracing. Values assigned to this environment variable may be: none (no tracing), all (full tracing), loading (provide traces from internal primordial classloader), verifying (provide traces from the verifier), loading, verifying or verifying, loading.

Default value: none

JVM_GC

Enables or disables garbage collection according to the mark and sweep method. Values assigned to this environment variable may be either enable or disable.

Default value: enable

APP_CLASSPATH

Search path for application classes and resources.

Default value: None (user-defined).

APP_LIBPATH

Search path for application native libraries.

Default value: None (user-defined).

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

NOTES

The jvmd actor behaves somewhat differently from Java Virtual Machines designed for other general purpose operating systems. Refer to startjvm(1CC) for more information about the jvmd actor.

ChorusOS 4.0.1 Last Revised July 2000

startjvm(1CC)

NAME

startjvm- run the Java Virtual Machine actor

SYNOPSIS

rsh target arun /jvm/bin/startjvm

FEATURES

JVM

DESCRIPTION

startjvm is a target utility.

The startjvm command starts the Java Virtual Machine for ChorusOS (the jvmd actor) initializing it according to the environment variables described in the ENVIRONMENT VARIABLES section of java(1CC). The jvmd actor is started only once, as all java applications executed on the target system run in the context of that actor.

Note that the startjvm command is not located under JVM_ROOT.

After the jvmd actor has been started using the startjvm command

Main JVM created

should appear on the ChorusOS console.

The corresponding command to terminate the jvmd actor is:

example% rsh target $JVM_ROOT/bin/java -quit

The jvmd actor

The jvmd actor runs on the target system.

The jvmd actor provides the Java Virtual Machine for ChorusOS. It may be terminated using the -quit option of the java command, but does not terminate simply because no Java applications are running.

The Java Virtual Machine component of ChorusOS is implemented as a single supervisor actor. That single actor holds all Java threads associated with all Java applications running on the target. In other words, all Java applications run in the supervisor space and all Java applications and associated threads belong to a single ChorusOS actor.

The following table indicates what is and is not supported.

SUPPORTED	NOT SUPPORTED
All Java^TM 2 Platform, Standard Edition, v1.2.2 application programming interfaces except AWT, including the following packages: java.beans, java.io, java.lang, java.math, java.net, java.rmi, java.security, java.sql, java.text, java.util, sun.beans, sun.dc, sun.io, sun.jdbc, sun.misc, sun.net, sun.rmi, sun.security, sun.tools, sunw.io, sunw.util	AWT and packages that depend on AWT
The Java^TM Native Interface with native code running in supervisor space	The Java Native Interface with native code running in user space only
Loading of dynamic libraries whose symbols are known to the Java Virtual Machine actor

The following particularities, limitations and restrictions apply:

Single Supervisor Actor

The Java Virtual Machine runs as a single actor.

All Java applications running on the target depend on this single actor, jvmd. All Java applications must be started after the jvmd actor has been launched, using the java(1CC) command.

System.exit() Stub

System.exit() takes no action, and simply returns control to the caller.

Java Virtual Machine implementations for other host platforms allow the developer to use System.exit() to terminate the Java Virtual Machine currently running. As the Java Virtual Machine actor for the ChorusOS operating system runs multiple Java applications, System.exit() is not designed to terminate the Java Virtual Machine itself.

Java Native Interface

Developers writing applications that use the Java Native Interface must use system calls that are available for use by supervisor actors.

The Java Virtual Machine is implemented as a supervisor actor. Some symbols that can be seen in a user space view of the system are not visible in supervisor space.

Messages

All messages from the Java Virtual Machine are directed to the ChorusOS console.

Developers who need to manage messages in some other way must implement their own mechanisms for doing so, for example, by using inter-process communication or log files written to a file system.

Thread Priority

By default, threads running in the Java Virtual Machine share the same priority scale than other system threads.

Before mapping Java thread priorities to the system priorities, developers may first tune the ChorusOS system to set the maximum priority for Java threads using the jvm.thread.maxPriority tunable. This value forces threads running in the Java Virtual Machine to be assigned a lower overall priority than other system threads.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

monitor(2K)

NAME

monitor, monitorInit, monitorGet, monitorNotify, monitorNotifyAll, monitorRel, monitorWait- initialize a monitor; acquire a monitor; release a monitor; wait within a monitor for notification; notify a thread waiting within a monitor; notify all threads waiting within a monitor

#include <sync/chMonitor.h>

monitor

timeout

FEATURES

MONITOR

DESCRIPTION

A monitor is a synchronization object used to protect shared procedures and data against simultaneous access. Once the monitor is acquired by a thread, the thread can suspend its ownership and wait until it is notified or a timeout occurs.

Monitors are KnMonitor structures allocated in memory.

monitorInit() initializes the monitor whose address is monitor. The monitor is initialized as unlocked.

Statically allocated monitors can be initialized using the K_KNMONITOR_INITIALIZER macro, which initializes the monitor as unlocked. This macro is used as follows:

KnMonitor myMonitor = K_KNMONITOR_INITIALIZER

monitorGet() is used by a thread to acquire a monitor. If the monitor is unlocked, it becomes locked by the thread and the caller continues its execution normally. If the monitor is already locked by the current thread, execution also continues normally. If the monitor is locked by another thread, the caller is blocked until the monitor is released.

monitorWait() is used by a thread which has acquired a monitor to relinquish its lock on it, to lie dormant until another thread notifies it using monitorNotify() or monitorNotifyAll(), or until the amount of time specified by timeout has elapsed, and finally to re-acquire its lock on the monitor.

monitorNotify() is used by a thread which has acquired the monitor specified by monitor to notify a thread waiting within monitorWait() to resume. The calling thread must then call monitorRel() so that the waiting thread may actually resume.

monitorNotifyAll() notifies all threads waiting within monitorWait() to resume.

monitorRel() is used by a thread which has acquired a monitor to release it. If threads are blocked behind the monitor, one of them is awakened.

A blocking monitorGet() is NONABORTABLE (see threadAbort(2K)). monitorWait() is ABORTABLE, that is, when a threadAbort() is addressed to a waiting thread, it behaves as if its time-out had expired.

RESTRICTIONS

A user application and a supervisor application may not share a monitor.

Conversely, two applications running in the same mode (user or supervisor) may share a monitor by mapping it in both address spaces. Such shared monitors must be dynamically allocated monitors. In supervisor mode, the same address may be used by both applications, but care must be taken to keep the monitor's region allocated because the system may crash otherwise.

RETURN VALUES

Upon successful completion, 0 is returned. Otherwise a negative error code is returned.

ERRORS

K_EFAULT: Some of the data provided are outside the address space of the current actor.
K_EINVAL: waitLimit is not a valid KnTimeVal.
K_EINVAL: The calling thread is not the current owner of the monitor on monitorRel, monitorNotify, monitorNotifyAll, monitorWait.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

JVM(5FEA)

NAME | FEATURE SUMMARY | API | ATTRIBUTES | SEE ALSO

NAME

JVM- Java Virtual Machine component

FEATURE SUMMARY

The JVM feature provides support for the Java Virtual Machine component. This feature requires the MONITOR feature to be set.

This feature allows the system to provide support for Java applications using the Java Virtual Machine actor, jvmd actor.

API

The JVM feature does not itself export an API.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

MONITOR(5FEA)

NAME | FEATURE SUMMARY | API | ATTRIBUTES | SEE ALSO

NAME

MONITOR- monitors

FEATURE SUMMARY

Monitors are a way of synchronizing concurrent threads. A monitor is a set of functions in which only one thread may execute at a time. It is possible for a thread running inside a monitor to suspend its execution so that another thread may enter the monitor. The initial thread waits for the second one to notify it (for example, that a resource is now available) and then to exit the monitor. By extension to object-oriented languages such as the Java^TM language, monitor objects are associated with the set of functions. The functions take a monitor object as argument. Only one thread at a time uses a given monitor object. In this context, the term "monitor" often refers to the monitor object itself.

API

The MONITOR feature API is summarized in the following table:

monitorGet(): Obtains the lock on the given monitor.
monitorInit(): Initializes the given monitor.
monitorNotify(): Notifies one thread waiting in monitorWait().
monitorNotifyAll(): Notifies all threads waiting in monitorWait().
monitorRel(): Releases a lock on a given monitor.
monitorWait(): Causes a thread that owns the lock on the given monitor to suspend itself until it receives notification from another thread.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving