 --------------------------------------------------------------------
 | README (Summary documentation for the Microsecond Clock package) |
 |                                                                  |
 | This file briefly describes the functionality  and the user      |
 | interface for the USC system.                                    |
 |                                                                  |
 | Written by:  Arun Nanda    (07/17/91)                            |
 |                                                                  |
 --------------------------------------------------------------------

This directory contains the source files for the Microsecond Clock
package (USC).

The machine classes that are supported are those that have a hardware
clock available with at least 1 microsecond resolution.  In that case,
true microsecond resolution is obtained.  For other machines (like SUN),
any real-time clock that is available (e.g. gettimeofday) is used and
scaled to a microsecond value.  Thus, the clock value returned on such 
machines will not yield true microsecond resolution.


CLOCK DATA TYPE
===============

For the purpose of maintaining portability of an application across a
range of architectures, a machine independent data type, denoted by
"usc_time_t", has been defined in the USC package.  The current clock
value and the clock rollover point (see below) are returned as data type
usc_time_t.  Hence, all variables within an user application used to
store and manipulate microsecond clock values must be declared as type
"usc_time_t".


MICROSECOND CLOCK INTERFACE
===========================

The package comprises of the following macros/functions that are
provided via the include file "usc.h" and the object module "usc.o".

	usc_init()        :  (with no parameters)
			     This function must be called exactly once
			     at the beginning before the microsecond
			     clock can be used.

	usc_clock()       :  (with no parameters)
			     This function returns the current value of
			     the microsecond clock as a data item of
			     type "usc_time_t".  The microsecond clock
			     is a free running counter that rolls over
			     after the maximum value which is machine
			     dependent.  No assumptions should be made
			     about what the rollover point for a given
			     machine is.  Instead, the generic macro
			     usc_rollover_val() should used to determine
			     this value.

	usc_rollover_val():  (with no parameters)
			     This macro is a generic interface to obtain
			     the maximum value that the microsecond
			     clock can take before rolling over to begin
			     a new cycle.  This macro must always be used 
			     to determine the clock rollover point.

An application that uses the USC functional interface must do the
following:

 1) Include the file "usc.h" at the beginning of the program.
 2) Link the application with the object module "usc.o" and the machine-
    specific library mentioned below.


INCLUDE FILE
============

	usc.h


OBJECT FILE TO LINK
===================

	usc.o


ADDITIONAL MACHINE DEPENDENT LIBRARIES
======================================

The application will also have to be linked with the following machine
dependent libraries in order to enable the microsecond clock to function
properly:

                 MULTIMAX        -lpp
                 BALANCE         -lseq
                 SYMMETRY        -lseq


LIST OF MACHINES SUPPORTED
==========================

		ALLIANT
		BALANCE 
		BFLY1 
		BFLY2 
		BFLY2_TCMP 
		DELTA 
		IBM3090
		RS6000 
		IPSC860_HOST 
		IPSC860_NODE 
		MULTIMAX 
		NEXT 
		SGI 
		SUN 
		SYMMETRY 
		TITAN 
