The following notice applies to all software in this alpha release:

The authors and Purdue University make this code freely available as a
public domain release.  Neither the authors nor Purdue University can
be held responsible for any problems deriving from use of this code;
however, the authors would like to be informed of any problems, and
intend to actively support the package.

The primary author is:

	Prof. Hank Dietz, email hankd@ecn.purdue.edu

Debugging help has come from:

	Tim Mattox, email tmattox@ecn.purdue.edu

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


HOW TO INSTALL AND USE THIS ALPHA RELEASE LIBRARY
                            ===== =======

You say you like the idea of PAPERS, but you are not quite convinced
that it is worth the effort of building a little hardware?  This
version of the alpha release TTL_PAPERS library introduces a simple,
highly accurate, software simulator that can be used with nearly any
UNIX system.  This simulator, TTL_VAPERS, is about two orders of
magnitude lower performance than using the library with TTL_PAPERS
hardware, but it is a good way to test the library and applications,
and it provides a friendly development environment including a
graphical, interactive, X-windows debugging interface.

Most of the library and support functions are shared by both
TTL_PAPERS and TTL_VAPERS and work identically -- the only difference
is which version of the library is linked in and the setting of a few
environment variables.  However, until the release of PEN (the Papers
ENvironment -- a simple parallel OS that runs on top of UNIX) later
this summer, the procedure for running a program using TTL_PAPERS will
be slightly more complicated than using the simulator.

This README is thus divided into two sections.  The first describes
how to make and use the library for TTL_VAPERS:  the Virtual Adapter
for Parallel Execution and Rapid Synchronization.  The second gives
comparable information for TTL_PAPERS.


----------------  To Make And Use TTL_VAPERS ----------------

The TTL_VAPERS software simulation currently consists of two separate
software mechanisms:  a simulation library that is compiled into each
user program and an independent X-windows program that provides the
graphical, interactive, debugging interface.  The library and the X
interface are truly independent of each other, although the X interface
isn't very interesting without a TTL_VAPERS library application running
for it to monitor.

The library code is intended to be compiled using GCC, and should
compile and operate correctly on most 32-bit UNIX-based systems
literally without any changes.  It was primarily developed and tested
on 486 systems running Linux.  Assuming that GCC is on your path, you
should be able to build the library and sample applications by simply
typing "make", and you can run any application by simply typing its
name (as you would for any other UNIX program).

The library code was deliberately designed to use only the most
portable UNIX process control and communication facilities.  When
p_init() is called, it forks four child processes that will pretend to
be PE0, PE1, PE2, and PE3.  The parent process precisely simulates the
TTL_PAPERS unit by reading simulated port I/O requests through a
single standard UNIX pipe, processing them in order of arrival, and
returning the data from any input request via a pipe to the requesting
PE process.  Communication between the library and X-based debugger is
accomplished by the parent process updating a status file whenever the
state of the simulated TTL_PAPERS unit changes.  Standard UNIX signals
are used only when the X-based debugger needs to stop/start part of
the simulation.  This stuff should work with any UNIX all the way back
to V6 PWB.  If your UNIX can't do this, it really isn't UNIX....

Which, of course, brings us to Solaris...  it works, but can yield
very poor performance.  A four-headed Sun server under Solaris was 5
times slower than a single 486DX2/66 under Linux.  Oh well.

Not surprisingly, porting the X-based debugger is a little more
difficult.  However, it was also constructed in as portable a way as
possible, using TCL/TK.  Thus, you must have both X and TCL/TK
installed in order to use this interface.  Both are freely available
and are commonly packaged with distributions of Linux.

The entire X interface for the simulator is implemented in a single
TCL/TK script called "xvapers".  However, this script uses a few other
files and invokes a few UNIX programs, so some configuration is
necessary.  All of the parameters that you are likely to need to
adjust are described at the top of the file "xvapers", so you should
simply edit "xvapers" and modify it as the comments within the file
suggest.  All the font and window parameters were selected so that they
would fit comfortably on a PC's standard 640x480 color display...  a
tad small for some small dot-pitch monitors, but they look great on my
486 laptop's 9.5" active color LCD.

To install and use VAPERS, unpack the archive and follow the following
few steps.

1.	As configured, you should be able to build the full system and
	demos by simply typing:

	$ make

2.	There are a few environment variables which must be set before
	you run any VAPERS applications.  We suggest that you set these
	parameters by the following sequence:

	$ psetenv >T
	$ . T

