ChorusOS 4.0.1 Simulator for the Solaris Operating Environment (SPARC Platform Edition) Target Family Guide

Previous: ChorusOS 4.0.1 Simulator for the Solaris Operating Environment (SPARC Platform Edition) Target Family Guide
Next: ChorusOS 4.0.1 Simulator Product Packages and Part Numbers

ChorusOS 4.0.1 Simulator 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 product release.

section 1CC: Host and Target Utilities

loader(1CC)
simudrv(1CC)

section 4CC: Files

simudrv.conf(4CC)
site_number.conf(4CC)

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

MONITOR(5FEA)

loader(1CC)

NAME

loader- boot simulator image

SYNOPSIS

loader

DESCRIPTION

The loader command is a host utility.

The loader boots the system image specified by simulator_image, assigning it the specified instance_number required for network communication. This is done by allocating 32 MB of virtual memory for the simulator_image on the host, copying the system image to the allocated memory, configuring the UDP port associated with the system image based on information in the site configuration file, site_number.conf(4CC) , and finally activating the system image entry point.

As the simulator boots, system messages are displayed on standard output.

OPERANDS

The following operands are supported:

simulator_image

Path from the build directory to the simulator system image to boot, for example: chorus.RAM.

instance_number

Number between 1 and 254 inclusive, used by the loader to locate site configuration information for the simulator_image in the site configuration file. For example, the IP address of the simulator is derived from the instance_number (see site_number.conf(4CC)).

The following entry in the sysadm.ini(4CC) file for the simulator_image makes it possible to use the same system image, each with its own IP address:

ifconfig ifeth0 TAG.TGT.IPA.TAG netmask \
netmask broadcast broadcast

The TAG.TGT.IPA.TAG string is replaced by the IP address defined for instance_number when the system image is booted with the loader. netmask and broadcast must be replaced with the corresponding parameters for the subnetwork where the simulator runs.

ENVIRONMENT VARIABLES

The following host environment variables are supported:

CHORUS_SITE_NUMBER_FILE

Contains the path to the site configuration file, site_number.conf(4CC).

If this environment variable is set, it overrides the default path, /usr/local/chorus/simu_admin/site_number.conf.

FILES

/usr/local/chorus/simu_admin/site_number.conf

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

simudrv(1CC)

NAME

simudrv- Ethernet pseudo-driver start/stop script

SYNOPSIS

/bin/sh simudrv

DESCRIPTION

The simudrv command is a host utility.

The simudrv is used to start and stop the Ethernet pseudo-driver on the host. The Ethernet pseudo-driver provides a logical Ethernet adaptor allowing the simulator to communicate through with the host, and with other systems when IP forwarding and routing is enabled on the host. simudrv requires an Ethernet pseudo-driver configuration file, simudrv.conf(4CC), indicating the IP address associated with the pseudo-driver and the hostname of the host system.

simudrv must be run on the host as a root process.

OPERANDS

The following operands are supported:

start: Start the Ethernet pseudo-driver
stop: Stop the Ethernet pseudo-driver

FILES

/usr/local/chorus/simu_admin/simudrv.conf

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

simudrv.conf(4CC)

NAME

simudrv.conf- Ethernet pseudo-driver configuration file

SYNOPSIS

/usr/local/chorus/simu_admin/simudrv.conf

DESCRIPTION

The ChorusOS simulator architecture includes an Ethernet pseudo-driver that handles communication between instances of the simulator running on the host and the host IP layer.

The Ethernet pseudo-driver configuration file specifies both the host name and the IP address associated with the Ethernet pseudo-driver.

The ChorusOS Simulator User's Guide includes a description of how to plan a simulator-related network.

EXAMPLES

An example of a typical Ethernet pseudo-driver configuration file:

#
# simudrv.conf: Ethernet pseudo-driver configuration file
#
#IP Address	host
2.1.1.1		server1

This indicates that on a system named server1 (according to uname -n), the Ethernet pseudo-driver uses IP address 2.1.1.1.

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

site_number.conf(4CC)

NAME

site_number.conf- simulator site configuration file

SYNOPSIS

/usr/local/chorus/simu_admin/site_number.conf

DESCRIPTION

The ChorusOS simulator architecture makes it possible to run multiple instances of the same system image. Each simulator instance is assigned an instance number between 1 and 254 inclusive at boot time. The instance number acts as an index to entries in the site configuration file, each of which defines:

The hostname of the host system on which the simulator instance runs
The UDP port number used by the simulator instance for remote IPC
The IP address assigned to the simulator instance, used to replace the TAG.TGT.IPA.TAG string passed as a parameter to ifconfig(1M) in an entry used to configure the network as part of the sysadm.ini(4CC) system initialization script.

The site configuration file is read by the loader(1CC) at boot time.

EXAMPLES

An example of a typical site configuration file:

#
# site_number.conf: site configuration file
#
#inst   host            UDP port        IP Address
1       server1         2052            2.1.1.2
2       server1         2053            2.1.1.3
11      server2         2052            3.7.12.11
12      server2         2100            3.7.12.12

This indicates, for example, that on a system named server2 (according to uname -n), the simulator with instance number 11 uses UDP port 2052 for Chorus remote IPC and IP address 3.7.12.11 for TCP/IP communication through the Ethernet pseudo-driver.

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

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