COMMON GUI FOR BOARD DIAGNOSTIC
TEST PROGRAMS SPECIFICATIONS
Franco Spinella
Rev 1.0
1)
General
approach
Each kind of SVT board will have one or more test programs, which will be called by the GUI.
The GUI will be used by the CDF shift crew to test suspicious SVT boards before paging the on-call SVT expert. For this reason the GUI must be easy to use also by non-experts. Test programs will generate a log file of the tests performed that can be examined remotely by SVT experts.
The main purpose of the package is to test the boards in their normal location and configuration, without the need for ad-hoc reshuffling of cable connections. The GUI will also allow to exercise SVT boards in a test stand.
The main goal of this set of test programs is for the shift crew to gain reasonable confidence that a given board is good or bad before trying to swap it. More detailed diagnostics can then be run by experts in a test stand.
Test programs will be provided by individual board designers. Multiple test programs may be provided for a single board type. The GUI will just act as a common “container” for all these programs.
A possible scheme is:
a) a “simple” standalone test program , which tests all the possible features of the boards without requiring interactions with other boards. This basic test program reads and writes all VME registers, memories and lookup tables.
b) a “complete” test program, with all the previous requirements plus the possibility to receive and send data from other boards, to simulate normal flow of data through cables and connectors.
All these test programs are expected to complete in a time of the order of one minute at most.
2)
Code
requirements
3)
Test
program function prototype
For the test program function the following prototype is suggested:
1)
return_value =
2)
SVT<board>_test<n> (
3)
char *cpu,
4)
int slot
5)
struct SVTboardConf *conf_data,
6)
char *error_string,
7)
int error_string_len
8)
FILE *logfile)
Let’s go through it :
1) The
return value is 0 if all tests were successful, otherwise it is a positive
number: the same number as the MessageID for the first error encountered (see
below for logfile format description).
The GUI will display a big label with
the word OK or ERROR depending if the returned value is 0 or not. This will be
the only information needed by the shift crew to decide whether to call an
expert or possibly try to swap the board.
2) The
name of the function starts with the board initials, like SC for the Spy
Control, then the word “test” followed by a single digit number: 1 could stand
for the quick test and 2 .. 3 etc for more complex tests if needed (e.g.
SVT_SC_test1)
Boards initials will be:
i. HB: Hit Buffer
ii. AM: Associative Memory board
iii. AS: Associative Memory Sequencer
iv. SC: Spy Control
v. XA: XTFA
vi. XB: XTFB
vii. XC: XTFC
viii. HF: Hit Finder
ix. TF: Track Fitter
x. MG: Merger
xi. GB: GhostBuster
3) The crate CPU name is passed by the GUI as a string. This is the name of the CPU in the crate where the board under test is located.
4) The slot number is passed by the GUI. This is the slot where the board under test sits.
5) The GUI reads a text file which defines the current cables and board configuration (see below for details). The cables connected to the board under test are then passed to the test program as a data structure. This is used by the test program to figure out which other boards are connected to the one under test and what is their VME address. This information is needed in order to be able to perform tests where multiple boards are involved. For example, while testing one Associative Memory bank, one Merger can be used as a data source and a Hit Buffer as a data sink. It is the responsibility of the test program to check that the current configuration is compatible with the test to be performed. See later for a description of the configuration data structure.
6) Error
string passed to the GUI.
It is a good policy to let the test continue as far as possible, even after an
error is encountered. Information about all tests performed will be written to
a logfile. Information about the first error encountered will be
returned to the GUI and displayed. The error string to be displayed will be
written by the test program in a string allocated by the GUI and passed to
the test program.
7) Max length of error string in bytes, passed by the GUI.
8) The logfile. Opened by the GUI and passed to the test program.
4)
Directory
tree structure
Two directories will be defined by two environment variables:
1. $SVTTEST_DATAFILES: will be used to define the path to the data files needed by each test programs such as maps, tables, patterns etc.. The full path will be contructed as <…>/<board initials>/…. So, for example, the directory $SVTTEST_DATAFILES/AM/ would contain all the data files needed for the tests of the Associative Memory board. The directory structure below this level can be different for different boards. Each individual test program is responsible for building the correct path and opening and closing all the necessary data files using this environment variable.
2. $SVTTEST_LOGFILES: will be used by the GUI to build the path to the logfiles generated by all test programs. The directories will be organized by board type and serial number in the following way:
<…>/<board initials>/SN<2-digit serial number>/filename
so, for example, the directory $SVTTEST_LOGFILES/AM/ID06/ will contain all the logfiles generated by all test programs run on the AMboard number 6. The convention used for file names is described further.
Every time a test program is invoqued, a new logfile is created and opened by the GUI with a unique file name and passed to the test program as the “FILE * logfile” parameter in the calling sequence. Before doing this the GUI will need to read the ID PROM of the board under test in order to get the serial number (used both in the directory and file name). If this operation fails the test program will not be invoqued and an error will be displayed (e.g. “board not found!”).
The test program does not need to be aware of this environment variable since all the work needed to open the logfile is done by the GUI. The test program just needs to fprintf meaningful messages to logfile following the standard outlined further.
5)
conf_data
structure format
Each connector on a board is numbered according to its vertical position, 1 to
6, starting from the top (see
www.pi.infn.it/cdf/svt/intdoc/infrastructure/FrontPanelCableConnectors.txt)
conf_data is an array of 6 elements, one for each possible connector position.
Each element contains information about the other end of the cable starting
from the connector in that position.
struct cable
conf_data[6];
struct cable {char *CPU;
int slot;
int connector;
char *board_initials;}
The GUI only fills array elements corresponding to connector actually existing
in the board under test. The contents of array elements corresponding to
non-existing connectors is undefined. If a connector exists on the board under
test, but no cable is connected, the CPU string is initialized to “” (empty
string).
6)
Log
file format
A new logfile with a unique file name will be created by the GUI every
time a test program is called. The logfile name will be unique and will contain
the test name, the board type, the board serial number, the date and the time
to one second.
1.
LogFileName:
<board><test_num><ser_num><date><time>.log
e.g. am122000324100040.log stands for
i. AMboard
ii. test_1,
iii. serial number=22
iv. year=00
v. month=03
vi. day=24
vii. hour=10
viii. minute=00
ix. seconds=40
2. Format: all messages will be on one line with the following format:
<MessageID> <TimeStamp> <Message>
i. <MessageID> is a 4-digit number unique within each test program. It must allow unambiguous identification of the line of C code the generated it.
ii. <TimeStamp> is a string with date and time to one second
iii. <Message> is user defined
Please see http://www.pi.infn.it/cdf/svt/intdoc/AM/logfiles/amv02000324100040.log
for a sample logfile.
7)
Configuration
text file
A text configuration file is parsed by the GUI, to extract the
informations to initialize the conf_data structure. All configurations must be
described in this manner. This includes the default standard SVT configuration
(as implemented in B0) or any ad-hoc test stand configuration. The GUI will
provide a way to load a configuration file different from the default one,
which is automatically loaded at startup. Please look at the following (we
hope) self-explanatory example:
// SVT flat cable configuration file
//
// CPU = CPU name
// SL = Slot number
// CN = Connector position (1..6 starting from top)
// BD = Board type
// HF = Hit Finder
// MG = Merger
// AS = AM Sequencer
// HB = Hit Buffer
//************************************************
// Data format:
// Driver Receiver
//CPU SL CN BD --> CPU SL CN BD
//************************************************
//
// Cabling of crate 2RR35I Top
//
b0svt00 4 3 HF b0svt00 7 2 MG
b0svt00 5 3 HF b0svt00 7 3 MG
b0svt00 6 3 HF b0svt00 7 4 MG
b0svt00 7 5 MG b0svt00 8 5 AS
b0svt00 7 6 MG b0svt00 12 6 HB
b0svt00 8 4 AS b0svt00 12 4 HB
b0svt00 12 2 HB b0svt06 4 2 TF
b0svt00 13 3 HF b0svt00 16 2 MG
b0svt00 14 3 HF b0svt00 16 3 MG
b0svt00 15 3 HF b0svt00 16 4 MG
b0svt00 16 5 MG b0svt00 17 5 AS
b0svt00 16 6 MG b0svt00 21 6 HB
b0svt00 17 4 AS b0svt00 21 4 HB
b0svt00 21 2 HB b0svt06 5 2 TF
//
// Cabling of crate 2RR35I Bottom
//
....
...
...
// End *********************************************