Mce cmd

Introduction

mce_cmd provides an interface between a Linux shell and the MCE. The application can run interactively (accepting commands from a user and issuing responses to stdout), or can be used to execute scripts containing mce_cmd instructions.

Running mce_cmd

Interactive mode

When invoked with the '-i' option, mce_cmd can be used interactively. A session command history (similar to the one in bash) can be accessed with the up and down arrow keys, and line editing is possible using emacs-based key-mappings.

mce_cmd -i

After displaying a version message, mce_cmd will be ready to accept input. There is no user prompt.

Single command execution

A single command can be issued using the '-x' option:

mce_cmd -x rb cc fw_rev

The application will execute the command, display any output, and exit. Currently, only single commands can be executed from the command line.

Script execution

The '-f' option tell mce_cmd to read lines from the specified file and attempt to execute them. The '-q' option suppresses unnecessary output.

mce_cmd -q -f my_script.scr

When redirecting commands to mce_cmd, the '-r' option should be used to disable the command history/line editing features of mce_cmd and decrease the execution time.

cat my_script.scr | mce_cmd -q -r

If a script command fails, mce_cmd will exit. To suppress that behaviour (and continue attempting commands even after one of them has failed), pass the '-i' option.

Commands

We can break the mce_cmd command set into three broad categories: MCE commands, data acquisition commands, and output formatting commands.

Special hardware commands

MCE_RESET: reset the MCE using special character override

The mce_reset command causes the PCI card to transmit a special character over the fibre-optic connection to the MCE. This causes the MCE to reinitialize. It is advisable to wait several microseconds following the mce_reset command before issuing other MCE commands.

Syntax:

mce_reset

DSP_RESET: reset the PCI card DSP firmware

The dsp_reset command causes the PCI card to reset.

Syntax:

dsp_reset

MCE data block commands

MCE configuration data is stored in blocks at certain card and parameter addresses (which we will call "block locations"). A typical block address is

rc2 flx_quanta4

This block consists of 41 32-bit words where the user writes the squid-1 flux quantum size for column 4 on readout card 2.

The most basic data manipulation commands are RB ("read block") and WB ("write block"). These commands read from or write to the entire range of data at the block location, starting at the beginning of the block.

The commands RRA ("read range") and WRA ("write range") can be used to read or write particular subranges of the data in a block location.

All read and write commands take a card (or virtual card ) name and a parameter name as the first two arguments.

RB: read block

The read block command returns the entire contents of a block location.

Syntax:

rb  <card> <param>

Example:

rb rc1 adc_offset0
Line   1 : ok : 10 11 9 8 12 13 14 15

WB: write block

The write block command writes the given data to the specified block location. If the number of data is smaller than block size, the remaining block elements will not be altered. If the number of data is larger than the block size, the behaviour depends on the implementation of the block location.

Syntax:

wb  <card> <param> [val0 val1 val2 ...]

Example:

wb rc1 adc_offset0 0 1 2
Line   1 : ok
rb rc1 adc_offset0
Line   2 : ok :  0 1 2 8 12 13 14 15

RRA: read range

The read range command returns <count> values from the block location, starting from the value at <start_index> (indexed from 0).

Syntax:

rra <card> <param> <start_index> <count>

Example:

rra rc1 adc_offset0 2 4
Line   1 : ok : 2 8 12 13

WRA: write range

The write range command writes the given values into the block location, starting at <start_index> (indexed from 0). Other block data (i.e. at indices lower than start_index) are not changed. (This command is implemented as a read-update-write and will usually take twice as long to execute as a WB command.)

Syntax:

wra <card> <param> <start_index> [val0 val1 val2 ...]

Example:

wra rc1 adc_offset0 4 100 200
Line   1 : ok
rb rc1 adc_offset0
Line   2 : ok :  0 1 2 8 100 200 14 15

MCE data acquisition commands

The acquisition of frame data is achieved by first configuring an output system (by specifying an output format, filename, and the target readout cards), and then by issuing ACQ_GO commands to acquire frames.

This simplest example will acquire 1000 frames from rc2 into the file /data/cryo/current_data/test:

acq_config /data/cryo/current_data/test rc2
Line   1 : ok
acq_go 1000
Line   2 : ok

The configuration commands have mnemonics that begin with "ACQ_CONFIG". They allow a small variety of output formats.

acq_config : configure simple MCE frame file

The acq_config command configures a single output file to receive MCE frames.

Syntax:

acq_config <filename> <readout_card>

Example:

acq_config test1.dat rc2

acq_config_fs : configure file-sequenced MCE frame file

The acq_config_fs command will result in the outputting of the frame data into a set of files whose filename contains an increasing index. The output file is changed after <change_interval> frames. The output files will be called <filename>.000, <filename>.001, etc.

Syntax:

acq_config_fs <filename> <readout_card> <change_interval>

acq_path : set the default path for data output

The acq_path command sets the default output directory for frame data. This path is only appled if the filenames given in acq_config_* do not specify a relative path. The given path can be absolute, or relative to the mce_cmd's run-time working directory. The default output location can also be specified using the '-o' command line option.

Syntax:

acq_path <path>

Example:

acq_path /data/cryo/current_data
acq_config test1 rc1
acq_go 10

acq_go : acquire frame data

The acq_go command causes the MCE to begin acquiring data. The frame data will be stored according to the most recent acq_config* command. It is not usually necessary to reconfigure the output system (i.e. perform another acq_config) between acq_go commands. The exception to this is that if the frame structure changes (i.e. "cc num_rows_reported" is altered), then acq_config should be issued again so that the acquisition system can determine the frame size.

Syntax:

acq_go <frame_count>

Example:

acq_config tes_bias_ramp rc1
wb tes bias 5 5 5
acq_go 1
wb tes bias 10 10 10
acq_go 1

Output formatting

Normally, mce_cmd produces a line of output following each command. The output consists of two or three parts, separated by colons. If in line prefix mode (which is the default) the output is:

Line <line number>: <success> [: data ... ]

The <success> indicator will be "ok" if the command succeeded, or "error" otherwise. Successful commands may return data (for example, an RB command). Failed commands will always return an error message as the data.

If mce_cmd is invoked with prefixes turned off ('-p'), the output format is

<success> [: data]

If mce_cmd is invoked in quiet mode ('q'), then all command responses that have no output data are suppressed. In quiet mode, "Line 12: ok" will not be displayed.