SPEW.DOC

Overview:

    SPEW is a simple little test program to verify existence and basic
    functionality of Async Serial Communications devices.  Though designed
    to work with any Async device that complies with the OS/2 API, it is
    provided -- allong with full source code -- as a test tool for DigiBoard
    hardware and device drivers.  It is text-only program designed to run in
    in a "OS/2 Full Screen" environment.

    Depending on command line arguments, SPEW can individually or collectively
    test device behavior with regard to Modem Signals, data throughput, and
    machine resource utilization.  It is a very simple program and is not
    intended to be a serious device performance testing or benchmarking
    tool.  

    The full test suite will require a "loopback" connector on the port
    being tested.  This connector should jumper the RS-232 signals together
    thus:

         Tx--Rx		DTR--CD--RI		RTS--CTS
        
Functions:

    MODEM SIGNALS:
    	When SPEW tests modem signal behaviour, it is simply issuing OS/2
	API DosDevIOCtl() command to the device.  It first retrieves the
	current signal, then raises both DTR,RTS, then drops just RTS, then
	drops just DTR, then drops both.  At each stage it makes further
	DosDevIOCtl calls to retrieve the the results of the above changes
	and reports them.  As the DTR and RTS signals are altered, you should
	at the very minimum see the DTR,RTS signals obey the changes.  Also,
	depending on the kind of cabling you have connected to the device,
	other signals (DSR,CD,CTS,RI) should follow the line they are tied to.

	If you wish to bypass the modem signal testing phase, specify the
	'-s' (NO-SIGNALS) flag on the comman line.

    DATA THROUGHPUT:
    	SPEW by default will assume that a "loopback" is connected to the
	device such that all data that is transmitted is automatically
	looped-back to the same device.  This is to permit the testing of
	both DosRead and DosWrite system calls on the device without having
	to provide an external source of data to Read.  In this case, SPEW
	will attempt to Read back all the test data that it has transmitted
	and will do some cursory verification of that data.

	Without a looback connector, SPEW can still perform Transmit-only
	testing though no verification of the output is possible.  This can
	be useful to test the basic accessibility of the device name(s) to
	application programs.

	If you do not have a loopback connector or would like to bypass the
	Read/Verify phase of SPEW, specify the '-l' (NO-LOOPBACK) flag on the
	command line.


    CPU UTILIZATION:
    	SPEW by default will attempt to give an idea of how much of the
	machine resources available to it are consumed by sustaining the
	level of throughput specified.  Ofcourse doing loopback simultaneous
	transmit and receive (Full Duplex) tests will result in lower
	throughput numbers and more computer resources (CPU) utilized.
	SPEW takes a guess at this by running a background thread at lo
	priority that simply does iterations of integer calculations.
	Note that this background thread is designed to run at every idle
	opportunity so OTHER processes (eg. BonAmi CPU MONITOR) that are
	attempting comperable monitoring tasks will report that close to
	100% of the CPU is in use.

	If you do not wish to have this background thread thus calculate CPU
	utilization for you, specify the '-c' (NO-CPU) option on the
	command line.


Examples:

>spew com1

## this will assume a loopback connector on COM1 and run modem signal tests
## followed by full duplex data throughput tests with CPU utilization reports

>spew com 1,8

## this will assume a loopback connector on ALL the devices: COM1,COM2...COM8
## and run modem signal tests on EACH one in turn (one at at time); followed 
## by full duplex data throughput tests with CPU utilization reports on all 
## ports in PARALLEL  (one data throughput thread per channel)

>spew -sl com 1,8

## this will skip the modem-signal and loopback Read tests and perform
## pure transmit tests on all devices COM1,COM2...COM8 in parallel, reporting
## performance and CPU utilization statistics.

>spew -cl com 7,8

## this will skip the loopback Read tests and perform (one device at a time)
## modem signal tests followed by transmit-only tests of the port but no
## CPU utilization information will be generated.
