Date: Mon, 4 Jan 1993 17:59:11 +0100
From: Martin Gergeleit <Martin.Gergeleit@gmd.de>
Message-Id: <199301041659.AA01071@gmdzi.gmd.de>
To: mach3@cs.cmu.edu
Subject: JEWEL_light V1.0 released

The German National Research Center for Computer Science (GMD) announces
Version 1.0 of the JEWEL_light system for Mach 3.0. JEWEL_light has been 
developed by GMD as one of the software components of the JEWEL distributed 
measurement system, in collaboration with the Open Software Foundation Research
Institute (OSF RI) in Grenoble, in order to provide a tool for the performance 
evaluation of Mach 3.0 based applications and servers (and specially the 
OSF/1 Single Server).

JEWEL_light is available from GMD via anonymous ftp:

gmdzi.gmd.de (129.26.8.90):

/ftp/gmd/RelaX/JEWEL_light_V1.0.tar.Z

This directory also holds several papers that describe the full JEWEL
system.

If you have any questions, bug-reports, or (even better) bug fixes, please
send a mail to Martin Gergeleit <mfg@gmd.de>.

--------------------------------------------------------------------------

		            JEWEL_light V1.0
		 Distributed Measurement System for Mach 3.0

			   Copyright (c) 1992 GMD 
	    German National Research Center for Computer Science

INTRODUCTION

     JEWEL_light is designed for online monitoring and computing 
     performance characteristics of Mach 3.0 based applications or
     servers.  JEWEL_light is able to deal with multi-threaded
     and multi-tasked programs.  It is also applicable for func-
     tional and performance debugging of concurrent programs as
     it produces an ordered global trace of all detected events.

     JEWEL_light requires an i386 machine running Mach 3.0 + BSD or OSF/1
     for running the observed Mach applications, and a Un*x host 
     as observer station. (either the same host (Mach 3.0 + BSD server) 
     or a remote SunOS 4.0  or DEC Ultrix have been tested).
     JEWEL_light also takes adventage of i386 multiprocessors (tested
     on Zenith Z1000). In this case one processor will be dedicated to
     JEWEL_light, while the others are executing the observed applications.


FUNCTIONAL OVERVIEW

     The program to be observe, the so called system under
     test (SUT) has to be instrumented with sensors which recog-
     nize relevant events inside the system under test. If a
     thread executes such a sensor the corresponding event will be
     recorded and merged into a global event stream.  Sensors are
     implemented as C macros (called NOTICE-macros). Events
     detected by the execution of NOTICE-macros are collected and
     transfered out of the context of the SUT by the JEWEL
     ms_server component.  This ms_server is a MACH 3.0 server
     that implements a low-interference event data collection and
     transmission service.  It transmits all extracted events
     from the system under test and sends them via sockets to
     the, possibly remote, JEWEL ms_supporter component.  The
     ms_supporter serves as the data collection and evaluation com-
     ponent and should be located on another host to reduced the
     interference of the measurement system with the SUT. The
     ms_supporter receives all extracted events and optionally
     orders them by using the events timestamps.  Finally, the
     ms_supporter prints all events with their timestamps to
     stdout.

     The JEWEL_light measurement system supports three time bases
     which may be used for timestamping events. The system clock,
     a logical clock and a special high resolution clock.  The
     system clock works on any Mach 3.0 system but the granular-
     ity of this clock may be too coarse for the observation of
     events with a high frequency.  The logical clock also works
     on any Mach 3.0 system. It consists of a simple global
     counter which is incremented after each read access.  This
     provides an easy method for achieving a global event order
     but it does not contain any real timing information.  The
     high resolution clock only works on multiprocessor machines
     which use a special Mach 3.0 kernel with a high resolution
     clock extension.

     Configuration of your experiments:

     Before starting instrumentation an experiment description
     must be edited. This file contains the (symbolic)
     names of the events that may occure in the SUT and the 
     corresponding event numbers used as parameter to the NOTICE-
     macros. Furthermore the state of each event is denoted here.
     This defines whether the event is enabled or disabled.

     The experiment description files are given as command line
     parameters to the ms_supporter which forwards the state of
     the events to the ms_server. According to this state only
     enabled events are collected. This allows for instrumenting
     code with a number of sensors belonging to different experi-
     ments.  The selection of the currently enabled sensors is
     done at run-time by choosing the corresponding experiment
     description files. The execution-costs of disabled sensors
     are very low (only one if-statement), so that unused sensors 
     should not introduce a significant performance penalty.

     Instrumentation of the SUT:

     A observed program consists of a number of cthreads or
     UX-threads in a number of tasks.  At first, the observed
     program has to include the file measurement.h. Before pro-
     ducing events each thread of the SUT has to register itself 
     at the ms_server by invoking the measurement_init call. The 
     ms_server maintains an event queue for each registered thread 
     in shared memory (provided by the Mach netmemoryserver).

     The instrumentation of the SUT is done by inserting some 
     NOTICE-macros at appropriate places inside the C-sources of 
     your observed program.  Finally the SUT has to be recompiled 
     and linked with the JEWEL library libmeasurement.a .

     To start a measurement experiment the ms_server has to be
     startedfirst. Hereby the clock base to be used in the
     experiment has to be determined.  Afterwards, the ms_supporter
     has to be started (this has to be done on another host if a
     low interference should be achieved).  Finally, the SUT has to
     be started. Now the extracted data will appear at stdout of 
     ms_supporter.

     The output of the ms_supporter may be used as input for sub-
     sequent evaluation steps, e.g with awk.


