Table of Contents

Previous Chapter

Next Chapter

5.0 The PSCI Program

This program reads a stream of ACIS packets, verifies their format and internal consistency, and optionally, sorts, reformats, and writes them to a series of data streams and disk files, as detailed in Table 11. The UNIX command syntax is as follows:

psci [-BDTVacmpqsuv] [-h name] [-l name] [file]

Packets are read from the input file named on the psci command line, or, if omitted, from the standard input stream, stdin. They are subjected to a variety of tests, as detailed below. If the ­l option is specified, their headers are translated into ASCII and written to log files. If ­m is specified, a one-line description is written to stdout, suitable for display by monitorScience (q.v.) Most packets are then discarded, and psci reads the next one, but some are retained, as follows:

• the most recent exposure header packet from each FEP,
• all event data packets, until a corresponding exposure header packet is encountered,
• multi-packet memory read-out packets originating from a single BEP command
• the most recent dumped*Block and dumpedHuffman packets.

5.1 Packet Field Verification

psci has been compiled with tables derived directly from the IP&CL Structures database. Packets with unrecognized TTAG codes (as defined in the "acis_h/interface.h" file) cause warning messages to be written to stderr, and are ignored. All fields in recognized packets and pseudopackets are then checked against their IP&CL limits--bit fields are expanded to "unsigned long int" values unless their minimum permissible values (column 15 in the IP&CL structure tables) are negative, in which case, psci treats them as twos-complement signed integers and expands them to "long int". If a field is discovered to beout of range, psci writes a message to stderr, e.g.

file: packet[ntotal,ncount].field[index] above maximum (val > maxval)
file: packet[ntotal,ncount].field[index] below minimum (val < minval)

This example illustrates several features of psci. All stderr messages begin with a file: argument; for errors and warnings, this is the name of the input file (or "stdin"); for informatory messages, it is usually the name of an output file. Packets are designated by their IP&CL names, e.g., exposureTeRaw, followed by ntotal, the sequence number of the packet within the input stream, and ncount, the sequence number among packets of this particular type. Both counts start at zero, so the first packet is [0,0]. Multi-dimensional fields within packets are followed by an array index, which also starts at 0. The value of the field is displayed as a decimal integer.

Since out-of-limits field-values are not considered to be sufficient reason for halting the program, psci writes these messages and continues processing. The messages themselves can be suppressed by invoking psci with the ­q option.

5.2 Packet Logging

When the -l option is used, psci writes packet-header information to the log files listed in Table 11. The format of these files is derived from that of data structures in the C language, e.g. Table 12, which identifies itself as the first dataTeFaintBias packet, the 16th packet in the stream. Note that fields whose values are enumerated in acis_h/interface.h will be followed by "#" and the enumeration. Unsigned values larger than 32767 are shown in hexadecimal base, preceded by "0x". The values of arrays of fields with dimension > 9 are not shown-merely their dimension. When a packet contains one or more command blocks, e.g. dumpedTeBlock, which contains a science parameter block (either loadTeBlock or loadCcBlock) and an optional window block (either load1dBlock or load2dBlock), the individual sub-fields are logged, shifted to the right by 2 columns.

As shown in Table 11, the "name" supplied with the -l option of psci is used as a common prefix to the names of all output files. When a dumpedCcBlock or dumpedTeBlock packet is received, a comment is written into all open log files, and the science run number is incremented. Any opened science and bias data files are automatically closed, and a warning message is written to stderr since they should have been closed: science files by the receipt of a previous scienceReport packet, and bias files when complete.

5.3 Monitor Output

When psci is invoked with the -m flag, monitor records are written to stdout. The example in Table 13 shows the start of a science run, from the BEP's restart message (bepStartupMessage) through the commands (commandEcho) used to configure the DEA and BEP, the dump of the parameter blocks (dumpedTeBlock), and the beginning of interleaved event (dataTeFaintBias) and bias (dataTeBiasMap) records. These records should be piped into monitorScience. They are not intended to be read in this form by humans!

