Mce cmd
Contents
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
Usage summary
mce_cmd [options] [-x cmd...] -i interactive mode, don't exit on errors -q quiet mode, only print errors or output data -p prefix-supression, don't print line number -e echo mode, print each command as well as response -r don't use readline on stdin (faster input in scripts) -n <card number> use the specified fibre card (Multicard MAS only) -c <file> choose a particular mce config file (mce.cfg) -m <file> choose a particular MAS config file (mas.cfg) -f <batch file> run commands from file instead of stdin -X "cmd string" execute this command and exit (these can be stacked) -o <directory> data file path -x <command> execute remainder of line as an mce_cmd command The -X command may be more useful as it allows multiple commands to be executed, e.g. mce_cmd -X "acq_config test_1 rc1" -X "acq_go 100" -v print version string and exit
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.
Multiple commands may be executed with the '-X' option. The commands are executed in order, in the same context. The command must be passed as a single shell argument (put it in quotes...):
mce_cmd -X "wb rc1 data_mode 4" -X "wb rca servo_mode 1"
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.
Note that after an mce_reset, not all of the DAC outputs are set to zero. Similarly, values written to RAM-based registers are not reset. A full reconfiguration is required for a proper reset.
Syntax:
mce_reset
DSP_RESET: reset the PCI card DSP firmware
The dsp_reset command causes the PCI card to reset.
Syntax:
dsp_reset
Special driver access commands
FAKESTOP: cause the driver to issue a stop-frame
In some cases an acquisition can hang because it has not received as many frames as it expected, and did not see a frame with the STOP bit set. This command triggers the driver to generate one or two data frames and place them in the output buffer. The last such frame will have the STOP bit set. An mce_cmd session that is acquiring data will receive the frame, see the STOP bit, and exit.
Note that in the absence of a data consumer, this command will leave frames outstanding in the data buffer. It is prudent to issue an EMPTY command after issuing FAKESTOP.
Syntax:
fakestop
EMPTY: cause the driver to empty the output data buffer
In some cases, following a failed acquisition, the output data buffer of the driver may contain residual data. This can lead to the failure of subsequent acquisitions. The EMPTY command causes the driver to update its pointers such that no data is retained.
Syntax:
empty
FRAME: set driver and PCI card frame-data size
To acquire data without an associated data handler (to write the data to disk), it is necessary to inform the driver and PCI card of the expected frame size. This is accomplished by passing the frame size, in 32-bit words, to the command 'FRAME'. If data acquisition is triggered (with the low-level 'GO' command, for example), and the driver/PCI card have not been informed of the frame size, the PCI card will simply discard the data.
Syntax:
frame <int>
Scripting and output formatting
SLEEP: delay execution for some number of microseconds
Note that the delays smaller than a few milliseconds cannot be commanded reliably.
Syntax:
sleep <microseconds>
DISPLAY: change integer output base
The output from MCE read commands is displayed in decimal or hex, depending on the mce.cfg configuration. To override this, decimal ('DEC') or hexadecimal ('HEX') output can be forced. Passing 'DEF' will return mce_cmd to its default behaviour.
Syntax:
display [ def | dec | hex ]
ECHO: echo commands to the terminal
In some scripting situations it may be useful to have commands echoed to the terminal along with their responses. This can be turned on and off by passing 1 or 0 to the ECHO command.
Syntax:
echo [ 0 | 1 ]
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 applied 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_link : turn on updating a symlink to the current acquisition
The acq_link command specifies the name of a symlink which will be created/retargeted to a current acquisition. This command only schedules the creation/retargeting of the link. The link is created by acq_config_<whatever>. As a result this command must be used before acq_config for it to do anything. As with the filename specified in acq_config, if the specified name is not an absolute path, the path specified by acq_path or the -o option. If doing a sequencing acquisition (either acq_config_fs or acq_config_dirfile_fs) the link will be updated whenever a new file is started.
Syntax:
acq_link <name>
Example:
acq_path /data/cryo/current_data acq_link mas.lnk 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
Low-level MCE commands
Issuing 'GO', 'RS', and 'STOP' will send MCE command packets to the MCE, but with no associated additional processing. For example, even though 'GO' causes the MCE to produce frame data, the frames will not be stored to disk and they will either accumulate in the driver's buffer or be discarded by the PCI card if they are not of the expected size. The 'STOP' command is intended for terminating MCE frame data acquisitions. It can not be used reliably with current PCI card firmware.
Of these, the only one useful to end users is the 'RS' command.
Syntax:
go <card> <param> rs <card> <param> stop <card> <param>
Example:
rs psc cycle_pow
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.
