This directory contains source files required to generate code
to spy on event data en-route from the event builder to
the tape server.

Three main components are generated:

1 sort-spy
----------

is a demon process that spys on the network (either ethernet or
FDDI). This picks out EB to TS UDP packets from the network and
rebuilds data blocks from them. These blocks are then queued in a
memory-mapped buffer ring file ready to be read by a sorting task. The
task sets the network device into promiscuous mode and therefore must
run with root id in order to access the hardware at a low level.  To
do this, either run the task as root or change the files ownership to
root and set the setuid permission bit.  See the man page for argument
details.


2 libspy.a
----------

is a library that on-line sort tasks should link with.
Functions are provided to enable a user task to read
the data blocks which sort-spy has picked off the net.
Three functions are provided:

int sortSpyOpenFile   (int stream, char* fileroot)

makes a conection with the ring file for that stream
derived by appending the stream number to 'fileroot'.
returns 0 on succes otherwise -1

int sortSpyOpen   (int stream)

makes a conection with the default ring file for that stream.
returns 0 on succes otherwise -1 
(for compatibility with version 1.x)

int sortSpyReadWithSeq (int stream, char *data, int length, int* seq)

reads a data block into the user supplied buffer 'data'
of length 'length' bytes. returns the actual size of 
data block (even if greater than 'length') or zero if 
there is no data available (ie does not block) or -1 on error.
returns in *seq the sequence number attached to the block.

int sortSpySignal (int stream, int bool)

if 'bool' is TRUE marks the buffer ring file so that sort-spy will send 
the client program a SIGUSR1 signal whenever it inserts a new data block 
into the buffer ring. if 'bool' is FALSE the sort-spy ceases to send 
signals and the client program must rely on polling. This is the default.

int sortSpyRead   (int stream, char *data, int length)

as for sortSpyRead () but ignoring the *seq argument.
(for compatibility with version 1.x)

int sortSpyClose  (int stream)

closes a conection with the ring for that stream
returns 0 on succes otherwise -1

Sort code can include the file 'libspy.h' for function declarations


3 libmole.a
-----------

is a library that a data acquisition program can link with for 
broadcasting EbyE blocks onto a private Ethernet or FDDI. It uses the
DLPI interface to talk to /dev/le (Ethernet) or /dev/bf (FDDI).

int sortMoleOpen (int stream, char* host, char* interface, int devnum);

opens 'stream' (1..4) on the given 'interface' (eg, /dev/le) and 'devnum'
(eg, 1) masquerading as 'host' (ie, the IP address of 'host' appears
as the source address in the generated IP packets. Zeros the sequence
number associated with 'stream'.

int sortMoleWrite (int stream, char* data, int length);

broadcasts the EbyE block 'data' of the given 'length' (bytes) on the
given 'stream' (1..4) in a sequence of fragments. increments the sequence 
numbering  associated with 'stream'. 'data' should constitute an event
'record' with appropriate header and trailer that is understood by
EbyE sorting programs such as sort-shell.

int sortMoleClose (int stream);

closes the given 'stream'. 

char* sortMoleError ();

returns a pointer to a string containing a formatted message for the
most recent error detected in libmole.

4. testmole
-----------

a trivial test program for libmole which can act as test source of 
EbyE data (one block repeatedly transmitted) for sort-spy. must be
run with root priviledge.

-------------------------------------------------------------------------------
Source files:

Makefile    To update files
README      This file
libmole.c   Source code for libmole
libmole.h   Definitions for libmole users
libmole.3   man page for libmole
libspy.c    Source code for libspy
libspy.h    Definitions for libspy users
libspy.3    man page for libspy
sort-spy.c  Source code for demon task
sort-spy.1  man page
spy.h       General definitions 
test.c      Source code for a simple test program
testmole.c  simple test of libmole

-------------------------------------------------------------------------------
version 1.1 15 Oct 1993, PHO

-------------------------------------------------------------------------------
version 2.1 Thu Mar  9 11:27:09 GMT 1995, DB

***Not compatible with version 1.x***. 

Modified for Edinburgh/Charissa data acqu projects.  In particular,
the file format is changed, but the library routine interfaces are
preserved and extended. progs using the library just need to relink
with the 2.1 library and be run against the 2.1 spy.

Increased the arguments and introduced -x type keywords. The default
arguments values are retained.

Debugging selectable by -d argument. ringsize and blocksize selectable
by -r and -b arguments which appear in the ring file header. Ring
file names selectable by -f argument. Enables multiple spy/sort
process pairs in a machine.

Modified the meaning of wrIndex and rdIndex buffer ring pointers:
rdIndex becomes wrCount and says how many of the ring slots contain a
valid data buffer. The valid slots are thus wrIndex-1, wrIndex-2,...,
wrIndex-wrCount, modulo the ringsize. The spy itself always writes the
latest buffer into the wrIndex slot, regardless of the state of the
reader. The reader always takes the wrIndex-wrCount slot (provided
wrCount>0) and decrements wrCount. This means that the spy can stomp
on a slot that the reader is copying out, but it never blocks waiting
for the sort program to do its stuff. We will see if this causes
trouble. If so, we will introduce a mutual exclusion semaphore. (see
sem.c for a demo of how to use Solaris semaphores)

These changes introduced having observed hang ups and missed blocks 
(even at data rates when the reader has plenty of spare cpu time)
and to ensure that the reader always has access to the most recent
ringsize buffers.

Changed the fragment handling to always resynchronise on a fragment
with offset zero. (Ah, the benefits of selectable runtime debugging!)

Block sequence numbers go into the ring and can be retreived with
sortSpyReadWithSeq ().

Exits cleanly on receipt of SIGHUP. Doesn't delete ring files.

Still misses about 2% of blocks, probably due to Solaris time
slicing. Worth investigating running at a RT priority. How do they do
that?
-------------------------------------------------------------------------------
version 2.2 Tue Mar 21 11:57:16 GMT 1995, DB

introduced libmole. note that libmole.c and sort-spy.c are intended
for use with the Sun /dev/le and /dev/bf drivers. The driver for the
Network Peripherals FDDI card behaves annoyingly differently (eg, it 
returns the MAC level addresses in the data, whereas the Sun drivers omit
them) and needs a slightly different variant. If I get time I'll get
round to modifying the code to handle the NP as well.
-------------------------------------------------------------------------------
version 2.3 Fri May  5 16:04:45 BST 1995, DB

introduced sortSpySignal() function. reported oversized data blocks in
sort-spy. removed file locking. in the intended mode of use, sort-spy is
a setuid root program, and any client sorting program which wants to spy
on a data stream launches its own instance of sort-spy with non-default
ring files. This largely obviates the need for file locking.  made
sort-spy elevate itself to the default (minimal) priority within the RT
scheduling class. this seems largely to overcome problems with missed
network fragments (discovered by Tom Davinson).