To save bandwidth, and lighten the load on monitorScience, psci does not write all packet fields to the monitor stream-the excluded items include all arrays and fields identified by the nomonitor directive in the tlm.aux file used to build the psci executable (see "Architecture").

A different level of monitoring is achieved when psci is invoked with the -s flag. In this case, all telemetry packets will be converted to ASCII and written to the standard output stream, stdout, in a format identical to that used for the various log files when the -l flag is used.

Finally, the -u flag causes psci to print all user-type pseudo-packets containing ASCII messages (i.e. those of type = 0) to the standard error stream, stderr.

5.4 Science Event Modes

psci saves the science parameter block and (optional) window block that ACIS reports at the start of a science run. It also saves event data blocks until an exposure packet is received for the corresponding FEP, at which time it writes 36-byte binary event records to the appropriate "name.s.n.m.erv.dat" file as shown in Table 14. During this process, psci checks numerous fields in each FEP's event data, exposure, and parameter block packets, as detailed in "Tests Applied to Packet Fields". This process should be sufficient to detect any missing, mislabeled, or out-of-order packet, but the events themselves-their row and column indices and pixel values-are not examined. Discrepancies are reported to stderr, in one of two formats:

file: packet1[tot1,cnt1].field1=val1 != val2
file: packet1[tot1,cnt1].field1=val1 != packet2[tot2,cnt2].field2=val2

where val1 is a (possibly signed) decimal integer, and val2 is an integer or an enumeration from acis_h/interface.h. As with the out-of-range messages described in "Packet Field Verification", these are merely warnings, and may be suppressed by the -q flag. psci also examines the irigB and bepSciTime fields of all scienceFramePseudo packets. Ifthese are accurate, it will calculate approximate irigtime fields for the ERV records, but the algorithm makes three assumptions: (a) that the BEPtimer runs at precisely 100 kHz, (b) that all exposures in timed exposure mode have the same duration, and (c) that until psci has received a pair of fepTimestamp fields, it will approximate the exposure repetition interval by the primaryExposure field of loadTeBlock

All event-finding modes generate ERV files in the same format, but the use of the 9 fields in the data array differs according to mode. In CC and TE graded modes, the event amplitude is recorded in data[0] and the grade code in data[1]; in graded TE mode, data[2] contains the mean of the 4 corner pixel amplitudes; the remaining graded-mode data fields contain zeroes. In faint modes, the central pixel value is reported in data[4], with the neighboring pixels from the same CCD row in data[3] and data[5]. In 1x3 faint mode, the remaining 6 fields contain zeroes; in 3x3 faint modes, data[0] through data[2] contain the pixel values from the previous row, and data[6] through data[8] those from the following row. CCD column and row numbers are defined from the lower left corner of the CCD.

 n  msec   irig  nq  col  row ----------------- Pixels ----------------- Doclk
 0  2800 80856262 2  566   1  191 1057  178  217 1406  168  174  180  176  0
 0  2800 80856262 0  192   2  197  181  201  175 1300  661  188  760  385  0
 0  2800 80856262 1  352   2  187  213  217  161 1453 1143  178  170  177  0
 0  2800 80856262 2  549   2  182  387  164  173 2094  177  169  155  165  0
 0  2800 80856262 2  650   2  175  176  174  177 1599  891  181  177  181  0
 0  2800 80856262 2  743   2  172  177  185  177 1292  185  160 1179  217  0
 0  2800 80856262 3 1017   2  227  602  619  211 1014  936  213  211  209  0
 0  2800 80856262 0  102   3  183  196  185  179 2549  184  180  180  184  0
 0  2800 80856262 0  224   3  185  175  175  167 2517  192  181  173  187  0
 0  2800 80856262 3  949   3  215  223  205  204 2431  205  205  217  214  0
 ...

In most event modes, psci will report the raw pixel values, but in Faint-with-Bias mode, the corresponding bias values are available. Even then, the subtraction will be made only if the -B flag is specified on the psci command line, in which case the appropriate "biasValues + deltaOverclocks" is subtracted from each valid pixel value. Invalid pixels, i.e. those with bias values exceeding 4093, will be assigned a value of -32768.

