Mce cmd

Template:Hierarchy header 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. Commands are case insensitive.

Special hardware commands

MCE_RESET: reset the MCE firmware using special character override

The mce_reset command causes the PCI card to transmit a special character (0x0b) over the fibre-optic connection to the MCE. This command was originally invented to clear the cmd/reply path when either of fibre or backplane communication is frozen. A tiny sniffer block in clock-card of the MCE detects this special character and asserts the mce_bclr line, which subsequently resets (only) the firmware on each MCE card.

Upon firmware reset, all state machines go to idle, register-based variables are reset to 0, but RAM-based variables stay unchanged. A firmware reset does not refresh the DAC outputs. Note that after an mce_reset, not all of the DAC outputs are set to zero.

mce_reset may lead to misleading information from mce_status, and rb commands in general. For example, flux_fbs are stored in registers which are overwritten by zero upon mce_reset. But mce_reset does not cause a rewrite of the DAC outputs. So, after a reset, rb flux_fb will report zero even if the actual flux_fb being applied is not zero. Other registers, such as servo_mode, which get reset, do affect the operation of MCE. Registers can only reinitialised by rewriting them (via a wb command). In gerenal, a mce_reconfig is recommended after mce_reset to ensure the system is properly configured.

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

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. The fakestop 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 with the display command. 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 cards) name and a parameter name as the first two arguments.

RB: read block

The read block (rb) 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 (wb) 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 (rra) 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 (wra) 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_CONFIG_DIRFILE and ACQ_CONFIG_DIRFILE_FS: dirfile-based acquisitions

The ACQ_CONFIG_DIRFILE and ACQ_CONFIG_DIRFILE_FS commands behave analogously to ACQ_CONFIG and ACQ_CONFIG_FS except they acquire data to a Dirfile instead of to a MCE frame file.

Syntax:

acq_config_dirfile <dirfilename> <readout_card>

and:

acq_config_dirfile_fs <dirfilename> <readout_card> <change_interval>

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

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 an 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 modified by an ACQ_CONFIG.... As a result this command must be used before an ACQ_CONFIG... for it to do anything. As with the filename specified in ACQ_CONFIG and friends, if the specified name is not an absolute path, the path specified by ACQ_PATH or the -o option will be prepended. 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_OPTION: set various acquisition options

The ACQ_OPTION command allows you to modify various optional parameters for a particular acquisition. Options are grouped by acquisition type (either "dirfile" or "flatfile", ignoring sequencing), and vary between acquisition type. They must be specified before configuration to take effect. Options are not persistent: an ACQ_CONFIG-type command consumes and then resets all relevant options to their default value after configuration (so ACQ_CONFIG_DIRFILE and ACQ_CONFIG_DIRFILE_FS reset the dirfile options after applying them to the acquisition it is configuring, but ACQ_CONFIG will neither reset nor use them).

Syntax:

acq_option <acq_type> <option_name> <option_value>

Currently, only acq_type "dirfile" has any options. These are:

• include <filename>: copies contents of the specified file to the output dirfile metadata. The file is copied verbatim, but the contents are not verified by MAS to see if it makes sense to use it as dirfile metadata. Default is the empty string, indicating no inclusion. If <filename> is a relative path, it will be to the current directory. (ie. it ignores both the -o option and ACQ_PATH)
• spf <number>: sets the samples-per-frame of the fields in the dirfile to the specified value, which must be positive. Default is one.
• version <number>: sets the Dirfile Standards Version used to write the dirfile metadata. This can be any integer greater than or equal to 3 (a smaller number results in the default, 7, being used), but only a few values are really of interest:
  • Versions < 7 are unable to properly extract signed bitfields from the packed MCE data. This affects data modes 4, 5, 7, and 10.
  • Versions > 4 can't be read by default builds of kst-1.x. (It is possible to build kst-1.x against a modern GetData library, making newer Dirfiles readable, although I don't think any distro shipping kst-1 has done this.)

Setting this to 4 should recover the behaviour of older versions of MAS. Also note: the dirfile formatted runfile metadata output by "mce_status -d" requires at least Version 8 to parse, but does not depend on, nor is affected by, the Version number specified here.

Example:

acq_option dirfile include /path/to/extra/format_metadata
acq_option dirfile version 4
acq_link mas.lnk
acq_config_dirfile test1 rc1
acq_go 10

ACQ_MULTI_BEGIN and ACQ_MULTI_END: manage multiple output syncs

In some cases it may be desirable to output to multiple files at the same time (e.g. to record a dirfile and a flatfile simultaneously). This is achieved my putting mce_cmd into "multisync" mode, creating a few different output configurations with an ACQ_CONFIG..., and then issuing ACQ_GO. The ACQ_MULTI_BEGIN command clears the acquisition stack and puts mce_cmd into multisync mode. The ACQ_MULTI_END command clears the acquisition stack and disables multisync mode. An ACQ_MULTI_END command is implicitly executed when mce_cmd exits, so it is not usually necessary to execute this command explicitly.

Syntax:

acq_multi_begin
acq_multi_end

Example (output to flatfile and dirfile simultaneously):

acq_multi_begin
acq_config 1234560000_flat rcs
acq_config_dirfile 1234560000_dirfile rcs
acq_go 164000

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. Parameters which use RS have the type rs in the MCE commands list. They are mostly commands which reset devices in the MCE (RS stands for reset), which means they must reply to the request before executing the command, unlike a normal WB command, which replies after execution.

The only parameter which respond to GO and STOP is the readout card's ret_dat parameter. In general, the MAS acquisition system (ACQ_GO, &c.) should be used instead of sending these commands directly.

Syntax:

go <card> <param>
rs <card> <param>
stop <card> <param>

Example:

rs cc config_fac

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.