MuSTARD Library Routines
The following describes the routines in the MuSTARD library (mus_lib.c).
You may find more enlightenment reading the code! All the routines return
an int status, which is zero for a non-error return. The basic
user routines are listed in alphabetic order.
Basic user routines
The following routines provide basic access to the functionality of
MuSTARD. The implementation tried to ensure that each routine was
self-contained. In the lower part of this page
are descriptions of
a few test routines which provide some assistance in debugging a
MuSTARD - their inclusion in mus_lib is to some extent an accident
of history.
- mus_clear_buffer(short identifier, short *nevents)
Clears the output event buffer by checking the first location for a
non-negative value, then clearing the event by writing to this location.
It loops round until no more events appear (ie. it times out waiting for
an event). "nevents returns the number of events cleared. MRDOEN
must be set elsewhere to permit access to the output buffer. The error
returns are:
-1 if the identifier is invalid
-2 if the control register can't be read
-3 if MRDOEN is incorrectly set to allow access to the buffer
- mus_clear_histogram(short identifier, short stream)
Clears the histogram memory for a single stream. All 2kx16 locations
are cleared, however many channels are really in use. MRDOEN must be
cleared elsewhere to permit access to the histogram memory. The error
returns are:
-1 if the identifier is invalid
-2 if the stream number is invalid
-3 if the control register can't be read
-4 if MRDOEN is incorrectly set to allow access to the buffer
- mus_exit()
Tidies-up the VME mapping and memory usage at the end of a program. This
routine should be called once just before exiting. It contains
machine-dependent code, so may need modifying
for a new platform. Also it takes no account of a known potential problem
on both NI-VXI and (to a lesser degree) RAID platforms, where the number
of maps to VME address space is limited and which might mean the mapping
logic will need changing for >1 MuSTARD. The routine always returns 0.
- mus_read_clock_cntl(short identifier, short *clock)
Reads the contents of the clock control register. Only bit 0 contains useful
information, so the clock argument only contains 0 (external clock)
or 1 (internal clock) on return. There is an error return -1 if the identifier
is invalid.
- mus_read_compress_event(short identifier, short *length, short **buffer)
Reads an event from the output buffer of the MuSTARD, packs the 8-bit hit
data in pairs into each short of the buffer array and then releases
the event by writing to the first location of the output buffer. This only
makes sense in raw mode (and the mode is not tested - the user must
ensure it is correct). Also to allow for decoding of the buffer, pointers to
each stream are provided at the front of the output data. The returned
length is the number of valid words in the buffer array.
This routine is
envisaged mainly for test beam use, where the data volume has an impact on
the data-taking rate. The error returns are:
-1 if the identifier is invalid
-2 if the control register can't be read
-3 if MRDOEN is incorrectly set to allow access to the buffer
-4 if there is no event available (timeout on waiting)
-5 if the error bit (14) is set in the first word (this should never happen
in raw mode)
- mus_read_event(short identifier, short *length, short **buffer)
Reads an event from the output buffer of the MuSTARD
into the buffer array and then releases
the event by writing to the first location of the output buffer. No test on
data quality is done. The returned length is obtained from bits 0-13
of the first word.
The error returns are:
-1 if the identifier is invalid
-2 if the control register can't be read
-3 if MRDOEN is incorrectly set to allow access to the buffer
-4 if there is no event available (timeout on waiting)
-5 if the error bit (14) is set in the first word (only relevant in decoded
mode)
- mus_read_histogram(short identifier, short hilo, short stream,
short *length, short **buffer)
Read the histogram memory of a MuSTARD. The hilo argument detemines
whether the lower 6 chips are read (=0) or the upper 6 chips (=1). The latter
case will only occur when the redundancy scheme is in use. length will
always return 768 (its presence is a relic of an alternative operation of
this routine). The user must determine external to this routine where the
histograms will be located. Error returns are:
The error returns are:
-1 if the identifier is invalid
-2 if the stream number is invalid
-3 if the control register can't be read
-4 if MRDOEN is incorrectly set to allow access to the histogram memory
- mus_read_readout_cntl(short identifier, short *mdaqen, short *mrdoen)
Read the contents of the readout control register. The contents of bits 0 and 1
are put into the arguments mrdoen and mdaqen respectively. The
routine returns -1 for an invalid identifier.
- mus_read_readout_modes(short identifier, short *raw_mode,
short *sample_all)
Read the contents of the readout modes register. The contents of bits 0 and 1
are put into the arguments raw_mode and sample_all respectively.
The routine returns -1 for an invalid identifier.
- mus_read_status(short identifier, short *status)
Read the contents of the status register. bit 15 (always set) is masked-off
inside the routine to ensure status always returns a positive number.
The interpretation of the bits is left to the caller.
The routine returns -1 for an invalid identifier.
- mus_read_stream_enable(short identifier, short stream, short *enable)
Read the contents of the stream enable register for a specific stream. The
enable information is duplicated in the registers for streams 0-3, 4-7 and 8-11
respectively - only the enable information for the specific stream is returned
to the caller. The routine returns -1 for an invalid identifier.and -2 for an
invalid stream.
- mus_read_stream_paf(short identifier, short stream, short *paf)
Read the contents of the stream PAF (PArtially Full) register for a specific
stream. Only bits 0 and 1 are returned by this routine, as the other bits are
not meaningful. The PAF information is common for streams 0-3, 4-7 and 8-11
respectively, so in principle an interrogation of all PAF information can be
achieved by only three calls to this routine..
The routine returns -1 for an invalid identifier.and -2 for an
invalid stream.
- mus_read_stream_status(short identifier, short stream, short *status)
Read the contents of the stream status register for a specific stream.
Only bits 0-4 of the status register are returned to the caller (the other
bits are undefined and hence masked-off). The routine returns -1 for an
invalid identifier.and -2 for an invalid stream.
- mus_read_stream_trlim(short identifier, short stream, short *trlim)
Read the contents of the stream trigger limit register for a specific stream.
Only bits 0 and 1 of the trlim register are returned to the caller (the other
bits are undefined and hence masked-off). The same register is used for
streams 0-3, 4-7, 8-11 respectively, so all the information can be obtained
by three calls to this routine. The routine returns -1 for an
invalid identifier.and -2 for an invalid stream.
- mus_read_testmode(short identifier, short *mode)
Read the contents of the test mode register.
Only bits 0 and 1 of this register are returned to the caller (the other
bits are undefined and hence masked-off).
The routine returns -1 for an invalid identifier.
- mus_release_event(short identifier)
Release an event from the output buffer of the MuSTARD. This routine should
only need to be used when either normal readout has failed, or you are not
interested in the data in the output buffer. To some extent it duplicates
the functionality of mus_clear_buffer, but it returns immediately if
there is no event in the buffer, and only clears a maximum of one event.
The error returns are:
-1 if the identifier is invalid
-2 if the control register can't be read
-3 if MRDOEN is incorrectly set to allow access to the buffer
-4 if there is no event in the buffer
- mus_reset(short identifier)
Reset the MuSTARD by writing 1 followed by 0 to the reset register. Returns
-1 if the identifier is invalid.
- mus_set_clock_cntl(short identifier, short clock)
Set the clock register with the value in clock. Only bit 0 of the
input argument is significant. Setting it =0 means us the external clock, =1
forces the use of the internal clock. -1 is returned if the identifier is
invalid.
- mus_set_readout_cntl(short identifier, short mdaqen, short mrdoen)
Set the readout control register with the values in mdaqen (bit 1) and
mrdoen (bit 0). Only bit 0 of each input argument is used.
-1 is returned if the identifier is invalid.
- mus_set_readout_modes(short identifier, short raw_mode, short sample_all)
Set the readout modes register with the values in raw_mode (bit 1) and
sample_all (bit 0). Only bit 0 of each input argument is used.
-1 is returned if the identifier is invalid.
- mus_set_stream_delay(short identifier, short stream, short delay)
Set the delay on a single stream. Only a delay in the range 0-24(nsec) is
valid (see error returns below). The routine waits for up to 2 msec (in units
of 200 microsec) for completion (the communication is via the I2C bus, which
is relatively slow). Error returns:
-1 if the identifier is invalid
-2 if the stream number is invalid
-3 if the delay to be set is outside the range 0-24
-4 if the control register doesn't indicate completion in 2 msec
- mus_set_stream_enable(short identifier, short stream, short enable)
Set the enable register on a single stream. Only bit 0 of the input argument
is used. Return -1 if the identifier is invalid, -2 if the stream is invalid.
- mus_set_stream_paf(short identifier, short stream, short paf)
Set the PArtially Full register on a single stream. Only bits 0 and 1 of the
input argument are used. The PAF registers are common for streams 0-3, 4-7 and
8-11, but this routine accesses them as if they were specific to each stream.
Return -1 if the identifier is invalid, -2 if the stream is invalid.
- mus_set_stream_trlim(short identifier, short stream, short trlim)
Set the trigger limit register on a single stream. Only bits 0 and 1 of the
input argument are used. The registers are common for streams 0-3, 4-7 and
8-11, but this routine accesses them as if they were specific to each stream.
Return -1 if the identifier is invalid, -2 if the stream is invalid.
- mus_set_testfifo(short identifier, short fifo)
Set the test fifo register. Only bits 0-13 of the
input argument are used, and the user is assumed to have set the correct
value.
Return -1 if the identifier is invalid.
- mus_set_testmode(short identifier, short mode)
Set the test mode register. Only bits 0 and 1 of the
input argument are used, and the user is assumed to have set the correct
value.
Return -1 if the identifier is invalid.
- mus_set_testtrig(short identifier)
Write to the test trigger register. The data written is irrelevant (in fact
zero is written to the register).
Return -1 if the identifier is invalid.
- mus_test_fifos(short identifier, short *empty)
Check if the input fifos are empty. Returns a bitmap of empty streams (denoted
by bit n = 1) in the empty argument. bit n = 0 if the stream is not
empty or a stream is not enabled.
Returns -1 if the identifier is invalid.
- mus_vmemap(unsigned long address, short *identifier)
Maps the VME address space of the MuSTARD to the CPU address space. This
routine is very machine-specific. The existing version has code for OS9 V2.x
and V3.x, NI-VXI interface and the RAID. For the first two, address
is the mapped address, for the second pair, it is the true VME address and
A32 addressing is assumed. It should be fairly easy for users to modify the
routine for other platforms if necessary. The returned identifier is
used in all other routines to identify the MuSTARD. A 128kB window in address
space is assumed. The routine returns the error code from the machine-specific
mapping routine.
Test routines
- mus_test_event(short identifier, short *length, short *nevents,
short *nerrors, short dump)
Reads an event and decodes the header. The MuSTARD is assumed to be in
decoded mode, so the length, nevents and nerrors
arguments return information inserted into the output buffer when in that
mode. dump is a flag to determine if mus_dump_event (q.v.) is called.
The event is released after the header is read (so the data of the event is
lost - it is assumed the histogram memory will be used to study the data).
The error returns are as for mus_read_event:
-1 if the identifier is invalid
-2 if the control register can't be read
-3 if MRDOEN is incorrectly set to allow access to the buffer
-4 if there is no event available (timeout on waiting)
-5 if the error bit (14) is set in the first word
- mus_test_stren(short identifier)
Read and print out the twelve stream enable registers.
- mus_loop_stren(short identifier, short offset)
Read the register at offset from the start of the stream logic
address space many times and print out the results. Intended to check the
stability of the enable registers,
but could be used for any stream register.
- mus_test_hmem(short identifier)
Test the histogram memory by writing a pattern into memory, reading the
first few locations back and printing the results. There are more thorough
test routines elsewhere.
- mus_dump_event(short identifier, short *data)
Used with mus_test_event to print out the contents of an event. base
points to the start address of the event buffer, so this routine could also be
used to decode an event already read out.
- mus_debug_event(short identifier, short *data, short level)
Essentially a duplicate of mus_dump_event! Probably intended to have more
extensive testing of the data quality - somehow it never happened...
John Hill
Last update 8 September 1999