If the -a flag is specified, psci writes ERV files in ASCII format to "name.s.n.m.erv.txt", as shown in Table 15. A tally is kept of all exposures, events, and bias parity errors for checking against the contents of the scienceReport packet that should terminate the science run. Additional informatory messages will be written to stderr if psci is invoked with the -v flag, e.g.

# psci -a -l test1 -v dat.1
dat.1: start TE EV3x3 FAINTBIAS bep 0x52ccbf71 irig 935:72262 exptime 3.207
test1.2.fits: bias file written, 2100032 bytes
test1.2.erv: written 13 exposures 25127 events
dat.1: scienceReport[909,0] irig 935:72301 exp 13 fep ok ccd ok dea 0 bep 0
test1.packet.log: 456 bytes written
test1.command.log: 1570 bytes written
test1.science.log: 80351 bytes written
test1.bias.log: 371820 bytes written
psci: 930 packets read from dat.1

5.5 Event Frame Timestamp Files

When the -T flag is specified on the psci command line, the times of each event-mode exposure frame present in the input stream are written to the ASCII file "name.s.time.txt". This consists of the quantities shown in Table 16. The timestamp file is only generated during event-mode science runs, i.e. not during raw or histogram mode. The BepTime value should be constant within a given file. Frames will only be listed if at least one FEP processed that exposureNumber. Since the external (IRIG) time will drift relative to the ~100 kHz pixel clock reported in BepTime and FepTime, the drift can be estimated by comparing BEP and IRIG timestamps within science header pseudopackets. This drift is reported in the dIrig0 field.

5.6 Histogram Files

Although ACIS writes histograms for each CCD output node at a time, psci saves the data packets until all expected nodes have been received, and writes a binary file in FITS format (see the left hand column of Table 18) named "name.s.n.i-j.hist.fits" for each contributing FEP. If the -a flag is specified, this will be an ASCII file named "name.s.n.i-j.hist.txt", consisting of 6 header lines followed by 4096 lines of 5 columns each containing, respectively, the pixel value and one pixel count for each output node A through D (see Table 17). If the CCDs are run with restricted output nodes (i.e. QUAD_AC or QUAD_BD), the unused columns are filled with zeroes.

5.7 Raw Mode

The contents of raw data packets are written to disk files in FITS format as soon as they are received. Since the data packets always precede the exposure packet that describes them, the output file is first named "name.s.n.TMP.fits", and renamed "name.s.n.m.raw.fits" as soon as the exposure number "m" is known. For greater efficiency, psci uses memory mapping (the mmap(2) system call) to write raw-mode and bias files. As a consequence, the "ls -l" command will indicate that these files contain at least 2 Mbytes (1 Mbyte in continuous clocking mode), but the actual disk allocation, e.g. from the "du -a" command, will gradually increase as the data packets are received. Care must be taken to allow for this extra disk space when psci is receiving raw data and bias maps.

The headers of raw-mode FITS files will contain the fields shown in the center column of Table 18. Overclocks are appended to each line of the image array. The data area is always 1024x1024 pixels in timed-exposure mode and 1024x512 pixels in continuous clocking mode. psci will examine the dumpedTeBlock or dumpedCcBlock packet to see whether the CCD was run in a pixel-summing mode, or in sub-array readout mode, and will replicate and shift pixels accordingly to recreate a FITS file that reconstructs the original CCD geometry.

5.8 Bias Files

These are created in the same manner as raw pixel images, i.e. they are memory-mapped into pre- allocated files of fixed length. The FITS file header format is shown in the right-hand column of Table 18. Timed exposure bias files always contain 2100032 bytes (2880 header bytes followed by 1024x1024 2-byte image pixels). As in raw mode, psci replicates and shifts the pixels to fill the entire 1024x1024 pixel array. Continuously clocked bias maps contain 1051456 bytes--the single row reported by the BEP is replicated 512 times.