3.	You can now run any of these applications:

	(a)	The program "pi" computes an approximation to the value
		of Pi by computing the area under a curve using the
		specified number of segments.  Try running:

		$ pi 1000000

	(b)	The program "libdemo" runs through the entire
		TTL_PAPERS library, timing each routine.  For example,
		running "libdemo" by:

		$ libdemo 10

		will give the times measured by executing each of the
		library routines 10 times.  Notice that, for the
		simulation, the times given are not very accurate nor
		repeatable because UNIX timer resolution is not fine
		enough to precisely measure simulation overhead (from
		pipes and UNIX process context switch).

	These applications also can be recompiled to run on the actual
	hardware (see below), but remember that the speed difference
	is substantial, so it makes sense to use smaller problem sizes
	for simulated runs.

	There are also a few other parallel programs you can try, but
	"cold" isn't needed and "music" and "musical" don't make much
	sense for the simulator.  The "check" program isn't very useful
	unless you are running the X debugger for TTL_VAPERS....

Do you want to be able to use the X-based debugger?  If so, make sure
you have X and TCL/TK installed, then:

4.	Edit the file "xvapers", making whatever changes are
	appropriate, as suggested by the comments at the top of the
	file.  For a typical Linux system, no changes should be needed.

5.	In an xterm, issue the following commands:

	$ psetenv >T
	$ . T
	$ xvapers &

	This should yield a small window displaying the simulated front
	panel of TTL_VAPERS (complete with simulated wood grain!).  All
	of the simulated LEDs should be black, because no program is
	being simulated.  Now try running:

	$ check 0

	You should see the LEDs change color just as though you were
	looking at the front panel of the real TTL_PAPERS hardware with
	the check program running on PE0.  Likewise, running "pi" or
	"libdemo" as you did in step 3 above will now yield the same
	display you'd get with the real TTL_PAPERS hardware.

	Clicking the left button on the TTL_VAPERS display window will
	open a self-updating status and control window; clicking the
	right button will open a documentation browser window.  There
	isn't much documentation on things, but remember -- this is
	just a alpha release.  ;-)  Besides, playing doesn't hurt.

	Notice that the xvapers display is completely independent of
	the simulation being executed; xvapers simply looks at a
	status file that the simulator regularly updates.  Thus, you
	can kill and restart xvapers without affecting the program
	being simulated.  Likewise, you don't have to restart xvapers
	with each new program being simulated.


----------------  To Make And Use TTL_PAPERS ----------------

We strongly recommend that the TTL_PAPERS unit be used with PCs
running Linux, since Linux appears to be unique in providing an
appropriate, and well documented, UNIX interface that supports
user-level direct port access.  Later releases of this library will
probably support a variety of other machines (e.g., DEC Alpha Linux
and PowerPC AIX), but we're keeping things simple in this alpha
release.  If you are interested in helping to port the TTL_PAPERS
library to other machine/OS combinations, please contact us.

Thus, for the following instructions, it is assumed that you have
already installed a reasonably recent version of Linux on four PCs.
After unpacking the shell archive, you have a directory containing
quite a few files that need to be recompiled.  Before you can use the
TTL_PAPERS library, you need to decide exactly how your cluster will
be configured, build the library, etc.  The following instructions
should help.

1.	Direct user-level access to the parallel printer port that is
	connected to TTL_PAPERS is needed, but standard Linux will
	only grant such access to priv processes.  Thus, you have two
	choices:

	(a)	Make every executable that uses TTL_PAPERS run priv.
		This can be done by making each executable be owned by
		root and have the s bit set.  For example, the program
		"libdemo" could be given permission by root issuing the
		commands:

		$ chown root libdemo
		$ chmod +s libdemo

		We consider this to be a serious security problem,
		although it is an acceptable method for testing.

	(b)	Modify the Linux OS call "ioperm()" so that it does not
		check that the caller is priv if the ports requested
		are those connected to the TTL_PAPERS unit.  This
		change alters just a few lines of code in the Linux
		kernel, and it preserves security, but it requires a
		rebuild of the kernel.

	As written, the Makefile included with this distribution
	assumes that approach (b) will be used.  However, you must
	remove the "-DP_VAPERS" option as instructed by the comments
	in the Makefile, otherwise, you'll be building the simulated
	system instead of the version that uses the real hardware.

	Notice that the demos that play music using the PC speaker
	have a similar problem getting access to the speaker port.