COPYRIGHT

     Permission to use, copy, modify and distribute this software and its
     documentation is hereby granted, provided that both the copyright
     notice and this permission notice appear in all copies of the
     software, derivative works or modified versions, and any portions
     thereof, and that both notices appear in supporting documentation.

     GMD ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" CONDITION.  
     GMD DISCLAIMS ANY LIABILITY OF ANY KIND FOR ANY DAMAGES WHATSOEVER 
     RESULTING FROM THE USE OF THIS SOFTWARE.


DISTRIBUTION

     The JEWEL_light public domain distribution consists of the following
     components:

     - the generic measurement server, which is able to work with a
       high-resolution clock of any frequency (on a multiprocessor) or with 
       the ordinary system clock (on a monoprocessor) and even with a 
       logical clock, that provides a global event ordering on a single 
       host. The measurement server has to be started on a Mach 3.0 
       machine with the netmemoryserver version running. We have tested 
       it on Intel 80386 machines only.

     - a generic version of the measurement supporter, that runs on any
       UX-host. We have tested it on MACH 3.0/Server, Ultrix, and SunOS. 
       The measurement supporter is configurable for new experiments by the 
       use of ascii-configuration files at start-up time. There is no need for 
       a recompilation. The ascii-output will be an ordered event-trace of all
       sensor executions, that may be useful on its own (e.g. during 
       debugging) or that may serve as input for further evaluation steps 
       using other tools.

     - the measurement library plus the corresponding include-files, that have
       to be linked with the instrumented application (e.g. the OSF/1 Server)

     - two simple examples of instrumented applications plus the corresponding
       experiment configuration files. One multi-threaded (cthreads)
       and one multi-task example are provided. They may be used to test 
       a new JEWEL_light installation or as a basis for your own development.

     - man-pages which describe the use of the system.

     The full JEWEL measurement system is a general purpose toolkit
     for low-interference on-line performance measurements in distributed
     systems. JEWEL has been developed at GMD (German National Research 
     Center for Computer Science). JEWEL provides performance experi-
     ment configuration and setup, measurement data collection 
     and processing, and graphical online presentation of the collected 
     data. JEWEL works in a distributed heterogenious environment and 
     is able to produce a global view of the SUT. JEWEL uses X11 and 
     OSF/Motif as graphical user interface. 

     This distribution, called JEWEL_light, contains only the Mach 3.0
     related event detection and collection mechanisms, which are 
     nevertheless VERY useful as standalone tools.

     The full JEWEL system has been adapted to various HW/operating 
     systems platforms. There are ports available for a VME-bus
     environment, for Mach 3.0, and for standard Un*x (as long as
     it provides SysV shared memory segments and sockets). A complete
     set of documentation is also available. This full version of
     the JEWEL system is NOT INCLUDED in this public domain
     distribution, but it is available under license from GMD. 
     Under a license agreement non-commercial use for scientific and
     educational purposes will be freely granted. Commercial usage will
     be licensed on fair and equal conditions.

     For further information please contact: 

	Reinhold Kroeger or Martin Gergeleit
	GMD, Postfach 1316
	D-5205 St. Augustin 1
	Germany
	email: kroeger@gmd.de  or  mfg@gmd.de