5.9 Memory Readout

When the -l flag is specified, psci copies the contents of all memory readout packets to disk files named "name.pkt.n.dat", where "name" is the prefix specified on the command line, "pkt" is the type of memory readout, and "n" is an index that increments whenever a packet, or group of packets of this type is encountered. They are written in the native byte order of the host machine. When the ­a flag is also present, the files are written in hexadecimal notation similar to the output of the "od -X" command (or "od -x" for the 16-bit SRAM and PRAM dumps), and they will be named "name.pkt.n.dat".

5.10 Huffman Tables

The compression tables used by the BEP to compress the contents of raw science and bias data packets are treated by psci as special cases of memory readout. Since the Huffman table block is too long to dump in a single packet, psci assembles it from several dumpedHuffman packets and, when it is complete, saves it to decompress any subsequent raw or bias packets. If the "­l" option is used, the Huffman block will also be written to a disk file. Since Huffman blocks will not always be part of the packet stream, psci can be told, via the "­h" option, to pre-load a previously saved binary Huffman block, but this will always be supplanted by a complete Huffman block in the packet stream.

When the "­a" flag is used, Huffman blocks will be written to disk in ASCII format. These cannot be loaded by the "­h" option, but they are more readable, e.g. the example in Table 19.

5.11 Pseudopackets

If the "­p" flag is specified, these are written to "name.pseudo.log". BEP & IRIG time fields are saved from scienceFramePseudo packets, as outlined in "Science Event Modes". above. Also, when psci is invoked with the "-u" flag, userPseudo packets with "type" field values of zero are interpreted as diagnostic messages from the flight software and the remainder of the packets, assumed to contain null-terminated character strings, are written to stderr.Otherwise, pseudopackets are ignored.

5.12 Architecture

With the exception of the external tables discussed in "Huffman Tables", psci is self-contained-all packet and field names and formats are compiled into the executable module. The code is generated in three stages. In the first, a Perl script named genmap reads the IP&CL structures file and creates intermediate cmd.map and tlm.map files which define the field formats and minimum and maximum values. genmap also extracts the enumeration values from acis_h/interface.h and writes them to enum.c as character string arrays.Then gentab, a second Perl script, converts cmd.map and tlm.map into C structures in cmdtab.c and cmdtab.h. Finally, gcc compiles the structures with the remaining source code. While the process is automatic, it can be guided by directives in the three files enum.aux, cmd.aux, and tlm.aux. An example of enum.aux is shown in Table 20-lines of the form "command id name" assign "name" to command packets with that "id", and "packet id name" performs the same function for telemetry packets. This causes psci to use the new names within messages and in log and monitor files, as well as giving symbolic names to pseudopackets, since these were never described by the IP&CL.

Examples of the cmd.aux and tlm.aux files are shown in Table 21 and Table 22. They share a common syntax. The "enumerate" command assigns a character string array in enum.c to a particular command or telemetry packet field. psci will display the enumerated value in its log files and error messages. The "nolog" directive prevents psci from logging a particular type of command, or packet, or field. The "nomonitor" command, which is only used in tlm.aux, performs the same function-of eliminating fields from monitor packets. The more restrictive "nomonitornull" command prevents fields from being written to the monitor stream if they have zero value.

5.13 Tests applied to packet fields

Table 23 details the tests applied within the particular packet-handling modules. These are in addition to the range tests described in "Packet Field Verification", which themselves verify the following fields:

• In all command blocks: commandLength, commandOpcode
• In all telemetry packets: synch, telemetryLength, formatTag

A number of other consistency checks are made in the process of creating the output data files, and may cause warning messages to appear on stderr. For instance, the ccdRow and ccdRowCount fields in dataTeBiasMap packets are verified against the sub-array fields in loadTeBlock. The warnings are usually self-explanatory; the user should consult the source code for further details.

Considerate la vostra semenza:
fatti non foste a viver come bruti,
ma per seguir virtute e canoscenza.

Table of Contents

Previous Chapter

Next Chapter