MCE flat-file format

This document describes one of MAS/MCE's output file formats. The "DAS flat-file" format is closely related to the form that frame data have when they arrive at the PC from the MCE. This format has many weaknesses as far as end users are concerned. Only flat-files with "header version 6" are described here.

The data consist of any number of "frames". In a given flat-file, all frames should have the same size. The frame size can be determined from the first 28 bytes of the file. No MCE flat-file will be shorter than 28 bytes.

The natural data unit of MCE data is the 32-bit unsigned integer. We refer to 32-bit integers as "words". All offsets are expressed in terms of words, and should be multiplied by 4 to get the byte offset.

An MCE/DAS frame, up to and including header version 6, consists of the following:

• 43 words of header information
• 8*R*N words of data, where N is the number of readout cards reporting and R is the number of rows reporting.
• 1 word of checksum information

Frame header

The frame header is 43 words long. The table below describes the most useful fields in the header. Esoteric fields are omitted; absent offsets are not necessarily unused.

Offset	Name	Category	Detail
0	Frame status bits	Status/Structure	described below
1	CC frame counter	Status	internal counter, starts at the value of "cc ret_dat_s" and increments by 1 for each output frame.
2	row_len	Timing	Dwell time of the multiplexer on each row, in units of 1/50 MHz
3	num_rows_reported	Structure	Number of rows in each column that are reported in each output frame.
4	data_rate	Timing	Number of internal frames that MCE processes before outputting one to the user.
5	CC ARZ counter	Timing	internal counter, counts number of address-return-to-zero (ARZ) or number of internal frames.
6	header version	Structure	6, the number "six". Subject to change in future header versions.
7	ramp value	Status	Current value of the internal ramping parameter
8	ramp address	Status	Card and parameter address of the internal ramping parameter (bits [31-16] are card_addr, bits [15-0] are param_id)
9	num_rows	Timing	Number of rows that the MCE is servoing
10	Sync box number	Status	Synchronization number, originating at the sync box, that is used to synchronize data from multiple MCEs and the housekeeping system
11	run_id	Status	Contents of "cc run_id", typically the ctime (unix time) associated with the acquisition.
12	user_word	Status	Contents of "cc user_word", which the user may use to store other significant information.

A more complete description of the version 6 frame header can be found in the document "MCE File Formats", version 3.3:

http://www.phas.ubc.ca/%7Emce/mcedocs/index.html

This document is out of date in some respects, but the descriptions of the frame headers up to version 6 should be accurate.

Frame status bits

Bit	Category	Detail
0	Status	Last frame bit, indicates that current acquisition cycle has completed. This does not necessarily indicate the last frame in a flat-file.
1	Status	Stop bit, indicates that MCE was commanded to stop acquisition and this is the last frame.
2	Status	Sync box free run mode bit, indicates that sync box is generating the data valid information (rather than accepting an external trigger)
3	Status	Sync box error bit.
4	Status	TES bias square wave level (not present in most firmware)
10	Structure	Readout card 1 data are present.
11	Structure	Readout card 2 data are present.
12	Structure	Readout card 3 data are present.
13	Structure	Readout card 4 data are present.
19:16 (v7 only!)	Structure	Number of columns returning data, per readout card. Reads as 0 in v6.

Bits 10-13 and 16-19 are especially relevant for determining the frame size and data structure.

Timing parameters

The internal frame rate of the MCE (the rate at which a given row is servoed) and the output frame rate of the MCE (the rate at which frames are returned to the PC and recorded to disk) can be calculated as follows:

f_internal = 50 MHz / (num_rows * row_len)
f_output   = f_internal / data_rate

Structure determination

The size and structure of the readout data block can be determined from

• num_rows_reported
• bits 10-13 of the frame status bits, which we will call RC1_on, RC2_on, RC3_on, RC4_on (each taking a value of 1 or 0)

In particular we can determine the number of readout cards reporting, as

N_card = (RC1_on + RC2_on + RC3_on + RC4_on)

and this gives the size of the readout data block, in words, as

N_data = 8 * num_rows_reported * N_card

with 8 representing the number of columns managed by each readout card.

The organization of the frame data is described in the next section.

Frame data

Normal acquisitions (row / column)

By "normal acquisitions", we mean everything except data mode 3.

Each word of MCE data is associated with a unique row and column in the multiplexing scheme. Each readout card is responsible for 8 columns and up to 41 rows. Columns 0-7 are associated with readout card 1, columns 8-15 are associated with readout card 2, and so on. MCE can support up to 32 columns.

Schematically, the data is organized like this (with rNNcMM indicating the data assoicated with row NN and column MM):

r00c00 r00c01 r00c02 ... r00c31
r01c00 r01c00 r01c02 ... r01c31
...
r40c00 r40c01 r40c02 ... r40c31

When num_rows_reported is less than 41, then the data for rows >= num_rows_reported is omitted. When a readout card is not reporting data, the data for its associated columns are omitted. For example, if num_rows_reported is 20 and only RC2 is reporting data then the frame structure is

r00c08 r00c09 r00c10 ... r00c15
r01c08 r01c09 r01c10 ... r01c15
r02c08 r02c09 r02c10 ... r02c15
...
r19c08 r19c09 r19c10 ... r19c15

Mathematically, the data for row R can be found starting at index

I_R = R * N_card * 8

The adjustment to this index to get the data associated with column C depends on which cards are reporting data.

Note that currently MCE only supports single-card and all-card modes; so the slightly more complicated cases of, for example, reporting from readout cards 2 and 4 are not available. The format described here does uniquely specify a way of handling those cases, however.

Checksum

The checksum word is the result of a cumulative XOR of all other words in the frame, including the header. Since the XOR of any number with itself is zero, the cumulative XOR of all words in the frame (including the header, data, and checksum) should be zero.