ChorusOS for UltraSPARC-IIi Additional Man Pages

The following additional 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 product release.

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)

section 9DRV: Driver Implementations

• intel28F016SA(9DRV)
• m48txx(9DRV)

java(1CC)

NAME | SYNOPSIS | FEATURES | DESCRIPTION | OPTIONS | ENVIRONMENT VARIABLES | ATTRIBUTES | SEE ALSO | NOTES

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

SEE ALSO

startjvm(1CC), JVM(5FEA).

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

NAME | SYNOPSIS | FEATURES | DESCRIPTION | OPTIONS | ENVIRONMENT VARIABLES | ATTRIBUTES | SEE ALSO | NOTES

startjvm(1CC)

NAME | SYNOPSIS | FEATURES | DESCRIPTION | ATTRIBUTES | SEE ALSO

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 JavaTM 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 JavaTM 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

SEE ALSO

java(1CC), JVM(5FEA)

ChorusOS 4.0.1  Last Revised July 2000

NAME | SYNOPSIS | FEATURES | DESCRIPTION | ATTRIBUTES | SEE ALSO

monitor(2K)

NAME | | FEATURES | DESCRIPTION | RESTRICTIONS | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO

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>

KnError monitorInit(KnMonitor *monitor);
KnError monitorGet(KnMonitor *monitor);
KnError monitorNotify(KnMonitor *monitor);
KnError monitorNotifyAll(KnMonitor *monitor);
KnError monitorRel(KnMonitor *monitor);
KnError monitorWait(KnMonitor *monitor, KnTimeVal *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

SEE ALSO

mutexGet(2K), mutexInit(2K), mutexRel(2K), CORE(5FEA), JVM(5FEA), MONITOR(5FEA), MUTEX(5FEA)

ChorusOS 4.0.1  Last Revised July 2000

NAME | | FEATURES | DESCRIPTION | RESTRICTIONS | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO

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

SEE ALSO

java(1CC), startjvm(1CC), MONITOR(5FEA).

ChorusOS 4.0.1  Last Revised July 2000

NAME | FEATURE SUMMARY | API | ATTRIBUTES | SEE ALSO

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

SEE ALSO

monitorGet(2K), monitorInit(2K), monitorNotify(2K), monitorNotifyAll(2K), monitorRel(2K), monitorWait(2K), mutexGet(2K), mutexInit(2K), mutexRel(2K), MUTEX(5FEA)

ChorusOS 4.0.1  Last Revised July 2000

NAME | FEATURE SUMMARY | API | ATTRIBUTES | SEE ALSO

intel28F016SA(9DRV)

NAME | SYNOPSIS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | ATTRIBUTES | SEE ALSO

NAME

intel28F016SA- intel28F016SA compatible flash driver

SYNOPSIS

drv/src/flash/intel28F016SA/intel28F016SA.h - driver structures and constants
drv/src/flash/intel28F016SA/intel28F016SA.c - driver code
drv/src/flash/intel28F016SA/intel28F016SAProp.h - driver specific properties

FEATURES

DRV

DESCRIPTION

The intel28F016SA driver implements the flash driver interface for intel28F016SA family chips, including the intel28F160 chip.

EXTENDED DESCRIPTION

The driver uses the common bus driver interface provided by a parent bus driver. Thus, the driver is generic and may be applied to any bus providing the same type of interface.

The driver does not provide the drv_probe() entry. The intel28F016SA driver does not therefore enumerate the bus, detect an intel28F016SA device or create an associated device node. When the intel28F016SA driver is used, associated device nodes should be created either statically by a boot program, or dynamically by a separate bus enumerator driver. This type of enumerator driver could be developed for this particular bus architecture.

The driver does not provide the drv_bind() routine. In other words, the driver does not support dynamic driver-to-device binding. When the intel28F016SA driver is used, the driver should be explicitly bound to the device using the PROP_DRIVER property. It is assumed that the device-to-driver binding is done either by a device node creator or by a separate binder driver. This type of driver-to-device binder could be developed for this particular bus architecture.

The driver provides the drv_unload() entry and supports driver component unloading. This allows the driver component to be unloaded if it is no longer being used (if it was dynamically loaded at run time).

The driver does not support hot-plug bus events.

The table below summarizes characteristics of the intel28F016SA flash driver.

driver name:	"sun:bus-intel28F016SA-flash"
hardware:	intel28F016SA compatible flash chip
exported interfaces:	"flash" (FLASH_CLASS)
exported interface versions:	0 (FLASH_VERSION_INITIAL)
imported parent interface:	"bus" (BUS_CLASS)
minimum parent interface version:	0 (BUS_VERSION_INITIAL)
device probing (auto-detection):	not supported
driver unloading:	supported
system (emergency) shut-down:	not supported
normal device shut-down:	supported
hot-plug (surprise) device removal:	not supported

The table below lists device node properties used by the intel28F016SA driver. Note that the column "m/o" specifies whether a given property is mandatory or optional. For optional properties, the "default value" column may show a default value which is used by the driver when a given property is not specified.

Name	Alias	Type	m/o	Default value
"mem-rgn"	BUS_PROP_MEM_RGN	<bus class specific>	m
"size"	FLASH_PROP_SIZE	FlashPropSize	m
"region-write"	FLASH_PROP_RGN_WRITE	FlashPropAccess	o
"region-exec"	FLASH_PROP_RGN_EXEC	FlashPropAccess	o
"region-cache"	FLASH_PROP_RGN_CACHE	FlashPropAccess	o

The BUS_PROP_MEM_RGN property specifies the base address of the media and is used by the driver as a parameter for the bus->mem_map() call. The property value is bus class specific.

The FLASH_PROP_SIZE property specifies the byte size of the media.

The upper layer should use optional properties FLASH_PROP_RGN_WRITE, FLASH_PROP_RGN_EXEC and FLASH_PROP_RGN_CACHE to map locked flash regions. The presence of each property gives information to the driver client about whether the locked region is writable, executable in place and cacheable.

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

SEE ALSO

bus(9DDI), isa(9DDI)

ChorusOS 4.0.1  Last Revised July 2000

NAME | SYNOPSIS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | ATTRIBUTES | SEE ALSO

m48txx(9DRV)

NAME | SYNOPSIS | FEATURES | DESCRIPTION | ATTRIBUTES | SEE ALSO

NAME

m48txx- SGS m48txx real time clock device driver

SYNOPSIS

drv/src/rtc/m48txx/m48txx.c         - driver code
drv/src/rtc/m48txx/m48txxProp.h     - driver specific properties

FEATURES

DRV

DESCRIPTION

The m48txx driver implements the RTC and NVRAM device driver interface.

The driver uses the common bus driver interface provided by a parent bus driver. Thus, the driver is generic and may be applied to any bus providing this type of interface.

The m48txx driver does not provide the drv_probe() routine. In other words, the m48txx driver does not enumerate the bus, nor does it detect an m48txx device or create an associated device node. When the m48txx driver is used, associated device nodes should be created either statically by a boot program or dynamically by a separate bus enumerator driver. Such an enumerator driver could be developed for this particular bus architecture.

The driver does not provide the drv_bind() routine. In other words, the driver does not support dynamic driver-to-device binding. When the m48txx driver is used, the driver should be explicitly bound to the device using the PROP_DRIVER property. It is assumed that the device-to-driver binding is done either by a device node creator or by a separate binder driver. Such a driver-to-device binder could be developed for this particular bus architecture.

The driver supports all bus events specified by the common bus driver interface. As a consequence, the driver may be used with a hot-pluggable bus (for example, PCMCIA).

The table below summarizes characteristics of the m48txx driver:

driver name:	"sun:bus-m48txx-(nvram,rtc)"
hardware:	SGS m48txx chip
exported interfaces:	"rtc" (RTC_CLASS) "nvram" (NVRAM_CLASS)
exported interface versions:	0 (RTC_VERSION_INITIAL) 0 (NVRAM_VERSION_INITIAL)
imported parent interface:	"bus" (BUS_CLASS)
minimum parent interface version:	0 (BUS_VERSION_INITIAL)
device probing (auto-detection):	not supported
driver unloading:	supported
system (emergency) shut-down:	supported
normal device shut-down:	supported
hot-plug (surprise) device removal:	supported

The table below lists device node properties used by the m48txx driver. Note that the column "m/o" specifies whether a given property is mandatory or optional. For optional properties, the "default value" column may show a default value which is used by the driver when a given property is not specified.

Name	Alias	Type	m/o	Default value
"io-regs"	BUS_PROP_IO_REGS	<bus class specific>	*
"mem-rgn"	BUS_PROP_MEM_RGN	<bus class specific>	*
"nvram-layout"	NVRAM_PROP_LAYOUT	<NvramPropChunk[]>	o
"year-base"	M48TXX_PROP_YEAR_BASE	<M48txxYearBase>	o	1900

* Indicates that one of these properties must be present. If both are defined, the BUS_PROP_IO_REGS will be used.

The BUS_PROP_IO_REGS property specifies the m48txx I/O registers' range. The property value is bus class specific.

The BUS_PROP_MEM_RGN property specifies the m48txx memory range. The property value is bus class specific.

The NVRAM_PROP_LAYOUT property specifies a physical layout of the NVRAM space. The property value is an array of NvramPropChunk structures. Each NvramPropChunk descriptor specifies access permissions to a given NVRAM chunk. NVRAM_PROP_LAYOUT covers all NVRAM space from the beginning to the end. A start offset of a given chunk is therefore calculated as the sum of the <size> fields of all previous chunks.

The M48TXX_PROP_YEAR_BASE property specifies the m48txx century base year.

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

SEE ALSO

bus(9DDI), isa(9DDI), nvram(9DDI), rtc(9DDI),

ChorusOS 4.0.1  Last Revised July 2000

NAME | SYNOPSIS | FEATURES | DESCRIPTION | ATTRIBUTES | SEE ALSO