
								8/22/89
			BIT - How to Add a Test


This document will describe key points in adding new tests to the bit suite 
of tests.  Tests written to run under bit are either executable scripts, or 
compiled from higher level sources, such as C or fortran.  The tests share the 
trait of running until they are killed, and generating no output on stdout.

The life cycle of a test run in the bit environment is basically that the 
test must be invoked by the BIT script, monitored by the watch.BIT script 
and killed by the clean.BIT script.  There are more details involved for bit's
operation, but a study of the three scripts will give you the most concise 
answers possible for new test integration.

Tests are allowed to write files on the system, typically communicating to bit 
through passcount and error files that allow watch.BIT to report on this 
information.  The process ID of the test that creates the files is prepended 
to the file names of the files that are subordinate to the test.

As usual for any test development, you should precisely define the objective 
of the test, and test it's implementation very carefully.  Once the test is
running to your satisfaction, then you will start to integrate the test in bit. 



Test Initiation under bit.

Bit begins with the user executing the script 'BIT'.   The file DATA.BIT is
tested for content (non-zero length), and if it's found to be empty, the
script CONFIG.BIT is run to accept operator input to build DATA.BIT.

DATA.BIT is used to enable or disable tests for a particular test run, by
BIT reading the content of DATA.BIT and setting configuration variables based
on DATA.BIT contents.

Obviously, if you are integrating a new test, you will have to provide a
new variable (And questions that supply values to the variable) for each test
added to the bit suite, within the CONFIG.BIT script.  You will have to 
propagate the variable to all tests that must use it.



Once the BIT script has started the tests requested in background, it passes
control to the watch.BIT script.  Watch.BIT is an infinite loop, that is 
constantly checking for error files from the tests, and generating the report
that is sent to the console on a pass by pass basis. 

The actual testing of the error files is performed by check.BIT.  This script 
checks for the presence of "ERR" files for the type specified by the first 
argument.  If it finds any, it checks if any are too big, and if so kills the 
process responsible for generating the oversize file.  It then appends a message
to the oversize file indicating that the process was killed ( and when ), and 
moves the file into a "SAV" file.  If no files of either "ERR" or "SAV" type 
are found, this script exits immediately.  You must provide the apropriate 
lines in watch.BIT to take advantage of the mechanisim described above.


clean.BIT is invoked by trap statements in BIT or watch.BIT. 
First it kills all tests that are running.  Then it concatenates all ERR 
and SAV files into the file "REPORT.BIT".  Then it removes all temporary files 
and directories.
After this script has completed execution, the machine is back in the exact
same state as immediately after the "BIT" tests were loaded, except that the
files "DATA.BIT", "REPORT.BIT", "LOG.BIT", and "LOCK.BIT.clean" are new.
Also, the gettys are all killed.  The "BIT" test can be restarted at this
point.

Because the operator might have halted and restarted "BIT" without ever
running the script "STATUS.BIT", this script checks for the presence of the
file "LOG.BIT". If a "LOG.BIT" from a previous run exists, it is appended to
the file "REPORT.BIT" and then overwritten with this run's "LOG.BIT".
The script checks for the presence of the lockfile "LOCK.BIT.clean" and exits
if it finds it so that this script will only be called once even though the
trap is passed to every previous shell that calls "clean.BIT".  Without the
lockfile this script would be invoked once per shell level.



Recomendations for test integration:

1.	Check that the implementation of the new test performs as expected
	under all possible conditions.  Do this in the unix environment, but
	not under the BIT environment.  

2.	When you have assured that the test implementation works as advertised,
	begin to "wire in" the test to BIT.  As previously mentioned, all tests
	subordinate to bit are started by the BIT script. 

	The following files should be updated to include the new test:

		Makefile
		config.BIT
		BIT
		watch.BIT
		clean.BIT
		check.BIT




Files in bit:

BIT		- The main script. Starts all tests.
CONFIG.BIT	- Takes information about tests desired, creates DATA.BIT
CONFIGURATION	- Describes settable paramaters such as net host etc.
CONFIGURATION.hw  A copy of CONFIGURATION, with the original values.
Makefile	- Provides a standard mechanisim for installation / removal.
README		- Installation notes and serial port testing description.
REPORT.BIT	- A null file that will contain the reports generated from test.
STATUS.BIT	- Reports errors generated by the burn-in test, if any.
alarm.BIT	- Provides a timeout mechanisim for various tests.
cart.BIT	- Cartrige tape test - runs 'till killed.
check.BIT	- Checks ERR file sizes, if too large, kills test responsible
clean.BIT	- Terminates tests, cleans up files, generates report.
comp.BIT	- Compile test - runs 'till killed.
cshrc		- Used by Makefile to create .cshrc for bit
disk.BIT	- Disk drive test -runs 'till killed.
echo.BIT	- local echo utility to allow echo's without \n
etc.d		- Bit's storage for files that are manipulated in /etc
fp.BIT		- Floating point test - runs 'till killed.
fptype		- Determines the kind of floating point support available.
fpu.d		- Floating point test directory.
grab.BIT	- Used to generate a list of files in special output format
ifconfig.BIT	- Performs network configuration (see ifconfig man page)
login		- used by Makefile to create .login for bit
mkdir.BIT	- Used to create directories for disk tests by the BIT script
mport.BIT	- Motherboard serial port test - runs 'till killed.
net.BIT		- Network test - runs 'till killed.
nine.BIT	- Half-inch tape test - runs 'till killed.
port.BIT	- Serial port test (A la ISI) runs 'till killed.
prevmake	- Used by Makefile to prevent multiple install attempts.
src.d		- Source directory for non-script tests and routines in bit
mem.BIT		- Memory test - runs 'till killed.
watch.BIT	- Generates status screens, checks for excessive ERR file sizes