2.	To build the library and demos, there is only one parameter
	you are likely to need to change:  the port number for the
	TTL_PAPERS unit.  As distributed, "P_PORTBASE" is set to 0x378
	in the file "intern.h".  This is correct for the parallel port
	of most machines except some built by IBM, in which case you
	must change the value to 0x3bc.

	After checking that "P_PORTBASE" is set correctly, simply:

	$ make

	to build the library and demos.

	If you want to use approach (a) described above, you will need
	to follow the make with:

	$ make priv

	Notice that, at this time, we have not yet specified a standard
	directory for all these routines.  Everything is assumed to be
	in the current directory, whatever that is.

3.	The shell script called "run" is used to start copies of the
	specified program on all processors.  It is a very simple
	script using rsh -- which means that your cluster must be
	connected by a traditional network (e.g., Ethernet) in
	addition to the TTL_PAPERS unit.  You must change the
	definitions of PE3, PE2, PE1, and PE0 in "run" to the network
	names of the corresponding processors.  This script assumes
	that it is being executed on PE0.

	This script also assumes that rsh requires no password, so you
	will need to make accounts by the same name on all machines
	and give each a .rhosts entry allowing PE0 access.

	Finally, this script assumes that the same executable files are
	visible by the same path on all PEs.  This can be done either
	by replicating the files on each machine or simply by NFS
	cross-mounting from one node to the others.  We recommend NFS
	cross-mounting.

	Notice that use of this run script is not strictly necessary,
	and this script will soon be replaced by a real parallel OS
	built on top of Linux -- PEN, the Papers ENvironment.  It is
	also useful to recall that, as a general rule, you cannot be
	root when you execute an rsh; thus, even though the executable
	files might be owned by root and s-bitted, you should always be
	some ordinary user when you use "run".

4.	Once PEN is released, running parallel jobs will be nearly
	indentical to running ordinary unix jobs, but the "run" script
	needs a little help:

	(a)	It is up to the user to make sure that only one
		parallel job is being run at a time -- the "run"
		script uses a crude script called "killrsh" to
		clean-up after straggling processes, but having a
		stray process touch the TTL_PAPERS unit can be the
		source of very ponderous errors.  If something strange
		happens, check for stray processes.

	(b)	There is a C program called "psetenv" that can be used
		to generate a shell script setting some of the basic
		environment variables that are used in the TTL_PAPERS
		library.  By convention, we expect that "psetenv" will
		be used to create a file called "T" that will be
		visible to each machine.  Do this by:

		$ psetenv >T

		Why "T"?  Because that's where "run" looks.  Feel free
		to change both, but remember that this stuff will all
		go away when PEN is released.

5.	Now you are ready to go...  but don't just start running
	things.  The first thing you should do is to check that your
	TTL_PAPERS hardware is correctly constructed.  The "check"
	program was designed for this purpose.

	First, plug one of the TTL_PAPERS cables into the parallel
	port of one of your machines, leaving the other cables free.
	Now run "check" on that machine:

	$ check

	Note that check is NOT run using the "run" script.  Do what
	"check" suggests, and then repeat the procedure for all four
	cables on the TTL_PAPERS unit -- one at a time.

6.	Now you are ready to connect the TTL_PAPERS unit to all PEs
	and really get things going.  There are two demonstration
	programs included in this release; you are now ready to run
	any of these applications:

	(a)	The program "pi" computes an approximation to the value
		of Pi by computing the area under a curve using the
		specified number of segments.  Try running:

		$ run pi 1000000

	(b)	The program "libdemo" runs through the entire
		TTL_PAPERS library, timing each routine.  For example,
		running "libdemo" by:

		$ run libdemo 1000

		will give the times measured by executing each of the
		library routines 1,000 times.

	(c)	The program "music" plays multi-voice music using the
		built-in speaker of each PC -- using TTL_PAPERS to keep
		everything synchronized.  The music is quite coherent,
		although doing the same thing using Ethernet to
		synchronize yields something that the ear doesn't hear
		as music.  ;-)

		In any case, "music" uses the speaker port, so it needs
		to have access (remember the note in 1 above?).  It
		also uses a software loop for timing the note
		frequency, which means it is a CPU hog and it needs to
		be re-calibrated for different speed CPUs.  There is a
		calibration program called "musical" for this purpose.
		Run "musical" by:

		$ run musical

		If it tells you to change the magic constant, make the
		change and type:

		$ make

		In any case, you are now ready for some music:

		$ run music


There really isn't any good documentation for the library routines
yet, but feel free to browse the source code and examples.  Whatever
documentation we have is posted under WWW URL:

http://garage.ecn.purdue.edu/~papers


Likewise, if you have any questions or comments, please send them to:

hankd@ecn.purdue.edu


The current definition of the library is relatively stable, but, of
course, is subject to change without notice.  After all, that's why we
are calling this an Alpha Release.  ;-)
